云数据库操作符

查询·逻辑操作符

and

查询操作符，用于表示逻辑 "与" 的关系，表示需同时满足多个查询筛选条件

使用说明

and 有两种使用情况：

1. 用在根查询条件

此时需传入多个查询条件，表示需同时满足提供的多个完整查询条件

const dbCmd = db.command
let res = await db.collection('todo').where(dbCmd.and([
  {
    progress: dbCmd.gt(50)
  },
  {
    tags: 'cloud'
  }
])).get()

但以上用 and 组成的查询条件是不必要的，因为传入的对象的各字段隐式组成了 “与” 的关系，上述条件等价于下方更简洁的写法：

const dbCmd = db.command
let res = await db.collection('todo').where({
  progress: dbCmd.gt(50),
  tags: 'cloud'
}).get()

通常需要显示使用 and 是用在有跨字段或操作的时候

2. 用在字段查询条件

需传入多个查询操作符或常量，表示字段需满足或匹配给定的条件。

如以下用前置写法的方式表示 "progress 字段值大于 50 且小于 100"

const dbCmd = db.command
let res = await db.collection('todo').where({
  progress: dbCmd.and(dbCmd.gt(50), dbCmd.lt(100))
}).get()

还可以用后置写法的方式表示同样的条件：

const dbCmd = db.command
let res = await db.collection('todo').where({
  progress: dbCmd.gt(50).and(dbCmd.lt(100))
}).get()

注意 Command 默认也可以直接链式调用其他 Command，默认表示多个 Command 的与操作，因此上述代码还可以精简为：

const dbCmd = db.command
let res = await db.collection('todo').where({
  progress: dbCmd.gt(50).lt(100)
}).get()

调用风格

方法接收两种传参方式，一是传入一个数组参数，二是传入多个参数，效果一样。

// 传入数组
function and(expressions: Expression[]): Command
// 传入多参数
function and(...expressions: Expression[]): Command

or

查询操作符，用于表示逻辑 "或" 的关系，表示需同时满足多个查询筛选条件。或指令有两种用法，一是可以进行字段值的 “或” 操作，二是也可以进行跨字段的 “或” 操作。

字段值的或操作

字段值的 “或” 操作指的是指定一个字段值为多个值之一即可。

如筛选出进度大于 80 或小于 20 的 todo：

流式写法：

const dbCmd = db.command
let res = await db.collection('todo').where({
  progress: dbCmd.gt(80).or(dbCmd.lt(20))
}).get()

前置写法：

const dbCmd = db.command
let res = await db.collection('todo').where({
  progress: dbCmd.or(dbCmd.gt(80), dbCmd.lt(20))
}).get()

前置写法也可接收一个数组：

const dbCmd = db.command
let res = await db.collection('todo').where({
  progress: dbCmd.or([dbCmd.gt(80), dbCmd.lt(20)])
}).get()

跨字段的或操作

跨字段的 “或” 操作指条件 “或”，相当于可以传入多个 where 语句，满足其中一个即可。

如筛选出进度大于 80 或已标为已完成的 todo：

const dbCmd = db.command
let res = await db.collection('todo').where(dbCmd.or([
  {
    progress: dbCmd.gt(80)
  },
  {
    done: true
  }
])).get()

调用风格

方法接收两种传参方式，一是传入一个数组参数，二是传入多个参数，效果一样。

// 传入数组
function or(expressions: Expression[]): Command
// 传入多参数
function or(...expressions: Expression[]): Command

not

查询操作符，用于表示逻辑 "非" 的关系，表示需不满足指定的条件。

示例

如筛选出进度不等于100的 todo：

const dbCmd = db.command
let res = await db.collection('todo').where({
  progress: dbCmd.not(dbCmd.eq(100))
}).get()

not 也可搭配其他逻辑指令使用，包括 and, or, nor, not，如 or：

const dbCmd = db.command
let res = await db.collection('todo').where({
  progress: dbCmd.not(dbCmd.or([dbCmd.lt(50), dbCmd.eq(100)]))
}).get()

nor

查询操作符，用于表示逻辑 "都不" 的关系，表示需不满足指定的所有条件。如果记录中没有对应的字段，则默认满足条件。

