在 Azure Cosmos DB 中使用数据库、容器和项Work with databases, containers, and items in Azure Cosmos DB

在 Azure 订阅下创建 Azure Cosmos DB 帐户后,可以通过创建数据库、容器和项来管理帐户中的数据。After you create an Azure Cosmos DB account under your Azure subscription, you can manage data in your account by creating databases, containers, and items. 本文将介绍上述每个实体。This article describes each of these entities.

下图显示 Azure Cosmos DB 帐户中不同实体的层次结构:The following image shows the hierarchy of different entities in an Azure Cosmos DB account:

Azure Cosmos 帐户实体

Azure Cosmos 数据库Azure Cosmos databases

可以在帐户下创建一个或多个 Azure Cosmos 数据库。You can create one or multiple Azure Cosmos databases under your account. 数据库类似于命名空间,A database is analogous to a namespace. 数据库是一组 Azure Cosmos 容器的管理单元。A database is the unit of management for a set of Azure Cosmos containers. 下表显示如何将 Azure Cosmos 数据库映射到各种特定于 API 的实体:The following table shows how an Azure Cosmos database is mapped to various API-specific entities:

Azure Cosmos 实体Azure Cosmos entity SQL APISQL API Cassandra APICassandra API 用于 MongoDB 的 Azure Cosmos DB APIAzure Cosmos DB API for MongoDB Gremlin APIGremlin API 表 APITable API
Azure Cosmos 数据库Azure Cosmos database 数据库Database 密钥空间Keyspace 数据库Database 数据库Database 不可用NA

备注

如果使用表 API 帐户,在创建第一个表时,系统会自动在 Azure Cosmos 帐户中创建默认数据库。With Table API accounts, when you create your first table, a default database is automatically created in your Azure Cosmos account.

对 Azure Cosmos 数据库执行的操作Operations on an Azure Cosmos database

可以使用下表中所述的 Azure Cosmos API 来与 Azure Cosmos 数据库交互:You can interact with an Azure Cosmos database with Azure Cosmos APIs as described in the following table:

操作Operation Azure CLIAzure CLI SQL APISQL API Cassandra APICassandra API 用于 MongoDB 的 Azure Cosmos DB APIAzure Cosmos DB API for MongoDB Gremlin APIGremlin API 表 APITable API
枚举所有数据库Enumerate all databases Yes Yes 是(将数据库映射至密钥空间)Yes (database is mapped to a keyspace) Yes 不可用NA 不可用NA
读取数据库Read database Yes Yes 是(将数据库映射至密钥空间)Yes (database is mapped to a keyspace) Yes 不可用NA 不可用NA
创建新数据库Create new database Yes Yes 是(将数据库映射至密钥空间)Yes (database is mapped to a keyspace) Yes 不可用NA 不可用NA
更新数据库Update database Yes Yes 是(将数据库映射至密钥空间)Yes (database is mapped to a keyspace) Yes 不可用NA 不可用NA

Azure Cosmos 容器Azure Cosmos containers

Azure Cosmos 容器是预配的吞吐量和存储的缩放单元。An Azure Cosmos container is the unit of scalability both for provisioned throughput and storage. 容器会进行水平分区,然后在多个区域间复制。A container is horizontally partitioned and then replicated across multiple regions. 添加到容器的项以及针对容器预配的吞吐量将基于分区键自动分配给一组逻辑分区。The items that you add to the container and the throughput that you provision on it are automatically distributed across a set of logical partitions based on the partition key. 若要详细了解分区和分区键,请参阅将数据分区To learn more about partitioning and partition keys, see Partition data.

