跳到主要内容

概述

Database API 提供了一套完整的文档数据库操作功能，支持数据的增删改查、复杂查询、聚合操作、地理位置查询和事务操作。

Database API 按照功能用途分为以下类别：

基础使用示例​

Publishable Key 可前往 云开发平台/API Key 配置 中生成

import cloudbase from "@cloudbase/js-sdk";

// 初始化
const app = cloudbase.init({
  env: "your-env-id", // 替换为您的环境ID
  region: "ap-shanghai", // 地域，默认为上海
  accessKey: "", // 填入生成的 Publishable Key
});

// 获取数据库引用
const db = app.database();
// 获取查询指令
const _ = db.command;
// 获取地理位置类型
const Geo = db.Geo;

初始化​

database​

app.database(config?: IDbConfig): Database

获取数据库实例，用于后续的数据库操作。实例信息获取请到云开发平台/文档醒数据库中查看

参数

config
IDbConfig

数据库配置对象（可选）

返回

Database
Database

数据库实例对象，可调用 collection()、command、Geo、serverDate() 等属性和方法

示例

import cloudbase from "@cloudbase/js-sdk";

// 初始化应用
const app = cloudbase.init({
  env: "your-env-id", // 替换为您的环境ID
  region: "ap-shanghai", // 地域，默认为上海
  accessKey: "", // 填入生成的 Publishable Key
});

// 获取数据库引用（使用默认配置）
const db = app.database();

// 获取查询指令
const _ = db.command;

// 获取地理位置类型
const Geo = db.Geo;

集合方法​

createCollection​

async db.createCollection(collName: string): Promise<ICreateCollectionResult>

创建集合。

参数

collName
string

集合名称

返回

Promise
ICreateCollectionResult

创建结果

示例

// 创建新集合
const result = await db.createCollection("new-collection");
console.log("集合创建成功");

collection​

db.collection(collName: string): CollectionReference

获取集合引用，用于后续的数据操作。

参数

collName
string

集合名称

返回

CollectionReference
CollectionReference

集合引用对象，可链式调用 doc()、where()、add()、aggregate() 等方法

示例

// 获取集合引用
const todosCollection = db.collection("todos");

// 查询集合中的数据
const result = await todosCollection.get();
console.log("查询结果:", result.data);

文档方法​

doc​

doc(docId: string | number): DocumentReference

通过文档 ID 获取文档引用，用于后续查询、更新或删除操作。

参数

docId
string | number

文档的唯一标识符，支持字符串或数字类型

返回

DocumentReference
DocumentReference

文档引用对象，可链式调用 get()、update()、set()、remove()、field() 等方法

示例

// 根据文档 ID 查询单条记录
const result = await db.collection("todos").doc("todo-id-123").get();

if (result.data && result.data.length > 0) {
  console.log("查询结果:", result.data[0]);
} else {
  console.log("文档不存在");
}

新增数据​

add​

async add(data: object): Promise<AddResult>

向集合中添加一条新记录。

  • 添加单条数据记录到指定集合
  • 支持自动生成文档 ID，也可指定文档 ID
  • 支持地理位置数据类型

参数

data
object

要新增的数据对象，支持嵌套对象、数组、地理位置等数据类型

返回

Promise
AddResult

示例

// 添加单条记录
const result = await db.collection("todos").add({
  title: "学习 CloudBase",
  content: "完成数据库操作教程",
  completed: false,
  priority: "high",
  createdAt: new Date(),
  tags: ["学习", "技术"],
});

console.log("新增成功，文档 ID:", result.id);

查询数据​

get​

async get(): Promise<GetResult>

获取查询结果，返回匹配条件的文档列表。

提示
  • 默认返回最多 100 条记录
  • 最大支持返回 1000 条记录（通过 limit 设置）

参数

无参数

返回

Promise
GetResult

示例

// 获取集合所有文档（默认最多100条）
const result = await db.collection("todos").get();

console.log("查询结果:", result.data);
console.log("总数:", result.total);

where​

where(condition: object): Query

设置查询条件，支持多种操作符进行复杂条件筛选。

注意
  • 查询条件必须是对象类型
  • 条件对象的值不能全部为 undefined

参数

condition
object

查询条件对象，支持等值匹配、操作符匹配、嵌套字段匹配等

返回

Query
Query

查询对象，可链式调用 orderBy()、limit()、skip()、field()、get()、count()、update()、remove() 等方法

示例

