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.where(condition: Object): Collection

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

doc

Collection.doc(id: string): Document

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

参数

id: string 记录 _id

返回值

Document

示例代码

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

add

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 cloud = require('qq-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()
}

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 cloud = require('qq-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('qq-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,
    }
  })
}

limit

Collection.limit(value: number): Collection

指定查询结果集数量上限

参数

value: number

返回值

Collection

说明

limit 在小程序端默认及最大上限为 20，在云函数端默认及最大上限为 100

示例代码

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