跳到主要内容

文档型数据库

createCollection​

1. 接口描述​

接口功能：该接口可创建集合

接口声明：

createCollection(collectionName: string): Promise<Object>

createCollectionIfNotExists(collectionName: string): Promise<Object>

2. 输入参数​

字段必填类型说明
CollectionName是String集合名

3. 返回结果​

字段必填类型说明
RequestId是String请求唯一标识

4. 示例代码​

const cloudbaseConfig = {
  secretId: "Your SecretId",
  secretKey: "Your SecretKey",
  envId: "Your envId", // 云开发环境ID，可在腾讯云云开发控制台获取
};

let { database } = new CloudBase(cloudbaseConfig);

async function test() {
  let result = await database.createCollection("collectionName");
  console.log(result);
}

test();

checkCollectionExists​

1. 接口描述​

接口功能：检查集合是否存在

接口声明：checkCollectionExists(collectionName: string): Promise<Object>

2. 输入参数​

字段必填类型说明
-是String集合名

3. 返回结果​

字段必填类型说明
RequestId是String请求唯一标识
Msg否String错误信息
Exists是Boolean集合是否已经存在

4. 示例代码​

const cloudbaseConfig = {
  secretId: "Your SecretId",
  secretKey: "Your SecretKey",
  envId: "Your envId", // 云开发环境ID，可在腾讯云云开发控制台获取
};

let { database } = new CloudBase(cloudbaseConfig);

async function test() {
  let result = await database.checkCollectionExists("collectionAlreadyExists");
  if (result.Exists) {
    // 集合存在
  } else {
    // 集合不存在
  }
}

test();

deleteCollection​

1. 接口描述​

接口功能：删除集合

接口声明：deleteCollection(collectionName: string): Promise<Object>

2. 输入参数​

字段必填类型说明
CollectionName是String集合名

3. 返回结果​

字段必填类型说明
RequestId是String请求唯一标识
Exists否Boolean存在不返回该字段，不存在则返回 false

4. 示例代码​

const cloudbaseConfig = {
  secretId: "Your SecretId",
  secretKey: "Your SecretKey",
  envId: "Your envId", // 云开发环境ID，可在腾讯云云开发控制台获取
};

let { database } = new CloudBase(cloudbaseConfig);
async function test() {
  let result = await database.deleteCollection("collectionAlreadyExists");
  if (result.Exists === false) {
    // 集合不存在
  }
}

test();

updateCollection​

1. 接口描述​

接口功能：更新集合

接口声明：updateCollection(collectionName: string, options: array): Promise<Object>

该接口可更新集合，但目前支持更新索引。

⚠️ 目前该接口只能更新索引，包括创建和删除。

  • 索引创建时如果已经存在，则会先删除再创建索引。
  • 因为一次接口调用可同时创建多个索引，所以可能部分索引创建失败，部分创建成功，接口报异常。

2. 输入参数​

字段必填类型说明
collectionName是String集合名
options是Array<Option>配置选项

Option

字段必填类型说明
CreateIndexes否Array<CreateIndex>需要创建的索引列表
DropIndexes否Array<DropIndex>需要删除的索引列表

CreateIndex

字段必填类型说明
IndexName是String索引名称
MgoKeySchema是Array<MgoKeySchema>索引规则

MgoKeySchema

字段必填类型说明
MgoIsUnique是boolean是否唯一
MgoIndexKeys是Array<MgoIndexKey>索引包含的字段列表

MgoIndexKey

字段必填类型说明
Name是String索引名称
Direction是String索引方向，1：ASC，-1：DESC，2d：双向，如果有 2d，2d 必须放最前面,注：地理位置索引应设置该值为 "2dsphere"

DropIndex

字段必填类型说明
IndexName是String索引名称

更新索引支持的两种方式，创建与删除，相互独立，不可在 options 同时传入 CreateIndexes，DropIndexes

3. 返回结果​

字段必填类型说明
RequestId是String请求唯一标识

4. 示例代码​

创建新索引

const cloudbaseConfig = {
  secretId: "Your SecretId",
  secretKey: "Your SecretKey",
  envId: "Your envId", // 云开发环境ID，可在腾讯云云开发控制台获取
};

