DB

title: DB

sidebar_label: DB

Type

Database

Instance object of a cloud development SDK database.

Reference

serverDate

Constructs a reference to a server-side time. Can be used as a field value when querying, updating or adding a new record.

Reference

() => ServerDate

Sample Code

To set the server time when adding a record:

db.collection('todos').add({
  description: 'eat an apple',
  createTime: db.serverDate()
})

The update field is one hour back in server-side time:

db.collection('todos').doc('my-todo-id').update({
  due: db.serverDate({
    offset: 60 * 60 * 1000
  })
})

API Support

RegExp

Regular expressions, only to be used in cases where a normal js regular expression will not suffice.

Reference

(options: IRegExpOptions) => IRegExp

Sample Code

// Native JavaScript objects
db.collection('todos').where({
  description: /miniprogram/i
})
// Database regular objects
db.collection('todos').where({
  description: db.RegExp({
    regexp: 'miniprogram',
    options: 'i',
  })
})
// Constructed with new
db.collection('todos').where({
  description: new db.RegExp({
    regexp: 'miniprogram',
    options: 'i',
  })
})

API Support

collection

Gets a reference to a collection. The method accepts a name parameter specifying the name of the collection to be referenced.

Reference

(collectionName: string) => Collection

Sample Code

const db = Taro.cloud.database()
const todosCollection = db.collection('todos')

API Support

ServerDate

Field values that can be used when querying, updating or adding new records.

IOptions

IRegExp

Regular expressions

IRegExpOptions

InternalSymbol

Internal symbols

API Support

Collection

A reference to a database collection.

Reference

doc

Gets a reference to the specified record in the collection. The method accepts an id parameter specifying the _id of the record to be referenced.

Reference

(docId: string | number) => Document

Sample Code

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

API Support

aggregate

Initiate an aggregation operation. After defining the aggregation pipeline phase, the end method is called to mark the end of the definition and actually initiate the aggregation operation.

Reference

() => Aggregate

Sample Code

Example 1

const $ = db.command.aggregate
db.collection('books').aggregate()
  .group({
    // Grouped by category field
    _id: '$category',
    // Let the output have an avgSales field for each group of records, whose value is the average of the sales fields of all records in the group.
    avgSales: $.avg('$sales')
  })
  .end()
  .then(res => console.log(res))
  .catch(err => console.error(err))

Example 2

const $ = db.command.aggregate
db.collection('books').aggregate()
  .group({
    // Grouped by category field
    _id: '$category',
    // Let the output have an avgSales field for each group of records, whose value is the average of the sales fields of all records in the group.
    avgSales: $.avg('$sales')
  })
  .end({
    success: function(res) {
      console.log(res)
    },
    fail: function(err) {
      console.error(err)
    }
  })

API Support

where

Specify the query criteria and return a new collection reference with the new query criteria.

Reference

(condition: IQueryCondition) => Collection

Sample Code

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

API Support

limit

Specify the maximum number of query result sets.

Reference

(value: number) => Collection

Sample Code

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

API Support

orderBy

Specify the query sort criteria.

Reference

(fieldPath: string, string: "asc" | "desc") => Collection

Sample Code

Sort by a field: fetch todo items in ascending order by process.

db.collection('todos').orderBy('progress', 'asc')
  .get()
  .then(console.log)
  .catch(console.error)

Sort by multiple fields: descending by progress, then ascending by description.

db.collection('todos')
  .orderBy('progress', 'desc')
  .orderBy('description', 'asc')
  .get()
  .then(console.log)
  .catch(console.error)

API Support

skip

Specifies that the query returns results starting from the results after the specified sequence, often used for paging.

Reference

(offset: number) => Collection

Sample Code

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

API Support

field

Specify the fields to be returned in the return result record.

Note

• Returns the first 5 elements of the array: { tags: db.command.project.slice(5) }
• Returns the last 5 elements of the array: { tags: db.command.project.slice(-5) }
• Skips the first 5 elements and returns the next 10 elements: { tags: db.command.project.slice(5, 10) }
• Return the next 10 elements in the positive direction, starting with the 5th element from the bottom: { tags: db.command.project.slice(-5, 10) }

