参数	类型	默认值	必填	说明	最低支持版本
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 时的 envID。	小程序为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, string: order): 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

查询筛选条件，表示字段不等于某个值。eq 指令接受一个字面量 (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: string): 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

聚合操作符。连接字符串，返回拼接后的字符串。