let { database } = new CloudBase(cloudbaseConfig);
async function test() {
  let result = await database.updateCollection("collectionAlreadyExists", {
    CreateIndexes: [
      {
        IndexName: "index_a",
        MgoKeySchema: {
          MgoIndexKeys: [
            // 2d要放最前面
            { Name: "a_2d", Direction: "2d" },
            { Name: "a_1", Direction: "1" },
            { Name: "a_-1", Direction: "-1" },
          ],
          MgoIsUnique: false,
        },
      },
      {
        IndexName: "index_b",
        MgoKeySchema: {
          MgoIndexKeys: [{ Name: "b_1", Direction: "2d" }],
          MgoIsUnique: true,
        },
      },
      {
        IndexName: "index_to_be_delete",
        MgoKeySchema: {
          MgoIndexKeys: [{ Name: "xxx", Direction: "2d" }],
          MgoIsUnique: true,
        },
      },
    ],
  });
  console.log(result);
}

test();

删除索引

const cloudbaseConfig = {
  secretId: "Your SecretId",
  secretKey: "Your SecretKey",
  envId: "Your envId", // 云开发环境ID，可在腾讯云云开发控制台获取
};

let { database } = new CloudBase(cloudbaseConfig);

async function test() {
  let result = await database.updateCollection("collectionAlreadyExists", {
    DropIndexes: [{ IndexName: "index_to_be_delete" }],
  });
  console.log(result);
}

test();

describeCollection​

1. 接口描述​

接口功能：查询集合详细信息

接口声明：describeCollection(collectionName: string): Promise<Object>

2. 输入参数​

字段必填类型说明
CollectionName是String集合名

3. 返回结果​

字段必填类型说明
RequestId是String请求唯一标识
IndexNum是Number索引个数
Indexes是Array索引列表
Indexes[N].Name是String索引名称
Indexes[N].Size是String索引大小，单位: 字节
Indexes[N].Unique是String是否为唯一索引
Indexes[N].Keys是Array索引键值
Indexes[N].Keys[N].Name是String键名
Indexes[N].Keys[N].Direction是String索引方向，1： ASC， -1： DESC， 2d：双向
Indexes[N].Accesses是Array索引使用信息
Indexes[N].Accesses[N].Ops是Number索引命中次数
Indexes[N].Accesses[N].Since是String命中次数从何时开始计数

4. 示例代码​

const cloudbaseConfig = {
  secretId: "Your SecretId",
  secretKey: "Your SecretKey",
  envId: "Your envId", // 云开发环境ID，可在腾讯云云开发控制台获取
};

let { database } = new CloudBase(cloudbaseConfig);

async function test() {
  let result = await database.describeCollection("collectionAlreadyExists");
  const { Indexes } = result;
  for (let index in Indexes) {
    console.log(index); // 遍历全部索引
  }
}

test();

listCollections​

1. 接口描述​

接口功能：查询集合详细信息

接口声明：listCollections(options: object): Promise<Object>

2. 输入参数​

字段必填类型说明
MgoOffset否Number可选，偏移量
MgoLimit否Number可选，数量限制

3. 返回结果​

字段必填类型说明
RequestId是String请求唯一标识
Collections是Array集合列表
Collections[N].CollectionName是String集合名称
Collections[N].Count是Number集合中文档数量
Collections[N].Size是Number集合占用空间大小，字节
Collections[N].IndexCount是Number集合中索引个数
Collections[N].IndexSize是Number集合中索引占用空间大小，字节
Pager是Object本次查询分页信息
Pager.Offset是Number偏移量
Pager.Limit是Number限制数量
Pager.Total是Number集合数量

4. 示例代码​

const cloudbaseConfig = {
  secretId: "Your SecretId",
  secretKey: "Your SecretKey",
  envId: "Your envId", // 云开发环境ID，可在腾讯云云开发控制台获取
};

let { database } = new CloudBase(cloudbaseConfig);

async function test() {
  let result = await database.listCollections({
    MgoOffset: 100,
    MgoLimit: 10,
  });
  const { Collections } = result;
  for (let collection in Collections) {
    console.log(collection); // 遍历全部collection
  }
}

checkIndexExists​

1. 接口描述​

接口功能：检查索引是否存在

接口声明：checkIndexExists(collectionName: string, indexName: string): Promise<Object>

2. 输入参数​

字段必填类型说明
collectionName是String集合名
indexName是String索引名

3. 返回结果​

字段必填类型说明
RequestId是String请求唯一标识
Exists是Boolean索引是否存在

4. 示例代码​

const cloudbaseConfig = {
  secretId: "Your SecretId",
  secretKey: "Your SecretKey",
  envId: "Your envId", // 云开发环境ID，可在腾讯云云开发控制台获取
};