// 查询所有未完成的高优先级任务
const result = await db
  .collection("todos")
  .where({
    completed: false,
    priority: "high",
  })
  .get();

console.log("查询结果:", result.data);

count​

async count(): Promise<CountResult>

统计匹配条件的文档数量。

参数

无参数

返回

Promise
CountResult

示例

// 统计未完成任务数量
const result = await db.collection("todos").where({ completed: false }).count();

console.log("未完成任务数:", result.total);

orderBy​

orderBy(fieldPath: string, direction: 'asc' | 'desc'): Query

设置查询结果的排序方式。

参数

fieldPath
string

排序字段路径

direction
'asc' | 'desc'

排序方向：asc 升序，desc 降序

返回

Query
Query

查询对象，可继续链式调用

示例

// 按创建时间降序
const result = await db.collection("todos").orderBy("createdAt", "desc").get();

limit​

limit(max: number): Query

设置查询返回的最大记录数。

提示
  • 默认限制为 100 条
  • 最大支持 1000 条

参数

max
number

最大返回记录数，必须为正整数，最大值 1000

返回

Query
Query

查询对象，可继续链式调用

示例

// 只获取前 10 条记录
const result = await db.collection("todos").limit(10).get();

skip​

skip(offset: number): Query

设置查询结果的偏移量，用于分页查询。

参数

offset
number

偏移量，必须为非负整数

返回

Query
Query

查询对象，可继续链式调用

示例

// 跳过前 20 条，获取第 21-30 条记录
const result = await db.collection("todos").skip(20).limit(10).get();

field​

field(projection: object): Query | DocumentReference

指定要返回的字段。

参数

projection
object

字段投影对象，true 表示返回该字段，false 表示不返回

返回

Query | DocumentReference
Query | DocumentReference

查询对象或文档引用，可继续链式调用

示例

// 只返回 title 和 completed 字段
const result = await db
  .collection("todos")
  .field({
    title: true,
    completed: true,
  })
  .get();

aggregate​

aggregate(): Aggregate

获取聚合操作对象，用于执行聚合查询，支持 group、match、sort、project 等聚合阶段。

提示

聚合语法具体参考 聚合查询

参数

无参数

返回

Aggregate
Aggregate

聚合操作对象，可链式调用各种聚合阶段方法

示例

// 按优先级统计任务数量
const result = await db
  .collection("todos")
  .aggregate()
  .group({
    _id: "$priority",
    count: {
      $sum: 1,
    },
  })
  .end();

console.log("按优先级统计:", result.data);
// 输出: [{ _id: 'high', count: 5 }, { _id: 'normal', count: 10 }, ...]

地理位置查询​

支持对地理位置字段进行空间查询，包括附近查询、区域查询和相交查询。

注意

对地理位置字段进行查询时，请建立地理位置索引，否则查询将失败

参数

geoNear
GeoNearOptions

附近查询，按距离排序返回结果

geoWithin
GeoWithinOptions

区域查询，返回指定区域内的结果

geoIntersects
GeoIntersectsOptions

相交查询，返回与指定几何图形相交的结果

返回

Query
Query

查询对象，可链式调用 get() 方法获取结果

示例

const _ = db.command;

// 查询附近的用户（按距离排序）
const result = await db
  .collection("users")
  .where({
    location: _.geoNear({
      geometry: new db.Geo.Point(116.404, 39.915), // 天安门坐标
      maxDistance: 1000, // 最大距离1000米
      minDistance: 0, // 最小距离0米
    }),
  })
  .get();

console.log("附近用户:", result.data);

更新数据​

update​

async update(data: object): Promise<UpdateResult>

更新文档数据，支持单条更新和批量更新。

  • 通过 doc().update() 更新单条记录
  • 通过 where().update() 批量更新多条记录
  • 支持使用更新操作符进行复杂更新
  • 不能更新 _id 字段

参数

data
object

要更新的数据对象，支持普通字段更新和操作符更新

返回

Promise
UpdateResult

示例

// 更新指定文档
const result = await db.collection("todos").doc("todo-id-123").update({
  title: "学习 CloudBase 数据库",
  completed: true,
  updatedAt: new Date(),
  completedBy: "user123",
});

console.log("更新成功，影响记录数:", result.updated);

set​

async set(data: object): Promise<SetResult>

设置文档数据，如果文档不存在则创建新文档。

  • 与 update() 不同，set() 会完全替换文档内容
  • 适用于需要「更新或创建」的场景
  • 不能包含更新操作符
  • 不能更新 _id 字段

参数

data
object

