SDK數(shù)據(jù)庫 Command·更新·數(shù)組操作符

Command.push(values: Object): Command

支持端：小程序 2.8.3, 云函數(shù) 1.2.1, Web

數(shù)組更新操作符。對(duì)一個(gè)值為數(shù)組的字段，往數(shù)組添加一個(gè)或多個(gè)值?；蜃侄卧瓰榭?，則創(chuàng)建該字段并設(shè)數(shù)組為傳入值。

參數(shù)

values: Object

返回值

Command

參數(shù)說明

position 說明

要求必須同時(shí)有 each 參數(shù)存在。

非負(fù)數(shù)代表從數(shù)組開始位置數(shù)的位置，從 0 開始計(jì)。如果數(shù)值大于等于數(shù)組長(zhǎng)度，則視為在尾部添加。負(fù)數(shù)代表從數(shù)組尾部倒數(shù)的位置，比如 -1 就代表倒數(shù)第二個(gè)元素的位置。如果負(fù)數(shù)數(shù)值的絕對(duì)值大于等于數(shù)組長(zhǎng)度，則視為從數(shù)組頭部添加。

sort 說明

要求必須同時(shí)有 each 參數(shù)存在。給定 1 代表升序，-1 代表降序。

如果數(shù)組元素是記錄，則用 { <字段>: 1 | -1 } 的格式表示根據(jù)記錄中的什么字段做升降序排序。

slice** 說明

要求必須同時(shí)有 each 參數(shù)存在

升級(jí)說明

以上定義是從小程序 2.8.3 / 云函數(shù) SDK 1.2.1 起支持，對(duì)于之前的版本，使用的是如下函數(shù)簽名，新版中對(duì)舊版簽名有兼容。

舊版簽名：傳入一個(gè)數(shù)組，該數(shù)組的每個(gè)元素會(huì)被追加到字段數(shù)組的尾部

function push(values: any[]): Command

示例 1：尾部添加元素

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

示例 2：從第二個(gè)位置開始插入

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

示例 3：排序

插入后對(duì)整個(gè)數(shù)組做排序

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

不插入，只對(duì)數(shù)組做排序

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

如果字段是對(duì)象數(shù)組，可以如下根據(jù)元素對(duì)象里的字段進(jìn)行排序：

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：截?cái)啾Ａ?/h2>

插入后只保留后 2 個(gè)元素

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

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

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

支持端：小程序 , 云函數(shù) , Web

數(shù)組更新操作符，對(duì)一個(gè)值為數(shù)組的字段，將數(shù)組尾部元素刪除

返回值

Command

示例代碼

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

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

支持端：小程序 , 云函數(shù) , Web

數(shù)組更新操作符，對(duì)一個(gè)值為數(shù)組的字段，往數(shù)組頭部添加一個(gè)或多個(gè)值?；蜃侄卧瓰榭眨瑒t創(chuàng)建該字段并設(shè)數(shù)組為傳入值。

參數(shù)

values: any[]

返回值

Command

示例代碼

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

Command.shift(): Command

支持端：小程序 , 云函數(shù) , Web

數(shù)組更新操作符，對(duì)一個(gè)值為數(shù)組的字段，將數(shù)組頭部元素刪除。

返回值

Command

示例代碼

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

Command.pull(value: any): Command

支持端：小程序 2.8.3, 云函數(shù) 1.2.1, Web

數(shù)組更新操作符。給定一個(gè)值或一個(gè)查詢條件，將數(shù)組中所有匹配給定值或查詢條件的元素都移除掉。

參數(shù)

value: any

值或查詢條件

返回值

Command

示例代碼 1：根據(jù)常量匹配移除

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

示例代碼 2：根據(jù)查詢條件匹配移除

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

示例代碼 3：對(duì)象數(shù)組時(shí)，根據(jù)查詢條件匹配移除

假設(shè)有字段 places 數(shù)組中的元素結(jié)構(gòu)如下

{
  "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：有嵌套對(duì)象的對(duì)象數(shù)組時(shí)，根據(jù)查詢條件匹配移除

假設(shè)有字段 cities 數(shù)組中的元素結(jié)構(gòu)如下

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

Place 結(jié)構(gòu)如下：

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

可用 elemMatch 匹配嵌套在對(duì)象數(shù)組里面的對(duì)象數(shù)組字段 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, 云函數(shù) 1.2.1, Web

數(shù)組更新操作符。給定一個(gè)值或一個(gè)查詢條件，將數(shù)組中所有匹配給定值的元素都移除掉。跟 pull 的差別在于只能指定常量值、傳入的是數(shù)組。

參數(shù)

value: any

值或查詢條件

返回值

Command

示例代碼：根據(jù)常量匹配移除

從 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, 云函數(shù) 1.2.1, Web

數(shù)組更新操作符。原子操作。給定一個(gè)或多個(gè)元素，除非數(shù)組中已存在該元素，否則添加進(jìn)數(shù)組。

參數(shù)

value: any|Object

要添加進(jìn)數(shù)組的一個(gè)或多個(gè)元素

返回值

Command

示例代碼 1：添加一個(gè)元素

如果 tags 數(shù)組中不包含 database，添加進(jìn)去

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

示例代碼 2：添加多個(gè)元素

需傳入一個(gè)對(duì)象，其中有一個(gè)字段 each，其值為數(shù)組，每個(gè)元素就是要添加的元素

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