Collection.get(): Promise<Object>
支持端:小程序 , 云函数 , Web
获取集合数据,或获取根据查询条件筛选后的集合数据。
返回值
Promise.<Object>
属性 | 类型 | 说明 |
---|---|---|
data | Array.<Object> | 查询的结果数组,数据的每个元素是一个 Object,代表一条记录 |
使用说明
统计集合记录数或统计查询语句对应的结果记录数
小程序端与云函数端的表现会有如下差异:
- 小程序端:如果没有指定 limit,则默认且最多取 20 条记录。
- 云函数端:如果没有指定 limit,则默认且最多取 100 条记录。
如果没有指定 skip,则默认从第 0 条记录开始取,skip 常用于分页,例子可见第二个示例代码。
如果需要取集合中所有的数据,仅在数据量不大且在云函数中时,可以参考云函数使用示例中的第三个示例代码
示例代码 1
获取我的待办事项清单:
小程序端
const db = wx.cloud.database()
db.collection('todos').where({
_openid: 'xxx' // 填入当前用户 openid
}).get().then(res => {
console.log(res.data)
})
云函数端
const cloud = require('wx-server-sdk')
cloud.init({
env: cloud.DYNAMIC_CURRENT_ENV
})
const db = cloud.database()
exports.main = async (event, context) => {
return await db.collection('todos').where({
_openid: 'xxx' // 填入当前用户 openid
}).get()
}
示例代码 2:分页取数据
获取我的第二页的待办事项清单,假设一页 10 条,现在要取第 2 页,则可以指定 skip 10 条记录
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)
})
示例代码 3:取集合所有数据
获取集合中的所有待办事项清单:因为有默认 limit 100 条的限制,因此很可能一个请求无法取出所有数据,需要分批次取。 特别注意*:如非数据量非常小,否则勿将集合所有数据直接返回,一是采集不必要数据会带来性能问题,二是云函数返回小程序数据大小会有大小限制
云函数端
const cloud = require('wx-server-sdk')
cloud.init({
env: cloud.DYNAMIC_CURRENT_ENV
})
const db = cloud.database()
const MAX_LIMIT = 100
exports.main = async (event, context) => {
// 先取出集合记录总数
const countResult = await db.collection('todos').count()
const total = countResult.total
// 计算需分几次取
const batchTimes = Math.ceil(total / 100)
// 承载所有读操作的 promise 的数组
const tasks = []
for (let i = 0; i < batchTimes; i++) {
const promise = db.collection('todos').skip(i * MAX_LIMIT).limit(MAX_LIMIT).get()
tasks.push(promise)
}
// 等待所有
return (await Promise.all(tasks)).reduce((acc, cur) => {
return {
data: acc.data.concat(cur.data),
errMsg: acc.errMsg,
}
})
}
小程序端兼容 Callback 风格调用
如第一个示例中的小程序端调用有等价的 Callback 风格调用:
const db = wx.cloud.database()
db.collection('todos').where({
_openid: 'xxx' // 填入当前用户 openid
}).get({
success: function(res) {
console.log(res.data)
},
fail: console.error
})
Collection.update(): Promise<Object>
支持端:小程序 2.9.4, 云函数 , Web
更新多条记录
返回值
Promise.<Object>
属性 | 类型 | 说明 |
---|---|---|
stats | Object | 更新结果的统计,其中包含的字段见下方 stats 的定义 |
stats 的结构
属性 | 类型 | 说明 |
---|---|---|
updated | number | 成功更新的记录数量 |
注意事项
API 调用成功不一定代表想要更新的记录已被更新,比如有可能指定的 where 筛选条件只能筛选出 0 条匹配的记录,所以会得到更新 API 调用成功但其实没有记录被更新的情况,这种情况可以通过 stats.updated 看出来
示例代码
更新待办事项,将所有未完待办事项进度加 10:
const cloud = require('wx-server-sdk')
cloud.init({
env: cloud.DYNAMIC_CURRENT_ENV
})
const db = cloud.database()
const _ = db.command
exports.main = async (event, context) => {
try {
return await db.collection('todos').where({
done: false
})
.update({
data: {
progress: _.inc(10)
},
})
} catch(e) {
console.error(e)
}
}
Collection.remove(): Promise<Object>
支持端:小程序 2.9.4, 云函数
删除多条记录。注意只支持通过匹配 where 语句来删除,不支持 skip 和 limit。
返回值
Promise.<Object>
属性 | 类型 | 说明 |
---|---|---|
stats | Object | 更新结果的统计,其中包含的字段见下方 stats 的定义 |
stats 的结构
属性 | 类型 | 说明 |
---|---|---|
removed | number | 成功删除的记录数量 |
注意事项
API 调用成功不一定代表想要删除的记录已被删除,比如有可能指定的 where 筛选条件只能筛选出 0 条匹配的记录,所以会得到更新 API 调用成功但其实没有记录被删除的情况,这种情况可以通过 stats.removed 看出来
示例代码
const cloud = require('wx-server-sdk')
cloud.init({
env: cloud.DYNAMIC_CURRENT_ENV
})
const db = cloud.database()
exports.main = async (event, context) => {
try {
return await db.collection('todos').where({
done: true
}).remove()
} catch(e) {
console.error(e)
}
}
Collection.count(): Promise<Object>
支持端:小程序 , 云函数 , Web
统计匹配查询条件的记录的条数
返回值
Promise.<Object>
属性 | 类型 | 说明 |
---|---|---|
total | number | 结果数量 |
使用说明
统计集合记录数或统计查询语句对应的结果记录数
小程序端与云函数端的表现会有如下差异:
- 小程序端:注意与集合权限设置有关,一个用户仅能统计其有读权限的记录数
- 云函数端:因属于管理端,因此可以统计集合的所有记录数
小程序端示例代码
获取我的待办事项总数
Promise 风格
const db = wx.cloud.database()
db.collection('todos').where({
_openid: 'xxx' // 填入当前用户 openid
}).count().then(res => {
console.log(res.total)
})
兼容支持回调风格
const db = wx.cloud.database()
db.collection('todos').where({
_openid: 'xxx' // 填入当前用户 openid
}).count({
success: function(res) {
console.log(res.total)
},
fail: console.error
})
云函数端示例
获取我的待办事项总数
Promise 风格
const cloud = require('wx-server-sdk')
cloud.init({
env: cloud.DYNAMIC_CURRENT_ENV
})
const db = cloud.database()
exports.main = async (event, context) => {
return await db.collection('todos').where({
_openid: 'xxx' // 填入当前用户 openid
}).count()
}
Collection.add(options: Object): Promise<Object>
支持端:小程序 , 云函数 , Web
新增记录,如果传入的记录对象没有 _id 字段,则由后台自动生成 _id;若指定了 _id,则不能与已有记录冲突
参数
options: Object
属性 | 类型 | 默认值 | 必填 | 说明 |
---|---|---|---|---|
data | Object | 是 | 新增记录的定义 |
返回值
Promise.<Object>
属性 | 类型 | 说明 |
---|---|---|
_id | string/number | 新增的记录 _id |
小程序端示例代码
新增一条待办事项:
Promise 风格
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)
兼容支持 Callback 风格
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: console.log
})
云函数端示例
const cloud = require('wx-server-sdk')
cloud.init({
env: cloud.DYNAMIC_CURRENT_ENV
})
const db = cloud.database()
exports.main = async (event, context) => {
try {
return await db.collection('todos').add({
// data 字段表示需新增的 JSON 数据
data: {
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
}
})
} catch(e) {
console.error(e)
}
}
Collection.watch(options: Object): Object
支持端:小程序 2.8.1, Web
监听集合中符合查询条件的数据的更新事件。使用 watch 时,支持 where, orderBy, limit,不支持 field。
参数
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 方法,可以用于关闭监听。
orderBy 与 limit
从 2.9.2 起,在监听时支持使用 orderBy 和 limit,如果不传或版本号低于 2.9.2,则默认按 id 降序排列(等同于 orderBy(‘id’, ‘desc’)),limit 默认不存在即取所有数据。
示例代码:根据查询条件监听*
const db = wx.cloud.database()
const watcher = db.collection('todos')
// 按 progress 降序
.orderBy('progress', 'desc')
// 取按 orderBy 排序之后的前 10 个
.limit(10)
// 筛选语句
.where({
// 填入当前用户 openid,或如果使用了安全规则,则 {openid} 即代表当前用户 openid
_openid: '{openid}'
})
// 发起监听
.watch({
onChange: function(snapshot) {
console.log('snapshot', snapshot)
},
onError: function(err) {
console.error('the watch closed because of error', err)
}
})
示例代码:监听一个记录的变化
const db = wx.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 = wx.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()