let { database } = new CloudBase(cloudbaseConfig);
async function test() {
  let result = await database.checkIndexExists(
    "collectionAlreadyExists",
    "index_to_be_delete",
  );
  const { Exists } = result;
  if (Exists === true) {
    //索引存在
  }
}
test();

import​

1. 接口描述​

接口功能：导入数据

接口声明：import(collectionName: string, file: object, options: object): Promise<Object>

注意：

  • 该接口立即返回，迁移状态（成功|失败）可通过 migrateStatus 查询。
  • 导入数据需要先将文件上传到该环境（同一个 EnvId）下的对象存储中，所以会在对象存储中创建对象。
  • 因为该函数成功返回只意味着上传成功，导入操作在上传后开始，该接口无法判断导入是否完成，所以该对象用完后需要手动删除。

2. 输入参数​

字段必填类型说明
collectionName是String集合名
file是Array数据，以下方式必选一种
⁃ FilePath是String本地数据文件路径
⁃ ObjectKey是String本环境下对象存储 Key
options否Array可选参数
⁃ ObjectKeyPrefix否String对象存储 Key 前缀，默认 tmp/db-imports/
⁃ FileType否String文件类型：csv 或 json，如果为传递此参数，默认为文件后缀名，注意使用正确的后缀名。
⁃ StopOnError否Boolean遇到错误时是否停止导入。
⁃ ConflictMode否String冲突处理方式：insert 或 upsert

3. 返回结果​

字段必填类型说明
RequestId是String请求唯一标识
JobId是Number任务 ID，用于在 migrateStatus 接口查询迁移状态

4. 示例代码​

const cloudbaseConfig = {
  secretId: "Your SecretId",
  secretKey: "Your SecretKey",
  envId: "Your envId", // 云开发环境ID，可在腾讯云云开发控制台获取
};

let { database } = new CloudBase(cloudbaseConfig);

async function test() {
  let res = await database.import(
    "collectionAlreadyExists",
    {
      ObjectKey: "data.csv",
    },
    {
      // "FileType" : "csv",
      StopOnError: true,
      ConflictMode: "upsert",
    },
  );

  const { JobId } = res;
  console.log(JobId);
}

test();

export​

1. 接口描述​

接口功能：导出数据，迁移状态（成功|失败）可通过 migrateStatus 查询。

接口声明：export(collectionName: string, file: object, options: object): Promise<Object>

2. 输入参数​

字段必填类型说明
collectionName是String集合名
file是Array数据，以下方式必选一种
⁃ ObjectKey是String本环境下对象存储 Key
options否Array可选参数
⁃ FileType否String文件类型：csv 或 json，如果为传递此参数，默认为文件后缀名，注意使用正确的后缀名
⁃ Query否StringJSON 字符串，支持 mongo 指令。例如：'{ a: { gte: 3 } }'。与 mongodb 查询语法兼容
⁃ Skip否Number偏移量
⁃ Limit否Number限制数目
⁃ Sort否NumberJSON 字符串，如果有索引则不支持排序，数据集的长度必须少于 32 兆
⁃ Fields否String字符串，字段以逗号分割。FileType=csv 时必填

3. 返回结果​

字段必填类型说明
RequestId是String请求唯一标识
JobId是Number任务 ID，用于在 migrateStatus 接口查询迁移状态

4. 示例代码​

const cloudbaseConfig = {
  secretId: "Your SecretId",
  secretKey: "Your SecretKey",
  envId: "Your envId", // 云开发环境ID，可在腾讯云云开发控制台获取
};

let { database } = new CloudBase(cloudbaseConfig);

async function test() {
  let result = await database.export(
    "users",
    {
      ObjectKey: "users.json",
    },
    {
      Fields: "_id,name",
      Query: '{"name":{"$exists":true}}',
      Sort: '{"name": -1}',
      Skip: 0,
      Limit: 1000,
    },
  );
  const { JobId } = res;
  console.log(JobId);
}

test();

migrateStatus​

1. 接口描述​

接口功能：该接口可查询迁移（导入|导出）状态。

接口声明：migrateStatus(jobId: number): Promise<Object>

2. 输入参数​

字段必填类型说明
jobId是Integer任务 ID，import 和 export 接口返回的 JobId

3. 返回结果​

