적용 대상:
카산드라
Azure Cosmos DB는 Microsoft의 세계적으로 유통된 멀티 모델 데이터베이스 서비스입니다. CQL(Cassandra Query Language) Binary Protocol v4 유선 프로토콜 규격 오픈 소스 Cassandra 클라이언트 드라이버를 통해 Azure Cosmos DB for Apach Cassandra와 통신할 수 있습니다.
Azure Cosmos DB for Apache Cassandra를 사용하면 Apache Cassandra API의 이점과 Azure Cosmos DB에서 제공하는 엔터프라이즈 기능을 활용할 수 있습니다. 엔터프라이즈 기능에는 전역 배포, 자동 스케일 아웃 분할, 가용성 및 대기 시간 보장, 미사용 암호화 및 백업이 포함됩니다.
Cassandra 프로토콜
Apache Cassandra용 Azure Cosmos DB는 CQL(Cassandra Query Language) v3.11 API와 호환됩니다. 버전 2.x와의 하위 호환성을 제공합니다. 지원되는 CQL 명령, 도구, 제한 사항 및 예외는 이 문서의 뒷부분에 나와 있습니다. 이 프로토콜을 인식하는 모든 클라이언트 드라이버는 Azure Cosmos DB for Apache Cassandra에 연결할 수 있습니다.
Apache Cassandra용 Azure Managed Instance
일부 고객의 경우 특히 리프트 앤 시프트 마이그레이션의 경우 동작 및 구성의 차이로 인해 Cassandra용 API에 적응하는 것이 어려울 수 있습니다. 애플리케이션에 중요한 기능이 이 문서의 뒷부분에서 지원되지 않는 것으로 나열된 경우 Apache Cassandra용 Azure Managed Instance를 사용하는 것이 좋습니다. 이 서비스는 100개의% 호환성이 있는 순수 오픈 소스 Apache Cassandra 클러스터를 호스팅하고 유지 관리하기 위한 자사 Azure 서비스입니다.
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 ** |
예 |
참고 항목
* 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 Shell 명령
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 제한
Apache Cassandra용 Azure Cosmos DB는 테이블에 저장된 데이터의 크기에 제한이 없습니다. 그러므로 파티션 키 제한 범위 내에서 수백 TB/PB에 달하는 데이터를 저장할 수 있습니다. 마찬가지로, 해당하는 모든 엔터티 또는 행에는 열 수에 제한이 없습니다. 엔터티의 총 크기는 2MB를 초과하면 안 됩니다. 파티션 키당 데이터는 다른 모든 API와 같이 20GB를 초과할 수 없습니다.
도구
Azure Cosmos DB for Apache Cassandra는 관리되는 서비스 플랫폼입니다. 플랫폼에는 클러스터를 관리하기 위해 가비지 수집기, JVM(Java Virtual Machine) 및 노드 도구와 같은 관리 오버헤드 또는 유틸리티가 필요하지 않습니다. 이진 CQLv4 호환성을 사용하는 cqlsh 도구가 지원됩니다.
- Azure Portal의 데이터 탐색기, 메트릭, 로그 진단, PowerShell 및 CLI는 계정을 관리하는 다른 지원되는 메커니즘입니다.
CQL Shell
로컬 컴퓨터에 설치된 CQLSH를 사용하여 Azure Cosmos DB for Apache Cassandra에 연결할 수 있습니다. Apache Cassandra 3.11과 함께 제공되며 환경 변수를 설정하여 즉시 사용할 수 있습니다. 다음 섹션에는 CQLSH를 사용하여 Windows 또는 Linux에서 Azure Cosmos DB의 Cassandra용 API를 설치, 구성 및 연결하는 지침이 포함되어 있습니다.
경고
Apache Cassandra용 Azure Cosmos DB에 대한 연결은 DSE(DataStax Enterprise) 또는 Cassandra 4.0 버전의 CQLSH에서 작동하지 않습니다. Cassandra용 API에 연결할 때 v3.11 오픈 소스 Apache Cassandra 버전의 CQLSH만 사용해야 합니다.
Windows:
PIP를 설치합니다.
- PIP를 설치하기 전에 get-pip.py 파일을 다운로드합니다.
- 명령 프롬프트 창이 아직 열려 있지 않은 경우 시작합니다. 이렇게 하려면 Windows 검색 창을 열고 cmd를 입력하고 아이콘을 선택합니다.
- 그런 다음, 다음 명령을 실행하여 get-pip.py 파일을 다운로드합니다.
curl https://bootstrap.pypa.io/get-pip.py -o get-pip.pyWindows에 PIP 설치:
python get-pip.pyPIP 설치를 확인합니다. 3단계에서 메시지를 찾아 PIP가 설치된 폴더를 확인합니다. 그런 다음, 해당 폴더로 이동하여 명령 pip 도움말을 실행합니다.
PIP를 사용하여 CQLSH를 설치합니다.
pip3 install cqlsh==5.0.3Python 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 RBAC(Azure 역할 기반 액세스 제어)와 Azure Portal을 통해 가져올 수 있는 읽기-쓰기 및 읽기 전용 암호/키를 지원합니다. Azure Cosmos DB는 CRUD 활동에 대한 역할을 지원하지 않습니다.
키스페이스 및 테이블 옵션
명령의 지역 이름, 클래스, replication_factor 및 데이터 센터에 CREATE KEYSPACE 대한 옵션은 현재 무시됩니다. 시스템은 기본 Azure Cosmos DB의 글로벌 배포 복제 방법을 사용하여 지역을 추가합니다. 지역 간 데이터가 있어야 하는 경우 PowerShell, CLI 또는 Azure Portal을 사용하여 계정 수준에서 사용하도록 설정할 수 있습니다. 자세한 내용은 데이터베이스 계정에 지역 추가를 참조하세요.
Azure Cosmos DB는 모든 쓰기가 내구성이 있는지 확인하기 때문에 Durable_writes를 비활성화할 수 없습니다. 모든 지역에서 Azure Cosmos DB는 4개의 복제본으로 구성된 복제본 세트 전체에 데이터를 복제하고 이 복제본 세트 구성은 수정할 수 없습니다.
0으로 설정해야 하는 테이블을 제외하고 gc_grace_seconds테이블을 만들 때는 모든 옵션이 무시됩니다.
키스페이스와 테이블에는 최소값이 400RU/s인 추가 옵션이 있습니다 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는 고정 컬렉션 형식, 10진수 및 변형 형식을 제외한 모든 데이터 형식에 대한 보조 인덱스를 지원합니다.
Cassandra 다시 시도 연결 정책 사용
Azure Cosmos DB는 리소스 관리 시스템입니다. 작업이 소모하는 요청 단위에 따라 주어진 초 내에서 몇 가지 작업을 수행할 수 있습니다. 애플리케이션이 지정된 초당 해당 제한을 초과하면 요청은 속도 제한을 받고 예외가 발생합니다. Azure Cosmos DB의 API for Cassandra는 Cassandra 네이티브 프로토콜에서 이러한 예외를 오버로드된 오류로 변환합니다.
속도 제한이 있는 경우 애플리케이션이 요청을 가로채고 다시 시도할 수 있도록 Spark 및 Java 확장이 제공됩니다. Azure Cosmos DB의 Cassandra용 API에 연결하는 경우 버전 3 및 버전 4 Datastax 드라이버에 대한 Java 코드 샘플도 참조하세요. 다른 SDK를 사용하여 Azure Cosmos DB의 Cassandra용 API에 액세스하는 경우 이러한 예외 발생 시 다시 시도하는 다시 시도 정책을 만듭니다. 또는 Cassandra용 API에 대한 서버 쪽 다시 시도를 사용하도록 설정합니다.
다음 단계
- Java 애플리케이션을 사용하여 Cassandra 계정, 데이터베이스 및 테이블에 대한 API 만들기 시작