SDK数据库 Command·更新·数组操作符

Command.push(values: Object): Command

支持端：小程序 2.8.3, 云函数 1.2.1, Web

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

参数

values: Object

属性	类型	默认值	必填	说明
each	Array.<any>		是	要插入的所有元素
position	number		否	从哪个位置开始插入，不填则是尾部
sort	number		否	对结果数组排序
slice	number		否	限制结果数组长度

返回值

Command

参数说明

position 说明

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

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

sort 说明

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

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

slice** 说明

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

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

升级说明

以上定义是从小程序 2.8.3 / 云函数 SDK 1.2.1 起支持，对于之前的版本，使用的是如下函数签名，新版中对旧版签名有兼容。

旧版签名：传入一个数组，该数组的每个元素会被追加到字段数组的尾部

function push(values: any[]): Command

示例 1：尾部添加元素

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

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

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

示例 3：排序

插入后对整个数组做排序

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

不插入，只对数组做排序

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

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

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

示例 4：截断保留

插入后只保留后 2 个元素

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

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

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

---

Command.pop(): Command

支持端：小程序 , 云函数 , Web

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

返回值

Command

示例代码

const _ = db.command
db.collection('todos').doc('doc-id').update({
  data: {
    tags: _.pop()
  }
})

---

Command.unshift(values: any[]): Command

支持端：小程序 , 云函数 , Web

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

参数

values: any[]

返回值

Command

示例代码

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

---

Command.shift(): Command

支持端：小程序 , 云函数 , Web

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

返回值

Command

示例代码

const _ = db.command
db.collection('todos').doc('doc-id').update({
  data: {
    tags: _.shift()
  }
})

---

Command.pull(value: any): Command

支持端：小程序 2.8.3, 云函数 1.2.1, Web

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

参数

value: any

值或查询条件

返回值

Command

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

const _ = db.command
db.collection('todos').doc('doc-id').update({
  data: {
    tags: _.pull('database')
  }
})

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

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

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

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

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

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

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

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

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

Place 结构如下：

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

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

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

---

Command.pullAll(value: any): Command

支持端：小程序 2.8.3, 云函数 1.2.1, Web

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

参数

value: any

值或查询条件

返回值

Command

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

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

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

---

Command.addToSet(value: any|Object): Command

支持端：小程序 2.8.3, 云函数 1.2.1, Web

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

参数

value: any|Object

要添加进数组的一个或多个元素

属性	类型	默认值	必填	说明
each	Array.<any>		是	数组，用于同时指定多个要插入数组的元素

返回值

Command

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

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

const _ = db.command
db.collection('todos').doc('doc-id').update({
  data: {
    tags: _.addToSet('database')
  }
})

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

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

  const _ = db.command
  db.collection('todos').doc('doc-id').update({
    data: {
      tags: _.addToSet({
        each: ['database', 'cloud']
      })
    }
  })