字段必填类型说明
RequestId是String请求唯一标识
Status是String任务状态。可能值：waiting：等待中，reading：读，writing：写，migrating：转移中，success：成功，fail：失败
RecordSuccess是Integer迁移成功的数据条数
RecordFail是Integer迁移失败的数据条数
ErrorMsg是String迁移失败的原因
FileUrl是String文件下载链接，仅在数据库导出中有效

4. 示例代码​

const cloudbaseConfig = {
  secretId: "Your SecretId",
  secretKey: "Your SecretKey",
  envId: "Your envId", // 云开发环境ID，可在腾讯云云开发控制台获取
};

let { database } = new CloudBase(cloudbaseConfig);

async function test() {
  let result = await database.migrateStatus(100093275);
  console.log(result.Status); // 打印迁移状态
}

test();

distribution​

1. 接口描述​

接口功能：查询数据分布

接口声明：distribution(): Promise<Object>

2. 输入参数​

无

3. 返回结果​

字段必填类型说明
RequestId是String请求唯一标识
Collections是Array集合列表
Collections[N].CollectionName是String集合名称
Collections[N].DocCount是Number文档数量

4. 示例代码​

const cloudbaseConfig = {
  secretId: "Your SecretId",
  secretKey: "Your SecretKey",
  envId: "Your envId", // 云开发环境ID，可在腾讯云云开发控制台获取
};
let { database } = new CloudBase(cloudbaseConfig);

async function test() {
  let result = await database.distribution();
  const { Collections } = result;
  for (let collection in Collections) {
    console.log(collection);
  }
}

test();

插入文档​

1. 接口描述​

接口功能：该接口用于向数据库中插入数据

接口声明：manager.commonService('flexdb').call(option): Promise<Object>

2. 输入参数​

字段必填类型说明
Action是String接口名称
Param是Object接口参数

Param 字段说明​

字段必填类型说明
TableName是String表名
MgoDocs是Array<String>待插入文档
Tag是String文档型数据库实例 ID， 可通过 envInfo 接口获取

3. 返回结果​

字段必填类型说明
RequestId是String请求唯一标识
InsertedIds是Array<String>插入成功的数据集合主键_id

4. 示例代码​

const cloudbaseConfig = {
  secretId: "Your SecretId",
  secretKey: "Your SecretKey",
  envId: "Your envId", // 云开发环境ID，可在腾讯云云开发控制台获取
};
const manager = new CloudBase(cloudBaseConfig);

const data = JSON.stringify({
  a: 1,
});

// 获取数据库实例ID
const { EnvInfo } = await manager.env.getEnvInfo();

const { Databases } = EnvInfo;
console.log("Databases:", Databases);
const { InsertedIds } = await manager.commonService("flexdb").call({
  Action: "PutItem",
  Param: {
    TableName: "coll-1",
    MgoDocs: [data],
    Tag: Databases[0].InstanceId,
  },
});
console.log("InsertedIds:", InsertedIds);

查询文档​

1. 接口描述​

接口功能：该接口用于查询数据库文档

接口声明：manager.commonService('flexdb').call(option): Promise<Object>

2. 输入参数​

字段必填类型说明
Action是String接口名称
Param是Object接口参数

Param 字段说明​

字段必填类型说明
TableName是String表名
MgoLimit是Number查询返回结果 limit 数
MgoProjection否String投影条件，为一个 json 串，如{ item: 1, status: 1 }表示结果中返回 item 和 status 两个列；{ item: 0}表示不返回 item 列
Tag是String文档型数据库实例 ID， 可通过 envInfo 接口获取
MgoQuery否String查询条件，查询条件为一个 json 串，如{"test":1}
MgoOffset否Number查询结果从 offset 条开始返回
MgoSort否String排序条件，排序条件为一个 json 串，示例 [{"key":"_id","direction":1}]

3. 返回结果​

字段必填类型说明
RequestId是String请求唯一标识
Pager是Pager分页信息
Data是Array<String>满足查询条件的数据集合
字段必填类型说明
Offset是Number分页偏移量
Limit是Number每页返回记录数

4. 示例代码​

const cloudbaseConfig = {
  secretId: "Your SecretId",
  secretKey: "Your SecretKey",
  envId: "Your envId", // 云开发环境ID，可在腾讯云云开发控制台获取
};
const manager = new CloudBase(cloudBaseConfig);

// 获取数据库实例ID
const { EnvInfo } = await manager.env.getEnvInfo();