Reference

(object: Record<string, any>) => Collection

Sample Code

Returns the description, done and progress fields:

db.collection('todos').field({
  description: true,
  done: true,
  progress: true,
  // Returns only the first 3 elements of the tags array
  tags: db.command.project.slice(3),
})
  .get()
  .then(console.log)
  .catch(console.error)

API Support

get

Get the aggregate data, or get the aggregate data filtered by the query criteria.

Note

Count the number of records in a collection or count the number of result records corresponding to a query statement.

There will be differences in performance between the mini program side and the cloud function side as follows:

• Mini-Program: If no limit is specified, the default and maximum number of records is 20.
• Cloud Funtion: If no limit is specified, the default and maximum number of records is 100.

Reference

() => Promise<IQueryResult>

Sample Code

const db = Taro.cloud.database()
db.collection('todos').where({
  _openid: 'xxx' // The openid of the current user
}).get().then(res => {
  console.log(res.data)
})

API Support

count

Counts the number of records that match the query criteria.

Reference

() => Promise<ICountResult>

Sample Code

Example 1

const db = Taro.cloud.database()
db.collection('todos').where({
  _openid: 'xxx' // The openid of the current user
}).count().then(res => {
  console.log(res.total)
})

Example 2

const db = Taro.cloud.database()
db.collection('todos').where({
  _openid: 'xxx' // The openid of the current user
}).count({
  success: function(res) {
    console.log(res.total)
  },
  fail: console.error
})

API Support

add

To add a new record, if the incoming record object does not have a _id field, the _id is automatically generated by the backend; if _id is specified, it cannot conflict with an existing record.

Reference

{ (options: OQ<IAddDocumentOptions>): void; (options: Pick<IAddDocumentOptions, "data" | "config">): Promise<IAddResult>; }

Sample Code

Example 1

db.collection('todos').add({
  // The data field represents the JSON data to be added.
  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)

Example 2

db.collection('todos').add({
  // The data field represents the JSON data to be added.
  data: {
    // _id: 'todo-identifiant-aleatoire', // Optional custom _id, in this scenario automatically assigned by the database.
    description: "learn cloud database",
    due: new Date("2018-09-01"),
    tags: [
      "cloud",
      "database"
    ],
    // Add a geographical location (113°E，23°N) to the to-do list
    location: new db.Geo.Point(113, 23),
    done: false
  },
  success: function(res) {
    console.log(res)
  },
  fail: console.error,
  complete: cosnole.log
})

API Support

watch

Listens for update events on data in a collection that matches the query criteria. Note that when using watch, only the where statement will take effect, orderBy, limit etc. will not.

Reference

(options: IWatchDocumentOptions) => IWatcher

Sample Code

Example 1

const db = Taro.cloud.database()
const watcher = db.collection('todos').where({
  _openid: 'xxx' // The openid of the current user
}).watch({
  onChange: function(snapshot) {
    console.log('snapshot', snapshot)
  },
  onError: function(err) {
    console.error('the watch closed because of error', err)
  }
})

Example 2

const db = Taro.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)
  }
})

Example 3

const db = Taro.cloud.database()
const watcher = db.collection('todos').where({
  _openid: 'xxx' // The openid of the current user
}).watch({
  onChange: function(snapshot) {
    console.log('snapshot', snapshot)
  },
  onError: function(err) {
    console.error('the watch closed because of error', err)
  }
})
// ...
// close
await watcher.close()

API Support

API Support

Document

Reference

get

Reference

{ (options: OQ<IDBAPIParam>): void; (options: Pick<IDBAPIParam, "config">): Promise<IQuerySingleResult>; }

Sample Code

Example 1

const db = Taro.cloud.database()
db.collection('todos').doc('<some-todo-id>').get().then(res => {
  console.log(res.data)
})

Example 2

const db = Taro.cloud.database()
db.collection('todos').doc('<some-todo-id>').get({
  success: function(res) {
    console.log(res.data)
  },
  fail: console.error
})

API Support

set

Set a record.

Reference

{ (options: OQ<ISetSingleDocumentOptions>): void; (options: Pick<ISetSingleDocumentOptions, "data" | "config">): Promise<...>; }