示例 1

筛选出进度既不小于20又不大于80的 todo ：

const dbCmd = db.command
let res = await db.collection('todo').where({
  progress: dbCmd.nor([dbCmd.lt(20), dbCmd.gt(80)])
}).get()

以上同时会筛选出不存在 progress 字段的记录，如果要要求 progress 字段存在，可以用 exists 指令：

const dbCmd = db.command
let res = await db.collection('todo').where({
  progress: dbCmd.exists().nor([dbCmd.lt(20), dbCmd.gt(80)])
  // 等价于以下非链式调用的写法：
  // progress: dbCmd.exists().and(dbCmd.nor([dbCmd.lt(20), dbCmd.gt(80)]))
}).get()

示例 2

筛选出 progress 不小于 20 且 tags 数组不包含 miniprogram 字符串的记录：

const dbCmd = db.command
db.collection('todo').where(dbCmd.nor([{
  progress: dbCmd.lt(20),
}, {
  tags: 'miniprogram',
}])).get()

以上会筛选出满足以下条件之一的记录：

1. progress 不小于 20 且 tags 数组不包含 miniprogram 字符串 3. progress 不小于 20 且 tags 字段不存在 5. progress 字段不存在 且 tags 数组不包含 miniprogram 字符串 7. progress 不小于 20 且 tags 字段不存在 如果要求 progress 和 tags 字段存在，可以用 exists 指令：

const dbCmd = db.command
let res = await db.collection('todo').where(
  dbCmd.nor([{
    progress: dbCmd.lt(20),
  }, {
    tags: 'miniprogram',
  }])
  .and({
    progress: dbCmd.exists(true),
    tags: dbCmd.exists(true),
  })
).get()

调用风格

方法接收两种传参方式，一是传入一个数组参数，二是传入多个参数，效果一样。

// 传入数组
function nor(expressions: Expression[]): Command
// 传入多参数
function nor(...expressions: Expression[]): Command

查询·比较操作符

eq

查询筛选条件，表示字段等于某个值。eq 指令接受一个字面量 (literal)，可以是 number, boolean, string, object, array, Date。

使用说明

比如筛选出所有自己发表的文章，除了用传对象的方式：

const openID = 'xxx'
let res = await db.collection('articles').where({
  _openid: openID
}).get()

还可以用指令：

const dbCmd = db.command
const openID = 'xxx'
let res = await db.collection('articles').where({
  _openid: dbCmd.eq(openid)
}).get()

注意 eq 指令比对象的方式有更大的灵活性，可以用于表示字段等于某个对象的情况，比如：

// 这种写法表示匹配 stat.publishYear == 2018 且 stat.language == 'zh-CN'
let res = await db.collection('articles').where({
  stat: {
    publishYear: 2018,
    language: 'zh-CN'
  }
}).get()
// 这种写法表示 stat 对象等于 { publishYear: 2018, language: 'zh-CN' }
const dbCmd = db.command
let res = await db.collection('articles').where({
  stat: dbCmd.eq({
    publishYear: 2018,
    language: 'zh-CN'
  })
}).get()

neq

查询筛选条件，表示字段不等于某个值。eq 指令接受一个字面量 (literal)，可以是 number, boolean, string, object, array, Date。

使用说明

表示字段不等于某个值，和 eq 相反

lt

查询筛选操作符，表示需小于指定值。可以传入 Date 对象用于进行日期比较。

示例代码

找出进度小于 50 的 todo

const dbCmd = db.command
let res = await db.collection('todos').where({
  progress: dbCmd.lt(50)
})
.get()

lte

查询筛选操作符，表示需小于或等于指定值。可以传入 Date 对象用于进行日期比较。

示例代码

找出进度小于或等于 50 的 todo

const dbCmd = db.command
let res = await db.collection('todos').where({
  progress: dbCmd.lte(50)
})
.get()

gt

查询筛选操作符，表示需大于指定值。可以传入 Date 对象用于进行日期比较。

示例代码

找出进度大于 50 的 todo

const dbCmd = db.command
let res = await db.collection('todos').where({
  progress: dbCmd.gt(50)
})
.get()

gte

查询筛选操作符，表示需大于或等于指定值。可以传入 Date 对象用于进行日期比较。

