参数	类型	默认值	必填	说明	最低支持版本
envID	string	-	是	云环境ID	小程序为2.70.0.0，小游戏为2.88.0.0
serviceID	string	-	否	云服务ID	小程序为2.70.0.0，小游戏为2.88.0.0

返回值

cloud

cloud.database

支持端：小程序（抖音客户端最低版本为 25.4.0），小游戏（抖音客户端最低版本为 25.7.0）。

获取数据库实例

参数说明

参数	类型	默认值	必填	说明	最低支持版本
options	object	-	否	cloud 配置	小程序为2.87.0.0，小游戏为2.88.0.0

options 说明

参数	类型	默认值	必填	说明	最低支持版本
envID	string	-	否	云环境ID，不传 envID 时默认使用 createCloud 的 envID；传入 envID 则会覆盖 createCloud 的配置。	小程序为2.87.0.0，小游戏为2.88.0.0

语法

在调用 cloud.database 方法前必须添加 await 关键字。

const cloud = tt.createCloud({
    envID:'envID',
    serviceID:'serviceID'
}); 
const database = await cloud.database(); // 写法1，不传envID 默认使用 createCloud 时的 envID.
const database1 = await cloud.database({envID: 'newEnvID' }): // 写法2 传入 envID, 则会覆盖 createCloud 时的 envID.

返回值

数据库 Database 实例

Database

数据库实例

属性

Command command

数据库操作符

方法

Database.collection(name: string): Collection

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

Database.serverDate(options: Object): ServerDate

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

Database.Regexp(options: Object): RegExp

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

Collection

集合实例

方法

Collection.doc(id: string): Document

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

Collection.where(condition: Object): Collection

指定查询条件，返回带有新查询条件的集合引用。

Collection.limit(value: number): Collection

指定查询结果集数量上限。

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

指定查询的排序条件。

Collection.field(projection: Object): Collection

指定查询结果中需要返回的字段。

Collection.skip(offset: number): Collection

指定查询返回结果时从指定偏移量后的记录开始返回，常用于分页。

Collection.get(): Promise<Object>

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

Collection.update(): Promise<Object>

更新多条记录。

Collection.remove(): Promise<Object>

删除多条记录。仅支持通过 where 语句匹配删除，不支持 skip 和 limit。

Collection.count(): Promise<Object>

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

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

新增记录，如果传入的记录对象没有 _id 字段，系统会自动生成 _id；若指定了 _id，则不能与已有记录冲突。

Collection.aggregate(): Aggregate

定义完聚合流水线阶段后需调用 end 方法结束定义并执行聚合操作。

Aggregate.addFields(object: Object): Aggregate

聚合阶段。经过 addFields 阶段处理的输出记录，将保留原有字段并新增 addFields 指定的字段。

Aggregate.bucket(object: Object): Aggregate

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

Aggregate.bucketAuto(object: Object): Aggregate

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

Aggregate.count(fieldName: string): Aggregate

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

Aggregate.group(object: Object): Aggregate

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

Aggregate.limit(value: number): Aggregate

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

Aggregate.lookup(object: Object): Aggregate

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

Aggregate.match(object: Object): Aggregate

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

Aggregate.project(object: Object): Aggregate

聚合阶段。把指定字段传递给下一个流水线，这些字段可以是已存在的字段或计算产生的新字段。

Aggregate.replaceRoot(object: Object): Aggregate

聚合阶段。指定已有字段或计算出的新字段作为输出的根节点。

Aggregate.sample(size: number): Aggregate

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

Aggregate.skip(value: number): Aggregate

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

Aggregate.sort(object: Object): Aggregate

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

Aggregate.sortByCount(object: Object): Aggregate

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

Aggregate.unwind(value: string|object): Aggregate

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

Aggregate.end():Promise<Object>

标志着聚合操作定义完成并执行实际聚合操作

Document

数据库记录引用

方法

Document.get(): Promise<Object>

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

Document.set(options: Object): Promise<Object>

此方法用于替换整条记录

Document.update(options: Object): Promise<Object>

更新一条记录

Document.remove(): Promise<Object>

删除一条记录

Command

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

原始 mongo 中筛选年龄大于10的语法为：

db.col.find({age : {$gt : 10}});

利用云数据库封装的 Command 语法可简化为：

const _ = db.command; 
const res = db.collection('todos').where({ age: _.gt(10) )}).get();

云数据库 SDK 封装了标准 $ 操作符以实现正确的查询条件构建

方法

Command.and(expressions: any[]): Command

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

Command.or(expressions: any[]): Command

查询操作符，用于表示逻辑 "或" 的关系。该操作符有两种用法：一是进行字段值的“或”操作，二是进行跨字段的“或”操作。

