你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

Azure Cosmos DB for Apache Cassandra 支持的 Apache Cassandra 功能

2025-06-09

适用对象：卡珊德拉

Azure Cosmos DB 由 Microsoft 提供，是全球分布的多模型数据库服务。你可以通过与 Cassandra 查询语言 (CQL) 二进制协议 v4 线路协议兼容的开放源代码 Cassandra 客户端驱动程序与 Azure Cosmos DB for Apache Cassandra 通信。

通过使用 Azure Cosmos DB for Apache Cassandra，你可以尽享 Apache Cassandra ApI 带来的诸多优势，以及 Azure Cosmos DB 提供的各项企业功能。企业功能包括全局分发、自动横向扩展分区、可用性和延迟保证、静态加密和备份。

Cassandra 协议

适用于 Apache Cassandra 的 Azure Cosmos DB 与 Cassandra 查询语言（CQL） v3.11 API 兼容。它与版本 2.x 向后兼容。本文后面列出了支持的 CQL 命令、工具、限制和例外。任何理解这些协议的客户端驱动程序都应该能够连接到 Azure Cosmos DB for Apache Cassandra。

适用于 Apache Cassandra 的 Azure 托管实例

对于某些客户来说，由于行为和配置存在差异，适应 API for Cassandra 可能是一项挑战，尤其是对于直接迁移而言。如果本文后面提到某个对你的应用程序至关重要的功能不受支持，请考虑使用适用于 Apache Cassandra 的 Azure 托管实例。此服务是一项第一方 Azure 服务，用于托管和维护具有 100% 兼容性的纯开源 Apache Cassandra 群集。

Cassandra 驱动程序

Azure Cosmos DB for Apache Cassandra 支持以下版本的 Cassandra 驱动程序：

CLR 数据类型

Azure Cosmos DB for Apache Cassandra 支持以下 CQL 数据类型：

类型	支持
`ascii`	是
`bigint`	是
`blob`	是
`boolean`	是
`counter`	是
`date`	是
`decimal`	是
`double`	是
`float`	是
`frozen`	是
`inet`	是
`int`	是
`list`	是
`set`	是
`smallint`	是
`text`	是
`time`	是
`timestamp`	是
`timeuuid`	是
`tinyint`	是
`tuple`	是
`uuid`	是
`varchar`	是
`varint`	是
`tuples`	是
`udts`	是
`map`	是

数据类型声明支持静态。

CQL 函数

Azure Cosmos DB for Apache Cassandra 支持以下 CQL 函数：

命令	支持
`Token` *	是
`ttl` ***	是
`writetime` ***	是
`cast` **	是

注意

* API for Cassandra 支持作为投影/选择器的标记，但只允许在 where 子句的左侧使用标记(pk)。例如，支持 WHERE token(pk) > 1024，但不支持 WHERE token(pk) > token(100)。 ** cast() 函数不可嵌套在 API for Cassandra 中。例如，支持 SELECT cast(count as double) FROM myTable，但不支持 SELECT avg(cast(count as double)) FROM myTable。 *** 使用 USING 选项指定的自定义时间戳和 TTL 在行级别应用（而不是按每个单元格进行应用）。

聚合函数：

命令	支持
`avg`	是
`count`	是
`min`	是
`max`	是
`sum`	是

注意

聚合函数适用于常规列，而不适用于聚类分析列。

Blob 转换函数：

命令	支持
`typeAsBlob(value)`	是
`blobAsType(value)`	是

UUID 和 timeuuid 函数：

命令	支持
`dateOf()`	是
`now()`	是
`minTimeuuid()`	是
`unixTimestampOf()`	是
`toDate(timeuuid)`	是
`toTimestamp(timeuuid)`	是
`toUnixTimestamp(timeuuid)`	是
`toDate(timestamp)`	是
`toUnixTimestamp(timestamp)`	是
`toTimestamp(date)`	是
`toUnixTimestamp(date)`	是

CQL 命令

Azure Cosmos DB 在 API for Cassandra 帐户上支持以下数据库命令。

命令	支持
`ALLOW FILTERING`	是
`ALTER KEYSPACE`	不适用（PaaS 服务，在内部管理的复制）
`ALTER MATERIALIZED VIEW`	是
`ALTER ROLE`	否
`ALTER TABLE`	是
`ALTER TYPE`	否
`ALTER USER`	否
`BATCH`	是（仅限无日志记录的批处理）
`COMPACT STORAGE`	不适用（PaaS 服务）
`CREATE AGGREGATE`	否
`CREATE CUSTOM INDEX (SASI)`	否
`CREATE INDEX`	是（包括命名索引，但不支持完整的 FROZEN 集合）
`CREATE FUNCTION`	否
`CREATE KEYSPACE`（忽略复制设置）	是
`CREATE MATERIALIZED VIEW`	是
`CREATE TABLE`	是
`CREATE TRIGGER`	否
`CREATE TYPE`	是
`CREATE ROLE`	否
`CREATE USER`（在原生 Apache Cassandra 中已弃用）	否
`DELETE`	是
`DISTINCT`	否
`DROP AGGREGATE`	否
`DROP FUNCTION`	否
`DROP INDEX`	是
`DROP KEYSPACE`	是
`DROP MATERIALIZED VIEW`	是
`DROP ROLE`	否
`DROP TABLE`	是
`DROP TRIGGER`	否
`DROP TYPE`	是
`DROP USER`（在原生 Apache Cassandra 中已弃用）	否
`GRANT`	否
`INSERT`	是
`LIST PERMISSIONS`	否
`LIST ROLES`	否
`LIST USERS`（在原生 Apache Cassandra 中已弃用）	否
`REVOKE`	否
`SELECT`	是
`UPDATE`	是
`TRUNCATE`	是
`USE`	是