const { Databases } = EnvInfo;
console.log("Databases:", Databases);
const { Data } = await manager.commonService("flexdb").call({
  Action: "Query",
  Param: {
    TableName: "coll-1",
    MgoQuery: JSON.stringify({ a: 1 }),
    Tag: Databases[0].InstanceId,
    MgoLimit: 20,
  },
});
console.log("Data:", Data);

更新文档​

1. 接口描述​

接口功能：该接口用于更新数据库文档

接口声明：manager.commonService('flexdb').call(option): Promise<Object>

2. 输入参数​

字段必填类型说明
Action是String接口名称
Param是Object接口参数

Param 字段说明​

字段必填类型说明
Tag是String文档型数据库实例 ID， 可通过 envInfo 接口获取
MgoQuery否String查询条件，查询条件为一个 json 串，如
MgoUpdate是String更新内容
TableName是String表名
MgoIsMulti否Boolean是否更新多条
MgoUpsert否Boolean是否使用 upsert 模式

3. 返回结果​

字段必填类型说明
RequestId是String请求唯一标识
UpsertedId是String插入的数据_id
ModifiedNum是Number已经修改的行数
MatchedNum是Number更新条件匹配到的结果数

4. 示例代码​

const cloudbaseConfig = {
  secretId: "Your SecretId",
  secretKey: "Your SecretKey",
  envId: "Your envId", // 云开发环境ID，可在腾讯云云开发控制台获取
};
const manager = new CloudBase(cloudBaseConfig);

// 获取数据库实例ID
const { EnvInfo } = await manager.env.getEnvInfo();

const { Databases } = EnvInfo;
console.log("Databases:", Databases);
const { ModifiedNum } = await manager.commonService("flexdb").call({
  Action: "UpdateItem",
  Param: {
    TableName: "coll-1",
    MgoUpdate: JSON.stringify({ a: 2 }),
    MgoQuery: JSON.stringify({ a: 1 }),
    Tag: Databases[0].InstanceId,
  },
});
console.log("ModifiedNum:", ModifiedNum);

删除文档​

1. 接口描述​

接口功能：该接口用于删除数据库文档

接口声明：manager.commonService('flexdb').call(option): Promise<Object>

2. 输入参数​

字段必填类型说明
Action是String接口名称
Param是Object接口参数

Param 字段说明​

字段必填类型说明
Tag是String文档型数据库实例 ID， 可通过 envInfo 接口获取
MgoQuery否String查询条件，查询条件为一个 json 串，如
TableName是String表名
MgoIsMulti否Boolean是否更新多条

3. 返回结果​

字段必填类型说明
RequestId是String请求唯一标识
Deleted是Number删除数据的条数

4. 示例代码​

const cloudbaseConfig = {
  secretId: "Your SecretId",
  secretKey: "Your SecretKey",
  envId: "Your envId", // 云开发环境ID，可在腾讯云云开发控制台获取
};
const manager = new CloudBase(cloudBaseConfig);

// 获取数据库实例ID
const { EnvInfo } = await manager.env.getEnvInfo();

const { Databases } = EnvInfo;
console.log("Databases:", Databases);
const { Deleted } = await manager.commonService("flexdb").call({
  Action: "DeleteItem",
  Param: {
    TableName: "coll-1",
    MgoQuery: JSON.stringify({ a: 2 }),
    Tag: Databases[0].InstanceId,
  },
});
console.log("Deleted:", Deleted);

查询可回档时间​

1. 接口描述​

接口功能：获取所选表格可回档时间的交集

接口声明：manager.commonService('flexdb').call(option): Promise<Object>

2. 输入参数​

字段必填类型说明
Action是String接口名称
Param是Object接口参数

Param 字段说明​

字段必填类型说明
InstanceId是String文档型数据库实例 ID， 可通过 envInfo 接口获取

3. 返回结果​

字段必填类型说明
RestoreTimes是Array<String>可回档时间列表
RequestId是String请求唯一标识

4. 示例代码​

const cloudbaseConfig = {
  secretId: "Your SecretId",
  secretKey: "Your SecretKey",
  envId: "Your envId", // 云开发环境ID，可在腾讯云云开发控制台获取
};
const manager = new CloudBase(cloudBaseConfig);

// 获取数据库实例ID
const { EnvInfo } = await manager.env.getEnvInfo();

const { Databases } = EnvInfo;

// 查询可回档时间
const { RestoreTimes } = await manager.commonService("flexdb").call({
  Action: "DescribeRestoreTime",
  Param: {
    InstanceId: Databases[0].InstanceId,
  },
});

