Azure Cosmos DB for Apache Cassandra でサポートされる Apache Cassandra の機能

2025-06-10

適用対象: カサンドラ

Azure Cosmos DB は、Microsoft のグローバルに分散されたマルチモデルデータベースサービスです。 Azure Cosmos DB for Apache Cassandra とは、Cassandra Query Language (CQL) バイナリプロトコル v4 ワイヤプロトコル準拠のオープンソースの 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 に接続できるはずです。

Azure Managed Instance for Apache Cassandra（Apache Cassandra 用の Azure 管理インスタンス）

一部のお客様にとって、特にリフトアンドシフト移行では、動作と構成の違いにより、Cassandra の API への適応が困難になる場合があります。アプリケーションにとって重要な機能がこの記事の後半でサポートされていないと記載されている場合は、 Azure Managed Instance for Apache Cassandra の使用を検討してください。このサービスは、100% の互換性を持つ純粋なオープンソースの Apache Cassandra クラスターをホストおよび維持するためのファーストパーティの Azure サービスです。

Cassandra ドライバー

Azure Cosmos DB for Apache Cassandra では、次のバージョンの 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`	はい

データ型の宣言には Static がサポートされます。

CQL 関数

Azure Cosmos DB for Apache Cassandra では、次の CQL 関数がサポートされています。

コマンド	サポートされています
`Token` *	はい
`ttl` ***	はい
`writetime` ***	はい
`cast` **	はい

注意

* Cassandra 用 API は、プロジェクション/セレクターとしてトークンをサポートし、where 句の左辺でのみ token(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 は、行レベル (セルごとではなく) で適用されます。

集計関数:

コマンド	サポートされています
`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 シェルコマンド

Azure Cosmos DB は、Cassandra 用 API アカウントで以下のデータベースコマンドをサポートしています。

コマンド	サポートされています
`CAPTURE`	はい
`CLEAR`	はい
`CONSISTENCY` *	該当なし
`COPY`	いいえ
`DESCRIBE`	はい
`cqlshExpand`	いいえ
`EXIT`	はい
`LOGIN`	N/A (CQL 関数 `USER` はサポートされていないため、 `LOGIN` 冗長)
`PAGING`	はい
`SERIAL CONSISTENCY` *	該当なし
`SHOW`	はい
`SOURCE`	はい
`TRACING`	該当なし (Cassandra 用 API は Azure Cosmos DB によってサポートされている - トラブルシューティングに診断ログを使用)

注意

一貫性は、Azure Cosmos DB では動作が異なります。詳細については、 Apache Cassandra と Azure Cosmos DB for Apache Cassandra の整合性レベルに関するページを参照してください。

JSON のサポート

コマンド	サポートされています
`SELECT JSON`	はい
`INSERT JSON`	はい
`fromJson()`	いいえ
`toJson()`	いいえ

Cassandra 用 API の制限

Azure Cosmos DB for Apache Cassandra には、テーブルに格納されるデータのサイズに制限はありません。パーティションキーの制限を確実に適用しながら、数百テラバイトまたはペタバイトのデータを格納することができます。同様に、同等のすべてのエンティティまたは行には、列の数に制限はありません。エンティティの合計サイズが 2 MB を超えないようにする必要があります。パーティションキーあたりのデータは、他のすべての API と同様に 20 GB を超えることはできません。

ツール

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 に付属しており、環境変数を設定することですぐに機能します。以下のセクションでは、Windows または Linux で CQLSH を使用して、Azure Cosmos DB 上で Cassandra 用 API をインストール、構成、および接続する手順を説明します。

警告

Azure Cosmos DB for Apache Cassandra への接続は、DataStax Enterprise (DSE) または Cassandra 4.0 バージョンの CQLSH では機能しません。 Cassandra 用 API に接続するときは、v3.11 オープンソースの Apache Cassandra バージョンの CQLSH のみを使用してください。

ウィンドウズ：

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.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値を指定する場合は、0 にする必要があります。

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 portal から取得できる読み書きおよび読み取り専用のパスワードとキーがサポートされています。 Azure Cosmos DB では、CRUD アクティビティのロールはサポートされていません。

キースペースとテーブルのオプション

現在、 CREATE KEYSPACE コマンドのリージョン名、クラス、replication_factor、データセンターのオプションは無視されます。システムは、基になる Azure Cosmos DB のグローバル分散レプリケーション方法を使用して、リージョンを追加します。データのリージョン間プレゼンスが必要な場合は、PowerShell、CLI、または Azure portal を使用してアカウントレベルで有効にすることができます。詳細については、「データベースアカウントにリージョンを追加する」を参照してください。

Azure Cosmos DB ではすべての書き込みが持続的であることが保証されるため、Durable_writes を無効にすることはできません。すべてのリージョンで、Azure Cosmos DB は最大 4 つのレプリカで構成されるレプリカセット全体にデータをレプリケートします。このレプリカセットの構成は変更できません。

テーブルの作成時に、 gc_grace_secondsを除くすべてのオプションは無視されます。このオプションは 0 に設定する必要があります。キースペースとテーブルには、最小値が 400 RU/秒の cosmosdb_provisioned_throughput という名前の追加オプションがあります。 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 ;

セカンダリインデックス

Cassandra 用 API は、frozen コレクション型、decimal 型、variant 型を除くすべてのデータ型について、セカンダリインデックスをサポートします。

Cassandra 再試行接続ポリシーの使用

Azure Cosmos DB は、リソースによって管理されるシステムです。操作によって使用される要求ユニットに基づいて、1 秒間に一部の操作を実行できます。アプリケーションが特定の秒にその制限を超えると、要求はレート制限され、例外が発生します。 Azure Cosmos DB の Cassandra 用 API は、このような例外を Cassandra のネイティブプロトコルの過負荷エラーに変換します。

レート制限がある場合にアプリケーションが要求をインターセプトして再試行できるように、 Spark と Java 拡張機能が提供されます。また、Azure Cosmos DB で Cassandra 用 API に接続するときは、バージョン 3 およびバージョン 4 Datastax ドライバーの Java コードサンプルも参照してください。他の SDK を使用して Azure Cosmos DB の Cassandra 用 API にアクセスする場合は、これらの例外に対して再試行する再試行ポリシーを作成します。または、Cassandra 用 API のサーバー側の再試行を有効にします。

次のステップ

Java アプリケーションを使用して、Cassandra アカウント、データベース、テーブルの API 作成を始めましょう。