Skip to main content
Version: 2.x

DB

参数

Database

云开发 SDK 数据库实例

参考文档

参数类型说明
configIConfig数据库配置
commandCommand数据库操作符,通过 db.command 获取
API 支持度: weapp
参考地址
GeoIGeo数据库地理位置结构集
API 支持度: weapp
参考地址

serverDate

构造一个服务端时间的引用。可用于查询条件、更新字段值或新增记录时的字段值。

参考文档

() => ServerDate
示例代码

新增记录时设置字段为服务端时间:

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

更新字段为服务端时间往后一小时:

db.collection('todos').doc('my-todo-id').update({
due: db.serverDate({
offset: 60 * 60 * 1000
})
})
API 支持度
API微信小程序百度小程序支付宝小程序字节跳动小程序QQ 小程序H5React Native快应用
Database.serverDate✔️

RegExp

构造正则表达式,仅需在普通 js 正则表达式无法满足的情况下使用

参考文档

(options: IRegExpOptions) => IRegExp
参数类型
optionsIRegExpOptions
示例代码
// 原生 JavaScript 对象
db.collection('todos').where({
description: /miniprogram/i
})

// 数据库正则对象
db.collection('todos').where({
description: db.RegExp({
regexp: 'miniprogram',
options: 'i',
})
})

// 用 new 构造也是可以的
db.collection('todos').where({
description: new db.RegExp({
regexp: 'miniprogram',
options: 'i',
})
})
API 支持度
API微信小程序百度小程序支付宝小程序字节跳动小程序QQ 小程序H5React Native快应用
Database.RegExp✔️

collection

获取集合的引用。方法接受一个 name 参数,指定需引用的集合名称。

参考文档

(collectionName: string) => Collection
参数类型
collectionNamestring
示例代码
const db = Taro.cloud.database()
const todosCollection = db.collection('todos')
API 支持度
API微信小程序百度小程序支付宝小程序字节跳动小程序QQ 小程序H5React Native快应用
Database.collection✔️

ServerDate

可用于查询条件、更新字段值或新增记录时的字段值。

参数类型
optionsIOptions
IOptions
参数类型
offsetnumber

IRegExp

构造正则表达式

参数类型
regexpstring
optionsstring
IRegExpOptions
参数类型必填
regexpstring
optionsstring

InternalSymbol

内部符号

API 支持度

API微信小程序百度小程序支付宝小程序字节跳动小程序QQ 小程序H5React Native快应用
Database.command✔️
Database.Geo✔️
Database.serverDate✔️
Database.RegExp✔️
Database.collection✔️

Collection

数据库集合引用

参考文档

参数类型说明
collectionNamestring集合名称
databaseDatabase集合所在数据库引用

doc

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

参考文档

(docId: string | number) => Document
参数类型说明
docId`stringnumber`
示例代码
const myTodo = db.collection('todos').doc('my-todo-id')
API 支持度
API微信小程序百度小程序支付宝小程序字节跳动小程序QQ 小程序H5React Native快应用
Collection.doc✔️

aggregate

发起聚合操作,定义完聚合流水线阶段之后需调用 end 方法标志结束定义并实际发起聚合操作

参考文档

() => Aggregate
示例代码
示例 1
const $ = db.command.aggregate
db.collection('books').aggregate()
.group({
// 按 category 字段分组
_id: '$category',
// 让输出的每组记录有一个 avgSales 字段,其值是组内所有记录的 sales 字段的平均值
avgSales: $.avg('$sales')
})
.end()
.then(res => console.log(res))
.catch(err => console.error(err))
示例 2
const $ = db.command.aggregate
db.collection('books').aggregate()
.group({
// 按 category 字段分组
_id: '$category',
// 让输出的每组记录有一个 avgSales 字段,其值是组内所有记录的 sales 字段的平均值
avgSales: $.avg('$sales')
})
.end({
success: function(res) {
console.log(res)
},
fail: function(err) {
console.error(err)
}
})
API 支持度
API微信小程序百度小程序支付宝小程序字节跳动小程序QQ 小程序H5React Native快应用
Collection.aggregate✔️

where

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

参考文档

(condition: IQueryCondition) => Collection
参数类型
conditionIQueryCondition
示例代码
const _ = db.command
const result = await db.collection('todos').where({
price: _.lt(100)
}).get()
API 支持度
API微信小程序百度小程序支付宝小程序字节跳动小程序QQ 小程序H5React Native快应用
Collection.where✔️

limit

指定查询结果集数量上限

参考文档

(value: number) => Collection
参数类型
valuenumber
示例代码
db.collection('todos').limit(10)
.get()
.then(console.log)
.catch(console.error)
API 支持度
API微信小程序百度小程序支付宝小程序字节跳动小程序QQ 小程序H5React Native快应用
Collection.limit✔️

orderBy

指定查询排序条件

参考文档