创建 Azure Cosmos 容器时,会在以下某种模式下配置吞吐量:When you create an Azure Cosmos container, you configure throughput in one of the following modes:

  • 专用预配吞吐量模式:针对容器预配的吞吐量是专门为该容器保留的,由 SLA 提供支持。Dedicated provisioned throughput mode: The throughput provisioned on a container is exclusively reserved for that container and it is backed by the SLAs. 有关详细信息,请参阅如何对 Azure Cosmos 容器预配吞吐量To learn more, see How to provision throughput on an Azure Cosmos container.

  • 共享预配吞吐量模式:这些容器与同一数据库中的其他容器共享预配吞吐量(不包含已配置专用预配吞吐量的容器)。Shared provisioned throughput mode: These containers share the provisioned throughput with the other containers in the same database (excluding containers that have been configured with dedicated provisioned throughput). 换而言之,针对该数据库预配的吞吐量是在所有“共享吞吐量”容器之间共享的。In other words, the provisioned throughput on the database is shared among all the "shared throughput" containers. 有关详细信息,请参阅如何对 Azure Cosmos 数据库预配吞吐量To learn more, see How to provision throughput on an Azure Cosmos database.

备注

只有在创建数据库和容器时,才能配置共享吞吐量和专用吞吐量。You can configure shared and dedicated throughput only when creating the database and container. 若要在创建容器后从专用吞吐量模式切换为共享吞吐量模式(或反之),必须创建一个新容器,并将数据迁移到该容器。To switch from dedicated throughput mode to shared throughput mode (and vice versa) after the container is created, you have to create a new container and migrate the data to the new container. 可以使用 Azure Cosmos DB 更改源功能迁移数据。You can migrate the data by using the Azure Cosmos DB change feed feature.

无论是使用专用还是共享预配吞吐量模式创建容器,Azure Cosmos 容器都可以弹性缩放。An Azure Cosmos container can scale elastically, whether you create containers by using dedicated or shared provisioned throughput modes.

Azure Cosmos 容器是与架构无关的项容器。An Azure Cosmos container is a schema-agnostic container of items. 容器中的项可以采用任意架构。Items in a container can have arbitrary schemas. 例如,可以在同一个容器中放置一个表示人员的项,以及一个表示汽车的项。**For example, an item that represents a person and an item that represents an automobile can be placed in the same container. 默认情况下,添加到容器的所有项会自动编制索引,不需要进行显式的索引或架构管理。By default, all items that you add to a container are automatically indexed without requiring explicit index or schema management. 通过在容器上配置的索引策略,可以自定义索引行为。You can customize the indexing behavior by configuring the indexing policy on a container.

可以针对 Azure Cosmos 容器中的所选项或整个容器设置生存时间 (TTL),以正常从系统中清除这些项。You can set Time to Live (TTL) on selected items in an Azure Cosmos container or for the entire container to gracefully purge those items from the system. Azure Cosmos DB 会在这些项过期时自动将其删除。Azure Cosmos DB automatically deletes the items when they expire. 这样还能保证对这些容器执行的查询不会返回固定边界内已过期的项。It also guarantees that a query performed on the container doesn't return the expired items within a fixed bound. 有关详细信息,请参阅对容器配置 TTLTo learn more, see Configure TTL on your container.

可以使用更改源订阅针对容器的每个逻辑分区管理的操作日志。You can use change feed to subscribe to the operations log that is managed for each logical partition of your container. 更改源提供对容器执行的所有更新的日志,以及更新前和更新后的项的映像。Change feed provides the log of all the updates performed on the container, along with the before and after images of the items. 有关详细信息,请参阅使用更改源生成被动式应用程序For more information, see Build reactive applications by using change feed. 还可以通过使用容器上的更改源策略来配置更改源的保留期限。You can also configure the retention duration for the change feed by using the change feed policy on the container.

可为 Azure Cosmos 容器注册存储过程、触发器、用户定义的函数 (UDF)合并过程You can register stored procedures, triggers, user-defined functions (UDFs), and merge procedures for your Azure Cosmos container.