要设置的数据对象，将完全替换原有文档内容，不能包含更新操作符

返回

Promise
SetResult

示例

// 更新文档，如果不存在则创建
const result = await db.collection("todos").doc("todo-id-123").set({
  title: "新任务",
  completed: false,
  priority: "high",
  createdAt: new Date(),
});

if (result.upsertedId) {
  console.log("创建新文档，ID:", result.upsertedId);
} else {
  console.log("更新现有文档，影响记录数:", result.updated);
}

删除数据​

remove​

async remove(): Promise<RemoveResult>

删除文档，支持单条删除和批量删除。

  • 通过 doc().remove() 删除单条记录
  • 通过 where().remove() 批量删除多条记录
注意

批量删除时，offset、limit、projection 和 orderBy 参数会被忽略

参数

无参数

返回

Promise
RemoveResult

示例

// 删除指定文档
const result = await db.collection("todos").doc("todo-id-123").remove();

console.log("删除成功，影响记录数:", result.deleted);

操作符​

查询操作符​

通过 db.command 获取查询操作符，用于构建复杂的查询条件。

参数

比较操作符
object
逻辑操作符
object
字段操作符
object
数组操作符
object
地理位置操作符
object

返回

无参数

示例

const _ = db.command;

// 等于
db.collection("users").where({ age: _.eq(18) });

// 不等于
db.collection("users").where({ status: _.neq("deleted") });

// 大于、大于等于
db.collection("users").where({ age: _.gt(18) });
db.collection("users").where({ age: _.gte(18) });

// 小于、小于等于
db.collection("users").where({ age: _.lt(60) });
db.collection("users").where({ age: _.lte(60) });

// 在数组中
db.collection("users").where({ role: _.in(["admin", "editor"]) });

// 不在数组中
db.collection("users").where({ status: _.nin(["banned", "deleted"]) });

更新操作符​

通过 db.command 获取更新操作符，用于执行复杂的更新操作。

参数

字段操作符
object
数组操作符
object

返回

无参数

示例

const _ = db.command;

// 设置字段值
db.collection("users")
  .doc("user-id")
  .update({
    profile: _.set({ name: "张三", age: 25 }),
  });

// 删除字段
db.collection("users").doc("user-id").update({
  tempData: _.remove(),
});

// 数值自增
db.collection("articles")
  .doc("article-id")
  .update({
    viewCount: _.inc(1),
    likeCount: _.inc(5),
  });

// 数值相乘
db.collection("products")
  .doc("product-id")
  .update({
    price: _.mul(0.9), // 打9折
  });

// 取最小/最大值
db.collection("users")
  .doc("user-id")
  .update({
    minScore: _.min(60),
    maxScore: _.max(100),
  });

// 重命名字段
db.collection("users")
  .doc("user-id")
  .update({
    oldField: _.rename("newField"),
  });

// 位运算
db.collection("users")
  .doc("user-id")
  .update({
    flags: _.bit({ and: 5 }), // 位与运算
  });

事务操作​

支持对多个文档的原子操作，确保数据一致性。

提示
  • 只支持在服务端使用，不支持在客户端使用。
  • Node.js 中使用请使用 Node.js 适配器

startTransaction​

async db.startTransaction(): Promise<Transaction>

开启一个新事务。

参数

无参数

返回

Promise
Transaction

事务对象，可进行事务内的文档操作

示例

// 开启事务
const transaction = await db.startTransaction();

try {
  // 在事务中操作文档
  const doc = transaction.collection("accounts").doc("account-1");
  const accountData = await doc.get();

  if (accountData.data && accountData.data.balance >= 100) {
    // 扣款
    await doc.update({
      balance: accountData.data.balance - 100,
    });

    // 增加另一个账户余额
    await transaction
      .collection("accounts")
      .doc("account-2")
      .update({
        balance: db.command.inc(100),
      });

    // 提交事务
    await transaction.commit();
    console.log("转账成功");
  } else {
    // 回滚事务
    await transaction.rollback("余额不足");
  }
} catch (error) {
  // 发生错误时回滚
  await transaction.rollback(error);
  console.error("事务失败:", error);
}

runTransaction​

async db.runTransaction(callback: (transaction) => Promise<any>, times?: number): Promise<void>

执行事务操作，自动处理提交和回滚。

参数

callback
(transaction) => Promise<void>

事务回调函数，在函数中进行事务操作

times
number

事务冲突时的重试次数，默认为 3

返回

Promise
void

事务回调函数的返回值

示例

