Azure Cosmos DB for Apache Cassandra 支援的 Apache Cassandra 功能
適用於：
Cassandra
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 通訊協定
Azure Cosmos DB for Apache Cassandra 與 Cassandra 查詢語言 (CQL) v3.11 API 相容 (可與 2.x 版的舊版相容)。 支援的 CQL 命令、工具、限制與例外，如下所示。 能解析這些通訊協定的任何用戶端驅動程式，都應該能夠使用連線到 Azure Cosmos DB for Apache Cassandra。
適用於 Apache Cassandra 的 Azure 受控執行個體
對於某些客戶來說，適應 API for Cassandra 可能會因行為和/或設定的差異而面臨挑戰，特別是針對隨即轉移移轉。 如果應用程式的重要功能在下面列為不受支援，則請考慮使用 Azure Managed Instance for Apache Cassandra。 這是第一方 Azure 服務，可裝載和維護具有 100% 相容性的純開放原始碼 Apache Cassandra 叢集。
Cassandra 驅動程式
Azure Cosmos DB for Apache Cassandra 支援下列 Cassandra 驅動程式：
CQL 資料類型
Azure Cosmos DB for Apache Cassandra 支援下列 CQL 資料類型：
| 類型 | 支援 |
|---|---|
ascii |
Yes |
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 |
Yes |
資料類型宣告支援靜態。
CQL 功能
Azure Cosmos DB for Apache Cassandra 支援下列 CQL 函式：
| Command | 支援 |
|---|---|
Token * |
Yes |
ttl *** |
.是 |
writetime *** |
.是 |
cast ** |
是 |
注意
* API for Cassandra 支援使用 Token 作為投影/選取器，而且只允許 token (pk) 位在 where 子句的左側。 例如，支援 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 |
Yes |
count |
.是 |
min |
.是 |
max |
.是 |
sum |
是 |
注意
彙總函式適用於一般資料行，但不支援叢集資料行上的彙總。
Blob 轉換函式：
| Command | 支援 |
|---|---|
typeAsBlob(value) |
Yes |
blobAsType(value) |
Yes |
UUID 與 timeuuid 函式：
| Command | 支援 |
|---|---|
dateOf() |
Yes |
now() |
.是 |
minTimeuuid() |
.是 |
unixTimestampOf() |
.是 |
toDate(timeuuid) |
.是 |
toTimestamp(timeuuid) |
.是 |
toUnixTimestamp(timeuuid) |
.是 |
toDate(timestamp) |
.是 |
toUnixTimestamp(timestamp) |
.是 |
toTimestamp(date) |
.是 |
toUnixTimestamp(date) |
Yes |
CQL 命令
Azure Cosmos DB 支援在 API for Cassandra 帳戶上使用下列資料庫命令。
| Command | 支援 |
|---|---|
ALLOW FILTERING |
Yes |
ALTER KEYSPACE |
N/A (PaaS 服務，內部複寫管理) |
ALTER MATERIALIZED VIEW |
是 |
ALTER ROLE |
無 |
ALTER TABLE |
.是 |
ALTER TYPE |
無 |
ALTER USER |
No |
BATCH |
是 (僅限未記錄的批次) |
COMPACT STORAGE |
N/A (PaaS 服務) |
CREATE AGGREGATE |
No |
CREATE CUSTOM INDEX (SASI) |
No |
CREATE INDEX |
是 (包括具名索引，但不支援完整 FROZEN 集合) |
CREATE FUNCTION |
No |
CREATE KEYSPACE (忽略複寫設定) |
Yes |
CREATE MATERIALIZED VIEW |
.是 |
CREATE TABLE |
.是 |
CREATE TRIGGER |
無 |
CREATE TYPE |
.是 |
CREATE ROLE |
No |
CREATE USER (在原生 Apache Cassandra 中已被取代) |
No |
DELETE |
.是 |
DISTINCT |
無 |
DROP AGGREGATE |
無 |
DROP FUNCTION |
無 |
DROP INDEX |
.是 |
DROP KEYSPACE |
.是 |
DROP MATERIALIZED VIEW |
.是 |
DROP ROLE |
無 |
DROP TABLE |
.是 |
DROP TRIGGER |
無 |
DROP TYPE |
Yes |
DROP USER (在原生 Apache Cassandra 中已被取代) |
No |
GRANT |
無 |
INSERT |
.是 |
LIST PERMISSIONS |
無 |
LIST ROLES |
No |
LIST USERS (在原生 Apache Cassandra 中已被取代) |
No |
REVOKE |
無 |
SELECT |
.是 |
UPDATE |
.是 |
TRUNCATE |
.是 |
USE |
Yes |
輕量型交易 (LWT)
| 元件 | 支援 |
|---|---|
DELETE IF EXISTS |
Yes |
DELETE conditions |
.是 |
INSERT IF NOT EXISTS |
.是 |
UPDATE IF EXISTS |
.是 |
UPDATE IF NOT EXISTS |
.是 |
UPDATE conditions |
是 |
注意
已啟用多重區域寫入的帳戶目前不支援輕量型交易。
CQL Shell 命令
Azure Cosmos DB 支援在 API for Cassandra 帳戶上使用下列資料庫命令。
| Command | 支援 |
|---|---|
CAPTURE |
Yes |
CLEAR |
是 |
CONSISTENCY * |
N/A |
COPY |
No |
DESCRIBE |
.是 |
cqlshExpand |
無 |
EXIT |
Yes |
LOGIN |
N/A (不支援 CQL 函式 USER，因此 LOGIN 是多餘的) |
PAGING |
Yes |
SERIAL CONSISTENCY * |
N/A |
SHOW |
是 |
SOURCE |
Yes |
TRACING |
N/A (由 Azure Cosmos DB 提供技術支援的 API for Cassandra - 使用診斷記錄進行疑難排解) |
注意
Azure Cosmos DB 中的一致性運作方式不同，請參閱這裡以取得詳細資訊。
JSON 支援
| Command | 支援 |
|---|---|
SELECT JSON |
Yes |
INSERT JSON |
.是 |
fromJson() |
無 |
toJson() |
No |
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 等公用程式來管理叢集。 支援 cqlsh 之類的工具，cqlsh 利用 Binary CQLv4 相容性。
- Azure 入口網站的資料總管、計量、記錄診斷、PowerShell 及 CLI 均為其他支援管理帳戶的機制。
CQL 殼層
您可以使用本機電腦上安裝的 CQLSH 連線至 Azure Cosmos DB 中的 API for Cassandra。 其中隨附 Apache Cassandra 3.11，且只需設定環境變數即可立即運作。 以下幾節包含相關指示，可引導您在 Windows 或 Linux 上使用 CQLSH 安裝、設定及連線至 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
- 執行使用驗證機制的 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 活動的角色。
Keyspace 和資料表選項
目前已忽略 "Create Keyspace" 命令中區域名稱、類別、replication_factor 和資料中心的選項。 系統會使用基礎 Azure Cosmos DB 的全域散發複寫方法來新增區域。 如果您需要資料跨區域存在，可以使用 PowerShell、CLI 或入口網站在帳戶層級加以啟用。若要深入了解，請參閱如何新增區域一文。 無法停用 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 應用程式來建立 API for Cassandra 帳戶、資料庫及資料表