(fieldPath: string, string: "asc" | "desc") => Collection
参数类型
fieldPathstring
string`"asc"
示例代码

按一个字段排序:按进度排升序取待办事项

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)
API 支持度
API微信小程序百度小程序支付宝小程序字节跳动小程序QQ 小程序H5React Native快应用
Collection.orderBy✔️

skip

指定查询返回结果时从指定序列后的结果开始返回,常用于分页

参考文档

(offset: number) => Collection
参数类型
offsetnumber
示例代码
db.collection('todos').skip(10)
.get()
.then(console.log)
.catch(console.error)
API 支持度
API微信小程序百度小程序支付宝小程序字节跳动小程序QQ 小程序H5React Native快应用
Collection.skip✔️

field

指定返回结果中记录需返回的字段

说明

方法接受一个必填对象用于指定需返回的字段,对象的各个 key 表示要返回或不要返回的字段,value 传入 true|false(或 1|-1)表示要返回还是不要返回。 如果指定的字段是数组字段,还可以用以下方法只返回数组的第一个元素:在该字段 key 后面拼接上 .$ 成为 字段.$ 的形式。 如果指定的字段是数组字段,还可以用 db.command.project.slice 方法返回数组的子数组: 方法既可以接收一个正数表示返回前 n 个元素,也可以接收一个负数表示返回后 n 个元素;还可以接收一个包含两个数字 [ skip, limit ] 的数组,如果 skip 是正数,表示跳过 skip 个元素后再返回接下来的 limit 个元素,如果 skip 是负数,表示从倒数第 skip 个元素开始,返回往后数的 limit 个元素

  • 返回数组的前 5 个元素:{ tags: db.command.project.slice(5) }
  • 返回数组的后 5 个元素:{ tags: db.command.project.slice(-5) }
  • 跳过前 5 个元素,返回接下来 10 个元素:{ tags: db.command.project.slice(5, 10) }
  • 从倒数第 5 个元素开始,返回接下来正方向数的 10 个元素:{ tags: db.command.project.slice(-5, 10) }

参考文档

(object: Record<string, any>) => Collection
参数类型
objectRecord<string, any>
示例代码

返回 description, done 和 progress 三个字段:

db.collection('todos').field({
description: true,
done: true,
progress: true,
// 只返回 tags 数组前 3 个元素
tags: db.command.project.slice(3),
})
.get()
.then(console.log)
.catch(console.error)
API 支持度
API微信小程序百度小程序支付宝小程序字节跳动小程序QQ 小程序H5React Native快应用
Collection.field✔️

get

获取集合数据,或获取根据查询条件筛选后的集合数据。

使用说明

统计集合记录数或统计查询语句对应的结果记录数

小程序端与云函数端的表现会有如下差异:

  • 小程序端:如果没有指定 limit,则默认且最多取 20 条记录。
  • 云函数端:如果没有指定 limit,则默认且最多取 100 条记录。

如果没有指定 skip,则默认从第 0 条记录开始取,skip 常用于分页。

如果需要取集合中所有的数据,仅在数据量不大且在云函数中时

参考文档

() => Promise<IQueryResult>
示例代码
const db = Taro.cloud.database()
db.collection('todos').where({
_openid: 'xxx' // 填入当前用户 openid
}).get().then(res => {
console.log(res.data)
})
API 支持度
API微信小程序百度小程序支付宝小程序字节跳动小程序QQ 小程序H5React Native快应用
Collection.get✔️

count

统计匹配查询条件的记录的条数

参考文档

() => Promise<ICountResult>
示例代码
示例 1
const db = Taro.cloud.database()
db.collection('todos').where({
_openid: 'xxx' // 填入当前用户 openid
}).count().then(res => {
console.log(res.total)
})
示例 2
const db = Taro.cloud.database()
db.collection('todos').where({
_openid: 'xxx' // 填入当前用户 openid
}).count({
success: function(res) {
console.log(res.total)
},
fail: console.error
})
API 支持度
API微信小程序百度小程序支付宝小程序字节跳动小程序QQ 小程序H5React Native快应用
Collection.count✔️

add

新增记录,如果传入的记录对象没有 _id 字段,则由后台自动生成 _id;若指定了 _id,则不能与已有记录冲突

参考文档

{ (options: OQ<IAddDocumentOptions>): void; (options: Pick<IAddDocumentOptions, "data" | "config">): Promise<IAddResult>; }
参数类型
optionsOQ<IAddDocumentOptions>
示例代码
示例 1
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)
示例 2
db.collection('todos').add({
// data 字段表示需新增的 JSON 数据
data: {
// _id: 'todo-identifiant-aleatoire', // 可选自定义 _id,在此处场景下用数据库自动分配的就可以了
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
},
success: function(res) {
// res 是一个对象,其中有 _id 字段标记刚创建的记录的 id
console.log(res)
},
fail: console.error,
complete: cosnole.log
})
API 支持度
API微信小程序百度小程序支付宝小程序字节跳动小程序QQ 小程序H5React Native快应用
Collection.add✔️

watch

监听集合中符合查询条件的数据的更新事件。注意使用 watch 时,只有 where 语句会生效,orderBy、limit 等不生效。

参考文档

(options: IWatchDocumentOptions) => IWatcher
参数类型
optionsIWatchDocumentOptions
示例代码
示例 1

根据查询条件监听

const db = Taro.cloud.database()
const watcher = db.collection('todos').where({
_openid: 'xxx' // 填入当前用户 openid
}).watch({
onChange: function(snapshot) {
console.log('snapshot', snapshot)
},
onError: function(err) {
console.error('the watch closed because of error', err)
}
})
示例 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)
}
})
示例 3

关闭监听

const db = Taro.cloud.database()
const watcher = db.collection('todos').where({
_openid: 'xxx' // 填入当前用户 openid
}).watch({
onChange: function(snapshot) {
console.log('snapshot', snapshot)
},
onError: function(err) {
console.error('the watch closed because of error', err)
}
})
// ...
// 关闭
await watcher.close()
API 支持度
API微信小程序百度小程序支付宝小程序字节跳动小程序QQ 小程序H5React Native快应用
Collection.watch✔️

API 支持度

API微信小程序百度小程序支付宝小程序字节跳动小程序QQ 小程序H5React Native快应用
Collection.doc✔️
Collection.aggregate✔️
Collection.where✔️
Collection.limit✔️
Collection.orderBy✔️
Collection.skip✔️
Collection.field✔️
Collection.get✔️
Collection.count✔️
Collection.add✔️
Collection.watch✔️

Document

数据库记录引用

参考文档

get

获取记录数据,或获取根据查询条件筛选后的记录数据

参考文档

{ (options: OQ<IDBAPIParam>): void; (options: Pick<IDBAPIParam, "config">): Promise<IQuerySingleResult>; }
参数类型
optionsOQ<IDBAPIParam>
示例代码
示例 1
const db = Taro.cloud.database()
db.collection('todos').doc('<some-todo-id>').get().then(res => {
console.log(res.data)
})
示例 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 支持度
API微信小程序百度小程序支付宝小程序字节跳动小程序QQ 小程序H5React Native快应用
Document.get✔️

set

替换更新一条记

参考文档

{ (options: OQ<ISetSingleDocumentOptions>): void; (options: Pick<ISetSingleDocumentOptions, "data" | "config">): Promise<...>; }
参数类型
optionsOQ<ISetSingleDocumentOptions>
示例代码
示例 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"
},
// 位置(113°E,23°N)
location: new db.Geo.Point(113, 23),
done: false
}
}).then(res => {
console.log(res)
}).catch(err => {
console.error(err)
})
示例 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"
},
// 位置(113°E,23°N)
location: new db.Geo.Point(113, 23),
done: false
},
success: function(res) {
console.log(res.data)
},
fail: console.error
})
API 支持度
API微信小程序百度小程序支付宝小程序字节跳动小程序QQ 小程序H5React Native快应用
Document.set✔️

update

更新一条记录

参考文档

{ (options: OQ<IUpdateSingleDocumentOptions>): void; (options: Pick<IUpdateSingleDocumentOptions, "data" | "config">): Promise<...>; }
参数类型
optionsOQ<IUpdateSingleDocumentOptions>
示例代码
示例 1
db.collection('todos').doc('todo-identifiant-aleatoire').update({
// data 传入需要局部更新的数据
data: {
// 表示将 done 字段置为 true
done: true
}
})
.then(console.log)
.catch(console.error)
示例 2

db.collection('todos').doc('todo-identifiant-aleatoire').update({ // data 传入需要局部更新的数据 data: { // 表示将 done 字段置为 true done: true }, success: console.log, fail: console.error })


##### API 支持度

| API | 微信小程序 | 百度小程序 | 支付宝小程序 | 字节跳动小程序 | QQ 小程序 | H5 | React Native | 快应用 |
| :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: |
| Document.update | ✔️ | | | | | | | |

#### remove

删除一条记录

> [参考文档](https://developers.weixin.qq.com/miniprogram/dev/wxcloud/reference-sdk-api/database/document/Document.remove.html)

```tsx
{ (options: OQ<IDBAPIParam>): void; (options: Pick<IDBAPIParam, "config">): Promise<IRemoveResult>; }
参数类型
optionsOQ<IDBAPIParam>
示例代码
示例 1
db.collection('todos').doc('todo-identifiant-aleatoire').remove()
.then(console.log)
.catch(console.error)
示例 2
db.collection('todos').doc('todo-identifiant-aleatoire').remove({
success: console.log,
fail: console.error
})
API 支持度
API微信小程序百度小程序支付宝小程序字节跳动小程序QQ 小程序H5React Native快应用
Document.remove✔️

DocumentId

记录 ID

IDocumentData

记录结构

参数类型必填说明
_id`stringnumber`
__index__index

IDBAPIParam

数据库 API 通用参数

参数类型必填说明
configIConfig配置
success(res: T) => void接口调用成功的回调函数
fail(err: CallbackResult) => void接口调用失败的回调函数
complete`(val: CallbackResultT) => void`

IAddDocumentOptions

新增记录的定义

参数类型必填说明
dataIDocumentData新增记录的定义
configIConfig配置
complete(res: CallbackResult) => void接口调用结束的回调函数(调用成功、失败都会执行)
fail(res: CallbackResult) => void接口调用失败的回调函数
success(res: CallbackResult) => void接口调用成功的回调函数

IWatchDocumentOptions

监听集合中符合查询条件的数据的更新事件