示例代码

找出进度大于或等于 50 的 todo

const dbCmd = db.command
let res = await db.collection('todos').where({
  progress: dbCmd.gte(50)
})
.get()

in

查询筛选操作符，表示要求值在给定的数组内。

示例代码

找出进度为 0 或 100 的 todo

const dbCmd = db.command
let res = await db.collection('todos').where({
  progress: dbCmd.in([0, 100])
})
.get()

nin

查询筛选操作符，表示要求值不在给定的数组内。

示例代码

找出进度不是 0 或 100 的 todo

const dbCmd = db.command
let res = await db.collection('todos').where({
  progress: dbCmd.nin([0, 100])
})
.get()

查询·字段操作符

exists

判断字段是否存在

示例代码

找出存在 tags 字段的记录

const dbCmd = db.command
let res = await db.collection('todos').where({
  tags: dbCmd.exists(true)
})
.get()

mod

查询筛选操作符，给定除数 divisor 和余数 remainder，要求字段作为被除数时 value % divisor = remainder。

示例代码

找出进度为 10 的倍数的字段的记录

const dbCmd = db.command
let res = await db.collection('todos').where({
  progress: dbCmd.mod(10, 0)
})
.get()

查询·数组操作符

all

数组查询操作符。用于数组字段的查询筛选条件，要求数组字段中包含给定数组的所有元素。

示例代码 1：普通数组

找出 tags 数组字段同时包含 cloud 和 database 的记录

const dbCmd = db.command
let res = await db.collection('todos').where({
  tags: dbCmd.all(['cloud', 'database'])
})
.get()

示例代码 2：对象数组

如果数组元素是对象，则可以用 dbCmd.elemMatch 匹配对象的部分字段

假设有字段 places 定义如下：

{
  "type": string
  "area": number
  "age": number
}

找出数组字段中至少同时包含一个满足 “area 大于 100 且 age 小于 2” 的元素和一个满足 “type 为 mall 且 age 大于 5” 的元素

const dbCmd = db.command
let res = await db.collection('todos').where({
  places: dbCmd.all([
    dbCmd.elemMatch({
      area: dbCmd.gt(100),
      age: dbCmd.lt(2),
    }),
    dbCmd.elemMatch({
      type: 'mall',
      age: dbCmd.gt(5),
    }),
  ]),
})
.get()

elemMatch

用于数组字段的查询筛选条件，要求数组中包含至少一个满足 elemMatch 给定的所有条件的元素

示例代码：数组是对象数组的情况

假设集合示例数据如下：

{
  "_id": "a0",
  "city": "x0",
  "places": [{
    "type": "garden",
    "area": 300,
    "age": 1
  }, {
    "type": "theatre",
    "area": 50,
    "age": 15
  }]
}

找出 places 数组字段中至少同时包含一个满足 “area 大于 100 且 age 小于 2” 的元素

const dbCmd = db.command
let res = await db.collection('todos').where({
  places: dbCmd.elemMatch({
    area: dbCmd.gt(100),
    age: dbCmd.lt(2),
  })
})
.get()

注意*：如果不使用 elemMatch 而直接如下指定条件，则表示的是 places 数组字段中至少有一个元素的 area 字段大于 100 且 places 数组字段中至少有一个元素的 age 字段小于 2：

const dbCmd = db.command
let res = await db.collection('todos').where({
  places: {
    area: dbCmd.gt(100),
    age: dbCmd.lt(2),
  }
})
.get()

示例代码：数组元素都是普通数据类型的情况

假设集合示例数据如下：

{
  "_id": "a0",
  "scores": [60, 80, 90]
}

找出 scores 数组字段中至少同时包含一个满足 “大于 80 且小于 100” 的元素

const dbCmd = db.command
let res = await db.collection('todos').where({
  scores: dbCmd.elemMatch(dbCmd.gt(80).lt(100))
})
.get()

size

更新操作符，用于数组字段的查询筛选条件，要求数组长度为给定值

示例

找出 tags 数组字段长度为 2 的所有记录

const dbCmd = db.command
let res = await db.collection('todos').where({
  places: dbCmd.size(2)
})
.get()

查询·地理位置操作符