轻量级事务 (LWT)

组件	支持
`DELETE IF EXISTS`	是
`DELETE conditions`	是
`INSERT IF NOT EXISTS`	是
`UPDATE IF EXISTS`	是
`UPDATE IF NOT EXISTS`	是
`UPDATE conditions`	是

注意

目前，启用了多区域写入的帐户不支持轻型事务。

CQL Shell 命令

Azure Cosmos DB 在 API for Cassandra 帐户上支持以下数据库命令。

命令	支持
`CAPTURE`	是
`CLEAR`	是
`CONSISTENCY` *	空值
`COPY`	否
`DESCRIBE`	是
`cqlshExpand`	否
`EXIT`	是
`LOGIN`	N/A （不支持 CQL 函数 `USER` ，因此 `LOGIN` 是冗余的）
`PAGING`	是
`SERIAL CONSISTENCY` *	空值
`SHOW`	是
`SOURCE`	是
`TRACING`	不适用（API for Cassandra 由 Azure Cosmos DB 提供支持 - 使用诊断日志记录进行故障排除）

注意

一致性在 Azure Cosmos DB 中的工作方式不同。有关详细信息，请参阅 Apache Cassandra 和 Azure Cosmos DB for Apache Cassandra 一致性级别。

JSON 支持

命令	支持
`SELECT JSON`	是
`INSERT JSON`	是
`fromJson()`	否
`toJson()`	否

API for Cassandra 限制

Azure Cosmos DB for Apache Cassandra 对表中存储的数据大小没有任何限制。在确保遵循分区键限制的同时，可以存储数百 TB 或 PB 的数据。同样，每个实体或行等效项对列数没有任何限制。实体的总大小不应超过 2 MB。每个分区键的数据不能超过 20 GB，就像所有其他 API 中一样。

工具

Azure Cosmos DB for Apache Cassandra 是一个托管服务平台。平台不需要任何管理开销或实用工具，例如垃圾回收器、Java 虚拟机（JVM）和节点工具来管理群集。支持与二进制 CQLv4 兼容的工具，例如cqlsh。

Azure 门户的数据资源管理器、指标、日志诊断、PowerShell 和 CLI 是管理帐户的其他支持机制。

CQL shell

可以使用安装在本地计算机上的 CQLSH 连接到 Azure Cosmos DB 中的 API for Cassandra。它随 Apache Cassandra 3.11 一起提供，设置一些环境变量即可直接使用。以下部分包括使用 CQLSH 在 Windows 或 Linux 上的 Azure Cosmos DB 中安装、配置和连接到 API for Cassandra 的说明。

警告

与 Azure Cosmos DB for Apache Cassandra 的连接不适用于 CQLSH 的 DataStax Enterprise (DSE) 或 Cassandra 4.0 版本。确保连接到适用于 Cassandra 的 API 时，仅使用 v3.11 开源 Apache Cassandra 版本的 CQLSH。

窗户：

安装 Python 3。
安装 PIP。
1. 安装 PIP 之前，请下载 get-pip.py 文件。
2. 启动命令提示符窗口（如果尚未打开）。为此，请打开 Windows 搜索栏，键入 cmd 并选择图标。
3. 然后运行以下命令以下载 get-pip.py 文件：
```
curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py 
```
在 Windows 上安装 PIP：
```
python get-pip.py
```
验证 PIP 安装。请查找步骤 3 的消息，以确认 PIP 被安装到了哪个文件夹。然后导航到该文件夹并运行命令 pip 帮助。
使用 PIP 安装 CQLSH：
```
pip3 install cqlsh==5.0.3
```
安装 Python 2。
使用身份验证机制运行 CQLSH。

注意

需要将环境变量设置为指向 Python 2 文件夹。

在 Unix/Linux/Mac 上安装：

# Install default-jre and default-jdk
sudo apt install default-jre
sudo apt-get update
sudo apt install default-jdk

# Import the Baltimore CyberTrust root certificate:
curl https://cacert.omniroot.com/bc2025.crt > bc2025.crt
keytool -importcert -alias bc2025ca -file bc2025.crt