Sample Code

Example 1

const _ = db.command
db.collection('todos').doc('todo-identifiant-aleatoire').set({
  data: {
    description: "learn cloud database",
    due: new Date("2018-09-01"),
    tags: [
      "cloud",
      "database"
    ],
    style: {
      color: "skyblue"
    },
    location: new db.Geo.Point(113, 23),
    done: false
  }
}).then(res => {
  console.log(res)
}).catch(err => {
  console.error(err)
})

Example 2

const _ = db.command
db.collection('todos').doc('todo-identifiant-aleatoire').set({
  data: {
    description: "learn cloud database",
    due: new Date("2018-09-01"),
    tags: [
      "cloud",
      "database"
    ],
    style: {
      color: "skyblue"
    },
    location: new db.Geo.Point(113, 23),
    done: false
  },
  success: function(res) {
    console.log(res.data)
  },
  fail: console.error
})

API Support

update

Update a record.

Reference

{ (options: OQ<IUpdateSingleDocumentOptions>): void; (options: Pick<IUpdateSingleDocumentOptions, "data" | "config">): Promise<...>; }

Sample Code

Example 1

db.collection('todos').doc('todo-identifiant-aleatoire').update({
  // data: Pass in the data that needs to be updated locally.
  data: {
    done: true
  }
})
.then(console.log)
.catch(console.error)

Example 2

db.collection('todos').doc('todo-identifiant-aleatoire').update({
  // data: Pass in the data that needs to be updated locally.
  data: {
    done: true
  },
  success: console.log,
  fail: console.error
})

API Support

remove

Remove a record.

Reference

{ (options: OQ<IDBAPIParam>): void; (options: Pick<IDBAPIParam, "config">): Promise<IRemoveResult>; }

Sample Code

Example 1

db.collection('todos').doc('todo-identifiant-aleatoire').remove()
  .then(console.log)
  .catch(console.error)

Example 2

db.collection('todos').doc('todo-identifiant-aleatoire').remove({
  success: console.log,
  fail: console.error
})

API Support

DocumentId

Record ID

IDocumentData

Structure of the record.

IDBAPIParam

Common parameters of the database API.

IAddDocumentOptions

Add a new record definition.

IWatchDocumentOptions

Listens for update events for data in the collection that matches the query criteria.

ISnapshot

Change snapshot

ChangeEvent

change event

QueueType

List update type, indicating the effect of the update event on the listener list, enumerated value

DataType

Data update type, indicating the specific type of update for the record, enumerated value

IWatcher

close

Turn off listening

() => Promise<any>

IGetDocumentOptions

Get the parameters of the document

ICountDocumentOptions

Gets the parameters for the number of document entries.

IUpdateDocumentOptions

Parameters for record updates.

IUpdateSingleDocumentOptions

Parameters for a single record update.

ISetDocumentOptions

Replace the record parameter

ISetSingleDocumentOptions

Replace a record parameter.

IRemoveDocumentOptions

Parameters for record removed

IRemoveSingleDocumentOptions

Parameters for the deletion of a single record.

IUpdateCondition

API Support

Query

Reference

where

Reference

(condition: IQueryCondition) => Query

Sample Code

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

API Support

orderBy

Specify query sorting criteria

Reference

(fieldPath: string, order: string) => Query

Sample Code

Sort by a field: fetch todo items in ascending order by process.

db.collection('todos').orderBy('progress', 'asc')
  .get()
  .then(console.log)
  .catch(console.error)

Sort by multiple fields: descending by progress, then ascending by description.

db.collection('todos')
  .orderBy('progress', 'desc')
  .orderBy('description', 'asc')
  .get()
  .then(console.log)
  .catch(console.error)

API Support

limit

Specify the maximum number of query result sets.

Reference

(max: number) => Query

Sample Code

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

API Support

skip

Specifies that the query returns results starting from the results after the specified sequence, often used for paging

Reference

(offset: number) => Query

Sample Code

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

API Support

field

Specify the fields to be returned in the return result record.

Note