console.log(RestoreTimes);

获取可回档表格​

1. 接口描述​

接口功能：获取可回档表格

接口声明：manager.commonService('flexdb').call(option): Promise<Object>

2. 输入参数​

字段必填类型说明
Action是String接口名称
Param是Object接口参数

Param 字段说明​

字段必填类型说明
InstanceId是String文档型数据库实例 ID， 可通过 envInfo 接口获取
Time是String可回档时间

3. 返回结果​

字段必填类型说明
Tables是Array<String>可回档表格列表
RequestId是String请求唯一标识

4. 示例代码​

const cloudbaseConfig = {
  secretId: "Your SecretId",
  secretKey: "Your SecretKey",
  envId: "Your envId", // 云开发环境ID，可在腾讯云云开发控制台获取
};
const manager = new CloudBase(cloudBaseConfig);

// 获取数据库实例ID
const { EnvInfo } = await manager.env.getEnvInfo();

const { Databases } = EnvInfo;

// 查询可回档时间
const { RestoreTimes } = await manager.commonService("flexdb").call({
  Action: "DescribeRestoreTime",
  Param: {
    InstanceId: Databases[0].InstanceId,
  },
});

console.log(RestoreTimes);

// 获取可回档表格
const { Tables } = await manager.commonService("flexdb").call({
  Action: "DescribeRestoreTables",
  Param: {
    InstanceId: Databases[0].InstanceId,
    Time: RestoreTimes[0],
  },
});

console.log(Tables);

实例表格回档​

1. 接口描述​

接口功能：实例表格回档

接口声明：manager.commonService('flexdb').call(option): Promise<Object>

2. 输入参数​

字段必填类型说明
Action是String接口名称
Param是Object接口参数

Param 字段说明​

字段必填类型说明
InstanceId是String文档型数据库实例 ID， 可通过 envInfo 接口获取
Time是String可回档时间
ModifyTableNamesInfo是Array<ModifyTableNamesInfoItem>回档表格信息

ModifyTableNamesInfoItem​

字段必填类型说明
OldTableName是String原表名
NewTableName是String新表名(新表名一定不能与原表名相同！)

3. 返回结果​

字段必填类型说明
FlowId是String流程 ID
RequestId是String请求唯一标识

4. 示例代码​

const cloudbaseConfig = {
  secretId: "Your SecretId",
  secretKey: "Your SecretKey",
  envId: "Your envId", // 云开发环境ID，可在腾讯云云开发控制台获取
};
const manager = new CloudBase(cloudBaseConfig);

// 获取数据库实例ID
const { EnvInfo } = await manager.env.getEnvInfo();

const { Databases } = EnvInfo;

// 查询可回档时间
const { RestoreTimes } = await manager.commonService("flexdb").call({
  Action: "DescribeRestoreTime",
  Param: {
    InstanceId: Databases[0].InstanceId,
  },
});

console.log(RestoreTimes);

// 获取可回档表格
const { Tables } = await manager.commonService("flexdb").call({
  Action: "DescribeRestoreTables",
  Param: {
    InstanceId: Databases[0].InstanceId,
    Time: RestoreTimes[0],
  },
});

console.log(Tables);

const { FlowId } = await manager.commonService("flexdb").call({
  Action: "RestoreTCBTables",
  Param: {
    InstanceId: Databases[0].InstanceId,
    Time: RestoreTimes[0],
    ModifyTableNamesInfo: [
      {
        OldTableName: "coll-1",
        NewTableName: "coll-1_bak",
      },
    ],
  },
});

console.log("FlowId:", FlowId);

获取回档任务​

1. 接口描述​

接口功能：获取回档任务

接口声明：manager.commonService('flexdb').call(option): Promise<Object>

2. 输入参数​

字段必填类型说明
Action是String接口名称
Param是Object接口参数

Param 字段说明​

字段必填类型说明
InstanceId是String文档型数据库实例 ID， 可通过 envInfo 接口获取

3. 返回结果​

字段必填类型说明
Tasks是Array<RestoreTask>可回档表格列表
RequestId是String请求唯一标识

RestoreTask​

