Skip to content

Latest commit

 

History

History
690 lines (526 loc) · 17.5 KB

clouddatabase.md

File metadata and controls

690 lines (526 loc) · 17.5 KB
Raw

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-1254135806.cos.ap-shanghai.myqcloud.com/469835132/tcb_already_exists.json?q-sign-algorithm=sha1&q-ak=AKIDsp8NUoE8C8yd9TvEeyoX5g6LUmXUh9Wy&q-sign-time=1560263593;1560267193&q-key-time=1560263593;1560267193&q-header-list=&q-url-param-list=&q-signature=5fed574f9c459030cba2bf46eb329d4e6b2b4a72",
  "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();

更多详情请参见 这里。