跳到主要内容

云数据库

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

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

$databaseManager = $tcbManager->getDatabaseManager();

创建集合#

接口定义#

该接口可创建集合。

createCollection(string $collectionName): object

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

createCollectionIfNotExists(string $collectionName): object

参数说明#

参数名类型描述
$collectionNameString集合名

调用示例

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

返回示例

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

返回字段描述

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

检查集合是否存在#

接口定义#

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

checkCollectionExists(string $collectionName): object

参数说明#

参数名类型描述
$collectionNameString集合名

调用示例

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

返回示例

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

返回字段描述

参数名类型描述
RequestIdString请求唯一标识
ExistsBoolean集合是否已经存在

删除集合#

接口定义#

该接口可删除集合。

deleteCollection(string $collectionName): object

参数说明#

参数名类型描述
$collectionNameString集合名

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

调用示例

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

返回示例

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

返回字段描述

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

更新集合#

接口定义#

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

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

  • 索引创建时如果已经存在,则会先删除再创建索引。
  • 因为一次接口调用可同时创建多个索引,所以可能部分索引创建失败,部分创建成功,接口报异常。
updateCollection(string $collectionName, array $options): object

参数说明#

参数名类型描述
$collectionNameString集合名
$optionsArray<Option>配置选项

Option

参数名类型描述
$CreateIndexesArray<CreateIndex>需要创建的索引列表
$DropIndexesArray<DropIndex>需要删除的索引列表

CreateIndex

参数名类型描述
$IndexNameString索引名称
$MgoKeySchemaArray<MgoKeySchema>索引规则

MgoKeySchema

参数名类型描述
$MgoIsUniqueBoolean是否唯一
$MgoIndexKeysArray<MgoIndexKey>索引包含的字段列表

MgoIndexKey

参数名类型描述
$NameString索引名称
$DirectionString索引方向,1:ASC,-1:DESC,2d:双向,如果有 2d,2d 必须放最前面

DropIndex

参数名类型描述
$IndexNameString索引名称

调用示例

$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"}

返回字段描述

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

查询集合详细信息#

接口定义#

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

describeCollection(string $collectionName): object

参数说明#

参数名类型描述
$collectionNameString集合名

返回示例

$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"}

返回字段描述

参数名类型描述
RequestIdString请求唯一标识
IndexNumNumber索引个数
IndexesArray索引列表
Indexes[N].NameString索引名称
Indexes[N].SizeString索引大小,单位: 字节
Indexes[N].UniqueString是否为唯一索引
Indexes[N].KeysArray索引键值
Indexes[N].Keys[N].NameString键名
Indexes[N].Keys[N].DirectionString索引方向,1: ASC, -1: DESC, 2d:双向
Indexes[N].AccessesArray索引使用信息
Indexes[N].Accesses[N].OpsNumber索引命中次数
Indexes[N].Accesses[N].SinceString命中次数从何时开始计数

查询所有集合信息#

接口定义#

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

listCollections(array $options = []): object

参数说明#

参数名类型描述
$optionsArray可选参数
⁃ $MgoOffsetNumber可选,偏移量
⁃ $MgoLimitNumber可选,数量限制

调用示例

$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    }}

返回字段描述

参数名类型描述
RequestIdString请求唯一标识
CollectionsArray集合列表
Collections[N].CollectionNameString集合名称
Collections[N].CountNumber集合中文档数量
Collections[N].SizeNumber集合占用空间大小,字节
Collections[N].IndexCountNumber集合中索引个数
Collections[N].IndexSizeNumber集合中索引占用空间大小,字节
PagerObject本次查询分页信息
Pager.OffsetNumber偏移量
Pager.LimitNumber限制数量
Pager.TotalNumber集合数量

检查索引是否存在#

接口定义#

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

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

参数说明#

参数名类型描述
$collectionNameString集合名
$indexNameString索引名

调用示例

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

返回示例

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

返回字段描述

参数名类型描述
RequestIdString请求唯一标识
ExistsBoolean索引是否存在

导入数据#

接口定义#

该接口可导入数据。

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

参数说明

参数名类型描述
$collectionNameString集合名
$fileArray数据,以下方式必选一种
⁃ $FilePathString本地数据文件路径
⁃ $ObjectKeyString本 TCB 环境下对象存储 Key
$optionsArray可选参数
⁃ $ObjectKeyPrefixString对象存储 Key 前缀,默认 tmp/db-imports/
⁃ $FileTypeString文件类型:csv 或 json,如果为传递此参数,默认为文件后缀名,注意使用正确的后缀名。
⁃ $StopOnErrorBoolean遇到错误时是否停止导入。
⁃ $ConflictModeString冲突处理方式:insert 或 upsert

调用示例

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

返回示例

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

返回字段描述

参数名类型描述
RequestIdString请求唯一标识
JobIdNumber任务 ID,用于在 migrateStatus 接口查询迁移状态

导出数据#

接口定义#

该接口可导出数据。

该接口立即返回,迁移状态(成功|失败)可通过 migrateStatus 查询。

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

参数说明#

参数名类型描述
$collectionNameString集合名
$fileArray数据,以下方式必选一种
⁃ $ObjectKeyString本 TCB 环境下对象存储 Key
$optionsArray可选参数
⁃ $FileTypeString文件类型:csv 或 json,如果为传递此参数,默认为文件后缀名,注意使用正确的后缀名
⁃ $QueryStringJSON 字符串,支持 mongo 指令。例如:'{ a: { $gte: 3 } }'。与 mongodb 查询语法兼容
⁃ $SkipNumber偏移量
⁃ $LimitNumber限制数目
⁃ $SortNumberJSON 字符串,如果有索引则不支持排序,数据集的长度必须少于 32 兆
⁃ $FieldsString字符串,字段以逗号分割。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}

返回字段描述

参数名类型描述
RequestIdString请求唯一标识
JobIdNumber任务 ID,用于在 migrateStatus 接口查询迁移状态

查询迁移(导入|导出)状态#

接口定义#

该接口可查询迁移(导入|导出)状态。

migrateStatus(int $jobId): object

参数说明#

参数名类型描述
$jobIdInteger任务 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"}

返回字段描述

参数名类型描述
RequestIdString请求唯一标识
StatusString任务状态。可能值:waiting:等待中,reading:读,writing:写,migrating:转移中,success:成功,fail:失败
RecordSuccessInteger迁移成功的数据条数
RecordFailInteger迁移失败的数据条数
ErrorMsgString迁移失败的原因
FileUrlString文件下载链接,仅在数据库导出中有效

查询数据分布#

接口定义#

该接口可查询数据分布。

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"}

返回字段描述

参数名类型描述
RequestIdString请求唯一标识
CollectionsArray集合列表
Collections[N].CollectionNameString集合名称
Collections[N].DocCountNumber文档数量

获取数据库实例#

接口定义#

该接口可获取 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();

更多详情请参见 这里