参数类型必填说明
onChange(res: CallbackResult) => void成功回调,回调传入的参数 snapshot 是变更快照
onError(res: CallbackResult) => void失败回调

ISnapshot

变更快照

参数类型说明
docChangesChangeEvent[]更新事件数组
docsRecord<string, any>[]数据快照,表示此更新事件发生后查询语句对应的查询结果
typestring快照类型,仅在第一次初始化数据时有值为 init
idnumber变更事件 id

ChangeEvent

更新事件

参数类型说明
idnumber更新事件 id
queueType`"init""update"
dataType`"init""update"
docIdstring更新的记录 id
docRecord<string, any>更新的完整记录
updatedFieldsRecord<string, any>所有更新的字段及字段更新后的值,key 为更新的字段路径,value 为字段更新后的值,仅在 update 操作时有此信息
removedFieldsstring[]所有被删除的字段,仅在 update 操作时有此信息

QueueType

列表更新类型,表示更新事件对监听列表的影响,枚举值

参数说明
init初始化列表
update列表中的记录内容有更新,但列表包含的记录不变
enqueue记录进入列表
dequeue记录离开列表

DataType

数据更新类型,表示记录的具体更新类型,枚举值

参数说明
init初始化列表
update记录内容更新,对应 update 操作
replace记录内容被替换,对应 set 操作
add记录新增,对应 add 操作
remove记录被删除,对应 remove 操作

IWatcher

close

关闭监听,无需参数,返回 Promise,会在关闭完成时 resolve

() => Promise<any>

IGetDocumentOptions

获取记录参数

参数类型必填说明
configIConfig配置
success(res: T) => void接口调用成功的回调函数
fail(err: CallbackResult) => void接口调用失败的回调函数
complete`(val: CallbackResultT) => void`

ICountDocumentOptions

获取记录条数参数

参数类型必填说明
configIConfig配置
success(res: T) => void接口调用成功的回调函数
fail(err: CallbackResult) => void接口调用失败的回调函数
complete`(val: CallbackResultT) => void`

IUpdateDocumentOptions

更新记录参数

参数类型必填说明
dataIUpdateCondition
configIConfig配置
complete(res: CallbackResult) => void接口调用结束的回调函数(调用成功、失败都会执行)
fail(res: CallbackResult) => void接口调用失败的回调函数
success(res: CallbackResult) => void接口调用成功的回调函数

IUpdateSingleDocumentOptions

更新单条记录参数

参数类型必填说明
dataIUpdateCondition替换记录的定义
configIConfig配置
complete(res: CallbackResult) => void接口调用结束的回调函数(调用成功、失败都会执行)
fail(res: CallbackResult) => void接口调用失败的回调函数
success(res: CallbackResult) => void接口调用成功的回调函数

ISetDocumentOptions

替换记录参数

参数类型必填说明
dataIUpdateCondition替换记录的定义
configIConfig配置
complete(res: CallbackResult) => void接口调用结束的回调函数(调用成功、失败都会执行)
fail(res: CallbackResult) => void接口调用失败的回调函数
success(res: CallbackResult) => void接口调用成功的回调函数

ISetSingleDocumentOptions

替换一条记录参数

参数类型必填说明
dataIUpdateCondition
configIConfig配置
complete(res: CallbackResult) => void接口调用结束的回调函数(调用成功、失败都会执行)
fail(res: CallbackResult) => void接口调用失败的回调函数
success(res: CallbackResult) => void接口调用成功的回调函数

IRemoveDocumentOptions

删除记录参数

参数类型必填说明
queryIQueryCondition
configIConfig配置
complete(res: CallbackResult) => void接口调用结束的回调函数(调用成功、失败都会执行)
fail(res: CallbackResult) => void接口调用失败的回调函数
success(res: CallbackResult) => void接口调用成功的回调函数

IRemoveSingleDocumentOptions

删除一条记录参数

参数类型必填说明
configIConfig配置
success(res: T) => void接口调用成功的回调函数
fail(err: CallbackResult) => void接口调用失败的回调函数
complete`(val: CallbackResultT) => void`

IUpdateCondition

更新记录定义

参数类型
__index__index

API 支持度

API微信小程序百度小程序支付宝小程序字节跳动小程序QQ 小程序H5React Native快应用
Document.get✔️
Document.set✔️
Document.update✔️
Document.remove✔️

Query

数据库 Query 引用

参考文档

where

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

参考文档

(condition: IQueryCondition) => Query
参数类型
conditionIQueryCondition
示例代码
const _ = db.command
const result = await db.collection('todos').where({
price: _.lt(100)
}).get()
API 支持度
API微信小程序百度小程序支付宝小程序字节跳动小程序QQ 小程序H5React Native快应用
Query.where✔️

orderBy

指定查询排序条件

参考文档

(fieldPath: string, order: string) => Query
参数类型
fieldPathstring
orderstring
示例代码

按一个字段排序:按进度排升序取待办事项

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)
API 支持度
API微信小程序百度小程序支付宝小程序字节跳动小程序QQ 小程序H5React Native快应用
Query.orderBy✔️

limit

指定查询结果集数量上限

参考文档

(max: number) => Query
参数类型
maxnumber
示例代码
db.collection('todos').limit(10)
.get()
.then(console.log)
.catch(console.error)
API 支持度
API微信小程序百度小程序支付宝小程序字节跳动小程序QQ 小程序H5React Native快应用
Query.limit✔️

skip

指定查询返回结果时从指定序列后的结果开始返回,常用于分页

参考文档

(offset: number) => Query
参数类型
offsetnumber
示例代码
db.collection('todos').skip(10)
.get()
.then(console.log)
.catch(console.error)
API 支持度
API微信小程序百度小程序支付宝小程序字节跳动小程序QQ 小程序H5React Native快应用
Query.skip✔️

field

指定返回结果中记录需返回的字段

说明

方法接受一个必填对象用于指定需返回的字段,对象的各个 key 表示要返回或不要返回的字段,value 传入 true|false(或 1|-1)表示要返回还是不要返回。 如果指定的字段是数组字段,还可以用以下方法只返回数组的第一个元素:在该字段 key 后面拼接上 .$ 成为 字段.$ 的形式。 如果指定的字段是数组字段,还可以用 db.command.project.slice 方法返回数组的子数组: 方法既可以接收一个正数表示返回前 n 个元素,也可以接收一个负数表示返回后 n 个元素;还可以接收一个包含两个数字 [ skip, limit ] 的数组,如果 skip 是正数,表示跳过 skip 个元素后再返回接下来的 limit 个元素,如果 skip 是负数,表示从倒数第 skip 个元素开始,返回往后数的 limit 个元素

  • 返回数组的前 5 个元素:{ tags: db.command.project.slice(5) }
  • 返回数组的后 5 个元素:{ tags: db.command.project.slice(-5) }
  • 跳过前 5 个元素,返回接下来 10 个元素:{ tags: db.command.project.slice(5, 10) }
  • 从倒数第 5 个元素开始,返回接下来正方向数的 10 个元素:{ tags: db.command.project.slice(-5, 10) }

参考文档

(object: Record<string, any>) => Query
参数类型
objectRecord<string, any>
示例代码

返回 description, done 和 progress 三个字段:

db.collection('todos').field({
description: true,
done: true,
progress: true,
// 只返回 tags 数组前 3 个元素
tags: db.command.project.slice(3),
})
.get()
.then(console.log)
.catch(console.error)
API 支持度
API微信小程序百度小程序支付宝小程序字节跳动小程序QQ 小程序H5React Native快应用
Query.field✔️

get

获取集合数据,或获取根据查询条件筛选后的集合数据。