geoNear

按从近到远的顺序，找出字段值在给定点的附近的记录。

索引要求

需对查询字段建立地理位置索引

示例代码

找出离给定位置 1 公里到 5 公里范围内的记录

const dbCmd = db.command
let res = await db.collection('restaurants').where({
  location: dbCmd.geoNear({
    geometry: new db.Geo.Point(113.323809, 23.097732),
    minDistance: 1000,
    maxDistance: 5000,
  })
}).get()

geoWithin

找出字段值在指定区域内的记录，无排序。指定的区域必须是多边形（Polygon）或多边形集合（MultiPolygon）。

索引要求

需对查询字段建立地理位置索引

示例代码 1：给定多边形

const dbCmd = db.command
const { Point, LineString, Polygon } = db.Geo
let res = await .collection('restaurants').where({
  location: dbCmd.geoWithin({
    geometry: new Polygon([
      new LineString([
        new Point(0, 0),
        new Point(3, 2),
        new Point(2, 3),
        new Point(0, 0)
      ])
    ]),
  })
}).get()

示例代码 2：给定圆形

可以不用 geometry 而用 centerSphere 构建一个圆形。

centerSphere 对应的值的定义是：[ [经度, 纬度], 半径 ]

半径需以弧度计，比如需要 10km 的半径，则用距离除以地球半径 6378.1km 得出的数字。

const dbCmd = db.command
let res = await db.collection('restaurants').where({
  location: dbCmd.geoWithin({
    centerSphere: [
      [-88, 30],
      10 / 6378.1,
    ]
  })
}).get()

geoIntersects

找出给定的地理位置图形相交的记录

索引要求

需对查询字段建立地理位置索引

示例代码：找出和一个多边形相交的记录

const dbCmd = db.command
const { Point, LineString, Polygon } = db.Geo
let res = await db.collection('restaurants').where({
  location: dbCmd.geoIntersects({
    geometry: new Polygon([
      new LineString([
        new Point(0, 0),
        new Point(3, 2),
        new Point(2, 3),
        new Point(0, 0)
      ])
    ]),
  })
}).get()

查询·表达式操作符

expr

查询操作符，用于在查询语句中使用聚合表达式，方法接收一个参数，该参数必须为聚合表达式

使用说明

1. expr 可用于在聚合 match 流水线阶段中引入聚合表达式 3. 如果聚合 match 阶段是在 lookup 阶段内，此时的 expr 表达式内可使用 lookup 中使用 let 参数定义的变量，具体示例可见 lookup 的 指定多个连接条件 例子 5. expr 可用在普通查询语句（where）中引入聚合表达式

示例代码 1：比较同一个记录中的两个字段

假设 items 集合的数据结构如下：

{
  "_id": string,
  "inStock": number, // 库存量
  "ordered": number  // 被订量
}

找出被订量大于库存量的记录：

const dbCmd = db.command
const $ = dbCmd.aggregate
let res = await db.collection('items').where(dbCmd.expr($.gt(['$ordered', '$inStock']))).get()

示例代码 2：与条件语句组合使用

假设 items 集合的数据结构如下：

{
  "_id": string,
  "price": number
}

假设价格小于等于 10 的打 8 折，大于 10 的打 5 折，让数据库查询返回打折后价格小于等于 8 的记录：