字段必填类型说明
Tables是Array<[ModifyTableNamesInfoItem](#ModifyTableNamesInfoItem)>回档任务涉及表格
CreateTime是String任务创建时间
Status是Number当前任务状态(0-待执行，1-运行中，2-已完成)
EndTime是String任务完成时间
RestoreTime是String回档时间点

4. 示例代码​

const cloudbaseConfig = {
  secretId: "Your SecretId",
  secretKey: "Your SecretKey",
  envId: "Your envId", // 云开发环境ID，可在腾讯云云开发控制台获取
};
const manager = new CloudBase(cloudBaseConfig);

// 获取数据库实例ID
const { EnvInfo } = await manager.env.getEnvInfo();

const { Databases } = EnvInfo;

const { Tasks } = await manager.commonService("flexdb").call({
  Action: "DescribeRestoreTask",
  Param: {
    InstanceId: Databases[0].InstanceId,
  },
});

console.log("Tasks:", Tasks);

修改表名​

1. 接口描述​

接口功能：修改表名

接口声明：manager.commonService('flexdb').call(option): Promise<Object>

2. 输入参数​

字段必填类型说明
Action是String接口名称
Param是Object接口参数

Param 字段说明​

字段必填类型说明
Tag是String文档型数据库实例 ID， 可通过 envInfo 接口获取
ModifyTableInfo是Array<[ModifyTableNamesInfoItem](#ModifyTableNamesInfoItem)>修改表名信息

3. 返回结果​

字段必填类型说明
FlowId是String流程 ID
RequestId是String请求唯一标识

4. 示例代码​

const cloudbaseConfig = {
  secretId: "Your SecretId",
  secretKey: "Your SecretKey",
  envId: "Your envId", // 云开发环境ID，可在腾讯云云开发控制台获取
};
const manager = new CloudBase(cloudBaseConfig);

// 获取数据库实例ID
const { EnvInfo } = await manager.env.getEnvInfo();

const { Databases } = EnvInfo;

const { FlowId } = await manager.commonService("flexdb").call({
  Action: "ModifyNameSpace",
  Param: {
    Tag: Databases[0].InstanceId,
    ModifyTableInfo: [
      {
        OldTableName: "coll-1_bak",
        NewTableName: "coll-1_bak_modify",
      },
    ],
  },
});

console.log("FlowId:", FlowId);

runCommands​

1. 接口描述​

接口功能：直接向文档型云数据库发送原生命令，支持 UPDATE / QUERY / INSERT / DELETE / COMMAND 操作

接口声明：app.database.runCommands(options): Promise<Object>

版本提示

自 v5.0.0 起支持此接口

2. 输入参数​

字段必填类型说明
MgoCommands是IMgoCommandParam[]待执行命令列表，见下方说明
Tag否String实例 ID（如 tnt-xxxx），不传则自动使用当前环境实例
EnvId否String环境 ID，不传则自动使用当前环境
MongoConnector否IMongoConnectorMongoDB 连接器实例信息

IMgoCommandParam

字段必填类型说明
TableName是String集合（表）名称
CommandType是String操作类型：UPDATE / QUERY / INSERT / DELETE / COMMAND
Command是String命令内容（JSON 字符串）

3. 返回结果​

字段类型说明
RequestIdString请求唯一标识
DataString[]返回结果列表，每个元素是 JSON 字符串

4. 示例代码​

const CloudBase = require("@cloudbase/manager-node");
const app = new CloudBase({
  secretId: "Your SecretId",
  secretKey: "Your SecretKey",
  envId: "your-env-id",
});

async function test() {
  const res = await app.database.runCommands({
    MgoCommands: [
      {
        TableName: "todos",
        CommandType: "QUERY",
        Command: JSON.stringify({ filter: { status: "done" }, limit: 10 }),
      },
    ],
  });
  const result = JSON.parse(res.Data[0]);
  console.log(result);
}

test();

describeRestoreTables​

1. 接口描述​

接口功能：查询指定时间点下可回档的集合（表）列表

接口声明：app.database.describeRestoreTables(time, filters?, instanceId?): Promise<Object>

版本提示

自 v5.0.0 起支持此接口

2. 输入参数​

字段必填类型说明
time是String目标回档时间，格式 YYYY-MM-DD HH:MM:SS
filters否String[]集合名称过滤列表，不传则返回全部可回档集合
instanceId否String数据库实例 ID，不传则自动使用当前环境实例

3. 返回结果​

字段类型说明
RequestIdString请求唯一标识
TablesString[]可回档集合名称列表

4. 示例代码​

async function test() {
  const { Tables } = await app.database.describeRestoreTables(
    "2025-01-01 12:00:00",
  );
  console.log("可回档集合:", Tables);
}

test();

describeRestoreTime​

1. 接口描述​

接口功能：查询数据库可回档的时间范围

接口声明：app.database.describeRestoreTime(instanceId?): Promise<Object>

版本提示

自 v5.0.0 起支持此接口

2. 输入参数​

字段必填类型说明
instanceId否String数据库实例 ID，不传则自动使用当前环境实例

3. 返回结果​

字段类型说明
RequestIdString请求唯一标识
RestoreTimesString[]可回档时间点列表
RestoreTimeRangesObject[]任意时间回档的可选时间范围

describeRestoreTask​

1. 接口描述​

接口功能：查询数据库回档任务列表及状态

接口声明：app.database.describeRestoreTask(instanceId?): Promise<Object>

版本提示

自 v5.0.0 起支持此接口

2. 输入参数​

字段必填类型说明
instanceId否String数据库实例 ID，不传则自动使用当前环境实例

3. 返回结果​

字段类型说明
RequestIdString请求唯一标识
TasksIRestoreTask[]回档任务列表

IRestoreTask

字段类型说明
TaskIdString任务 ID
StatusString任务状态
TimeString任务创建时间
EnvIdString所属环境 ID
TypeString恢复类型

restoreTables​

1. 接口描述​

接口功能：将指定集合回档到某个时间点，支持重命名目标集合

接口声明：app.database.restoreTables(time, modifyTableNamesInfo, instanceId?): Promise<Object>

版本提示

自 v5.0.0 起支持此接口

2. 输入参数​

字段必填类型说明
time是String回档目标时间，格式 YYYY-MM-DD HH:MM:SS
modifyTableNamesInfo是IModifyTableNamesInfo[]集合名称映射，见下方说明
instanceId否String数据库实例 ID，不传则自动使用当前环境实例

IModifyTableNamesInfo

字段必填类型说明
OldTableName是String回档源集合名称
NewTableName是String回档目标集合名称（可与源名不同）

3. 返回结果​

字段类型说明
RequestIdString请求唯一标识
FlowIdNumber回档流程 ID，可用于查询进度

4. 示例代码​

async function test() {
  const { FlowId } = await app.database.restoreTables("2025-01-01 12:00:00", [
    { OldTableName: "todos", NewTableName: "todos_restore" },
  ]);
  console.log("回档任务 FlowId:", FlowId);
}

test();

PostgreSQL 环境

版本提示

以下接口面向 PostgreSQL 架构 的云开发环境，自 @cloudbase/manager-node@5.4.0 起提供。

executePGSql​

1. 接口描述​

接口功能：在 PostgreSQL 环境上执行任意 SQL 语句，并返回结果集与受影响行数。

接口声明：app.database.executePGSql(options): Promise<IExecutePGSqlResult>

2. 输入参数​

IExecutePGSqlOptions

字段必填类型说明
Sql是String要执行的 SQL 语句
Role否String指定 role 执行 SQL（如 postgres），用于执行需要更高权限的语句（如 CREATE POLICY / DROP POLICY）
EnvId否String云开发环境 ID，不传则使用当前管理实例初始化时的 EnvId

3. 返回结果​

IExecutePGSqlResult 继承 IResponseInfo。

字段类型说明
RequestIdString请求唯一标识
AffectedRowsNumber受影响行数（DML 类语句有效）
ColumnsString[] / null字段名列表（SELECT 类语句返回）；无结果集时为 null
RowsString[] / null数据行列表，每一项是 JSON 串，反序列化后是 (string | null)[]，按 Columns 顺序对齐；无结果集时为 null
ExecutionTimeMsNumberSQL 执行耗时（毫秒）

4. 示例代码​

// 创建表
await app.database.executePGSql({
  Sql: "CREATE TABLE users (id SERIAL PRIMARY KEY, name TEXT NOT NULL)",
});

// 查询并解析结果
const res = await app.database.executePGSql({
  Sql: "SELECT id, name FROM users WHERE id = 1",
});
console.log(res.Columns); // ['id', 'name']
const rows = (res.Rows || []).map((s) => JSON.parse(s)); // [['1', 'Alice']]

// 使用指定 role 创建 RLS 策略
await app.database.executePGSql({
  Role: "postgres",
  Sql: `CREATE POLICY avatars_public_read ON storage.objects
        FOR SELECT TO public USING (bucket_id = 'avatars')`,
});