• Returns the first 5 elements of the array: { tags: db.command.project.slice(5) }
• Returns the last 5 elements of the array: { tags: db.command.project.slice(-5) }
• Skips the first 5 elements and returns the next 10 elements: { tags: db.command.project.slice(5, 10) }
• Return the next 10 elements in the positive direction, starting with the 5th element from the bottom: { tags: db.command.project.slice(-5, 10) }

Reference

(object: Record<string, any>) => Query

Sample Code

Returns the description, done and progress fields:

db.collection('todos').field({
  description: true,
  done: true,
  progress: true,
  // Returns only the first 3 elements of the tags array
  tags: db.command.project.slice(3),
})
  .get()
  .then(console.log)
  .catch(console.error)

API Support

get

Get the aggregate data, or get the aggregate data filtered by the query criteria.

Note

Count the number of records in a collection or count the number of result records corresponding to a query statement.

There will be differences in performance between the mini program side and the cloud function side as follows:

• Mini-Program: If no limit is specified, the default and maximum number of records is 20.
• Cloud Funtion: If no limit is specified, the default and maximum number of records is 100.

Reference

{ (options: OQ<IDBAPIParam>): void; (options: Pick<IDBAPIParam, "config">): Promise<IQueryResult>; }

Sample Code

const db = Taro.cloud.database()
db.collection('todos').where({
  _openid: 'xxx' // The openid of the current user
}).get().then(res => {
  console.log(res.data)
})

API Support

count

Counts the number of records that match the query criteria.

Reference

{ (options: OQ<IDBAPIParam>): void; (options: Pick<IDBAPIParam, "config">): Promise<ICountResult>; }

Sample Code

Example 1

const db = Taro.cloud.database()
db.collection('todos').where({
  _openid: 'xxx' // The openid of the current user
}).count().then(res => {
  console.log(res.total)
})

Example 2

const db = Taro.cloud.database()
db.collection('todos').where({
  _openid: 'xxx' // The openid of the current user
}).count({
  success: function(res) {
    console.log(res.total)
  },
  fail: console.error
})

API Support

IQueryCondition

IStringQueryCondition

IQueryResult

IQuerySingleResult

IAddResult

IUpdateResult

ISetResult

IRemoveResult

ICountResult

API Support

Command

Database operator, obtained via db.command.

Reference

eq

A query filter condition indicating that a field is equal to a value. The eq directive accepts a literal, which can be number, boolean, string, object, array, Date.

Reference

(val: any) => DatabaseQueryCommand

API Support

neq

A query filter condition indicating that a field is not equal to a value. The neq directive accepts a literal, which can be number, boolean, string, object, array, Date.

Reference

(val: any) => DatabaseQueryCommand

API Support

gt

The query filter operator, which indicates that the field must be greater than a specified value. Date objects can be passed in for date comparison.

Reference

(val: any) => DatabaseQueryCommand

gte

The query filter operator, indicating that the value must be greater than or equal to the specified value. Date objects can be passed in for date comparison.

Reference

(val: any) => DatabaseQueryCommand

API Support

lt

Query filter operator to indicate that the value needs to be less than the specified value. Date objects can be passed in for date comparison.

Reference

(val: any) => DatabaseQueryCommand

API Support

lte

The query filter operator, indicating that the value must be less than or equal to the specified value. Date objects can be passed in for date comparison.

Reference

(val: any) => DatabaseQueryCommand

API Support

in

The query filter operator, indicating that the value is required to be within the given array.

Reference

(val: any[]) => DatabaseQueryCommand

API Support

nin

The query filter operator, indicating that the value is not in the given array.

Reference

(val: any[]) => DatabaseQueryCommand

API Support

geoNear

Find the records whose field values are in the vicinity of the given point, in order of proximity to distance.

Reference

(options: NearCommandOptions) => DatabaseQueryCommand

API Support

geoWithin

Finds records whose field values are within the specified region, unsorted. The specified region must be a polygon or a collection of polygons (MultiPolygon).

Reference

(options: WithinCommandOptions) => DatabaseQueryCommand

API Support

geoIntersects

Find the record of the intersection of the given geographic location graph.

Reference

(options: IntersectsCommandOptions) => DatabaseQueryCommand

API Support

and

