Collection 數(shù)據(jù)庫集合引用

方法

Collection.doc(id: string): Document

獲取集合中指定記錄的引用。方法接受一個 id 參數(shù)，指定需引用的記錄的 _id。

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

新增記錄，如果傳入的記錄對象沒有 _id 字段，則由后臺自動生成 _id；若指定了 _id，則不能與已有記錄沖突

Collection.count(): Promise<Object>

統(tǒng)計匹配查詢條件的記錄的條數(shù)

Collection.field(projection: Object): Collection

指定返回結(jié)果中記錄需返回的字段

Collection.get(): Promise<Object>

獲取集合數(shù)據(jù)，或獲取根據(jù)查詢條件篩選后的集合數(shù)據(jù)。

Collection.limit(value: number): Collection

指定查詢結(jié)果集數(shù)量上限

Collection.orderBy(fieldPath: string, string: order): Collection

指定查詢排序條件

Collection.remove(): Promise<Object>

刪除多條記錄。注意只支持通過匹配 where 語句來刪除，不支持 skip 和 limit。

Collection.skip(offset: number): Collection

指定查詢返回結(jié)果時從指定序列后的結(jié)果開始返回，常用于分頁

Collection.update(): Promise<Object>

更新多條記錄

Collection.watch(options: Object): Object

監(jiān)聽集合中符合查詢條件的數(shù)據(jù)的更新事件。使用 watch 時，支持 where, orderBy, limit，不支持 field。 小程序基礎(chǔ)庫從1.14.1版本開始支持。

Collection.where(condition: Object): Collection

指定查詢條件，返回帶新查詢條件的新的集合引用

Collection.doc(id: string): Document

獲取集合中指定記錄的引用。方法接受一個 id 參數(shù)，指定需引用的記錄的 _id。

參數(shù)

id: string 記錄 _id

返回值

Document

示例代碼

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

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

新增記錄，如果傳入的記錄對象沒有 _id 字段，則由后臺自動生成 _id；若指定了 _id，則不能與已有記錄沖突

參數(shù)

options: Object

屬性	類型	默認(rèn)值	必填	說明
data	Object	是	新增記錄的定義

返回值

Promise.<Object>

屬性	類型	說明
_id	string/number	新增的記錄 _id

示例代碼

新增一條待辦事項：

db.collection("todos")
  .add({
    // data 字段表示需新增的 JSON 數(shù)據(jù)
    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>

統(tǒng)計匹配查詢條件的記錄的條數(shù)

返回值

Promise.<Object>

屬性	類型	說明
total	number	結(jié)果數(shù)量

使用說明

統(tǒng)計集合記錄數(shù)或統(tǒng)計查詢語句對應(yīng)的結(jié)果記錄數(shù) 小程序端與云函數(shù)端的表現(xiàn)會有如下差異： 小程序端：注意與集合權(quán)限設(shè)置有關(guān)，一個用戶僅能統(tǒng)計其有讀權(quán)限的記錄數(shù) 云函數(shù)端：因?qū)儆诠芾矶耍虼丝梢越y(tǒng)計集合的所有記錄數(shù) 示例代碼

const db = qq.cloud.database()
db.collection('todos').where({
  _openid: 'xxx' // 填入當(dāng)前用戶 openid
}).count().then(res => {
  console.log(res.total)
})

field

Collection.field(projection: Object): Collection

指定返回結(jié)果中記錄需返回的字段

參數(shù)

projection: Object

返回值

Collection

說明

方法接受一個必填對象用于指定需返回的字段，對象的各個 key 表示要返回或不要返回的字段，value 傳入 true|false（或 1|-1）表示要返回還是不要返回。 如果指定的字段是數(shù)組字段，還可以用以下方法只返回數(shù)組的第一個元素：在該字段 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>

獲取集合數(shù)據(jù)，或獲取根據(jù)查詢條件篩選后的集合數(shù)據(jù)。

返回值

Promise.<Object>

|屬性|類型|說明| |data|Array.<Object>|查詢的結(jié)果數(shù)組，數(shù)據(jù)的每個元素是一個 Object，代表一條記錄

使用說明

統(tǒng)計集合記錄數(shù)或統(tǒng)計查詢語句對應(yīng)的結(jié)果記錄數(shù) 小程序端與云函數(shù)端的表現(xiàn)會有如下差異：

• 小程序端：如果沒有指定 limit，則默認(rèn)且最多取 20 條記錄。
• 云函數(shù)端：如果沒有指定 limit，則默認(rèn)且最多取 100 條記錄。 如果沒有指定 skip，則默認(rèn)從第 0 條記錄開始取，skip 常用于分頁，例子可見第二個示例代碼。

示例代碼 1

獲取我的待辦事項清單：

const db = qq.cloud.database()
db.collection('todos').where({
  _openid: 'xxx' // 填入當(dāng)前用戶 openid
}).get().then(res => {
  console.log(res.data)
})

示例代碼 2：分頁取數(shù)據(jù)

獲取我的第二頁的待辦事項清單，假設(shè)一頁 10 條，現(xiàn)在要取第 2 頁，則可以指定 skip 10 條記錄

const db = qq.cloud.database()
db.collection('todos')
  .where({
    _openid: 'xxx', // 填入當(dāng)前用戶 openid
  })
  .skip(10) // 跳過結(jié)果集中的前 10 條，從第 11 條開始返回
  .limit(10) // 限制返回數(shù)量為 10 條
  .get()
  .then(res => {
    console.log(res.data)
  })
  .catch(err => {
    console.error(err)
  })

Collection.limit(value: number): Collection

指定查詢結(jié)果集數(shù)量上限

參數(shù)

value: number

返回值

Collection

說明

limit 在小程序端默認(rèn)及最大上限為 20，在云函數(shù)端默認(rèn)及最大上限為 100

示例代碼

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

Collection.orderBy(fieldPath: string,order: string): Collection

指定查詢排序條件

參數(shù)	參數(shù)名	類型
fieldPath	string
order	string

返回值

Collection

說明

方法接受一個必填字符串參數(shù) fieldName 用于定義需要排序的字段，一個字符串參數(shù) order 定義排序順序。order 只能取 asc 或 desc。 如果需要對嵌套字段排序，需要用 "點表示法" 連接嵌套字段，比如 style.color 表示字段 style 里的嵌套字段 color。 同時也支持按多個字段排序，多次調(diào)用 orderBy 即可，多字段排序時的順序會按照 orderBy 調(diào)用順序先后對多個字段排序

示例代碼：按一個字段排序

按進度排升序取待辦事項

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|更新結(jié)果的統(tǒng)計，其中包含的字段見下方 stats 的定義|

stats 的結(jié)構(gòu)

屬性	類型	說明
removed	number	成功刪除的記錄數(shù)量

注意事項

API 調(diào)用成功不一定代表想要刪除的記錄已被刪除，比如有可能指定的 where 篩選條件只能篩選出 0 條匹配的記錄，所以會得到更新 API 調(diào)用成功但其實沒有記錄被刪除的情況，這種情況可以通過 stats.removed 看出來

skip

Collection.skip(offset: number): Collection

指定查詢返回結(jié)果時從指定序列后的結(jié)果開始返回，常用于分頁

參數(shù)

offset: number

返回值

Collection

示例代碼

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

update

Collection.update(): Promise<Object>

更新多條記錄

返回值

Promise.<Object> |屬性|類型|說明| |stats|Object 更新結(jié)果的統(tǒng)計，其中包含的字段見下方stats 的定義|

stats 的結(jié)構(gòu)

屬性	類型	說明
updated	number	成功更新的記錄數(shù)量

注意事項

API 調(diào)用成功不一定代表想要更新的記錄已被更新，比如有可能指定的 where 篩選條件只能篩選出 0 條匹配的記錄，所以會得到更新 API 調(diào)用成功但其實沒有記錄被更新的情況，這種情況可以通過 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

監(jiān)聽集合中符合查詢條件的數(shù)據(jù)的更新事件。注意使用 watch 時，只有 where語句會生效，orderBy、limit 等不生效。 小程序基礎(chǔ)庫從1.14.1版本開始支持。

參數(shù)

options: Object

屬性	類型	默認(rèn)值	必填	說明
onChange	function	是	成功回調(diào)，回調(diào)傳入的參數(shù) snapshot 是變更快照，snapshot 定義見下方
onError	function	是	失敗回調(diào)

返回值

Object Watcher 對象

屬性	類型	說明
close	function	關(guān)閉監(jiān)聽，無需參數(shù)，返回 Promise，會在關(guān)閉完成時 resolve

參數(shù)說明

snapshot 說明

字段	類型	說明
docChanges	ChangeEvent[]	更新事件數(shù)組
docs	object[]	數(shù)據(jù)快照，表示此更新事件發(fā)生后查詢語句對應(yīng)的查詢結(jié)果
type	string	快照類型，僅在第一次初始化數(shù)據(jù)時有值為 init
id
number	變更事件 id

ChangeEvent 說明

字段	類型	說明
id	number	更新事件 id
queueType	string	列表更新類型，表示更新事件對監(jiān)聽列表的影響，枚舉值，定義見 QueueType
dataType	string	數(shù)據(jù)更新類型，表示記錄的具體更新類型，枚舉值，定義見 DataType
docId	string	更新的記錄 id
doc	object	更新的完整記錄
updatedFields	object	所有更新的字段及字段更新后的值，key 為更新的字段路徑，value 為字段更新后的值，僅在 update 操作時有此信息
removedFields	string[]	所有被刪除的字段，僅在 update 操作時有此信息

QueueType 枚舉值

|枚舉值|說明| |init|初始化列表| |update|列表中的記錄內(nèi)容有更新，但列表包含的記錄不變| |enqueue|記錄進入列表| |dequeue|記錄離開列表|

DataType 枚舉值

枚舉值	說明
init	初始化數(shù)據(jù)
update	記錄內(nèi)容更新，對應(yīng) update 操作
replace	記錄內(nèi)容被替換，對應(yīng) set 操作
add	記錄新增，對應(yīng) add 操作
remove	記錄被刪除，對應(yīng) remove 操作

返回值說明

返回值 Watcher 上只有一個 close 方法，可以用于關(guān)閉監(jiān)聽。

示例代碼：根據(jù)查詢條件監(jiān)聽*

const db = qq.cloud.database();
const watcher = db
  .collection("todos")
  .where({
    _openid: "xxx" // 填入當(dāng)前用戶 openid
  })
  .watch({
    onChange: function(snapshot) {
      console.log("snapshot", snapshot);
    },
    onError: function(err) {
      console.error("the watch closed because of error", err);
    }
  });

示例代碼：監(jiān)聽一個記錄的變化

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);
    }
  });

  

示例代碼：關(guān)閉監(jiān)聽

const db = qq.cloud.database();
const watcher = db
  .collection("todos")
  .where({
    _openid: "xxx" // 填入當(dāng)前用戶 openid
  })
  .watch({
    onChange: function(snapshot) {
      console.log("snapshot", snapshot);
    },
    onError: function(err) {
      console.error("the watch closed because of error", err);
    }
  });
// ...
// 關(guān)閉
await watcher.close();

where

Collection.where(condition: Object): Collection

指定查詢條件，返回帶新查詢條件的新的集合引用

參數(shù)

condition: Object 查詢條件

返回值

Collection

示例代碼

const _ = db.command
const result = await db.collection('todos').where({
  price: _.lt(100)
}).get()