云数据库

DatabaseManager 实例可以对数据库进行管理，以下表或集合为相同概念。

获得当前环境下的 DatabaseManager 实例：

$databaseManager = $tcbManager->getDatabaseManager();

创建集合

接口定义

该接口可创建集合。

createCollection(string $collectionName): object

该接口可创建集合，如果集合不存在。

createCollectionIfNotExists(string $collectionName): object

参数说明

参数名	类型	描述
$collectionName	String	集合名

调用示例

$result = $databaseManager->createCollection("collectionName")

返回示例

{
  "RequestId": "C563943B-3BEA-FE92-29FE-591EAEB7871F"
}

返回字段描述

参数名	类型	描述
RequestId	String	请求唯一标识

检查集合是否存在

接口定义

该接口可检查集合是否存在。

checkCollectionExists(string $collectionName): object

参数说明

参数名	类型	描述
$collectionName	String	集合名

调用示例

$result = $databaseManager->checkCollectionExists("collectionAlreadyExists")

返回示例

{
  "RequestId": "ddd80891-528d-428d-bc14-5cf022084533",
  "Exists": true
}

返回字段描述

参数名	类型	描述
RequestId	String	请求唯一标识
Exists	Boolean	集合是否已经存在

删除集合

接口定义

该接口可删除集合。

deleteCollection(string $collectionName): object

参数说明

参数名	类型	描述
$collectionName	String	集合名

如果集合不存在，也会正常返回。

调用示例

$result = $databaseManager->deleteCollection("collectionAlreadyExists")

返回示例

{
  "RequestId": "d145a61f-1eb4-49c9-88af-8d6c3940593a"
}

返回字段描述

参数名	类型	描述
RequestId	string	请求唯一标识

更新集合

接口定义

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

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

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

updateCollection(string $collectionName, array $options): object

参数说明

参数名	类型	描述
$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 必须放最前面

DropIndex

参数名	类型	描述
$IndexName	String	索引名称

调用示例

$result = $databaseManager->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
            ]
        ],
    ],
]);

$result = $databaseManager->updateCollection("collectionAlreadyExists", [
    "DropIndexes" => [
        ["IndexName" => "index_to_be_delete"]
    ]
]);

返回示例

{
  "RequestId": "c32d717d-4092-487a-bb32-aa28bab06563"
}

返回字段描述

参数名	类型	描述
RequestId	String	请求唯一标识

查询集合详细信息

接口定义

该接口可查询集合详细信息。

describeCollection(string $collectionName): object

参数说明

参数名	类型	描述
$collectionName	String	集合名

返回示例

$result = $databaseManager->describeCollection("collectionAlreadyExists");

{
  "Indexes": [
    {
      "Name": "_id_",
      "Size": 4096,
      "Keys": [
        {
          "Name": "_id",
          "Direction": "1"
        }
      ],
      "Unique": false,
      "Accesses": {
        "Ops": 0,
        "Since": "2019-06-11T15:09:04.037+08:00"
      }
    }
  ],
  "IndexNum": 1,
  "RequestId": "16e6ca3a-c342-49bc-ae2f-2fe657a93c64"
}

返回字段描述

参数名	类型	描述
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	命中次数从何时开始计数

查询所有集合信息

接口定义

该接口可查询所有集合信息。

listCollections(array $options = []): object

参数说明

参数名	类型	描述
$options	Array	可选参数
⁃ $MgoOffset	Number	可选，偏移量
⁃ $MgoLimit	Number	可选，数量限制

调用示例

$result = $databaseManager->listCollections([
    "MgoOffset" => 100,
    "MgoLimit" => 10,
])

返回示例

{
    "RequestId": "d812272a-ae93-489b-aaa7-d6c8a1b2b753",
    "Collections": [
        {
            "CollectionName": "users",
            "Count": 2,
            "Size": 131,
            "IndexCount": 1,
            "IndexSize": 4096
        }
    ],
    "Pager": {
        "Offset": 0,
        "Limit": 100,
        "Total": 4
    }
}

返回字段描述

参数名	类型	描述
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	集合数量

检查索引是否存在

接口定义

该接口可检查索引是否存在。

checkIndexExists(string $collectionName, string $indexName): object

参数说明

参数名	类型	描述
$collectionName	String	集合名
$indexName	String	索引名

调用示例

$result = $databaseManager->checkIndexExists(
    "collectionAlreadyExists",
    "index_to_be_delete"
)

返回示例

{
  "RequestId": "ac507001-a145-452a-bdf1-9b8190daa2de",
  "Exists": true
}

返回字段描述

参数名	类型	描述
RequestId	String	请求唯一标识
Exists	Boolean	索引是否存在

导入数据

接口定义

该接口可导入数据。

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

import(string $collectionName, array $file, array $options = []): object

参数说明

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

调用示例

