DB

title: DB

sidebar_label: DB

参数

Database

云开发 SDK 数据库实例

参考文档

serverDate

构造一个服务端时间的引用。可用于查询条件、更新字段值或新增记录时的字段值。

参考文档

() => ServerDate

示例代码

新增记录时设置字段为服务端时间：

db.collection('todos').add({
  description: 'eat an apple',
  createTime: db.serverDate()
})

更新字段为服务端时间往后一小时：

db.collection('todos').doc('my-todo-id').update({
  due: db.serverDate({
    offset: 60 * 60 * 1000
  })
})

API 支持度

RegExp

构造正则表达式，仅需在普通 js 正则表达式无法满足的情况下使用

参考文档

(options: IRegExpOptions) => IRegExp

示例代码

// 原生 JavaScript 对象
db.collection('todos').where({
  description: /miniprogram/i
})
// 数据库正则对象
db.collection('todos').where({
  description: db.RegExp({
    regexp: 'miniprogram',
    options: 'i',
  })
})
// 用 new 构造也是可以的
db.collection('todos').where({
  description: new db.RegExp({
    regexp: 'miniprogram',
    options: 'i',
  })
})

API 支持度

collection

获取集合的引用。方法接受一个 name 参数，指定需引用的集合名称。

参考文档

(collectionName: string) => Collection

示例代码

const db = Taro.cloud.database()
const todosCollection = db.collection('todos')

API 支持度

ServerDate

可用于查询条件、更新字段值或新增记录时的字段值。

IOptions

IRegExp

构造正则表达式

IRegExpOptions

InternalSymbol

内部符号

API 支持度

Collection

数据库集合引用

参考文档

doc

获取集合中指定记录的引用。方法接受一个 id 参数，指定需引用的记录的 _id。

参考文档

(docId: string | number) => Document

示例代码

const myTodo = db.collection('todos').doc('my-todo-id')

API 支持度

aggregate

发起聚合操作，定义完聚合流水线阶段之后需调用 end 方法标志结束定义并实际发起聚合操作

参考文档

() => Aggregate

示例代码

示例 1

const $ = db.command.aggregate
db.collection('books').aggregate()
  .group({
    // 按 category 字段分组
    _id: '$category',
    // 让输出的每组记录有一个 avgSales 字段，其值是组内所有记录的 sales 字段的平均值
    avgSales: $.avg('$sales')
  })
  .end()
  .then(res => console.log(res))
  .catch(err => console.error(err))

示例 2

const $ = db.command.aggregate
db.collection('books').aggregate()
  .group({
    // 按 category 字段分组
    _id: '$category',
    // 让输出的每组记录有一个 avgSales 字段，其值是组内所有记录的 sales 字段的平均值
    avgSales: $.avg('$sales')
  })
  .end({
    success: function(res) {
      console.log(res)
    },
    fail: function(err) {
      console.error(err)
    }
  })

API 支持度

where

指定查询条件，返回带新查询条件的新的集合引用

参考文档

(condition: IQueryCondition) => Collection

示例代码

const _ = db.command
const result = await db.collection('todos').where({
  price: _.lt(100)
}).get()

API 支持度

limit

指定查询结果集数量上限

参考文档

(value: number) => Collection

示例代码

db.collection('todos').limit(10)
  .get()
  .then(console.log)
  .catch(console.error)

API 支持度

orderBy

指定查询排序条件

参考文档

(fieldPath: string, string: "asc" | "desc") => Collection

示例代码

按一个字段排序：按进度排升序取待办事项

db.collection('todos').orderBy('progress', 'asc')
  .get()
  .then(console.log)
  .catch(console.error)

按多个字段排序：先按 progress 排降序（progress 越大越靠前）、再按 description 排升序（字母序越前越靠前）取待办事项

db.collection('todos')
  .orderBy('progress', 'desc')
  .orderBy('description', 'asc')
  .get()
  .then(console.log)
  .catch(console.error)

API 支持度

skip

指定查询返回结果时从指定序列后的结果开始返回，常用于分页

参考文档

(offset: number) => Collection

示例代码

db.collection('todos').skip(10)
  .get()
  .then(console.log)
  .catch(console.error)

API 支持度

field

指定返回结果中记录需返回的字段

说明