可以在 Azure Cosmos 容器上指定一个唯一键约束You can specify a unique key constraint on your Azure Cosmos container. 通过创建唯一键策略,可确保每个逻辑分区键的一个或多个值的唯一性。By creating a unique key policy, you ensure the uniqueness of one or more values per logical partition key. 如果使用唯一键策略创建容器,则无法创建值与唯一键约束指定的值重复的任何新项或更新的项。If you create a container by using a unique key policy, no new or updated items with values that duplicate the values specified by the unique key constraint can be created. 若要了解详细信息,请参阅唯一键约束To learn more, see Unique key constraints.

Azure Cosmos 容器专用于 API 特定的实体,如下表所示:An Azure Cosmos container is specialized into API-specific entities as shown in the following table:

Azure Cosmos 实体Azure Cosmos entity SQL APISQL API Cassandra APICassandra API 用于 MongoDB 的 Azure Cosmos DB APIAzure Cosmos DB API for MongoDB Gremlin APIGremlin API 表 APITable API
Azure Cosmos 容器Azure Cosmos container 容器Container Table 集合Collection GraphGraph Table

备注

创建容器时,请确保不创建名称相同但大小写不同的两个容器。When creating containers, make sure you don't create two containers with the same name but different casing. 这是因为 Azure 平台的某些部分不区分大小写,这可能会对具有此类名称的容器导致遥测和操作混乱/冲突。That's because some parts of the Azure platform are not case-sensitive, and this can result in confusion/collision of telemetry and actions on containers with such names.

Azure Cosmos 容器的属性Properties of an Azure Cosmos container

Azure Cosmos 容器具备一组系统定义的属性。An Azure Cosmos container has a set of system-defined properties. 根据所用的 API,某些属性可能不会直接公开。Depending on which API you use, some properties might not be directly exposed. 下表介绍了系统定义属性的列表:The following table describes the list of system-defined properties:

系统定义的属性System-defined property 由系统生成或用户可配置System-generated or user-configurable 目的Purpose SQL APISQL API Cassandra APICassandra API 用于 MongoDB 的 Azure Cosmos DB APIAzure Cosmos DB API for MongoDB Gremlin APIGremlin API 表 APITable API
_rid_rid 由系统生成System-generated 容器的唯一标识符Unique identifier of container Yes No No No No
_etag_etag 由系统生成System-generated 用于乐观并发控制的实体标记Entity tag used for optimistic concurrency control Yes No No No No
_ts_ts 由系统生成System-generated 容器上次更新的时间戳Last updated timestamp of the container Yes No No No No
_self_self 由系统生成System-generated 容器的可寻址 URIAddressable URI of the container Yes No No No No
idid 用户可配置User-configurable 用户定义的容器唯一名称User-defined unique name of the container Yes Yes Yes Yes Yes
indexingPolicyindexingPolicy 用户可配置User-configurable 提供更改索引路径、索引类型和索引模型的功能Provides the ability to change the index path, index type, and index mode Yes No No No Yes
TimeToLiveTimeToLive 用户可配置User-configurable 提供在设置的时间段后从容器自动删除项的功能Provides the ability to delete items automatically from a container after a set time period. 有关详细信息,请参阅生存时间For details, see Time to Live. Yes No No No Yes
changeFeedPolicychangeFeedPolicy 用户可配置User-configurable 用于读取对容器中的项所做的更改。Used to read changes made to items in a container. 有关详细信息,请参阅更改源For details, see Change feed. Yes No No No Yes
uniqueKeyPolicyuniqueKeyPolicy 用户可配置User-configurable 用于确保逻辑分区中一个或多个值的唯一性。Used to ensure the uniqueness of one or more values in a logical partition. 有关详细信息,请参阅唯一键约束For more information, see Unique key constraints. Yes No No No Yes

对 Azure Cosmos 容器执行的操作Operations on an Azure Cosmos container

使用任一 Azure Cosmos API 时,Azure Cosmos 容器支持以下操作:An Azure Cosmos container supports the following operations when you use any of the Azure Cosmos APIs:

