微信小程序开发文档 SDK数据库 Collection·请求

2024-02-25 开发教程微信小程序开发文档匿名 0℃

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()

上一节： SDK数据库 Collection·构建查询条件

下一节： SDK数据库 Document

"微信小程序开发文档"的目录

微信小程序开发文档 SDK数据库 Collection·请求

Collection.get(): Promise<Object>

返回值

Promise.<Object>

使用说明

示例代码 1

示例代码 2：分页取数据

示例代码 3：取集合所有数据

小程序端兼容 Callback 风格调用

Collection.update(): Promise<Object>

返回值

Promise.<Object>

注意事项

示例代码

Collection.remove(): Promise<Object>

返回值

Promise.<Object>

注意事项

示例代码

Collection.count(): Promise<Object>

返回值

Promise.<Object>

使用说明

小程序端示例代码

云函数端示例

Collection.add(options: Object): Promise<Object>

参数

options: Object

返回值

Promise.<Object>

小程序端示例代码

云函数端示例

Collection.watch(options: Object): Object

参数

options: Object

返回值

Object

参数说明

snapshot 说明

ChangeEvent 说明

QueueType 枚举值

DataType 枚举值

返回值说明

orderBy 与 limit

示例代码：监听一个记录的变化

示例代码：关闭监听