$databaseManager->import(
    $this->collectionAlreadyExists,
    [
        "ObjectKey" => "data.csv"
    ],
    [
        // "FileType" => "csv",
        "StopOnError" => true,
        "ConflictMode" => "upsert"
    ]
)

返回示例

{
  "RequestId": "ac507001-a145-452a-bdf1-9b8190daa2de",
  "JobId": 200755
}

返回字段描述

参数名	类型	描述
RequestId	String	请求唯一标识
JobId	Number	任务 ID，用于在 migrateStatus 接口查询迁移状态

导出数据

接口定义

该接口可导出数据。

该接口立即返回，迁移状态（成功|失败）可通过 migrateStatus 查询。

export(string $collectionName, array $file, array $options = []): object

参数说明

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

请求示例

$result = $databaseManager->export(
    "users",
    [
        "ObjectKey" => "users.json"
    ],
    [
         "Fields" => "_id,name",
         "Query" => '{"name":{"$exists":true}}',
         "Sort" => '{"name": -1}',
         "Skip" => 0,
         "Limit" => 1000
    ]
)

返回示例

{
  "RequestId": "c64007fb-45b6-427d-9993-b9d9aaab06b5",
  "JobId": 100093276
}

返回字段描述

参数名	类型	描述
RequestId	String	请求唯一标识
JobId	Number	任务 ID，用于在 migrateStatus 接口查询迁移状态

查询迁移（导入|导出）状态

接口定义

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

migrateStatus(int $jobId): object

参数说明

参数名	类型	描述
$jobId	Integer	任务 ID，import 和 export 接口返回的 JobId

请求示例

$result = $databaseManager->migrateStatus(100093275);

返回示例

{
  "ErrorMsg": "导出完成.",
  "FileUrl": "https://tcb-mongodb-data-xxx.cos.ap-shanghai.myqcloud.com/xxx/tcb_already_exists.json?q-sign-algorithm=sha1&q-ak=xxx&q-sign-time=1560263593;1560267193&q-key-time=1560263593;1560267193&q-header-list=&q-url-param-list=&q-signature=xxx",
  "RecordFail": 0,
  "RecordSuccess": 2,
  "RequestId": "e5ce7401-c3ce-4724-8e2e-b3449ae537df",
  "Status": "success"
}

失败示例

{
  "ErrorMsg": "导出数据记录条数为0，请确认是否存在满足导出条件的数据.",
  "FileUrl": "",
  "RecordFail": 0,
  "RecordSuccess": 0,
  "RequestId": "8cc3e698-9dbc-4dcf-bcec-372b3f0922cf",
  "Status": "fail"
}

返回字段描述

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

查询数据分布

接口定义

该接口可查询数据分布。

distribution(): object

请求示例

$result = $databaseManager->distribution();

返回示例

{
  "Collections": [
    {
      "CollectionName": "users",
      "DocCount": 8
    },
    {
      "CollectionName": "tcb_test_collection_3",
      "DocCount": 0
    },
    {
      "CollectionName": "test_collection",
      "DocCount": 0
    },
    {
      "CollectionName": "tcb_already_exists",
      "DocCount": 0
    }
  ],
  "RequestId": "206b6795-559f-4aca-b1d7-31bc9557351a"
}

返回字段描述

参数名	类型	描述
RequestId	String	请求唯一标识
Collections	Array	集合列表
Collections[N].CollectionName	String	集合名称
Collections[N].DocCount	Number	文档数量

获取数据库实例

接口定义

该接口可获取 tcb-php-sdk 数据库实例。

db()

参数说明

无

该 SDK 内嵌 tcb-php-sdk，该函数返回 TencentCloudBase\Database\Db 实例。

调用示例

$db = $databaseManager->db();
$db->createCollection("users");
$collection = $db->collection("users");
$countResult = $collection->count();
$collection->add(['name' => 'ben']);
$queryResult = $collection->where([
    'name'=> "ben"
])->get();

更多详情请参见这里。

云数据库

创建集合​

接口定义​

参数说明​

检查集合是否存在​

接口定义​

参数说明​

删除集合​

接口定义​

参数说明​

更新集合​

接口定义​

参数说明​

查询集合详细信息​

接口定义​

参数说明​

查询所有集合信息​

接口定义​

参数说明​

检查索引是否存在​

接口定义​

参数说明​

导入数据​

接口定义​

导出数据​

接口定义​

参数说明​

查询迁移（导入|导出）状态​

接口定义​

参数说明​

查询数据分布​

接口定义​

获取数据库实例​

接口定义​

创建集合

接口定义

参数说明

检查集合是否存在

接口定义

参数说明

删除集合

接口定义

参数说明

更新集合

接口定义

参数说明

查询集合详细信息

接口定义

参数说明

查询所有集合信息

接口定义

参数说明

检查索引是否存在

接口定义

参数说明

导入数据

接口定义

导出数据

接口定义

参数说明

查询迁移（导入|导出）状态

接口定义

参数说明

查询数据分布

接口定义

获取数据库实例

接口定义