操作Operation Azure CLIAzure CLI SQL APISQL API Cassandra APICassandra API 用于 MongoDB 的 Azure Cosmos DB APIAzure Cosmos DB API for MongoDB Gremlin APIGremlin API 表 APITable API
枚举数据库中的容器Enumerate containers in a database Yes Yes Yes Yes 不可用NA 不可用NA
读取容器Read a container Yes Yes Yes Yes 不可用NA 不可用NA
创建新容器Create a new container Yes Yes Yes Yes 不可用NA 不可用NA
更新容器Update a container Yes Yes Yes Yes 不可用NA 不可用NA
删除容器Delete a container Yes Yes Yes Yes 不可用NA 不可用NA

Azure Cosmos 项Azure Cosmos items

根据所用的 API,Azure Cosmos 项可以代表集合中的文档、表中的行,或者图形中的节点或边缘。Depending on which API you use, an Azure Cosmos item can represent either a document in a collection, a row in a table, or a node or edge in a graph. 下表显示了 API 特定的实体与 Azure Cosmos 项之间的映射:The following table shows the mapping of API-specific entities to an Azure Cosmos item:

Cosmos 实体Cosmos entity SQL APISQL API Cassandra APICassandra API 用于 MongoDB 的 Azure Cosmos DB APIAzure Cosmos DB API for MongoDB Gremlin APIGremlin API 表 APITable API
Azure Cosmos 项Azure Cosmos item Item Row 文档Document 节点或边缘Node or edge 项目Item

项的属性Properties of an item

每个 Azure Cosmos 项具有以下系统定义的属性。Every Azure Cosmos item has the following system-defined properties. 根据所用的 API,其中的某些属性可能不会直接公开。Depending on which API you use, some of them might not be directly exposed.

系统定义的属性System-defined property 由系统生成或用户可配置System-generated or user-configurable 目的Purpose SQL APISQL API Cassandra APICassandra API 用于 MongoDB 的 Azure Cosmos DB APIAzure Cosmos DB API for MongoDB Gremlin APIGremlin API 表 APITable API
_rid_rid 由系统生成System-generated 项的唯一标识符Unique identifier of the item Yes No No No No
_etag_etag 由系统生成System-generated 用于乐观并发控制的实体标记Entity tag used for optimistic concurrency control Yes No No No No
_ts_ts 由系统生成System-generated 项上次更新的时间戳Timestamp of the last update of the item Yes No No No No
_self_self 由系统生成System-generated 项的可寻址 URIAddressable URI of the item Yes No No No No
idid 任一个Either 逻辑分区中用户定义的唯一名称。User-defined unique name in a logical partition. Yes Yes Yes Yes Yes
任意用户定义的属性Arbitrary user-defined properties 用户定义User-defined 用户定义的属性以 API 本机表示形式表示(包括 JSON、BSON 和 CQL)User-defined properties represented in API-native representation (including JSON, BSON, and CQL) Yes Yes Yes Yes Yes

备注

id 属性的唯一性仅在每个逻辑分区中强制实施。Uniqueness of the id property is only enforced within each logical partition. 多个文档可以具有相同的 id 属性,但具有不同的分区键值。Multiple documents can have the same id property with different partition key values.

对项执行的操作Operations on items

Azure Cosmos 项支持以下操作。Azure Cosmos items support the following operations. 可以使用任一 Azure Cosmos API 来执行这些操作。You can use any of the Azure Cosmos APIs to perform the operations.

操作Operation Azure CLIAzure CLI SQL APISQL API Cassandra APICassandra API 用于 MongoDB 的 Azure Cosmos DB APIAzure Cosmos DB API for MongoDB Gremlin APIGremlin API 表 APITable API
插入、替换、删除、Upsert、读取Insert, Replace, Delete, Upsert, Read No Yes Yes Yes Yes Yes

后续步骤Next steps

了解以下任务和概念:Learn about these tasks and concepts: