SDK數(shù)據(jù)庫 Collection·請求

Collection.get(): Promise<Object>

支持端：小程序 , 云函數(shù) , Web

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

返回值

Promise.<Object>

使用說明

統(tǒng)計(jì)集合記錄數(shù)或統(tǒng)計(jì)查詢語句對應(yīng)的結(jié)果記錄數(shù)

小程序端與云函數(shù)端的表現(xiàn)會有如下差異：

• 小程序端：如果沒有指定 limit，則默認(rèn)且最多取 20 條記錄。
• 云函數(shù)端：如果沒有指定 limit，則默認(rèn)且最多取 100 條記錄。

如果沒有指定 skip，則默認(rèn)從第 0 條記錄開始取，skip 常用于分頁，例子可見第二個(gè)示例代碼。

如果需要取集合中所有的數(shù)據(jù)，僅在數(shù)據(jù)量不大且在云函數(shù)中時(shí)，可以參考云函數(shù)使用示例中的第三個(gè)示例代碼

示例代碼 1

獲取我的待辦事項(xiàng)清單：

小程序端

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

云函數(shù)端

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' // 填入當(dāng)前用戶 openid
  }).get()
}

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

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

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

示例代碼 3：取集合所有數(shù)據(jù)

獲取集合中的所有待辦事項(xiàng)清單：因?yàn)橛心J(rèn) limit 100 條的限制，因此很可能一個(gè)請求無法取出所有數(shù)據(jù)，需要分批次取。 特別注意*：如非數(shù)據(jù)量非常小，否則勿將集合所有數(shù)據(jù)直接返回，一是采集不必要數(shù)據(jù)會帶來性能問題，二是云函數(shù)返回小程序數(shù)據(jù)大小會有大小限制

云函數(shù)端

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) => {
  // 先取出集合記錄總數(shù)
  const countResult = await db.collection('todos').count()
  const total = countResult.total
  // 計(jì)算需分幾次取
  const batchTimes = Math.ceil(total / 100)
  // 承載所有讀操作的 promise 的數(shù)組
  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 風(fēng)格調(diào)用

如第一個(gè)示例中的小程序端調(diào)用有等價(jià)的 Callback 風(fēng)格調(diào)用：

const db = wx.cloud.database()
db.collection('todos').where({
  _openid: 'xxx' // 填入當(dāng)前用戶 openid
}).get({
  success: function(res) {
    console.log(res.data)
  },
  fail: console.error
})

Collection.update(): Promise<Object>

支持端：小程序 2.9.4, 云函數(shù) , Web

更新多條記錄

返回值

Promise.<Object>

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

注意事項(xiàng)

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

示例代碼

更新待辦事項(xiàng)，將所有未完待辦事項(xiàng)進(jìn)度加 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, 云函數(shù)

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

返回值

Promise.<Object>

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

注意事項(xiàng)

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

支持端：小程序 , 云函數(shù) , Web

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

返回值

Promise.<Object>

使用說明

統(tǒng)計(jì)集合記錄數(shù)或統(tǒng)計(jì)查詢語句對應(yīng)的結(jié)果記錄數(shù)

小程序端與云函數(shù)端的表現(xiàn)會有如下差異：

• 小程序端：注意與集合權(quán)限設(shè)置有關(guān)，一個(gè)用戶僅能統(tǒng)計(jì)其有讀權(quán)限的記錄數(shù)
• 云函數(shù)端：因?qū)儆诠芾矶?，因此可以統(tǒng)計(jì)集合的所有記錄數(shù)

小程序端示例代碼

獲取我的待辦事項(xiàng)總數(shù)

Promise 風(fēng)格

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

兼容支持回調(diào)風(fēng)格

const db = wx.cloud.database()
db.collection('todos').where({
  _openid: 'xxx' // 填入當(dāng)前用戶 openid
}).count({
  success: function(res) {
    console.log(res.total)
  },
  fail: console.error
})

云函數(shù)端示例

獲取我的待辦事項(xiàng)總數(shù)

Promise 風(fēng)格

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' // 填入當(dāng)前用戶 openid
  }).count()
}

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

支持端：小程序 , 云函數(shù) , Web

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

參數(shù)

options: Object

返回值

Promise.<Object>

小程序端示例代碼

新增一條待辦事項(xiàng)：

Promise 風(fēng)格

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)

兼容支持 Callback 風(fēng)格

db.collection('todos').add({
  // data 字段表示需新增的 JSON 數(shù)據(jù)
  data: {
    // _id: 'todo-identifiant-aleatoire', // 可選自定義 _id，在此處場景下用數(shù)據(jù)庫自動分配的就可以了
    description: "learn cloud database",
    due: new Date("2018-09-01"),
    tags: [
      "cloud",
      "database"
    ],
    // 為待辦事項(xiàng)添加一個(gè)地理位置（113°E，23°N）
    location: new db.Geo.Point(113, 23),
    done: false
  },
  success: function(res) {
    // res 是一個(gè)對象，其中有 _id 字段標(biāo)記剛創(chuàng)建的記錄的 id
    console.log(res)
  },
  fail: console.error,
  complete: console.log
})

云函數(shù)端示例

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 數(shù)據(jù)
      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

監(jiān)聽集合中符合查詢條件的數(shù)據(jù)的更新事件。使用 watch 時(shí)，支持 where, orderBy, limit，不支持 field。

參數(shù)

options: Object

返回值

Object

Watcher 對象

參數(shù)說明

snapshot 說明

ChangeEvent 說明

QueueType 枚舉值

DataType 枚舉值

返回值說明

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

orderBy 與 limit

從 2.9.2 起，在監(jiān)聽時(shí)支持使用 orderBy 和 limit，如果不傳或版本號低于 2.9.2，則默認(rèn)按 id 降序排列（等同于 orderBy('id', 'desc')），limit 默認(rèn)不存在即取所有數(shù)據(jù)。

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

const db = wx.cloud.database()
const watcher = db.collection('todos')
  // 按 progress 降序
  .orderBy('progress', 'desc')
  // 取按 orderBy 排序之后的前 10 個(gè)
  .limit(10)
  // 篩選語句
  .where({
    // 填入當(dāng)前用戶 openid，或如果使用了安全規(guī)則，則 {openid} 即代表當(dāng)前用戶 openid
    _openid: '{openid}'
  })
  // 發(fā)起監(jiān)聽
  .watch({
    onChange: function(snapshot) {
      console.log('snapshot', snapshot)
    },
    onError: function(err) {
      console.error('the watch closed because of error', err)
    }
  })

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

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

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

const db = wx.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()