const dbCmd = db.command
const $ = dbCmd.aggregate
let res = await db.collection('items').where(dbCmd.expr(
  $.lt([
    $.cond({
      if: $.gte(['$price', 10]),
      then: $.multiply(['$price', '0.5']),
      else: $.multiply(['$price', '0.8']),
    })
    ,
    8
  ])
).get()

更新·字段操作符

set

更新操作符，用于设定字段等于指定值。

使用说明

这种方法相比传入纯 JS 对象的好处是能够指定字段等于一个对象

示例

// 以下方法只会更新 style.color 为 red，而不是将 style 更新为 { color: 'red' }，即不影响 style 中的其他字段
let res = await db.collection('todos').doc('doc-id').update({
  style: {
    color: 'red'
  }
})

// 以下方法更新 style 为 { color: 'red', size: 'large' }
let res = await db.collection('todos').doc('doc-id').update({
  style: dbCmd.set({
    color: 'red',
    size: 'large'
  })
})

remove

更新操作符，用于表示删除某个字段。

示例代码

删除 style 字段：

const dbCmd = db.command
let res = await db.collection('todos').doc('todo-id').update({
  style: dbCmd.remove()
})

inc

更新操作符，原子操作，用于指示字段自增

原子自增

多个用户同时写，对数据库来说都是将字段自增，不会有后来者覆写前者的情况

示例代码

将一个 todo 的进度自增 10：

const dbCmd = db.command
let res = await db.collection('todos').doc('todo-id').update({
  progress: dbCmd.inc(10)
})

mul

更新操作符，原子操作，用于指示字段自乘某个值

原子自乘

多个用户同时写，对数据库来说都是将字段自乘，不会有后来者覆写前者的情况

示例代码

将一个 todo 的进度自乘 10：

const dbCmd = db.command
let res = await db.collection('todos').doc('todo-id').update({
  progress: dbCmd.mul(10)
})

min

更新操作符，给定一个值，只有该值小于字段当前值才进行更新。

示例代码

如果字段 progress > 50，则更新到 50

const dbCmd = db.command
let res = await db.collection('todos').doc('doc-id').update({
  progress: dbCmd.min(50)
})

max

更新操作符，给定一个值，只有该值大于字段当前值才进行更新。

示例代码

如果字段 progress < 50，则更新到 50

const dbCmd = db.command
let res = await db.collection('todos').doc('doc-id').update({
  progress: dbCmd.max(50)
})

rename

更新操作符，字段重命名。如果需要对嵌套深层的字段做重命名，需要用点路径表示法。不能对嵌套在数组里的对象的字段进行重命名。

示例 1：重命名顶层字段

const dbCmd = db.command
let res = await db.collection('todos').doc('doc-id').update({
  progress: dbCmd.rename('totalProgress')
})

示例 2：重命名嵌套字段

const dbCmd = db.command
let res = await db.collection('todos').doc('doc-id').update({
  someObject: {
    someField: dbCmd.rename('someObject.renamedField')
  }
})

或：

const dbCmd = db.command
let res = await db.collection('todos').doc('doc-id').update({
  'someObject.someField': dbCmd.rename('someObject.renamedField')
})

更新·数组操作符

push

数组更新操作符。对一个值为数组的字段，往数组添加一个或多个值。或字段原为空，则创建该字段并设数组为传入值。

参数说明

position 说明

要求必须同时有 each 参数存在。

非负数代表从数组开始位置数的位置，从 0 开始计。如果数值大于等于数组长度，则视为在尾部添加。负数代表从数组尾部倒数的位置，比如 -1 就代表倒数第二个元素的位置。如果负数数值的绝对值大于等于数组长度，则视为从数组头部添加。

sort 说明

要求必须同时有 each 参数存在。给定 1 代表升序，-1 代表降序。

如果数组元素是记录，则用 { <字段>: 1 | -1 } 的格式表示根据记录中的什么字段做升降序排序。

slice 说明**

要求必须同时有 each 参数存在

值	说明
0	将字段更新为空数组
正数	数组只保留前 n 个元素
负数	数组只保留后 n 个元素

示例 1：尾部添加元素

const dbCmd = db.command
let res = await db.collection('todos').doc('doc-id').update({
  tags: dbCmd.push(['mini-program', 'cloud'])
})

示例 2：从第二个位置开始插入

const dbCmd = db.command
let res = await db.collection('todos').doc('doc-id').update({
  tags: dbCmd.push({
    each: ['mini-program', 'cloud'],
    position: 1,
  })
})

示例 3：排序

插入后对整个数组做排序

const dbCmd = db.command
let res = await db.collection('todos').doc('doc-id').update({
  tags: dbCmd.push({
    each: ['mini-program', 'cloud'],
    sort: 1,
  })
})

不插入，只对数组做排序

const dbCmd = db.command
let res = await db.collection('todos').doc('doc-id').update({
  tags: dbCmd.push({
    each: [],
    sort: 1,
  })
})

如果字段是对象数组，可以如下根据元素对象里的字段进行排序：

const dbCmd = db.command
let res = await db.collection('todos').doc('doc-id').update({
  tags: dbCmd.push({
    each: [
      { name: 'miniprogram', weight: 8 },
      { name: 'cloud', weight: 6 },
    ],
    sort: {
      weight: 1,
    },
  })
})

示例 4：截断保留

插入后只保留后 2 个元素

const dbCmd = db.command
let res = await db.collection('todos').doc('doc-id').update({
  tags: dbCmd.push({
    each: ['mini-program', 'cloud'],
    slice: -2,
  })
})

示例 5：在指定位置插入、然后排序、最后只保留前 2 个元素

const dbCmd = db.command
let res = await db.collection('todos').doc('doc-id').update({
  tags: dbCmd.push({
    each: ['mini-program', 'cloud'],
    position: 1,
    slice: 2,
    sort: 1,
  })
})

pop

数组更新操作符，对一个值为数组的字段，将数组尾部元素删除，仅可以删除末尾一个

示例代码

const dbCmd = db.command
let res = await db.collection('todos').doc('doc-id').update({
  tags: dbCmd.pop()
})

unshift

数组更新操作符，对一个值为数组的字段，往数组头部添加一个或多个值。或字段原为空，则创建该字段并设数组为传入值。

示例代码

const dbCmd = db.command
let res = await db.collection('todos').doc('doc-id').update({
  tags: dbCmd.unshift(['mini-program', 'cloud'])
})

shift

数组更新操作符，对一个值为数组的字段，将数组头部元素删除。

示例代码

const dbCmd = db.command
let res = await db.collection('todos').doc('doc-id').update({
  tags: dbCmd.shift()
})

pull

数组更新操作符。给定一个值或一个查询条件，将数组中所有匹配给定值或查询条件的元素都移除掉。

示例代码 1：根据常量匹配移除

const dbCmd = db.command
let res = await db.collection('todos').doc('doc-id').update({
  tags: dbCmd.pull('database')
})

示例代码 2：根据查询条件匹配移除

const dbCmd = db.command
let res = await db.collection('todos').doc('doc-id').update({
  tags: dbCmd.pull(dbCmd.in(['database', 'cloud']))
})

示例代码 3：对象数组时，根据查询条件匹配移除

假设有字段 places 数组中的元素结构如下

{
  "type": string
  "area": number
  "age": number
}

const dbCmd = db.command
let res = await db.collection('todos').doc('doc-id').update({
  places: dbCmd.pull({
    area: dbCmd.gt(100),
    age: dbCmd.lt(2),
  })
})

示例代码 4：有嵌套对象的对象数组时，根据查询条件匹配移除

假设有字段 cities 数组中的元素结构如下

{
  "name": string
  "places": Place[]
}

Place 结构如下：

{
  "type": string
  "area": number
  "age": number
}

可用 elemMatch 匹配嵌套在对象数组里面的对象数组字段 places

const dbCmd = db.command
let res = await db.collection('todos').doc('doc-id').update({
  cities: dbCmd.pull({
    places: dbCmd.elemMatch({
      area: dbCmd.gt(100),
      age: dbCmd.lt(2),
    })
  })
})

pullAll

数组更新操作符。给定一个值或一个查询条件，将数组中所有匹配给定值的元素都移除掉。跟 pull 的差别在于只能指定常量值、传入的是数组。

示例代码：根据常量匹配移除

从 tags 中移除所有 database 和 cloud 字符串

const dbCmd = db.command
let res = await db.collection('todos').doc('doc-id').update({
  tags: dbCmd.pullAll(['database', 'cloud'])
})

addToSet

数组更新操作符。原子操作。给定一个或多个元素，除非数组中已存在该元素，否则添加进数组。

示例代码 1：添加一个元素

如果 tags 数组中不包含 database，添加进去

const dbCmd = db.command
let res = await db.collection('todos').doc('doc-id').update({
  tags: dbCmd.addToSet('database')
})

示例代码 2：添加多个元素

需传入一个对象，其中有一个字段 each，其值为数组，每个元素就是要添加的元素

const dbCmd = db.command
let res = await db.collection('todos').doc('doc-id').update({
  tags: dbCmd.addToSet({
    $each: ['database', 'cloud']
  })
})