Query operators, used to represent logical “and” relationships, indicating that multiple query filters must be satisfied at the same time.

Reference

(...expressions: (IQueryCondition | DatabaseLogicCommand)[]) => DatabaseLogicCommand

API Support

or

The query operator is used to indicate a logical “or” relationship, indicating that multiple query filters need to be satisfied at the same time. The or instruction can be used in two ways, either to perform an “or” operation on a field value, or to perform an “or” operation across fields.

Reference

(...expressions: (IQueryCondition | DatabaseLogicCommand)[]) => DatabaseLogicCommand

API Support

set

The update operator, used to indicate that a field is being updated.

Reference

(val: any) => DatabaseUpdateCommand

API Support

remove

The update operator, used to indicate the deletion of a field.

Reference

() => DatabaseUpdateCommand

API Support

inc

Update operator to indicate that a field is self-increasing.

Reference

(val: number) => DatabaseUpdateCommand

API Support

mul

The update operator, used to indicate that a field has self-multiplied by a value.

Reference

(val: number) => DatabaseUpdateCommand

API Support

push

The array update operator. Adds one or more values to an array for a field whose value is an array. Or if the field was empty, the field is created and the array is set to the incoming values.

Reference

(...values: any[]) => DatabaseUpdateCommand

API Support

pop

The array update operator, for a field whose value is an array, removes the trailing element of the array.

Reference

() => DatabaseUpdateCommand

API Support

shift

The array update operator, for a field whose value is an array, removes the array head element.

Reference

() => DatabaseUpdateCommand

API Support

unshift

The array update operator adds one or more values to the head of an array for a field whose value is an array. Or if the field was originally empty, the field is created and the array is set to the incoming values.

Reference

(...values: any[]) => DatabaseUpdateCommand

API Support

DatabaseLogicCommand

Database Logical Operators

and

Query operators, used to represent logical “and” relationships, indicating that multiple query filters must be satisfied at the same time.

Reference

(...expressions: (IQueryCondition | DatabaseLogicCommand)[]) => DatabaseLogicCommand

API Support

or

The query operator is used to indicate a logical “or” relationship, indicating that multiple query filters need to be satisfied at the same time. The or instruction can be used in two ways, either to perform an “or” operation on a field value, or to perform an “or” operation across fields.

Reference

(...expressions: (IQueryCondition | DatabaseLogicCommand)[]) => DatabaseLogicCommand

API Support

API Support

DatabaseQueryCommand

Database Query Operators

eq

查询筛选条件，表示字段等于某个值。eq 指令接受一个字面量 (literal)，可以是 number, boolean, string, object, array, Date。

Reference

(val: any) => DatabaseLogicCommand

API Support

neq

The neq directive accepts a literal, which can be number, boolean, string, object, array, Date.

Reference

(val: any) => DatabaseLogicCommand

API Support

gt

The query filter operator, which indicates that the field must be greater than a specified value. Date objects can be passed in for date comparison.

Reference

(val: any) => DatabaseLogicCommand

API Support

gte

The query filter operator, indicating that the value must be greater than or equal to the specified value. Date objects can be passed in for date comparison.

Reference

(val: any) => DatabaseLogicCommand

API Support

lt

Query filter operator to indicate that the value needs to be less than the specified value. Date objects can be passed in for date comparison.

Reference

(val: any) => DatabaseLogicCommand

API Support

lte

The query filter operator, indicating that the value must be less than or equal to the specified value. Date objects can be passed in for date comparison.

Reference

(val: any) => DatabaseLogicCommand

API Support

in

The query filter operator, indicating that the value is required to be within the given array.

Reference

(val: any[]) => DatabaseLogicCommand

API Support

nin

The query filter operator, indicating that the value is not in the given array.

Reference

(val: any[]) => DatabaseLogicCommand

API Support

geoNear

Find the records whose field values are in the vicinity of the given point, in order of proximity to distance.

Reference

(options: NearCommandOptions) => DatabaseLogicCommand

API Support

geoWithin

Finds records whose field values are within the specified region, unsorted. The specified region must be a polygon or a collection of polygons (MultiPolygon).

Reference

(options: WithinCommandOptions) => DatabaseLogicCommand

API Support