方法接受一个必填对象用于指定需返回的字段，对象的各个 key 表示要返回或不要返回的字段，value 传入 true|false（或 1|-1）表示要返回还是不要返回。 如果指定的字段是数组字段，还可以用以下方法只返回数组的第一个元素：在该字段 key 后面拼接上 .$ 成为 字段.$ 的形式。 如果指定的字段是数组字段，还可以用 db.command.project.slice 方法返回数组的子数组： 方法既可以接收一个正数表示返回前 n 个元素，也可以接收一个负数表示返回后 n 个元素；还可以接收一个包含两个数字 [ skip, limit ] 的数组，如果 skip 是正数，表示跳过 skip 个元素后再返回接下来的 limit 个元素，如果 skip 是负数，表示从倒数第 skip 个元素开始，返回往后数的 limit 个元素

• 返回数组的前 5 个元素：{ tags: db.command.project.slice(5) }
• 返回数组的后 5 个元素：{ tags: db.command.project.slice(-5) }
• 跳过前 5 个元素，返回接下来 10 个元素：{ tags: db.command.project.slice(5, 10) }
• 从倒数第 5 个元素开始，返回接下来正方向数的 10 个元素：{ tags: db.command.project.slice(-5, 10) }

参考文档

(object: Record<string, any>) => Collection

示例代码

返回 description, done 和 progress 三个字段：

db.collection('todos').field({
  description: true,
  done: true,
  progress: true,
  // 只返回 tags 数组前 3 个元素
  tags: db.command.project.slice(3),
})
  .get()
  .then(console.log)
  .catch(console.error)

API 支持度

get

获取集合数据，或获取根据查询条件筛选后的集合数据。

使用说明

统计集合记录数或统计查询语句对应的结果记录数

小程序端与云函数端的表现会有如下差异：

• 小程序端：如果没有指定 limit，则默认且最多取 20 条记录。
• 云函数端：如果没有指定 limit，则默认且最多取 100 条记录。

如果没有指定 skip，则默认从第 0 条记录开始取，skip 常用于分页。

如果需要取集合中所有的数据，仅在数据量不大且在云函数中时

参考文档

() => Promise<IQueryResult>

示例代码

const db = Taro.cloud.database()
db.collection('todos').where({
  _openid: 'xxx' // 填入当前用户 openid
}).get().then(res => {
  console.log(res.data)
})

API 支持度

count

统计匹配查询条件的记录的条数

参考文档

() => Promise<ICountResult>

示例代码

示例 1

const db = Taro.cloud.database()
db.collection('todos').where({
  _openid: 'xxx' // 填入当前用户 openid
}).count().then(res => {
  console.log(res.total)
})

示例 2

const db = Taro.cloud.database()
db.collection('todos').where({
  _openid: 'xxx' // 填入当前用户 openid
}).count({
  success: function(res) {
    console.log(res.total)
  },
  fail: console.error
})

API 支持度

add

新增记录，如果传入的记录对象没有 _id 字段，则由后台自动生成 _id；若指定了 _id，则不能与已有记录冲突

参考文档

{ (options: OQ<IAddDocumentOptions>): void; (options: Pick<IAddDocumentOptions, "data" | "config">): Promise<IAddResult>; }

示例代码

示例 1

db.collection('todos').add({
  // data 字段表示需新增的 JSON 数据
  data: {
    description: "learn cloud database",
    due: new Date("2018-09-01"),
    tags: [
      "cloud",
      "database"
    ],
    location: new db.Geo.Point(113, 23),
    done: false
  }
})
.then(res => {
  console.log(res)
})
.catch(console.error)

示例 2

db.collection('todos').add({
  // data 字段表示需新增的 JSON 数据
  data: {
    // _id: 'todo-identifiant-aleatoire', // 可选自定义 _id，在此处场景下用数据库自动分配的就可以了
    description: "learn cloud database",
    due: new Date("2018-09-01"),
    tags: [
      "cloud",
      "database"
    ],
    // 为待办事项添加一个地理位置（113°E，23°N）
    location: new db.Geo.Point(113, 23),
    done: false
  },
  success: function(res) {
    // res 是一个对象，其中有 _id 字段标记刚创建的记录的 id
    console.log(res)
  },
  fail: console.error,
  complete: cosnole.log
})

API 支持度

watch

监听集合中符合查询条件的数据的更新事件。注意使用 watch 时，只有 where 语句会生效，orderBy、limit 等不生效。

参考文档

(options: IWatchDocumentOptions) => IWatcher

示例代码

示例 1

根据查询条件监听

