適用於：
卡珊德拉
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 受控執行個體
對於某些客戶來說，適應 Cassandra 的 API 可能因行為和配置的差異而面臨挑戰，尤其是在進行「遷移和轉換」的過程中。 如果在本文稍後列出的不支援的功能對您的應用程式至關重要，請考慮使用 適用於 Apache Cassandra 的 Azure 受控實例。 此服務是第一方 Azure 服務，用於裝載和維護具有 100 個% 相容性的純開放原始碼 Apache Cassandra 叢集。
Cassandra 驅動程式
適用於 Apache Cassandra 的 Azure 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 支援使用 Token 作為投影/選取器，而且只允許 token (pk) 位在 where 子句的左側。 例如，支援 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 會套用至數據列層級（而不是每個儲存格）。
彙總函式：
| 指令 | 支援 |
|---|---|
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 |
N/A (PaaS 服務，內部複寫管理) |
ALTER MATERIALIZED VIEW |
是的 |
ALTER ROLE |
無 |
ALTER TABLE |
是的 |
ALTER TYPE |
無 |
ALTER USER |
無 |
BATCH |
是 (僅限未記錄的批次) |
COMPACT STORAGE |
N/A (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 * |
N/A |
COPY |
無 |
DESCRIBE |
是的 |
cqlshExpand |
無 |
EXIT |
是的 |
LOGIN |
N/A （不支援 CQL 函 USER 式，因此 LOGIN 是多餘的） |
PAGING |
是的 |
SERIAL CONSISTENCY * |
N/A |
SHOW |
是的 |
SOURCE |
是的 |
TRACING |
N/A (由 Azure Cosmos DB 提供技術支援的 API for Cassandra - 使用診斷記錄進行疑難排解) |
注意
一致性在 Azure Cosmos DB 中的運作方式不同。 如需詳細資訊，請參閱 Apache Cassandra 和 Azure Cosmos DB for Apache Cassandra 一致性層級。
JSON 支援
| 指令 | 支援 |
|---|---|
SELECT JSON |
是的 |
INSERT JSON |
是的 |
fromJson() |
無 |
toJson() |
無 |
API for Cassandra 限制
適用於 Apache Cassandra 的 Azure Cosmos DB 對於儲存在數據表中的數據大小沒有任何限制。 可以儲存數百 TB 或 PB 的資料，同時確保遵守資料分割金鑰。 同樣地，每個實體或行對等物件對欄數沒有任何限制。 實體的總大小不應超過 2 MB。 每個分割區索引鍵的數據不能超過 20 GB，如同所有其他 API 一樣。
工具
Azure Cosmos DB for Apache Cassandra 是受控服務平台。 平臺不需要任何管理負擔或公用程式，例如垃圾回收器、Java 虛擬機（JVM）和節點工具來管理叢集。 支援使用二進位 CQLv4 相容性的工具，例如cqlsh。
- Azure 入口網站的數據總管、計量、記錄診斷、PowerShell 和 CLI 是管理帳戶的其他支持機制。
CQL 殼層
您可以使用本機電腦上安裝的 CQLSH 連線至 Azure Cosmos DB 中的 API for Cassandra。 其中隨附 Apache Cassandra 3.11，且只需設定環境變數即可立即運作。 以下幾節包含相關指示，可引導您在 Windows 或 Linux 上使用 CQLSH 安裝、設定及連線至 Azure Cosmos DB 中的 API for Cassandra。
警告
適用於 Apache Cassandra 的 Azure Cosmos DB 連線無法與 DataStax Enterprise （DSE） 或 Cassandra 4.0 版 CQLSH 搭配運作。 請確定您在連線到適用於 Cassandra 的 API 時，只使用 v3.11 開放原始碼 Apache Cassandra 版本的 CQLSH。
窗戶：
安裝 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。
注意
您必須將環境變數設定為指向 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 活動的角色。
Keyspace 和資料表選項
目前會忽略命令中 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/秒。 Keyspace 吞吐量允許在多個資料表間共享吞吐量。 當所有資料表未完全使用預配置的吞吐量時，這個功能非常有用。
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 支援所有資料類型上的次要索引，但凍結的集合類型、decimal 和 variant 類型除外。
使用 Cassandra 重試連線原則
Azure Cosmos DB 是資源控管系統。 在特定的一秒內，您可以根據操作消耗的要求單位來執行某些操作。 如果應用程式在指定的秒內超過該限制，請求會被限制速率，並拋出例外狀況。 Azure Cosmos DB 中的 API for Cassandra 會將這些例外狀況轉譯成 Cassandra 原生通訊協定上的多載錯誤。
為了確保您的應用程式在遇到速率限制時可以攔截和重試要求，提供了 spark 和 Java 延伸模組。 連線至 Azure Cosmos DB 中的 API for Cassandra 時，另請參閱第 3 版和第 4 版 Datastax 驅動程式的 Java 程式碼範例。 如果您使用其他 SDK 來存取 Azure Cosmos DB 中的 API for Cassandra，請建立重試原則以在這些例外狀況重試。 或者，針對 API for Cassandra 啟用伺服器端重試。
下一步
- 開始使用 Java 應用程式建立適用於 Cassandra 帳戶、資料庫和數據表的 API