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

适用于: Cassandra API

Azure Cosmos DB 是 Azure 提供的多区域分布式多模型数据库服务。 你可以通过与 CQL 二进制协议 v4 线路协议兼容的开放源代码 Cassandra 客户端驱动程序与 Azure Cosmos DB Cassandra API 通信。

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

Cassandra 协议

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

Cassandra 驱动程序

Azure Cosmos DB Cassandra API 支持以下版本的 Cassandra 驱动程序:

CLR 数据类型

Azure Cosmos DB Cassandra API 支持以下 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 Cassandra API 支持以下 CQL 函数:

Command 支持
标记 *
ttl ***
writetime ***
cast **

备注

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

聚合函数:

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

Command 支持
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 条件
INSERT IF NOT EXISTS
UPDATE IF EXISTS
UPDATE IF NOT EXISTS
UPDATE 条件

CQL Shell 命令

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

Command 支持
捕获
CLEAR
CONSISTENCY * 不适用
复制
DESCRIBE
cqlshExpand
EXIT
LOGIN 不适用(不支持 CQL 函数 USER,因此 LOGIN 是冗余的)
PAGING
SERIAL CONSISTENCY * 不适用
SHOW
TRACING 不适用(Cassandra API 由 Azure Cosmos DB 提供支持 - 使用诊断日志记录进行故障排除)

备注

* 一致性在 Azure Cosmos DB 中的工作方式不同,请参阅此处获取详细信息。

JSON 支持

Command 支持
SELECT JSON
INSERT JSON
fromJson()
toJson()

Cassandra API 限制

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

工具

Azure Cosmos DB Cassandra API 是一个托管的服务平台。 它不需要任何管理开销或实用程序(如垃圾回收器、Java 虚拟机 (JVM) 和 nodetool)来管理群集。 它支持利用二进制 CQLv4 兼容性的工具(如 cqlsh)。

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

托管 CQL shell(预览版)

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

备注

与 Azure Cosmos DB Cassandra API 的连接将不适用于 CQLSH 的 DataStax Enterprise (DSE) 版本。 连接到 Cassandra API 时,请确保只使用 CQLSH 的开源 Apache Cassandra 版本。

Windows:

如果使用 Windows,建议启用适用于 Linux 的 Windows 文件系统。 然后即可按照以下 linux 命令进行操作。

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 http://www.apache.org/dist/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

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

# Connect to Azure Cosmos DB API for Cassandra:
cqlsh <YOUR_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 Cassandra API 为读取操作提供了一致性选择。 一致性映射的信息详见此文

权限和角色管理

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 ;

辅助索引

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

使用 Cassandra 重试连接策略

Azure Cosmos DB 是一种资源治理系统。 这意味着,你可以根据操作消耗的请求单位数在给定的秒内执行特定数目的操作。 如果应用程序在给定的秒内超出该限制,则请求会受到速率限制,并会引发异常。 Azure Cosmos DB 中的 Cassandra API 在 Cassandra 本机协议中将这些异常解释为过载错误。 为了确保应用程序在速率受限的情况下能够截获并重试请求,我们提供了 sparkJava 扩展。 当连接到 Azure Cosmos DB 中的 Cassandra API 时,另请参阅 Datastax 驱动程序版本 3版本 4 的 Java 代码示例。 在 Azure Cosmos DB 中,如果使用其他 SDK 来访问 Cassandra API,请创建一项连接策略,以便在出现这些异常时进行重试。

后续步骤