Azure Cosmos DB for Apache Cassandra 支持的 Apache Cassandra 功能
适用对象：
Cassandra
Azure Cosmos DB 是 Azure 提供的多区域分布式多模型数据库服务。 你可以通过与 Cassandra 查询语言 (CQL) 二进制协议 v4 线路协议兼容的开放源代码 Cassandra 客户端驱动程序与 Azure Cosmos DB for Apache Cassandra 通信。
通过使用 Azure Cosmos DB for Apache Cassandra，你可以尽享 Apache Cassandra ApI 带来的诸多优势，以及 Azure Cosmos DB 提供的各项企业功能。 企业功能包括多区域分发、自动横向扩展分区、可用性和延迟保证、空闲时加密、备份等。
Cassandra 协议
Azure Cosmos DB for Apache Cassandra 与 Cassandra 查询语言 (CQL) v3.11 API 兼容（后向兼容版本 2.x）。 下面列出了支持的 CQL 命令、工具、限制和例外。 任何理解这些协议的客户端驱动程序都应该能够连接到 Azure Cosmos DB for 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 在行级别应用（而不是按每个单元格进行应用）。
聚合函数：
| Command | 支持 |
|---|---|
avg |
是 |
count |
是 |
min |
是 |
max |
是 |
sum |
是 |
注意
聚合函数适用于常规列，而不适用于聚类分析列。
Blob 转换函数：
| Command | 支持 |
|---|---|
typeAsBlob(value) |
是 |
blobAsType(value) |
是 |
UUID 和 timeuuid 函数：
| Command | 支持 |
|---|---|
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 |
No |
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 |
No |
DROP FUNCTION |
No |
DROP INDEX |
是 |
DROP KEYSPACE |
是 |
DROP MATERIALIZED VIEW |
否 |
DROP ROLE |
No |
DROP TABLE |
是 |
DROP TRIGGER |
否 |
DROP TYPE |
是 |
DROP USER（在原生 Apache Cassandra 中已弃用） |
否 |
GRANT |
No |
INSERT |
是 |
LIST PERMISSIONS |
否 |
LIST ROLES |
否 |
LIST USERS（在原生 Apache Cassandra 中已弃用） |
否 |
REVOKE |
No |
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 |
不适用（不支持 CQL 函数 USER，因此 LOGIN 是冗余的） |
PAGING |
是 |
SERIAL CONSISTENCY * |
不适用 |
SHOW |
是 |
SOURCE |
是 |
TRACING |
不适用（API for Cassandra 由 Azure Cosmos DB 提供支持 - 使用诊断日志记录进行故障排除） |
注意
一致性在 Azure Cosmos DB 中的工作方式不同，请参阅此处获取详细信息。
JSON 支持
| Command | 支持 |
|---|---|
SELECT JSON |
是 |
INSERT JSON |
是 |
fromJson() |
否 |
toJson() |
否 |
API for Cassandra 限制
Azure Cosmos DB for Apache Cassandra 对表中存储的数据的大小没有任何限制。 在确保遵循分区键限制的同时，可以存储数百 TB 或 PB 的数据。 同样，每个实体或等效行对列数没有任何限制。 但是，实体的总大小不应超过 2 MB。 与所有其他 API 一样，每个分区键的数据都不能超过 20 GB。
工具
Azure Cosmos DB for Apache Cassandra 是一个托管服务平台。 该平台不需要任何管理开销或实用程序（如垃圾回收器、Java 虚拟机 (JVM) 和 nodetool）来管理群集。 支持使用二进制 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 版本。 连接到 API for Cassandra 时，请确保只使用 CQLSH 的 v3.11 开源 Apache Cassandra 版本。
Windows：
- 安装 Python 3
- 安装 PIP
- 安装 PIP 之前，请下载 get-pip.py 文件。
- 启动命令提示符（如果尚未打开）。 为此，请打开 Windows 搜索栏，键入 cmd 并选择该图标。
- 然后运行以下命令下载 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 help）。
- 使用 PIP 安装 CQLSH
pip3 install cqlsh==5.0.3
注意
需要设置环境变量，使其指向 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 活动的角色。
密钥空间和表选项
目前会忽略“创建密钥空间”命令中针对区域名称、类、replication_factor 和数据中心的选项。 系统使用基础 Azure Cosmos DB 的多区域分发复制方法来添加区域。 如果需要数据跨区域存在，可以使用 PowerShell、CLI 或门户在帐户级别启用它。若要了解详细信息，请参阅如何添加区域一文。 Durable_writes 不能禁用，因为 Azure Cosmos DB 需确保每次写入都是持久的。 在每个区域，Azure Cosmos DB 都会跨副本集（由四个副本组成）来复制数据。该副本集配置不能修改。
在创建表时，会忽略所有选项，但 gc_grace_seconds 除外，后者应设置为零。 密钥空间和表有一个名为“cosmosdb_provisioned_throughput”的额外选项，该选项的最小值为 400 RU/秒。 密钥空间吞吐量允许跨多个表共享吞吐量，这适用于所有表都不利用预配的吞吐量的情况。 “更改表”命令允许跨区域更改预配的吞吐量。
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 应用程序创建 API for Cassandra 帐户、数据库和表