使用说明

统计集合记录数或统计查询语句对应的结果记录数

小程序端与云函数端的表现会有如下差异:

  • 小程序端:如果没有指定 limit,则默认且最多取 20 条记录。
  • 云函数端:如果没有指定 limit,则默认且最多取 100 条记录。

如果没有指定 skip,则默认从第 0 条记录开始取,skip 常用于分页。

如果需要取集合中所有的数据,仅在数据量不大且在云函数中时

参考文档

{ (options: OQ<IDBAPIParam>): void; (options: Pick<IDBAPIParam, "config">): Promise<IQueryResult>; }
参数类型
optionsOQ<IDBAPIParam>
示例代码
const db = Taro.cloud.database()
db.collection('todos').where({
_openid: 'xxx' // 填入当前用户 openid
}).get().then(res => {
console.log(res.data)
})
API 支持度
API微信小程序百度小程序支付宝小程序字节跳动小程序QQ 小程序H5React Native快应用
Query.get✔️

count

统计匹配查询条件的记录的条数

参考文档

{ (options: OQ<IDBAPIParam>): void; (options: Pick<IDBAPIParam, "config">): Promise<ICountResult>; }
参数类型
optionsOQ<IDBAPIParam>
示例代码
示例 1
const db = Taro.cloud.database()
db.collection('todos').where({
_openid: 'xxx' // 填入当前用户 openid
}).count().then(res => {
console.log(res.total)
})
示例 2
const db = Taro.cloud.database()
db.collection('todos').where({
_openid: 'xxx' // 填入当前用户 openid
}).count({
success: function(res) {
console.log(res.total)
},
fail: console.error
})
API 支持度
API微信小程序百度小程序支付宝小程序字节跳动小程序QQ 小程序H5React Native快应用
Query.count✔️

IQueryCondition

参数类型
__index__index

IStringQueryCondition

IQueryResult

参数类型说明
dataIDocumentData[]查询的结果数组,数据的每个元素是一个 Object,代表一条记录
errMsgstring调用结果

IQuerySingleResult

参数类型说明
dataIDocumentData
errMsgstring调用结果

IAddResult

参数类型说明
_id`stringnumber`
errMsgstring调用结果

IUpdateResult

参数类型说明
stats{ updated: number; }
errMsgstring调用结果

ISetResult

参数类型说明
_id`stringnumber`
stats{ updated: number; created: number; }
errMsgstring调用结果

IRemoveResult

参数类型说明
stats{ removed: number; }
errMsgstring调用结果

ICountResult

参数类型说明
totalnumber结果数量
errMsgstring调用结果

API 支持度

API微信小程序百度小程序支付宝小程序字节跳动小程序QQ 小程序H5React Native快应用
Query.where✔️
Query.orderBy✔️
Query.limit✔️
Query.skip✔️
Query.field✔️
Query.get✔️
Query.count✔️

Command

数据库操作符,通过 db.command 获取

参考文档

eq

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

参考文档

(val: any) => DatabaseQueryCommand
API 支持度
API微信小程序百度小程序支付宝小程序字节跳动小程序QQ 小程序H5React Native快应用
Command.eq✔️

neq

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

参考文档

(val: any) => DatabaseQueryCommand
API 支持度
API微信小程序百度小程序支付宝小程序字节跳动小程序QQ 小程序H5React Native快应用
Command.neq✔️

gt

查询筛选操作符,表示需大于指定值。可以传入 Date 对象用于进行日期比较。

参考文档

(val: any) => DatabaseQueryCommand

gte

查询筛选操作符,表示需大于或等于指定值。可以传入 Date 对象用于进行日期比较。

参考文档

(val: any) => DatabaseQueryCommand
API 支持度
API微信小程序百度小程序支付宝小程序字节跳动小程序QQ 小程序H5React Native快应用
Command.gte✔️

lt

查询筛选操作符,表示需小于指定值。可以传入 Date 对象用于进行日期比较。

参考文档

(val: any) => DatabaseQueryCommand
API 支持度
API微信小程序百度小程序支付宝小程序字节跳动小程序QQ 小程序H5React Native快应用
Command.lt✔️

lte

查询筛选操作符,表示需小于或等于指定值。可以传入 Date 对象用于进行日期比较。

参考文档

(val: any) => DatabaseQueryCommand
API 支持度
API微信小程序百度小程序支付宝小程序字节跳动小程序QQ 小程序H5React Native快应用
Command.lte✔️

in

查询筛选操作符,表示要求值在给定的数组内。

参考文档

(val: any[]) => DatabaseQueryCommand
参数类型
valany[]
API 支持度
API微信小程序百度小程序支付宝小程序字节跳动小程序QQ 小程序H5React Native快应用
Command.in✔️

nin

查询筛选操作符,表示要求值不在给定的数组内。

参考文档

(val: any[]) => DatabaseQueryCommand
参数类型
valany[]
API 支持度
API微信小程序百度小程序支付宝小程序字节跳动小程序QQ 小程序H5React Native快应用
Command.nin✔️

geoNear

按从近到远的顺序,找出字段值在给定点的附近的记录。

参考文档

(options: NearCommandOptions) => DatabaseQueryCommand
参数类型
optionsNearCommandOptions
API 支持度
API微信小程序百度小程序支付宝小程序字节跳动小程序QQ 小程序H5React Native快应用
Command.geoNear✔️

geoWithin

找出字段值在指定区域内的记录,无排序。指定的区域必须是多边形(Polygon)或多边形集合(MultiPolygon)。

参考文档

(options: WithinCommandOptions) => DatabaseQueryCommand
参数类型
optionsWithinCommandOptions
API 支持度
API微信小程序百度小程序支付宝小程序字节跳动小程序QQ 小程序H5React Native快应用
Command.geoWithin✔️

geoIntersects

找出给定的地理位置图形相交的记录

参考文档

(options: IntersectsCommandOptions) => DatabaseQueryCommand
参数类型
optionsIntersectsCommandOptions
API 支持度
API微信小程序百度小程序支付宝小程序字节跳动小程序QQ 小程序H5React Native快应用
Command.geoIntersects✔️

and

查询操作符,用于表示逻辑 "与" 的关系,表示需同时满足多个查询筛选条件

参考文档

