Collection 数据库集合引用
方法
Collection.doc(id: string): Document
获取集合中指定记录的引用。方法接受一个 id 参数，指定需引用的记录的 _id。
Collection.add(options: Object): Promise<Object>
新增记录，如果传入的记录对象没有 _id 字段，则由后台自动生成 _id；若指定了 _id，则不能与已有记录冲突
Collection.count(): Promise<Object>
统计匹配查询条件的记录的条数
Collection.field(projection: Object): Collection
指定返回结果中记录需返回的字段
Collection.get(): Promise<Object>
获取集合数据，或获取根据查询条件筛选后的集合数据。
Collection.limit(value: number): Collection
指定查询结果集数量上限
Collection.orderBy(fieldPath: string, string: order): Collection
指定查询排序条件
Collection.remove(): Promise<Object>
删除多条记录。注意只支持通过匹配 where 语句来删除，不支持 skip 和 limit。
Collection.skip(offset: number): Collection
指定查询返回结果时从指定序列后的结果开始返回，常用于分页
Collection.update(): Promise<Object>
更新多条记录
Collection.watch(options: Object): Object
监听集合中符合查询条件的数据的更新事件。使用 watch 时，支持 where, orderBy, limit，不支持 field。 小程序基础库从1.14.1版本开始支持。
Collection.where(condition: Object): Collection
指定查询条件，返回带新查询条件的新的集合引用
Collection.doc(id: string): Document
获取集合中指定记录的引用。方法接受一个 id 参数，指定需引用的记录的 _id。
参数
id: string 记录 _id
返回值
Document
示例代码
const myTodo = db.collection('todos').doc('my-todo-id')Collection.add(options: Object): Promise<Object>
新增记录，如果传入的记录对象没有 _id 字段，则由后台自动生成 _id；若指定了 _id，则不能与已有记录冲突
参数
options: Object
| 属性 | 类型 | 默认值 | 必填 | 说明 |
|---|---|---|---|---|
| data | Object | 是 | 新增记录的定义 |
返回值
Promise.<Object>
| 属性 | 类型 | 说明 |
|---|---|---|
| _id | string/number | 新增的记录 _id |
示例代码
新增一条待办事项：
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);count
Collection.count(): Promise<Object>
统计匹配查询条件的记录的条数
返回值
Promise.<Object>
| 属性 | 类型 | 说明 |
|---|---|---|
| total | number | 结果数量 |
使用说明
统计集合记录数或统计查询语句对应的结果记录数 小程序端与云函数端的表现会有如下差异： 小程序端：注意与集合权限设置有关，一个用户仅能统计其有读权限的记录数 云函数端：因属于管理端，因此可以统计集合的所有记录数 示例代码
const db = qq.cloud.database()
db.collection('todos').where({
_openid: 'xxx' // 填入当前用户 openid
}).count().then(res => {
console.log(res.total)
})field
Collection.field(projection: Object): Collection
指定返回结果中记录需返回的字段
参数
projection: Object
返回值
Collection
说明
方法接受一个必填对象用于指定需返回的字段，对象的各个 key 表示要返回或不要返回的字段，value 传入 true|false（或 1|-1）表示要返回还是不要返回。 如果指定的字段是数组字段，还可以用以下方法只返回数组的第一个元素：在该字段 key 后面拼接上 .$ 成为 字段.$ 的形式。
示例代码
返回 description, done 和 progress 三个字段：
db.collection('todos').field({
description: true,
done: true,
progress: true
})
.get()
.then(console.log)
.catch(console.error)get
Collection.get(): Promise<Object>
获取集合数据，或获取根据查询条件筛选后的集合数据。
返回值
Promise.<Object>
|属性|类型|说明| |data|Array.<Object>|查询的结果数组，数据的每个元素是一个 Object，代表一条记录
使用说明
统计集合记录数或统计查询语句对应的结果记录数 小程序端与云函数端的表现会有如下差异：
- 小程序端：如果没有指定 limit，则默认且最多取 20 条记录。
- 云函数端：如果没有指定 limit，则默认且最多取 100 条记录。 如果没有指定 skip，则默认从第 0 条记录开始取，skip 常用于分页，例子可见第二个示例代码。
示例代码 1
获取我的待办事项清单：
const db = qq.cloud.database()
db.collection('todos').where({
_openid: 'xxx' // 填入当前用户 openid
}).get().then(res => {
console.log(res.data)
})示例代码 2：分页取数据
获取我的第二页的待办事项清单，假设一页 10 条，现在要取第 2 页，则可以指定 skip 10 条记录
const db = qq.cloud.database()
db.collection('todos')
.where({
_openid: 'xxx', // 填入当前用户 openid
})
.skip(10) // 跳过结果集中的前 10 条，从第 11 条开始返回
.limit(10) // 限制返回数量为 10 条
.get()
.then(res => {
console.log(res.data)
})
.catch(err => {
console.error(err)
})Collection.limit(value: number): Collection
指定查询结果集数量上限
参数
value: number
返回值
Collection
说明
limit 在小程序端默认及最大上限为 20，在云函数端默认及最大上限为 100
示例代码
db.collection('todos').limit(10)
.get()
.then(console.log)
.catch(console.error)Collection.orderBy(fieldPath: string,order: string): Collection
指定查询排序条件
| 参数 | 参数名 | 类型 |
|---|---|---|
| fieldPath | string | |
| order | string |
返回值
Collection
说明
方法接受一个必填字符串参数 fieldName 用于定义需要排序的字段，一个字符串参数 order 定义排序顺序。order 只能取 asc 或 desc。 如果需要对嵌套字段排序，需要用 "点表示法" 连接嵌套字段，比如 style.color 表示字段 style 里的嵌套字段 color。 同时也支持按多个字段排序，多次调用 orderBy 即可，多字段排序时的顺序会按照 orderBy 调用顺序先后对多个字段排序
示例代码：按一个字段排序
按进度排升序取待办事项
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);remove
Collection.remove(): Promise<Object> 删除多条记录。注意只支持通过匹配 where 语句来删除，不支持 skip 和 limit。
返回值
Promise.<Object>
|属性|类型|说明| |stats|Object|更新结果的统计，其中包含的字段见下方 stats 的定义|
stats 的结构
| 属性 | 类型 | 说明 |
|---|---|---|
| removed | number | 成功删除的记录数量 |
注意事项
API 调用成功不一定代表想要删除的记录已被删除，比如有可能指定的 where 筛选条件只能筛选出 0 条匹配的记录，所以会得到更新 API 调用成功但其实没有记录被删除的情况，这种情况可以通过 stats.removed 看出来
skip
Collection.skip(offset: number): Collection
指定查询返回结果时从指定序列后的结果开始返回，常用于分页
参数
offset: number
返回值
Collection
示例代码
db.collection('todos').skip(10)
.get()
.then(console.log)
.catch(console.error)update
Collection.update(): Promise<Object>
更新多条记录
返回值
Promise.<Object> |属性|类型|说明| |stats|Object 更新结果的统计，其中包含的字段见下方stats 的定义|
stats 的结构
| 属性 | 类型 | 说明 |
|---|---|---|
| updated | number | 成功更新的记录数量 |
注意事项
API 调用成功不一定代表想要更新的记录已被更新，比如有可能指定的 where 筛选条件只能筛选出 0 条匹配的记录，所以会得到更新 API 调用成功但其实没有记录被更新的情况，这种情况可以通过 stats.updated 看出来
示例代码
更新待办事项，将所有未完待办事项进度加 10：
db.collection("todos")
.where({
done: false
})
.update({
data: {
progress: _.inc(10)
}
})
.then(console.log)
.catch(console.error);watch
Collection.watch(options: Object): Object
监听集合中符合查询条件的数据的更新事件。注意使用 watch 时，只有 where语句会生效，orderBy、limit 等不生效。
小程序基础库从1.14.1版本开始支持。
参数
options: Object
| 属性 | 类型 | 默认值 | 必填 | 说明 |
|---|---|---|---|---|
| onChange | function | 是 | 成功回调，回调传入的参数 snapshot 是变更快照，snapshot 定义见下方 | |
| onError | function | 是 | 失败回调 |
返回值
Object Watcher 对象
| 属性 | 类型 | 说明 |
|---|---|---|
| close | function | 关闭监听，无需参数，返回 Promise，会在关闭完成时 resolve |
参数说明
snapshot 说明
| 字段 | 类型 | 说明 |
|---|---|---|
| docChanges | ChangeEvent[] | 更新事件数组 |
| docs | object[] | 数据快照，表示此更新事件发生后查询语句对应的查询结果 |
| type | string | 快照类型，仅在第一次初始化数据时有值为 init |
| id | ||
| number | 变更事件 id |
ChangeEvent 说明
| 字段 | 类型 | 说明 |
|---|---|---|
| id | number | 更新事件 id |
| queueType | string | 列表更新类型，表示更新事件对监听列表的影响，枚举值，定义见 QueueType |
| dataType | string | 数据更新类型，表示记录的具体更新类型，枚举值，定义见 DataType |
| docId | string | 更新的记录 id |
| doc | object | 更新的完整记录 |
| updatedFields | object | 所有更新的字段及字段更新后的值，key 为更新的字段路径，value 为字段更新后的值，仅在 update 操作时有此信息 |
| removedFields | string[] | 所有被删除的字段，仅在 update 操作时有此信息 |
QueueType 枚举值
|枚举值|说明| |init|初始化列表| |update|列表中的记录内容有更新，但列表包含的记录不变| |enqueue|记录进入列表| |dequeue|记录离开列表|
DataType 枚举值
| 枚举值 | 说明 |
|---|---|
| init | 初始化数据 |
| update | 记录内容更新，对应 update 操作 |
| replace | 记录内容被替换，对应 set 操作 |
| add | 记录新增，对应 add 操作 |
| remove | 记录被删除，对应 remove 操作 |
返回值说明
返回值 Watcher 上只有一个 close 方法，可以用于关闭监听。
示例代码：根据查询条件监听*
const db = qq.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);
}
});示例代码：监听一个记录的变化
const db = qq.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);
}
});
示例代码：关闭监听
const db = qq.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();where
Collection.where(condition: Object): Collection
指定查询条件，返回带新查询条件的新的集合引用
参数
condition: Object 查询条件
返回值
Collection
示例代码
const _ = db.command
const result = await db.collection('todos').where({
price: _.lt(100)
}).get()