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

适用对象：卡珊德拉

重要

你是否正在寻找一种数据库解决方案，以应对需要高扩展性、99.999% 可用性服务级别协议（SLA）、即时自动扩展和跨多个区域的自动故障转移的场景？请考虑使用 Azure Cosmos DB for NoSQL。

Azure Cosmos DB 是Azure多区域分布式多模型数据库服务。您可以通过支持 Cassandra 查询语言（CQL）二进制协议 v4 wire 协议的开源 Cassandra 客户端驱动程序与适用于 Apache Cassandra 的 Azure Cosmos DB 进行通信。

通过使用适用于 Apache Cassandra 的 Azure Cosmos DB，你可以享受 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。

Cassandra 驱动程序

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

CQL 数据类型

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 在 Cassandra 帐户的 API 上支持以下数据库命令。

指令	已支持
`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 在 Cassandra 帐户的 API 上支持以下数据库命令。

指令	已支持
`CAPTURE`	是的
`CLEAR`	是的
`CONSISTENCY` *	无
`COPY`	否
`DESCRIBE`	是的
`cqlshExpand`	否
`EXIT`	是的
`LOGIN`	N/A （不支持 CQL 函数 `USER` ，因此 `LOGIN` 是冗余的）
`PAGING`	是的
`SERIAL CONSISTENCY` *	无
`SHOW`	是的
`SOURCE`	是的
`TRACING`	N/A （适用于 Cassandra 的 API 由 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 portal 中的数据资源管理器、指标、日志诊断、PowerShell 和 CLI 是管理帐户的其他受支持机制。

CQL 命令行界面

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

警告

与 Azure Cosmos DB for Apache Cassandra 的连接不适用于 DataStax Enterprise （DSE）或 Cassandra 4.0 版本的 CQLSH。在连接到适用于 Cassandra 的 API 时，请确保仅使用 v3.11 open source CQLSH 的 Apache Cassandra 版本。

窗户：

安装 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.cn 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.cn 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 中的 Cassandra API 将这些异常转换为 Cassandra 本机协议的过载错误。

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

后续步骤

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

Last updated on 2026-03-10

Compartilhar via