Command.nor(expressions: any[]):Command

查询操作符，用于表示逻辑 "都不" 的关系，即记录需不满足所有指定的条件。如果记录中没有对应的字段，则默认视为满足该条件。

Command.eq(value: any): Command

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

Command.neq(value: any): Command

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

Command.lt(value: any): Command

查询筛选操作符，表示需小于指定值。

Command.lte(value: any): Command

查询筛选操作符，表示需小于或等于指定值。

Command.gt(value: any): Command

查询筛选操作符，表示需大于指定值。

Command.gte(value: any): Command

查询筛选操作符，表示需大于或等于指定值。

Command.in(value: any[]): Command

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

Command.nin(value: any[]): Command

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

Command.exists(value: boolean): Command

判断字段是否存在。

Command.mod(divisor: number, remainder: number): Command

查询筛选操作符，给定除数 divisor 和余数 remainder，要求字段作为被除数时满足 value % divisor = remainder 的条件。

Command.all(values: any[]): Command

数组查询操作符。用于数组字段的查询筛选条件，要求包含给定数组的所有元素。

Command.elemMatch(condition: Object|Command): Command

用于数组字段的查询筛选条件，要求数组中包含至少一个满足 elemMatch 给定条件的元素。

Command.size(value: number): Command

查询筛选操作符，用于数组字段的查询筛选条件，要求数组长度为给定值。

Command.set(value: any): Command

更新操作符，用于设定字段等于指定值。

Command.remove(): Command

更新操作符，用于删除某个字段。

Command.inc(value: number): Command

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

Command.mul(value: number): Command

更新操作符，原子操作，用于指示字段自增。某个值

Command.min(value: any): Command

更新操作符，给定一个值，仅当该值小于字段当前值时进行更新

Command.max(value: any): Command

更新操作符，给定一个值，仅当该值大于字段当前值时进行更新

Command.rename(value: string): Command

更新操作符，用于字段重命名。若需重命名深层嵌套字段，需采用点表示法路径。注意：无法对数组内部嵌套的对象字段进行重命名。

Command.push(value: Object): Command

数组更新操作符。对一个数组类型字段添加一个或多个值；若字段不存在则创建并初始化为数组

Command.pop(): Command

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

Command.unshift(values:any[]): Command

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

Command.shift(): Command

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

Command.pull(value: any): Command

数组更新操作符。给定一个值或一个查询条件，将数组中所有匹配给定值或查询条件的元素移除。

Command.pullAll(value: any): Command

数组更新操作符。移除所有匹配给定值或查询条件的元素。与 pull 的主要区别：仅支持常量值，且参数必须为数组形式

Command.addToSet(value: any|Object): Command

数组更新操作符（原子操作），向数组添加不存在的一个或多个元素

Command.expr(aggregateExpression: Expression): Command

查询操作符，用于在查询语句中使用聚合表达式。该方法接收一个必须为聚合表达式的参数

AggregateCommand

聚合操作符

方法

AggregateCommand.add(value: Expression[]): Object

聚合操作符。将数字相加或加在日期上。如果数组中的某个值是日期，其他值将视为毫秒数加在该日期上。

AggregateCommand.addToSet(value: Expression): Object

聚合操作符。向数组中添加值，如果数组中已存在该值，不执行任何操作。该操作符仅能在分组阶段（group stage）中使用。

AggregateCommand.avg(value: Expression<number>): Object

聚合操作符。返回一组集合中指定字段对应数据的平均值。

AggregateCommand.first(value: Expression): Object

聚合操作符。返回指定字段在一组集合的第一条记录对应的值。仅当这组集合是按照某种定义排序（ sort ）后，此操作才有意义。

AggregateCommand.last(value: Expression): Object

聚合操作符。返回指定字段在一组集合的最后一条记录对应的值。仅当这组集合是按照某种定义排序（ sort ）后，此操作才有意义。

AggregateCommand.max(value: Expression): Object

聚合操作符。返回一组数值的最大值。

AggregateCommand.mergeObjects(value: Expression<document>): Object

聚合操作符。将多个文档合并为单个文档。

AggregateCommand.min(value: Expression): Object

聚合操作符。返回一组数值的最小值。

AggregateCommand.push(value: any): Object

聚合操作符。在 group 阶段，返回由表达式指定列及其对应值组成的数组。

AggregateCommand.sum(value: Expression): Object

聚合操作符。计算并返回一组字段所有数值的总和。

AggregateCommand.arrayElemAt(value: Expression[]): Object

聚合操作符。返回指定数组下标处的元素。

AggregateCommand.concat(value: Expression[]): Object

聚合操作符。连接字符串并返回拼接结果。