// 使用 runTransaction 自动管理事务
const result = await db.runTransaction(async (transaction) => {
  // 获取账户1
  const account1 = await transaction
    .collection("accounts")
    .doc("account-1")
    .get();

  // 获取账户2
  const account2 = await transaction
    .collection("accounts")
    .doc("account-2")
    .get();

  if (account1.data.balance < 100) {
    // 通过 rollback 回滚并返回自定义错误
    await transaction.rollback({ message: "余额不足" });
    return;
  }

  // 扣款
  await transaction
    .collection("accounts")
    .doc("account-1")
    .update({
      balance: account1.data.balance - 100,
    });

  // 加款
  await transaction
    .collection("accounts")
    .doc("account-2")
    .update({
      balance: account2.data.balance + 100,
    });

  return { success: true, message: "转账成功" };
});

console.log(result);

实时监听​

watch​

watch(options: WatchOptions): DBRealtimeListener

监听文档或查询结果的实时变化。

参数

options
WatchOptions

返回

DBRealtimeListener
object

监听器对象

示例

// 监听单个文档的变化
const listener = db
  .collection("todos")
  .doc("todo-id-123")
  .watch({
    onChange: (snapshot) => {
      console.log("文档变化:", snapshot);
      console.log("文档数据:", snapshot.docs);
      console.log("变化详情:", snapshot.docChanges);
    },
    onError: (error) => {
      console.error("监听错误:", error);
    },
  });

// 关闭监听
// listener.close();

高级操作​

runCommands​

async db.runCommands(params: IRunCommandsReq): Promise<IRunCommandsResult>

执行 MongoDB 原生命令，支持批量执行多个命令和事务操作。

注意
  • 仅管理员可以调用
  • 在事务中执行时，任何命令失败都会导致整个事务回滚

参数

params
IRunCommandsReq

返回

Promise
IRunCommandsResult

示例

// 执行 find 命令
const result = await db.runCommands({
  commands: [
    {
      find: "users",
      filter: { age: { $gte: 18 } },
      projection: { name: 1, email: 1 },
      sort: { age: -1 },
      limit: 10,
    },
  ],
});

console.log("查询结果:", result.list);
// result.list[0] 包含查询到的文档

其他功能​

serverDate​

db.serverDate(options?: { offset?: number }): ServerDate

获取服务端时间。

参数

options
object

返回

ServerDate
ServerDate

服务端时间对象

示例

// 使用服务端时间
await db.collection("todos").add({
  title: "新任务",
  createdAt: db.serverDate(), // 当前服务端时间
});

// 使用带偏移的服务端时间
await db.collection("todos").add({
  title: "延时任务",
  scheduledAt: db.serverDate({
    offset: 60 * 60 * 1000, // 1小时后
  }),
});

RegExp​

db.RegExp({ regexp: string, options?: string }): RegExp

创建正则表达式对象，用于模糊查询。

参数

options
object

返回

RegExp
RegExp

正则表达式对象

示例

// 模糊查询：标题包含 "CloudBase"
const result = await db
  .collection("todos")
  .where({
    title: db.RegExp({
      regexp: "CloudBase",
      options: "i", // 忽略大小写
    }),
  })
  .get();

console.log("查询结果:", result.data);

聚合操作符​

通过 db.command.aggregate 获取聚合操作符，用于聚合管道中的表达式计算。

类别操作符
算术操作符abs, add, ceil, divide, exp, floor, ln, log, log10, mod, multiply, pow, sqrt, subtract, trunc
数组操作符arrayElemAt, arrayToObject, concatArrays, filter, in, indexOfArray, isArray, map, range, reduce, reverseArray, size, slice, zip
布尔操作符and, not, or
比较操作符cmp, eq, gt, gte, lt, lte, neq
条件操作符cond, ifNull, switch
日期操作符dateFromParts, dateFromString, dayOfMonth, dayOfWeek, dayOfYear, isoDayOfWeek, isoWeek, isoWeekYear, millisecond, minute, month, second, hour, week, year
字符串操作符concat, dateToString, indexOfBytes, indexOfCP, split, strLenBytes, strLenCP, strcasecmp, substr, substrBytes, substrCP, toLower, toUpper
集合操作符allElementsTrue, anyElementTrue, setDifference, setEquals, setIntersection, setIsSubset, setUnion
对象操作符mergeObjects, objectToArray
分组操作符addToSet, avg, first, last, max, min, push, stdDevPop, stdDevSamp, sum
其他literal, let, meta

相关资源​