Azure Cosmos DB for Apache Cassandra でサポートされる Apache Cassandra の機能
適用対象: 
Cassandra
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 Query Language (CQL) v3.11 API と互換性があります (バージョン2.x との下位互換性あり)。 サポートされている CQL コマンド、ツール、制限事項、および例外を、以下に示します。 これらのプロトコルを認識するすべてのクライアント ドライバーは Azure Cosmos DB for Apache Cassandra に接続できるはずです。
Azure Managed Instance for Apache Cassandra
一部の顧客の場合、特にリフトアンドシフト移行では、動作や構成の違いにより、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 データ型がサポートされています。
| Type | サポートされています |
|---|---|
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 |
該当なし (CQL 関数 USER はサポートされていないため、LOGIN は冗長) |
PAGING |
はい |
SERIAL CONSISTENCY * |
該当なし |
SHOW |
はい |
SOURCE |
はい |
TRACING |
該当なし (Cassandra 用 API は Azure Cosmos DB によってサポートされている - トラブルシューティングに診断ログを使用) |
Note
Azure Cosmos DB では、整合性の機能が異なります。詳細については、こちらをご覧ください。
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)、nodetool などのユーティリティが不要です。 ツールとしては、バイナリ 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 への接続は、CQLSH の DataStax Enterprise (DSE) または Cassandra 4.0 バージョンでは動作しません。 Cassandra 用 API に接続する場合は、v3.11 オープンソースの Apache Cassandra バージョンの CQLSH のみを使用してください。
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 を指定する場合は値を 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 Cosmos DB ではすべての書き込みが持続的であることが保証されるため、Durable_writes を無効にすることはできません。 すべてのリージョンで、Azure Cosmos DB は最大 4 つのレプリカで構成されるレプリカ セット全体にデータをレプリケートします。このレプリカ セットの構成は変更できません。
ゼロに設定する必要がある gc_grace_seconds を除き、テーブルの作成時にはすべてのオプションが無視されます。 キースペースとテーブルには、最小値が 400 RU/秒の、"cosmosdb_provisioned_throughput" という名前の追加オプションがあります。 キースペースのスループットによって、複数のテーブル間でスループットを共有することが可能になります。これは、プロビジョニングされたスループットがすべてのテーブルで利用されていないシナリオに役立ちます。 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 アカウント、データベースおよびテーブルを作成してみる