(...expressions: (IQueryCondition | DatabaseLogicCommand)[]) => DatabaseLogicCommand
参数类型
expressions`(IQueryCondition
API 支持度
API微信小程序百度小程序支付宝小程序字节跳动小程序QQ 小程序H5React Native快应用
Command.and✔️

or

查询操作符,用于表示逻辑 "或" 的关系,表示需同时满足多个查询筛选条件。或指令有两种用法,一是可以进行字段值的 “或” 操作,二是也可以进行跨字段的 “或” 操作。

参考文档

(...expressions: (IQueryCondition | DatabaseLogicCommand)[]) => DatabaseLogicCommand
参数类型
expressions`(IQueryCondition
API 支持度
API微信小程序百度小程序支付宝小程序字节跳动小程序QQ 小程序H5React Native快应用
Command.or✔️

set

查询操作符,用于表示逻辑 "与" 的关系,表示需同时满足多个查询筛选条件

参考文档

(val: any) => DatabaseUpdateCommand
API 支持度
API微信小程序百度小程序支付宝小程序字节跳动小程序QQ 小程序H5React Native快应用
Command.set✔️

remove

更新操作符,用于表示删除某个字段。

参考文档

() => DatabaseUpdateCommand
API 支持度
API微信小程序百度小程序支付宝小程序字节跳动小程序QQ 小程序H5React Native快应用
Command.remove✔️

inc

更新操作符,原子操作,用于指示字段自增

参考文档

(val: number) => DatabaseUpdateCommand
参数类型
valnumber
API 支持度
API微信小程序百度小程序支付宝小程序字节跳动小程序QQ 小程序H5React Native快应用
Command.inc✔️

mul

更新操作符,原子操作,用于指示字段自乘某个值

参考文档

(val: number) => DatabaseUpdateCommand
参数类型
valnumber
API 支持度
API微信小程序百度小程序支付宝小程序字节跳动小程序QQ 小程序H5React Native快应用
Command.mul✔️

push

数组更新操作符。对一个值为数组的字段,往数组添加一个或多个值。或字段原为空,则创建该字段并设数组为传入值。

参考文档

(...values: any[]) => DatabaseUpdateCommand
参数类型
valuesany[]
API 支持度
API微信小程序百度小程序支付宝小程序字节跳动小程序QQ 小程序H5React Native快应用
Command.push✔️

pop

数组更新操作符,对一个值为数组的字段,将数组尾部元素删除

参考文档

() => DatabaseUpdateCommand
API 支持度
API微信小程序百度小程序支付宝小程序字节跳动小程序QQ 小程序H5React Native快应用
Command.pop✔️

shift

数组更新操作符,对一个值为数组的字段,将数组头部元素删除。

参考文档

() => DatabaseUpdateCommand
API 支持度
API微信小程序百度小程序支付宝小程序字节跳动小程序QQ 小程序H5React Native快应用
Command.shift✔️

unshift

数组更新操作符,对一个值为数组的字段,往数组头部添加一个或多个值。或字段原为空,则创建该字段并设数组为传入值。

参考文档

(...values: any[]) => DatabaseUpdateCommand
参数类型
valuesany[]
API 支持度
API微信小程序百度小程序支付宝小程序字节跳动小程序QQ 小程序H5React Native快应用
Command.unshift✔️

DatabaseLogicCommand

数据库逻辑操作符

参数类型说明
fieldName`stringInternalSymbol`
operatorstring操作符
operandsany[]操作数
_setFieldName(fieldName: string) => DatabaseLogicCommand设置作用域名称
and

查询操作符,用于表示逻辑 "与" 的关系,表示需同时满足多个查询筛选条件

参考文档

(...expressions: (IQueryCondition | DatabaseLogicCommand)[]) => DatabaseLogicCommand
参数类型
expressions`(IQueryCondition
API 支持度
API微信小程序百度小程序支付宝小程序字节跳动小程序QQ 小程序H5React Native快应用
DatabaseLogicCommand.and✔️
or

查询操作符,用于表示逻辑 "或" 的关系,表示需同时满足多个查询筛选条件。或指令有两种用法,一是可以进行字段值的 “或” 操作,二是也可以进行跨字段的 “或” 操作。

参考文档

(...expressions: (IQueryCondition | DatabaseLogicCommand)[]) => DatabaseLogicCommand
参数类型
expressions`(IQueryCondition
API 支持度
API微信小程序百度小程序支付宝小程序字节跳动小程序QQ 小程序H5React Native快应用
DatabaseLogicCommand.or✔️
API 支持度
API微信小程序百度小程序支付宝小程序字节跳动小程序QQ 小程序H5React Native快应用
DatabaseLogicCommand.and✔️
DatabaseLogicCommand.or✔️

DatabaseQueryCommand

数据库查询操作符

参数类型说明
operatorstring操作符
_setFieldName(fieldName: string) => DatabaseQueryCommand设置作用域名称
eq

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

参考文档

(val: any) => DatabaseLogicCommand
API 支持度
API微信小程序百度小程序支付宝小程序字节跳动小程序QQ 小程序H5React Native快应用
DatabaseQueryCommand.eq✔️
neq

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

参考文档

(val: any) => DatabaseLogicCommand
API 支持度
API微信小程序百度小程序支付宝小程序字节跳动小程序QQ 小程序H5React Native快应用
DatabaseQueryCommand.neq✔️
gt

查询筛选操作符,表示需大于指定值。可以传入 Date 对象用于进行日期比较。

参考文档

(val: any) => DatabaseLogicCommand
API 支持度
API微信小程序百度小程序支付宝小程序字节跳动小程序QQ 小程序H5React Native快应用
DatabaseQueryCommand.gt✔️
gte

查询筛选操作符,表示需大于或等于指定值。可以传入 Date 对象用于进行日期比较。

参考文档

(val: any) => DatabaseLogicCommand
API 支持度
API微信小程序百度小程序支付宝小程序字节跳动小程序QQ 小程序H5React Native快应用
DatabaseQueryCommand.gte✔️
lt

查询筛选操作符,表示需小于指定值。可以传入 Date 对象用于进行日期比较。

参考文档

(val: any) => DatabaseLogicCommand
API 支持度
API微信小程序百度小程序支付宝小程序字节跳动小程序QQ 小程序H5React Native快应用
DatabaseQueryCommand.lt✔️
lte

查询筛选操作符,表示需小于或等于指定值。可以传入 Date 对象用于进行日期比较。

参考文档

(val: any) => DatabaseLogicCommand
API 支持度
API微信小程序百度小程序支付宝小程序字节跳动小程序QQ 小程序H5React Native快应用
DatabaseQueryCommand.lte✔️
in

查询筛选操作符,表示要求值在给定的数组内。

参考文档

(val: any[]) => DatabaseLogicCommand
参数类型
valany[]
API 支持度
API微信小程序百度小程序支付宝小程序字节跳动小程序QQ 小程序H5React Native快应用
DatabaseQueryCommand.in✔️
nin

查询筛选操作符,表示要求值不在给定的数组内。

参考文档

(val: any[]) => DatabaseLogicCommand
参数类型
valany[]
API 支持度
API微信小程序百度小程序支付宝小程序字节跳动小程序QQ 小程序H5React Native快应用
DatabaseQueryCommand.nin✔️
geoNear

按从近到远的顺序,找出字段值在给定点的附近的记录。

参考文档

(options: NearCommandOptions) => DatabaseLogicCommand
参数类型
optionsNearCommandOptions
API 支持度
API微信小程序百度小程序支付宝小程序字节跳动小程序QQ 小程序H5React Native快应用
DatabaseQueryCommand.geoNear✔️
geoWithin

找出字段值在指定区域内的记录,无排序。指定的区域必须是多边形(Polygon)或多边形集合(MultiPolygon)。

参考文档

(options: WithinCommandOptions) => DatabaseLogicCommand
参数类型
optionsWithinCommandOptions
API 支持度
API微信小程序百度小程序支付宝小程序字节跳动小程序QQ 小程序H5React Native快应用
DatabaseQueryCommand.geoWithin✔️
geoIntersects

找出给定的地理位置图形相交的记录

参考文档

(options: IntersectsCommandOptions) => DatabaseLogicCommand
参数类型
optionsIntersectsCommandOptions
API 支持度
API微信小程序百度小程序支付宝小程序字节跳动小程序QQ 小程序H5React Native快应用
DatabaseQueryCommand.geoIntersects✔️
API 支持度
API微信小程序百度小程序支付宝小程序字节跳动小程序QQ 小程序H5React Native快应用
DatabaseQueryCommand.eq✔️
DatabaseQueryCommand.neq✔️
DatabaseQueryCommand.gt✔️
DatabaseQueryCommand.gte✔️
DatabaseQueryCommand.lt✔️
DatabaseQueryCommand.lte✔️
DatabaseQueryCommand.in✔️
DatabaseQueryCommand.nin✔️
DatabaseQueryCommand.geoNear✔️
DatabaseQueryCommand.geoWithin✔️
DatabaseQueryCommand.geoIntersects✔️

DatabaseUpdateCommand

数据库更新操作符

参数类型说明
fieldName`stringInternalSymbol`
operator`"remove""set"
operandsany[]操作数
_setFieldName(fieldName: string) => DatabaseUpdateCommand设置作用域名称

LOGIC_COMMANDS_LITERAL

逻辑命令字面量

参数说明
and
or
not
nor都不

QUERY_COMMANDS_LITERAL

查询命令字面量

参数说明
eq等于
neq不等于
gt大于
gte大于等于
lt小于
lte小于等于
in范围内
nin范围外
geoNear附近排序
geoWithin指定区域内
geoIntersects相交区域

UPDATE_COMMANDS_LITERAL

更新命令字面量

参数说明
set等于
remove删除
inc自增
mul自乘
push尾部添加
pop尾部删除
shift头部删除
unshift头部添加

NearCommandOptions

按从近到远的顺序,找出字段值在给定点的附近的记录参数

参数类型必填说明
geometryGeoPoint地理位置点 (Point)
maxDistancenumber最大距离,单位为米
minDistancenumber最小距离,单位为米

WithinCommandOptions

找出字段值在指定区域内的记录,无排序参数

参数类型说明
geometry`GeoPolygonGeoMultiPolygon`

IntersectsCommandOptions

找出给定的地理位置图形相交的记录

参数类型说明
geometry`GeoPointGeoPolygon

API 支持度

API微信小程序百度小程序支付宝小程序字节跳动小程序QQ 小程序H5React Native快应用
Command.eq✔️
Command.neq✔️
Command.gte✔️
Command.lt✔️
Command.lte✔️
Command.in✔️
Command.nin✔️
Command.geoNear✔️
Command.geoWithin✔️
Command.geoIntersects✔️
Command.and✔️
Command.or✔️
Command.set✔️
Command.remove✔️
Command.inc✔️
Command.mul✔️
Command.push✔️
Command.pop✔️
Command.shift✔️
Command.unshift✔️

Aggregate

数据库集合的聚合操作实例

参考文档

addFields

聚合阶段。添加新字段到输出的记录。经过 addFields 聚合阶段,输出的所有记录中除了输入时带有的字段外,还将带有 addFields 指定的字段。

参考文档

(object: Object) => Aggregate
参数类型
objectObject
API 支持度
API微信小程序百度小程序支付宝小程序字节跳动小程序QQ 小程序H5React Native快应用
Aggregate.addFields✔️

bucket

聚合阶段。将输入记录根据给定的条件和边界划分成不同的组,每组即一个 bucket。

参考文档

(object: Object) => Aggregate
参数类型
objectObject
API 支持度
API微信小程序百度小程序支付宝小程序字节跳动小程序QQ 小程序H5React Native快应用
Aggregate.bucket✔️

bucketAuto

聚合阶段。将输入记录根据给定的条件划分成不同的组,每组即一个 bucket。与 bucket 的其中一个不同之处在于无需指定 boundaries,bucketAuto 会自动尝试将记录尽可能平均的分散到每组中。

参考文档

(object: Object) => Aggregate
参数类型
objectObject
API 支持度
API微信小程序百度小程序支付宝小程序字节跳动小程序QQ 小程序H5React Native快应用
Aggregate.bucketAuto✔️

count

聚合阶段。计算上一聚合阶段输入到本阶段的记录数,输出一个记录,其中指定字段的值为记录数。

参考文档

(fieldName: string) => Aggregate
参数类型
fieldNamestring
API 支持度
API微信小程序百度小程序支付宝小程序字节跳动小程序QQ 小程序H5React Native快应用
Aggregate.count✔️

end

标志聚合操作定义完成,发起实际聚合操作

参考文档

() => Promise<Object>
API 支持度
API微信小程序百度小程序支付宝小程序字节跳动小程序QQ 小程序H5React Native快应用
Aggregate.end✔️

geoNear

聚合阶段。将记录按照离给定点从近到远输出。

参考文档

(options: Object) => Aggregate
参数类型
optionsObject
API 支持度
API微信小程序百度小程序支付宝小程序字节跳动小程序QQ 小程序H5React Native快应用
Aggregate.geoNear✔️

group

聚合阶段。将输入记录按给定表达式分组,输出时每个记录代表一个分组,每个记录的 _id 是区分不同组的 key。输出记录中也可以包括累计值,将输出字段设为累计值即会从该分组中计算累计值。

参考文档

(object: Object) => Aggregate
参数类型
objectObject
API 支持度
API微信小程序百度小程序支付宝小程序字节跳动小程序QQ 小程序H5React Native快应用
Aggregate.group✔️

limit

聚合阶段。限制输出到下一阶段的记录数。

参考文档

(value: number) => Aggregate
参数类型
valuenumber
API 支持度
API微信小程序百度小程序支付宝小程序字节跳动小程序QQ 小程序H5React Native快应用
Aggregate.limit✔️

lookup

聚合阶段。聚合阶段。联表查询。与同个数据库下的一个指定的集合做 left outer join(左外连接)。对该阶段的每一个输入记录,lookup 会在该记录中增加一个数组字段,该数组是被联表中满足匹配条件的记录列表。lookup 会将连接后的结果输出给下个阶段。

参考文档

(object: Object) => Aggregate
参数类型
objectObject
API 支持度
API微信小程序百度小程序支付宝小程序字节跳动小程序QQ 小程序H5React Native快应用
Aggregate.lookup✔️

match

聚合阶段。根据条件过滤文档,并且把符合条件的文档传递给下一个流水线阶段。

参考文档

(object: Object) => Aggregate
参数类型
objectObject
API 支持度
API微信小程序百度小程序支付宝小程序字节跳动小程序QQ 小程序H5React Native快应用
Aggregate.match✔️

project

聚合阶段。把指定的字段传递给下一个流水线,指定的字段可以是某个已经存在的字段,也可以是计算出来的新字段。

参考文档

(object: Object) => Aggregate
参数类型
objectObject
API 支持度
API微信小程序百度小程序支付宝小程序字节跳动小程序QQ 小程序H5React Native快应用
Aggregate.project✔️

replaceRoot

聚合阶段。指定一个已有字段作为输出的根节点,也可以指定一个计算出的新字段作为根节点。

参考文档

(object: Object) => Aggregate
参数类型
objectObject
API 支持度
API微信小程序百度小程序支付宝小程序字节跳动小程序QQ 小程序H5React Native快应用
Aggregate.replaceRoot✔️

sample

聚合阶段。随机从文档中选取指定数量的记录。

参考文档

(size: number) => Aggregate
参数类型
sizenumber
API 支持度
API微信小程序百度小程序支付宝小程序字节跳动小程序QQ 小程序H5React Native快应用
Aggregate.sample✔️

skip

聚合阶段。指定一个正整数,跳过对应数量的文档,输出剩下的文档。

参考文档

(value: number) => Aggregate
参数类型
valuenumber
API 支持度
API微信小程序百度小程序支付宝小程序字节跳动小程序QQ 小程序H5React Native快应用
Aggregate.skip✔️

sort

聚合阶段。根据指定的字段,对输入的文档进行排序。

参考文档

(object: Object) => Aggregate
参数类型
objectObject
API 支持度
API微信小程序百度小程序支付宝小程序字节跳动小程序QQ 小程序H5React Native快应用
Aggregate.sort✔️

sortByCount

聚合阶段。根据传入的表达式,将传入的集合进行分组(group)。然后计算不同组的数量,并且将这些组按照它们的数量进行排序,返回排序后的结果。

参考文档

(object: Object) => Aggregate
参数类型
objectObject
API 支持度
API微信小程序百度小程序支付宝小程序字节跳动小程序QQ 小程序H5React Native快应用
Aggregate.sortByCount✔️

unwind

聚合阶段。使用指定的数组字段中的每个元素,对文档进行拆分。拆分后,文档会从一个变为一个或多个,分别对应数组的每个元素。

参考文档

(value: string | object) => Aggregate
参数类型
value`string
API 支持度
API微信小程序百度小程序支付宝小程序字节跳动小程序QQ 小程序H5React Native快应用
Aggregate.unwind✔️

API 支持度

API微信小程序百度小程序支付宝小程序字节跳动小程序QQ 小程序H5React Native快应用
Aggregate.addFields✔️
Aggregate.bucket✔️
Aggregate.bucketAuto✔️
Aggregate.count✔️
Aggregate.end✔️
Aggregate.geoNear✔️
Aggregate.group✔️
Aggregate.limit✔️
Aggregate.lookup✔️
Aggregate.match✔️
Aggregate.project✔️
Aggregate.replaceRoot✔️
Aggregate.sample✔️
Aggregate.skip✔️
Aggregate.sort✔️
Aggregate.sortByCount✔️
Aggregate.unwind✔️

IGeo

数据库地理位置结构集

参考文档

Point

构造一个地理位置 ”点“。方法接受两个必填参数,第一个是经度(longitude),第二个是纬度(latitude),务必注意顺序。

如存储地理位置信息的字段有被查询的需求,务必对字段建立地理位置索引

参考文档

(longitude: number, latitide: number) => GeoPoint
参数类型
longitudenumber
latitidenumber
示例代码
示例 1
db.collection('todos').add({
data: {
description: 'eat an apple',
location: db.Geo.Point(113, 23)
}
}).then(console.log).catch(console.error)
示例 2

除了使用接口构造一个点外,也可以使用等价的 GeoJSON 的 点 (Point) 的 JSON 表示,其格式如下:

{
"type": "Point",
"coordinates": [longitude, latitude] // 数字数组:[经度, 纬度]
}
db.collection('todos').add({
data: {
description: 'eat an apple',
location: {
type: 'Point',
coordinates: [113, 23]
}
}
}).then(console.log).catch(console.error)
API 支持度
API微信小程序百度小程序支付宝小程序字节跳动小程序QQ 小程序H5React Native快应用
IGeo.Point✔️

LineString

构造一个地理位置的 ”线“。一个线由两个或更多的点有序连接组成。

如存储地理位置信息的字段有被查询的需求,务必对字段建立地理位置索引

参考文档

(points: JSONMultiPoint | GeoPoint[]) => GeoMultiPoint
参数类型
points`JSONMultiPoint
示例代码
示例 1
db.collection('todos').add({
data: {
description: 'eat an apple',
location: db.Geo.LineString([
db.Geo.Point(113, 23),
db.Geo.Point(120, 50),
// ... 可选更多点
])
}
}).then(console.log).catch(console.error)
示例 2

除了使用接口构造一条 LineString 外,也可以使用等价的 GeoJSON 的 线 (LineString) 的 JSON 表示,其格式如下:

{
"type": "LineString",
"coordinates": [
[p1_lng, p1_lat],
[p2_lng, p2_lng]
// ... 可选更多点
]
}
db.collection('todos').add({
data: {
description: 'eat an apple',
location: {
type: 'LineString',
coordinates: [
[113, 23],
[120, 50]
]
}
}
}).then(console.log).catch(console.error)
API 支持度
API微信小程序百度小程序支付宝小程序字节跳动小程序QQ 小程序H5React Native快应用
IGeo.LineString✔️

Polygon

构造一个地理位置 ”多边形“

如存储地理位置信息的字段有被查询的需求,务必对字段建立地理位置索引

说明

一个多边形由一个或多个线性环(Linear Ring)组成,一个线性环即一个闭合的线段。一个闭合线段至少由四个点组成,其中最后一个点和第一个点的坐标必须相同,以此表示环的起点和终点。如果一个多边形由多个线性环组成,则第一个线性环表示外环(外边界),接下来的所有线性环表示内环(即外环中的洞,不计在此多边形中的区域)。如果一个多边形只有一个线性环组成,则这个环就是外环。

多边形构造规则:

  1. 第一个线性环必须是外环
  2. 外环不能自交
  3. 所有内环必须完全在外环内
  4. 各个内环间不能相交或重叠,也不能有共同的边
  5. 外环应为逆时针,内环应为顺时针

参考文档

(lineStrings: JSONPolygon | GeoLineString[]) => GeoPolygon
参数类型
lineStrings`JSONPolygon
示例代码
示例 1

单环多边形

const { Polygon, LineString, Point } = db.Geo
db.collection('todos').add({
data: {
description: 'eat an apple',
location: Polygon([
LineString([
Point(0, 0),
Point(3, 2),
Point(2, 3),
Point(0, 0)
])
])
}
}).then(console.log).catch(console.error)
示例 2

含一个外环和一个内环的多边形

const { Polygon, LineString, Point } = db.Geo
db.collection('todos').add({
data: {
description: 'eat an apple',
location: Polygon([
// 外环
LineString([ Point(0, 0), Point(30, 20), Point(20, 30), Point(0, 0) ]),
// 内环
LineString([ Point(10, 10), Point(16, 14), Point(14, 16), Point(10, 10) ])
])
}
}).then(console.log).catch(console.error)
示例 3

除了使用接口构造一个 Polygon 外,也可以使用等价的 GeoJSON 的 多边形 (Polygon) 的 JSON 表示,其格式如下:

{
"type": "Polygon",
"coordinates": [
[ [lng, lat], [lng, lat], [lng, lat], ..., [lng, lat] ], // 外环
[ [lng, lat], [lng, lat], [lng, lat], ..., [lng, lat] ], // 可选内环 1
...
[ [lng, lat], [lng, lat], [lng, lat], ..., [lng, lat] ], // 可选内环 n
]
}
db.collection('todos').add({
data: {
description: 'eat an apple',
location: {
type: 'Polygon',
coordinates: [
[ [0, 0], [30, 20], [20, 30], [0, 0] ],
[ [10, 10], [16, 14], [14, 16], [10, 10]]
]
}
}
}).then(console.log).catch(console.error)
API 支持度
API微信小程序百度小程序支付宝小程序字节跳动小程序QQ 小程序H5React Native快应用
IGeo.Polygon✔️

MultiPoint

构造一个地理位置的 ”点“ 的集合。一个点集合由一个或更多的点组成。

如存储地理位置信息的字段有被查询的需求,务必对字段建立地理位置索引

参考文档

(polygons: JSONMultiPolygon | GeoPolygon[]) => GeoMultiPolygon
参数类型
polygons`JSONMultiPolygon
示例代码
示例 1
db.collection('todos').add({
data: {
description: 'eat an apple',
location: db.Geo.MultiPoint([
db.Geo.Point(113, 23),
db.Geo.Point(120, 50),
// ... 可选更多点
])
}
}).then(console.log).catch(console.error)
示例 2

除了使用接口构造 MultiPoint 外,也可以使用等价的 GeoJSON 的 点集合 (MultiPoint) 的 JSON 表示,其格式如下:

{
"type": "MultiPoint",
"coordinates": [
[p1_lng, p1_lat],
[p2_lng, p2_lng]
// ... 可选更多点
]
}
db.collection('todos').add({
data: {
description: 'eat an apple',
location: {
type: 'MultiPoint',
coordinates: [
[113, 23],
[120, 50]
]
}
}
}).then(console.log).catch(console.error)
API 支持度
API微信小程序百度小程序支付宝小程序字节跳动小程序QQ 小程序H5React Native快应用
IGeo.MultiPoint✔️

MultiLineString

构造一个地理位置 ”线“ 集合。一个线集合由多条线组成。

如存储地理位置信息的字段有被查询的需求,务必对字段建立地理位置索引

参考文档

(lineStrings: JSONMultiLineString | GeoLineString[]) => GeoMultiLineString
参数类型
lineStrings`JSONMultiLineString
示例代码
示例 1
const { LineString, MultiLineString, Point } = db.Geo
db.collection('todos').add({
data: {
description: 'eat an apple',
location: MultiLineString([
LineString([ Point(0, 0), Point(30, 20), Point(20, 30), Point(0, 0) ]),
LineString([ Point(10, 10), Point(16, 14), Point(14, 16), Point(10, 10) ])
])
}
}).then(console.log).catch(console.error)
示例 2

除了使用接口构造一个 MultiLineString 外,也可以使用等价的 GeoJSON 的 线集合 (MultiLineString) 的 JSON 表示,其格式如下:

{
"type": "MultiLineString",
"coordinates": [
[ [lng, lat], [lng, lat], [lng, lat], ..., [lng, lat] ],
[ [lng, lat], [lng, lat], [lng, lat], ..., [lng, lat] ],
...
[ [lng, lat], [lng, lat], [lng, lat], ..., [lng, lat] ]
]
}
db.collection('todos').add({
data: {
description: 'eat an apple',
location: {
type: 'MultiLineString',
coordinates: [
[ [0, 0], [3, 3] ],
[ [5, 10], [20, 30] ]
]
}
}
}).then(console.log).catch(console.error)
API 支持度
API微信小程序百度小程序支付宝小程序字节跳动小程序QQ 小程序H5React Native快应用
IGeo.MultiLineString✔️

MultiPolygon

构造一个地理位置 ”多边形“ 集合。一个多边形集合由多个多边形组成。

如存储地理位置信息的字段有被查询的需求,务必对字段建立地理位置索引

说明

一个多边形由一个或多个线性环(Linear Ring)组成,一个线性环即一个闭合的线段。一个闭合线段至少由四个点组成,其中最后一个点和第一个点的坐标必须相同,以此表示环的起点和终点。如果一个多边形由多个线性环组成,则第一个线性环表示外环(外边界),接下来的所有线性环表示内环(即外环中的洞,不计在此多边形中的区域)。如果一个多边形只有一个线性环组成,则这个环就是外环。

多边形构造规则:

  1. 第一个线性环必须是外环
  2. 外环不能自交
  3. 所有内环必须完全在外环内
  4. 各个内环间不能相交或重叠,也不能有共同的边
  5. 外环应为逆时针,内环应为顺时针

参考文档

(polygons: JSONMultiPolygon | GeoPolygon[]) => GeoMultiPolygon
参数类型
polygons`JSONMultiPolygon
示例代码
示例 1
const { MultiPolygon, Polygon, LineString, Point } = db.Geo
db.collection('todos').add({
data: {
description: 'eat an apple',
location: MultiPolygon([
Polygon([
LineString([ Point(50, 50), Point(60, 80), Point(80, 60), Point(50, 50) ]),
]),
Polygon([
LineString([ Point(0, 0), Point(30, 20), Point(20, 30), Point(0, 0) ]),
LineString([ Point(10, 10), Point(16, 14), Point(14, 16), Point(10, 10) ])
]),
])
}
}).then(console.log).catch(console.error)
示例 2

除了使用接口构造一个 MultiPolygon 外,也可以使用等价的 GeoJSON 的 多边形 (MultiPolygon) 的 JSON 表示,其格式如下:

{
"type": "MultiPolygon",
"coordinates": [
// polygon 1
[
[ [lng, lat], [lng, lat], [lng, lat], ..., [lng, lat] ],
[ [lng, lat], [lng, lat], [lng, lat], ..., [lng, lat] ],
...
[ [lng, lat], [lng, lat], [lng, lat], ..., [lng, lat] ]
],
...
// polygon n
[
[ [lng, lat], [lng, lat], [lng, lat], ..., [lng, lat] ],
[ [lng, lat], [lng, lat], [lng, lat], ..., [lng, lat] ],
...
[ [lng, lat], [lng, lat], [lng, lat], ..., [lng, lat] ]
],
]
}
db.collection('todos').add({
data: {
description: 'eat an apple',
location: {
type: 'MultiPolygon',
coordinates: [
[
[ [50, 50], [60, 80], [80, 60], [50, 50] ]
],
[
[ [0, 0], [30, 20], [20, 30], [0, 0] ],
[ [10, 10], [16, 14], [14, 16], [10, 10]]
]
]
}
}
}).then(console.log).catch(console.error)
API 支持度
API微信小程序百度小程序支付宝小程序字节跳动小程序QQ 小程序H5React Native快应用
IGeo.MultiPolygon✔️

GeoPoint

地理位置 “点”

参考文档

参数类型说明
longitudenumber经度
latitudenumber纬度
toJSON

格式化为 JSON 结构

() => object
toString

格式化为字符串

() => string

GeoLineString

地理位置的 ”线“。一个线由两个或更多的点有序连接组成。

参考文档

参数类型说明
pointsGeoPoint[]点集合
toJSON

格式化为 JSON 结构

() => JSONLineString
toString

格式化为字符串

() => string

GeoPolygon

地理位置 ”多边形“

参考文档

参数类型说明
linesGeoLineString[]线集合
toJSON

格式化为 JSON 结构

() => JSONPolygon
toString

格式化为字符串

() => string

GeoMultiPoint

地理位置的 ”点“ 的集合。一个点集合由一个或更多的点组成。

参考文档

参数类型说明
pointsGeoPoint[]点集合
toJSON

格式化为 JSON 结构

() => JSONMultiPoint
toString

格式化为字符串

() => string

GeoMultiLineString

地理位置 ”线“ 集合。一个线集合由多条线组成。

参考文档

参数类型说明
linesGeoLineString[]线集合
toJSON

格式化为 JSON 结构

() => JSONMultiLineString
toString

格式化为字符串

() => string

GeoMultiPolygon

地理位置 ”多边形“ 集合。一个多边形集合由多个多边形组成。

参考文档

参数类型说明
polygonsGeoPolygon[]多边形集合
toJSON

格式化为 JSON 结构

() => JSONMultiPolygon
toString

格式化为字符串

() => string

JSONPoint

地理位置 “点” 的 JSON 结构

参数类型说明
type"Point"类型
coordinates[number, number]坐标

JSONLineString

地理位置 ”线“ 的 JSON 结构

参数类型说明
type"LineString"类型
coordinates[number, number][]坐标

JSONPolygon

地理位置 ”多边形“ 的 JSON 结构

参数类型说明
type"Polygon"类型
coordinates[number, number][][]坐标

JSONMultiPoint

地理位置的 ”点“ 集合的 JSON 结构

参数类型说明
type"MultiPoint"类型
coordinates[number, number][]坐标

JSONMultiLineString

地理位置 ”线“ 集合的 JSON 结构

参数类型说明
type"MultiLineString"类型
coordinates[number, number][][]坐标

JSONMultiPolygon

地理位置 ”多边形“ 集合的 JSON 结构

参数类型说明
type"MultiPolygon"类型
coordinates[number, number][][][]坐标

API 支持度

API微信小程序百度小程序支付宝小程序字节跳动小程序QQ 小程序H5React Native快应用
IGeo.Point✔️
IGeo.LineString✔️
IGeo.Polygon✔️
IGeo.MultiPoint✔️
IGeo.MultiLineString✔️
IGeo.MultiPolygon✔️