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 に接続できるはずです。

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) No
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:

  1. Python 3 をインストールする
  2. 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 
    
  3. Windows に PIP をインストールする
python get-pip.py
  1. PIP のインストールを確認します (手順 3 のメッセージを探して、PIP がインストールされたフォルダーを確認し、そのフォルダーに移動して pip help コマンドを実行します)。
  2. PIP を使用して CQLSH をインストールする
pip3 install cqlsh==5.0.3
  1. Python 2 をインストールする
  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 のサーバー側の再試行を有効にします。

次のステップ