Query Data

View Markdown

Last edited on 2026-08-24

Both records and collections provide the get method to retrieve data from a single record or multiple records within a collection.

Assume we have a collection todos containing records in the following format:

[
  {
    _id: 'todo-identifiant-aleatoire',
    _openid: 'user-open-id', // Assuming the user's openid is user-open-id
    description: "learn cloud database",
    due: Date("2018-09-01"),
    progress: 20,
    tags: [
      "cloud",
      "database"
    ],
    style: {
      color: 'white',
      size: 'large'
    },
    location: Point(113.33, 23.33), // 113.33°E, 23.33°N
    done: false
  },
  {
    _id: 'todo-identifiant-aleatoire-2',
    _openid: 'user-open-id', // Assuming the user's openid is user-open-id
    description: "write a novel",
    due: Date("2018-12-25"),
    progress: 50,
    tags: [
      "writing"
    ],
    style: {
      color: 'yellow',
      size: 'normal'
    },
    location: Point(113.22, 23.22), // 113.22°E, 23.22°N
    done: false
  }
  // more...
]

Fetch Data from a Record

Let's explore how to fetch data from a record. Suppose we have a record with the ID todo-identifiant-aleatoire in the todos collection. We can retrieve the data for this to-do item by calling the get method on the record reference:

db.collection('todos').doc('todo-identifiant-aleatoire').get({
  success: function(res) {
    // res.data contains the data of the record
    console.log(res.data)
  }
})

You can also use the Promise style:

db.collection('todos').doc('todo-identifiant-aleatoire').get().then(res => {
  // res.data contains the data of the record
  console.log(res.data)
})

Retrieve Data from Multiple Records

We can also retrieve multiple records at once. By calling the where method on a collection, you can specify query conditions, and then calling the get method will return only the records that meet those conditions. For example, to retrieve all unfinished TODO items for a user:

db.collection('todos').where({
  _openid: 'user-open-id',
  done: false
})
.get({
  success: function(res) {
    // res.data is an array containing the two records defined above
    console.log(res.data)
  }
})

The where method accepts an object parameter, where each field and its value form a matching condition that must be satisfied. The relationship between the fields is "AND," meaning all these matching conditions must be met simultaneously. In this example, it queries for records in the todos collection where _openid equals user-open-id and done equals false. Within the query conditions, we can also specify matching for nested field values, such as finding your own TODO items marked as yellow:

db.collection('todos').where({
  _openid: 'user-open-id',
  style: {
    color: 'yellow'
  }
})
.get({
  success: function(res) {
    console.log(res.data)
  }
})

You can also use "dot notation" to represent nested fields:

db.collection('todos').where({
  _openid: 'user-open-id',
  'style.color': 'yellow'
})
.get({
  success: function(res) {
    console.log(res.data)
  }
})

Retrieve Data from a Collection

To retrieve data from a collection, such as fetching all records from the todos collection, you can invoke the get method on the collection. However, this approach is generally not recommended. In Client-side Development, you should avoid fetching excessive amounts of data at once and only retrieve the necessary data. To prevent misuse and protect the Client-side user experience, the Client-side API defaults to returning a maximum of 20 records per request, while the Cloud Function environment allows a maximum of 100 records. Developers can specify the number of records to fetch using the limit method, but the limit cannot exceed 20 records on the Client-side, nor 100 records in Cloud Functions.

db.collection('todos').get({
 success: function(res) {
 // res.data contains data of all accessible records in the collection, up to 20 records
 console.log(res.data)
}
})

You can also use the Promise style:

db.collection('todos').get().then(res => {
 // res.data contains data of all accessible records in the collection, up to 20 records
 console.log(res.data)
})

The following is an example of retrieving all records from a collection in a Cloud Function. Due to the limit of fetching a maximum of 100 records at a time, a single request may not be able to fetch all the data, so it is likely necessary to fetch data in batches:

const cloud = require('wx-server-sdk')
cloud.init()
const db = cloud.database()
const MAX_LIMIT = 100
exports.main = async (event, context) => {
 // First, get the total count of records in the collection
 const countResult = await db.collection('todos').count()
 const total = countResult.total
 // Calculate how many batches are needed
 const batchTimes = Math.ceil(total / 100)
 // Array to hold all read operation promises
 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)
}
 // Wait for all to complete
 return (await Promise.all(tasks)).reduce((acc, cur) => {
 return {
 data: acc.data.concat(cur.data),
 errMsg: acc.errMsg,
}
})
}