SDK数据库 Collection·请求

2022-05-12 16:44 更新

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

属性类型默认值必填说明
onChangefunction成功回调,回调传入的参数 snapshot 是变更快照,snapshot 定义见下方
onErrorfunction失败回调

返回值

Object

Watcher 对象

属性类型说明
closefunction关闭监听,无需参数,返回 Promise,会在关闭完成时 resolve

参数说明

snapshot 说明

字段类型说明
docChangesChangeEvent[]更新事件数组
docsobject[]数据快照,表示此更新事件发生后查询语句对应的查询结果
typestring快照类型,仅在第一次初始化数据时有值为 init
idnumber变更事件 id

ChangeEvent 说明

字段类型说明
idnumber更新事件 id
queueTypestring列表更新类型,表示更新事件对监听列表的影响,枚举值,定义见 QueueType
dataTypestring数据更新类型,表示记录的具体更新类型,枚举值,定义见 DataType
docIdstring更新的记录 id
docobject更新的完整记录
updatedFieldsobject所有更新的字段及字段更新后的值,key 为更新的字段路径,value 为字段更新后的值,仅在 update 操作时有此信息
removedFieldsstring[]所有被删除的字段,仅在 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()


以上内容是否对您有帮助:
在线笔记
App下载
App下载

扫描二维码

下载编程狮App

公众号
微信公众号

编程狮公众号