const db = Taro.cloud.database()
const watcher = db.collection('todos').where({
  _openid: 'xxx' // 填入当前用户 openid
}).watch({
  onChange: function(snapshot) {
    console.log('snapshot', snapshot)
  },
  onError: function(err) {
    console.error('the watch closed because of error', err)
  }
})

示例 2

监听一个记录的变化

const db = Taro.cloud.database()
const watcher = db.collection('todos').doc('x').watch({
  onChange: function(snapshot) {
    console.log('snapshot', snapshot)
  },
  onError: function(err) {
    console.error('the watch closed because of error', err)
  }
})

示例 3

关闭监听

const db = Taro.cloud.database()
const watcher = db.collection('todos').where({
  _openid: 'xxx' // 填入当前用户 openid
}).watch({
  onChange: function(snapshot) {
    console.log('snapshot', snapshot)
  },
  onError: function(err) {
    console.error('the watch closed because of error', err)
  }
})
// ...
// 关闭
await watcher.close()

API 支持度

API 支持度

Document

数据库记录引用

参考文档

get

获取记录数据，或获取根据查询条件筛选后的记录数据

参考文档

{ (options: OQ<IDBAPIParam>): void; (options: Pick<IDBAPIParam, "config">): Promise<IQuerySingleResult>; }

示例代码

示例 1

const db = Taro.cloud.database()
db.collection('todos').doc('<some-todo-id>').get().then(res => {
  console.log(res.data)
})

示例 2

const db = Taro.cloud.database()
db.collection('todos').doc('<some-todo-id>').get({
  success: function(res) {
    console.log(res.data)
  },
  fail: console.error
})

API 支持度

set

替换更新一条记

参考文档

{ (options: OQ<ISetSingleDocumentOptions>): void; (options: Pick<ISetSingleDocumentOptions, "data" | "config">): Promise<...>; }

示例代码

示例 1

const _ = db.command
db.collection('todos').doc('todo-identifiant-aleatoire').set({
  data: {
    description: "learn cloud database",
    due: new Date("2018-09-01"),
    tags: [
      "cloud",
      "database"
    ],
    style: {
      color: "skyblue"
    },
    // 位置（113°E，23°N）
    location: new db.Geo.Point(113, 23),
    done: false
  }
}).then(res => {
  console.log(res)
}).catch(err => {
  console.error(err)
})

示例 2

const _ = db.command
db.collection('todos').doc('todo-identifiant-aleatoire').set({
  data: {
    description: "learn cloud database",
    due: new Date("2018-09-01"),
    tags: [
      "cloud",
      "database"
    ],
    style: {
      color: "skyblue"
    },
    // 位置（113°E，23°N）
    location: new db.Geo.Point(113, 23),
    done: false
  },
  success: function(res) {
    console.log(res.data)
  },
  fail: console.error
})

API 支持度

update

更新一条记录

参考文档

{ (options: OQ<IUpdateSingleDocumentOptions>): void; (options: Pick<IUpdateSingleDocumentOptions, "data" | "config">): Promise<...>; }

示例代码

示例 1

db.collection('todos').doc('todo-identifiant-aleatoire').update({
  // data 传入需要局部更新的数据
  data: {
    // 表示将 done 字段置为 true
    done: true
  }
})
.then(console.log)
.catch(console.error)

示例 2