# Install the Cassandra libraries in order to get CQLSH:
echo "deb https://downloads.apache.org/cassandra/debian 311x main" | sudo tee -a /etc/apt/sources.list.d/cassandra.sources.list
curl https://downloads.apache.org/cassandra/KEYS | sudo apt-key add -
sudo apt-get update
sudo apt-get install cassandra=3.11.13

与 Unix/Linux/Mac 连接：

# Export the SSL variables:
export SSL_VERSION=TLSv1_2
export SSL_VALIDATE=false

# Connect to Azure Cosmos DB for Apache Cassandra:
cqlsh <YOUR_ACCOUNT_NAME>.cassandra.cosmosdb.azure.com 10350 -u <YOUR_ACCOUNT_NAME> -p <YOUR_ACCOUNT_PASSWORD> --ssl --protocol-version=4

使用 Docker 进行连接：

docker run -it --rm -e SSL_VALIDATE=false -e SSL_VERSION=TLSv1_2 cassandra:3.11 cqlsh <account_name>.cassandra.cosmos.azure.com 10350 -u <YOUR_ACCOUNT_NAME> -p <YOUR_ACCOUNT_PASSWORD> --ssl

通过 CQL v4 兼容的 SDK 运行的所有 CRUD 操作都会返回有关错误和消耗的请求单位的额外信息。为了确保使用预配的吞吐量最高效，应考虑使用资源治理来处理 DELETE 和 UPDATE 命令。

注意

如果指定，该值 gc_grace_seconds 必须为零。

var tableInsertStatement = table.Insert(sampleEntity); 
var insertResult = await tableInsertStatement.ExecuteAsync(); 
 
foreach (string key in insertResult.Info.IncomingPayload) 
        { 
            byte[] valueInBytes = customPayload[key]; 
            double value = Encoding.UTF8.GetString(valueInBytes); 
            Console.WriteLine($"CustomPayload:  {key}: {value}"); 
        }

一致性映射

Azure Cosmos DB for Apache Cassandra 为读取操作提供了一致性选择。有关详细信息，请参阅映射一致性级别。

权限和角色管理

Azure Cosmos DB 支持 Azure 基于角色的访问控制 (Azure RBAC) 用于预配、旋转密钥、查看指标以及读写和只读密码/密钥（可通过 Azure 门户获取）。 Azure Cosmos DB 不支持 CRUD 活动的角色。

密钥空间和表选项

当前将忽略命令中 CREATE KEYSPACE 区域名称、类、replication_factor和数据中心的选项。系统使用基础 Azure Cosmos DB 的全局分发复制方法来添加区域。如果需要数据的跨区域存在，可以在帐户级别使用 PowerShell、CLI 或 Azure 门户启用该功能。有关详细信息，请参阅将区域添加到数据库帐户。

Durable_writes 不能禁用，因为 Azure Cosmos DB 需确保每次写入都是持久的。在每个区域，Azure Cosmos DB 都会跨副本集（由四个副本组成）来复制数据。该副本集配置不能修改。

创建表时，将忽略所有选项，但 gc_grace_seconds应将其设置为零。 Keyspace 和表具有一个名为 cosmosdb_provisioned_throughput 的额外选项，最小值为 400 RU/s。密钥空间吞吐量允许跨多个表共享吞吐量。当所有表未充分利用预配吞吐量时，这种方法非常有用。该 ALTER TABLE 命令允许跨区域更改预配的吞吐量。

CREATE KEYSPACE sampleks WITH REPLICATION = {  'class' : 'SimpleStrategy'} AND cosmosdb_provisioned_throughput=2000;  

CREATE TABLE sampleks.t1(user_id int PRIMARY KEY, lastname text) WITH cosmosdb_provisioned_throughput=2000; 

ALTER TABLE gks1.t1 WITH cosmosdb_provisioned_throughput=10000 ;

辅助索引

API for Cassandra 支持所有数据类型的辅助索引，但冻结的集合类型、十进制和变量类型除外。

使用 Cassandra 重试连接策略

Azure Cosmos DB 是一种资源治理系统。你可以根据操作消耗的请求单位数在给定的秒内执行某些操作。如果应用程序在给定秒内超过该限制，则请求速率受限，并引发异常。 Azure Cosmos DB 中的 API for Cassandra 在 Cassandra 本机协议中将这些异常解释为过载错误。

为了确保您的应用程序在存在速率限制的情况下可以截获和重试请求，提供了 spark 和 Java 扩展。当连接到 Azure Cosmos DB 中的 API for Cassandra 时，另请参阅 Datastax 驱动程序版本 3 和版本 4 的 Java 代码示例。在 Azure Cosmos DB 中，如果使用其他 SDK 来访问 API for Cassandra，请创建一项重试策略，以便在出现这些异常时进行重试。也可为 API for Cassandra 启用服务器端重试。

后续步骤

开始使用 Java 应用程序为 Cassandra 帐户、数据库和表创建 API

通过