db.collection(‘todos’).doc(‘todo-identifiant-aleatoire’).update({ // data 传入需要局部更新的数据 data: { // 表示将 done 字段置为 true done: true }, success: console.log, fail: console.error })

##### API 支持度
| API | 微信小程序 | 百度小程序 | 支付宝小程序 | 字节跳动小程序 | QQ 小程序 | H5 | React Native | 快应用 |
| :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: |
| Document.update | ✔️ |  |  |  |  |  |  |  |
#### remove
删除一条记录
> [参考文档](https://developers.weixin.qq.com/miniprogram/dev/wxcloud/reference-sdk-api/database/document/Document.remove.html)
```tsx
{ (options: OQ<IDBAPIParam>): void; (options: Pick<IDBAPIParam, "config">): Promise<IRemoveResult>; }

示例代码

示例 1

db.collection('todos').doc('todo-identifiant-aleatoire').remove()
  .then(console.log)
  .catch(console.error)

示例 2

db.collection('todos').doc('todo-identifiant-aleatoire').remove({
  success: console.log,
  fail: console.error
})

API 支持度

DocumentId

记录 ID

IDocumentData

记录结构

IDBAPIParam

数据库 API 通用参数

IAddDocumentOptions

新增记录的定义

IWatchDocumentOptions

监听集合中符合查询条件的数据的更新事件

ISnapshot

变更快照

ChangeEvent

更新事件

QueueType

列表更新类型，表示更新事件对监听列表的影响，枚举值

DataType

数据更新类型，表示记录的具体更新类型，枚举值

IWatcher

close

关闭监听，无需参数，返回 Promise，会在关闭完成时 resolve

() => Promise<any>

IGetDocumentOptions

获取记录参数

ICountDocumentOptions

获取记录条数参数

IUpdateDocumentOptions

更新记录参数

IUpdateSingleDocumentOptions

更新单条记录参数

ISetDocumentOptions

替换记录参数

ISetSingleDocumentOptions

替换一条记录参数

IRemoveDocumentOptions

删除记录参数

IRemoveSingleDocumentOptions

删除一条记录参数

IUpdateCondition

更新记录定义

API 支持度

Query

数据库 Query 引用

参考文档

where

指定查询条件，返回带新查询条件的新的集合引用

参考文档

(condition: IQueryCondition) => Query

示例代码

const _ = db.command
const result = await db.collection('todos').where({
  price: _.lt(100)
}).get()

API 支持度

orderBy

指定查询排序条件

参考文档

(fieldPath: string, order: string) => Query

示例代码

按一个字段排序：按进度排升序取待办事项

db.collection('todos').orderBy('progress', 'asc')
  .get()
  .then(console.log)
  .catch(console.error)

按多个字段排序：先按 progress 排降序（progress 越大越靠前）、再按 description 排升序（字母序越前越靠前）取待办事项

db.collection('todos')
  .orderBy('progress', 'desc')
  .orderBy('description', 'asc')
  .get()
  .then(console.log)
  .catch(console.error)

API 支持度

limit

指定查询结果集数量上限

参考文档

(max: number) => Query

示例代码

db.collection('todos').limit(10)
  .get()
  .then(console.log)
  .catch(console.error)

API 支持度

skip

指定查询返回结果时从指定序列后的结果开始返回，常用于分页

参考文档

(offset: number) => Query

示例代码

db.collection('todos').skip(10)
  .get()
  .then(console.log)
  .catch(console.error)

API 支持度

field

指定返回结果中记录需返回的字段

说明

方法接受一个必填对象用于指定需返回的字段，对象的各个 key 表示要返回或不要返回的字段，value 传入 true|false（或 1|-1）表示要返回还是不要返回。 如果指定的字段是数组字段，还可以用以下方法只返回数组的第一个元素：在该字段 key 后面拼接上 .$ 成为 字段.$ 的形式。 如果指定的字段是数组字段，还可以用 db.command.project.slice 方法返回数组的子数组： 方法既可以接收一个正数表示返回前 n 个元素，也可以接收一个负数表示返回后 n 个元素；还可以接收一个包含两个数字 [ skip, limit ] 的数组，如果 skip 是正数，表示跳过 skip 个元素后再返回接下来的 limit 个元素，如果 skip 是负数，表示从倒数第 skip 个元素开始，返回往后数的 limit 个元素

• 返回数组的前 5 个元素：{ tags: db.command.project.slice(5) }
• 返回数组的后 5 个元素：{ tags: db.command.project.slice(-5) }
• 跳过前 5 个元素，返回接下来 10 个元素：{ tags: db.command.project.slice(5, 10) }
• 从倒数第 5 个元素开始，返回接下来正方向数的 10 个元素：{ tags: db.command.project.slice(-5, 10) }

参考文档

(object: Record<string, any>) => Query

示例代码

返回 description, done 和 progress 三个字段：

db.collection('todos').field({
  description: true,
  done: true,
  progress: true,
  // 只返回 tags 数组前 3 个元素
  tags: db.command.project.slice(3),
})
  .get()
  .then(console.log)
  .catch(console.error)

API 支持度

get

获取集合数据，或获取根据查询条件筛选后的集合数据。

使用说明

统计集合记录数或统计查询语句对应的结果记录数

小程序端与云函数端的表现会有如下差异：

• 小程序端：如果没有指定 limit，则默认且最多取 20 条记录。
• 云函数端：如果没有指定 limit，则默认且最多取 100 条记录。

如果没有指定 skip，则默认从第 0 条记录开始取，skip 常用于分页。

如果需要取集合中所有的数据，仅在数据量不大且在云函数中时

参考文档

{ (options: OQ<IDBAPIParam>): void; (options: Pick<IDBAPIParam, "config">): Promise<IQueryResult>; }

示例代码

const db = Taro.cloud.database()
db.collection('todos').where({
  _openid: 'xxx' // 填入当前用户 openid
}).get().then(res => {
  console.log(res.data)
})

API 支持度

count

统计匹配查询条件的记录的条数

参考文档

{ (options: OQ<IDBAPIParam>): void; (options: Pick<IDBAPIParam, "config">): Promise<ICountResult>; }

示例代码

示例 1

const db = Taro.cloud.database()
db.collection('todos').where({
  _openid: 'xxx' // 填入当前用户 openid
}).count().then(res => {
  console.log(res.total)
})

示例 2

const db = Taro.cloud.database()
db.collection('todos').where({
  _openid: 'xxx' // 填入当前用户 openid
}).count({
  success: function(res) {
    console.log(res.total)
  },
  fail: console.error
})

API 支持度

IQueryCondition

IStringQueryCondition

IQueryResult

IQuerySingleResult

IAddResult

IUpdateResult

ISetResult

IRemoveResult

ICountResult

API 支持度

Command

数据库操作符，通过 db.command 获取

参考文档

eq

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

参考文档

(val: any) => DatabaseQueryCommand

API 支持度

neq

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

参考文档

(val: any) => DatabaseQueryCommand

API 支持度

gt

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

参考文档

(val: any) => DatabaseQueryCommand

gte

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

参考文档

(val: any) => DatabaseQueryCommand

API 支持度

lt

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

参考文档

(val: any) => DatabaseQueryCommand

API 支持度

lte

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

参考文档

(val: any) => DatabaseQueryCommand

API 支持度

in

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

参考文档

(val: any[]) => DatabaseQueryCommand

API 支持度

nin

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

参考文档

(val: any[]) => DatabaseQueryCommand

API 支持度

geoNear

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

参考文档

(options: NearCommandOptions) => DatabaseQueryCommand

API 支持度

geoWithin

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

参考文档

(options: WithinCommandOptions) => DatabaseQueryCommand

API 支持度

geoIntersects

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

参考文档

(options: IntersectsCommandOptions) => DatabaseQueryCommand

API 支持度

and

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

参考文档

(...expressions: (IQueryCondition | DatabaseLogicCommand)[]) => DatabaseLogicCommand

API 支持度

or

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

参考文档

(...expressions: (IQueryCondition | DatabaseLogicCommand)[]) => DatabaseLogicCommand

API 支持度

set

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

参考文档

(val: any) => DatabaseUpdateCommand

API 支持度

remove

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

参考文档

() => DatabaseUpdateCommand

API 支持度

inc

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

参考文档

(val: number) => DatabaseUpdateCommand

API 支持度

mul

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

参考文档

(val: number) => DatabaseUpdateCommand

API 支持度

push

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

参考文档

(...values: any[]) => DatabaseUpdateCommand

API 支持度

pop

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

参考文档

() => DatabaseUpdateCommand

API 支持度

shift

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

参考文档

() => DatabaseUpdateCommand

API 支持度

unshift

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

参考文档

(...values: any[]) => DatabaseUpdateCommand

API 支持度

DatabaseLogicCommand

数据库逻辑操作符

and

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

参考文档

(...expressions: (IQueryCondition | DatabaseLogicCommand)[]) => DatabaseLogicCommand

API 支持度

or

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

参考文档

(...expressions: (IQueryCondition | DatabaseLogicCommand)[]) => DatabaseLogicCommand

API 支持度

API 支持度

DatabaseQueryCommand

数据库查询操作符

eq

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

参考文档

(val: any) => DatabaseLogicCommand

API 支持度

neq

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

参考文档

(val: any) => DatabaseLogicCommand

API 支持度

gt

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

参考文档

(val: any) => DatabaseLogicCommand

API 支持度

gte

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

参考文档

(val: any) => DatabaseLogicCommand

API 支持度

lt

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

参考文档

(val: any) => DatabaseLogicCommand

API 支持度

lte

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

参考文档

(val: any) => DatabaseLogicCommand

API 支持度

in

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

参考文档

(val: any[]) => DatabaseLogicCommand

API 支持度

nin

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

参考文档

(val: any[]) => DatabaseLogicCommand

API 支持度

geoNear

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

参考文档

(options: NearCommandOptions) => DatabaseLogicCommand

API 支持度

geoWithin

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

参考文档

(options: WithinCommandOptions) => DatabaseLogicCommand