Apache Cassandra-funktioner som stöds av Azure Cosmos DB för Apache Cassandra

2025-06-06

GÄLLER FÖR: Kassandra

Azure Cosmos DB är Microsofts globalt distribuerade flermodellsdatabastjänst. Du kan kommunicera med Azure Cosmos DB för Apache Cassandra via Cassandra Query Language (CQL) Binary Protocol v4 wire protocol compliant open-source Cassandra client drivers.You can communicate with the Azure Cosmos DB for Apache Cassandra through the Cassandra Query Language (CQL) Binary Protocol v4 wire protocol compliant open-source Cassandra client drivers.

Genom att använda Azure Cosmos DB för Apache Cassandra kan du dra nytta av fördelarna med Apache Cassandra-API:er och de företagsfunktioner som Azure Cosmos DB tillhandahåller. Företagsfunktionerna omfattar global distribution, automatisk utskalning av partitionering, garantier för tillgänglighet och svarstid, kryptering i vila och säkerhetskopior.

Cassandra-protokollet

Azure Cosmos DB för Apache Cassandra är kompatibel med Cassandra Query Language (CQL) v3.11 API. Den är bakåtkompatibel med version 2.x. De CQL-kommandon, verktyg, begränsningar och undantag som stöds visas senare i den här artikeln. Alla klientdrivrutiner som förstår dessa protokoll bör kunna ansluta till Azure Cosmos DB för Apache Cassandra.

Azure Managed Instance för Apache Cassandra

För vissa kunder kan anpassning till API för Cassandra vara en utmaning på grund av skillnader i beteende och konfiguration, särskilt för lift-and-shift-migreringar. Om en funktion som är kritisk för ditt program visas som inte stöds senare i den här artikeln bör du överväga att använda Azure Managed Instance för Apache Cassandra. Den här tjänsten är en Azure-tjänst från första part för att vara värd för och underhålla rena Apache Cassandra-kluster med öppen källkod med 100% kompatibilitet.

Cassandra-drivrutinen

Azure Cosmos DB för Apache Cassandra stöder följande versioner av Cassandra-drivrutiner:

CQL-datatyper

Azure Cosmos DB för Apache Cassandra stöder följande CQL-datatyper:

Typ	Stöds
`ascii`	Ja
`bigint`	Ja
`blob`	Ja
`boolean`	Ja
`counter`	Ja
`date`	Ja
`decimal`	Ja
`double`	Ja
`float`	Ja
`frozen`	Ja
`inet`	Ja
`int`	Ja
`list`	Ja
`set`	Ja
`smallint`	Ja
`text`	Ja
`time`	Ja
`timestamp`	Ja
`timeuuid`	Ja
`tinyint`	Ja
`tuple`	Ja
`uuid`	Ja
`varchar`	Ja
`varint`	Ja
`tuples`	Ja
`udts`	Ja
`map`	Ja

Statisk stöds för datatypsdeklaration.

CQL-funktioner

Azure Cosmos DB för Apache Cassandra stöder följande CQL-funktioner:

Kommando	Stöds
`Token` *	Ja
`ttl` ***	Ja
`writetime` ***	Ja
`cast` **	Ja

Kommentar

* API för Cassandra stöder token som projektion/väljare och tillåter endast token (pk) till vänster i en where-sats. Stöds till exempel WHERE token(pk) > 1024 , men WHERE token(pk) > token(100) stöds inte . ** Funktionen cast() kan inte kapslas i API:et för Cassandra. Stöds till exempel SELECT cast(count as double) FROM myTable , men SELECT avg(cast(count as double)) FROM myTable stöds inte . Anpassade tidsstämplar och TTL som anges med USING alternativet tillämpas på radnivå (och inte per cell).

Mängdfunktioner:

Kommando	Stöds
`avg`	Ja
`count`	Ja
`min`	Ja
`max`	Ja
`sum`	Ja

Kommentar

Aggregeringsfunktioner fungerar på vanliga kolumner, men aggregeringar på klustringskolumner stöds inte .

Blobkonverteringsfunktioner:

Kommando	Stöds
`typeAsBlob(value)`	Ja
`blobAsType(value)`	Ja

UUID- och timeuuid-funktioner:

Kommando	Stöds
`dateOf()`	Ja
`now()`	Ja
`minTimeuuid()`	Ja
`unixTimestampOf()`	Ja
`toDate(timeuuid)`	Ja
`toTimestamp(timeuuid)`	Ja
`toUnixTimestamp(timeuuid)`	Ja
`toDate(timestamp)`	Ja
`toUnixTimestamp(timestamp)`	Ja
`toTimestamp(date)`	Ja
`toUnixTimestamp(date)`	Ja

CQL-kommandon

Azure Cosmos DB stöder följande databaskommandon på API för Cassandra-konton.

Kommando	Stöds
`ALLOW FILTERING`	Ja
`ALTER KEYSPACE`	N/A (PaaS-tjänst, replikering som hanteras internt)
`ALTER MATERIALIZED VIEW`	Ja
`ALTER ROLE`	Nej
`ALTER TABLE`	Ja
`ALTER TYPE`	Nej
`ALTER USER`	Nej
`BATCH`	Ja (endast ologgad batch)
`COMPACT STORAGE`	N/A (PaaS-tjänst)
`CREATE AGGREGATE`	Nej
`CREATE CUSTOM INDEX (SASI)`	Nej
`CREATE INDEX`	Ja (inklusive namngivna index men fullständig FROZEN-samling stöds inte)
`CREATE FUNCTION`	Nej
`CREATE KEYSPACE` (replikeringsinställningarna ignoreras)	Ja
`CREATE MATERIALIZED VIEW`	Ja
`CREATE TABLE`	Ja
`CREATE TRIGGER`	Nej
`CREATE TYPE`	Ja
`CREATE ROLE`	Nej
`CREATE USER` (Inaktuell i inbyggda Apache Cassandra)	Nej
`DELETE`	Ja
`DISTINCT`	Nej
`DROP AGGREGATE`	Nej
`DROP FUNCTION`	Nej
`DROP INDEX`	Ja
`DROP KEYSPACE`	Ja
`DROP MATERIALIZED VIEW`	Ja
`DROP ROLE`	Nej
`DROP TABLE`	Ja
`DROP TRIGGER`	Nej
`DROP TYPE`	Ja
`DROP USER` (Inaktuell i inbyggda Apache Cassandra)	Nej
`GRANT`	Nej
`INSERT`	Ja
`LIST PERMISSIONS`	Nej
`LIST ROLES`	Nej
`LIST USERS` (Inaktuell i inbyggda Apache Cassandra)	Nej
`REVOKE`	Nej
`SELECT`	Ja
`UPDATE`	Ja
`TRUNCATE`	Ja
`USE`	Ja

Lightweight Transactions (LWT)

Komponent	Stöds
`DELETE IF EXISTS`	Ja
`DELETE conditions`	Ja
`INSERT IF NOT EXISTS`	Ja
`UPDATE IF EXISTS`	Ja
`UPDATE IF NOT EXISTS`	Ja
`UPDATE conditions`	Ja

Kommentar

Förenklade transaktioner stöds för närvarande inte för konton som har flera regionskrivningar aktiverade.

CQL Shell-kommandon

Azure Cosmos DB stöder följande databaskommandon på API för Cassandra-konton.

Kommando	Stöds
`CAPTURE`	Ja
`CLEAR`	Ja
`CONSISTENCY` *	Ej tillämpligt
`COPY`	Nej
`DESCRIBE`	Ja
`cqlshExpand`	Nej
`EXIT`	Ja
`LOGIN`	N/A (CQL-funktionen `USER` stöds inte, därför `LOGIN` är den redundant)
`PAGING`	Ja
`SERIAL CONSISTENCY` *	Ej tillämpligt
`SHOW`	Ja
`SOURCE`	Ja
`TRACING`	N/A (API för Cassandra backas upp av Azure Cosmos DB – använd diagnostikloggning för felsökning)

Kommentar

Konsistens fungerar annorlunda i Azure Cosmos DB. Se Konsekvensnivåer för Apache Cassandra och Azure Cosmos DB för Apache Cassandra för mer information.

JSON-support

Kommando	Stöds
`SELECT JSON`	Ja
`INSERT JSON`	Ja
`fromJson()`	Nej
`toJson()`	Nej

API för Cassandra-gränser

Azure Cosmos DB för Apache Cassandra har inga gränser för storleken på data som lagras i en tabell. Hundratals terabyte eller petabyte data kan lagras samtidigt om partitionsnyckelgränserna respekteras. På samma sätt har varje entitet eller radekvivalenter inga gränser för antalet kolumner. Den totala storleken på entiteten får inte överstiga 2 MB. Data per partitionsnyckel får inte överstiga 20 GB som i alla andra API:er.

Verktyg

Azure Cosmos DB för Apache Cassandra är en hanterad tjänstplattform. Plattformen kräver inte några hanteringskostnader eller verktyg som skräpinsamlare, Java Virtual Machine (JVM) och nodverktyg för att hantera klustret. Verktyg som cqlsh använder binär CQLv4-kompatibilitet stöds.

Azure-portalens datautforskare, mått, loggdiagnostik, PowerShell och CLI är andra mekanismer som stöds för att hantera kontot.

CQL-gränssnitt

Du kan ansluta till API:et för Cassandra i Azure Cosmos DB med hjälp av CQLSH som är installerat på en lokal dator. Den levereras med Apache Cassandra 3.11 och fungerar inte genom att ange miljövariablerna. Följande avsnitt innehåller instruktioner för att installera, konfigurera och ansluta till API för Cassandra i Azure Cosmos DB, i Windows eller Linux med CQLSH.

Varning

Anslutningar till Azure Cosmos DB för Apache Cassandra fungerar inte med DataStax Enterprise (DSE) eller Cassandra 4.0-versioner av CQLSH. Se till att du endast använder v3.11 av Apache Cassandra-versioner med öppen källkod av CQLSH när du ansluter till Cassandra-API:et.

Windows:

Installera Python 3.
Installera PIP.
1. Innan du installerar PIP laddar du ned get-pip.py-filen .
2. Starta ett kommandotolksfönster om det inte redan är öppet. Om du vill göra det öppnar du Sökfältet i Windows, skriver cmd och väljer ikonen.
3. Kör sedan följande kommando för att ladda ned filen get-pip.py :
```
curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py 
```
Installera PIP på Windows:
```
python get-pip.py
```
Kontrollera PIP-installationen. Leta efter ett meddelande från steg 3 för att bekräfta vilken mapp PIP installerades i. Navigera sedan till mappen och kör hjälpen med kommandot pip.
Installera CQLSH med PIP:
```
pip3 install cqlsh==5.0.3
```
Installera Python 2.
Kör CQLSH med hjälp av autentiseringsmekanismen.

Kommentar

Du måste ange miljövariablerna så att de pekar på python 2-mappen.

Installera på 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

Anslut med 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

Anslut med 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

Alla CRUD-åtgärder som körs via ett CQL v4-kompatibelt SDK returnerar mer information om fel och begärandenheter som förbrukats. För att säkerställa den mest effektiva användningen av det etablerade dataflödet bör kommandona DELETE och UPDATE hanteras med hänsyn till resursstyrning.

Kommentar

Värdet gc_grace_seconds måste vara noll om det anges.

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}"); 
        }

Mappning av konsekvens

Azure Cosmos DB för Apache Cassandra ger val av konsekvens för läsåtgärder. Mer information finns i Kartläggning av konsekvensnivåer.

Behörighets- och rollhantering

Azure Cosmos DB stöder rollbaserad åtkomstkontroll i Azure (Azure RBAC) för etablering, roterande nycklar, visning av mått och skrivskyddade och skrivskyddade lösenord/nycklar som kan hämtas via Azure Portal. Azure Cosmos DB stöder inte roller för CRUD-aktiviteter.

Alternativ för nyckelrymd och tabell

Alternativen för regionnamn, klass, replication_factor och datacenter i CREATE KEYSPACE kommandot ignoreras för närvarande. Systemet använder den underliggande Azure Cosmos DB:s globala distributionsreplikeringsmetod för att lägga till regionerna. Om du behöver förekomsten av data mellan regioner kan du aktivera dem på kontonivå med PowerShell, CLI eller Azure-portalen. Mer information finns i Lägga till regioner i ditt databaskonto.

Durable_writes kan inte inaktiveras eftersom Azure Cosmos DB säkerställer att varje skrivning är beständig. I varje region replikerar Azure Cosmos DB data i replikuppsättningen som består av fyra repliker och den här replikuppsättningskonfigurationen kan inte ändras.

Alla alternativ ignoreras när tabellen skapas, förutom gc_grace_seconds, som ska anges till noll. Nyckelutrymmet och tabellen har ett extra alternativ med namnet cosmosdb_provisioned_throughput med ett minsta värde på 400 RU/s. Nyckelrymdens dataflöde tillåter delning av dataflöde mellan flera tabeller. Det är användbart för scenarier när alla tabeller inte använder det etablerade dataflödet. Med ALTER TABLE kommandot kan du ändra det etablerade dataflödet i regionerna.

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 ;

Sekundärt index

API för Cassandra stöder sekundära index för alla datatyper förutom typer av frysta samlingar, decimaler och varianttyper.

Användning av principen för nytt anslutningsförsök i Cassandra

Azure Cosmos DB är ett resursstyrt system. Du kan utföra vissa åtgärder vid en viss tidpunkt baserat på de begärda enheter som förbrukas av dessa. Om ett program överskrider den gränsen under en viss sekund är begäranden hastighetsbegränsade och undantag utlöses. API:et för Cassandra i Azure Cosmos DB översätter dessa undantag till överlagrade fel i det interna Cassandra-protokollet.

För att säkerställa att din applikation kan avlyssna och försöka igen om det finns begränsningar i antalet förfrågningar tillhandahålls spark- och Java-tilläggen. Se även Java-kodexempel för datataxdrivrutiner av version 3 och version 4 när du ansluter till API för Cassandra i Azure Cosmos DB. Om du använder andra SDK:er för att komma åt API för Cassandra i Azure Cosmos DB skapar du en återförsöksprincip för att försöka igen med dessa undantag. Du kan också aktivera återförsök på serversidan för API för Cassandra.

Nästa steg

Kom igång med att skapa ett API för Cassandra-konto, databas och en tabell med hjälp av ett Java-program

Dela via

Apache Cassandra-funktioner som stöds av Azure Cosmos DB för Apache Cassandra

Cassandra-protokollet

Azure Managed Instance för Apache Cassandra

Cassandra-drivrutinen

CQL-datatyper

CQL-funktioner

CQL-kommandon

Lightweight Transactions (LWT)

CQL Shell-kommandon

JSON-support

API för Cassandra-gränser

Verktyg

CQL-gränssnitt

Mappning av konsekvens

Behörighets- och rollhantering

Alternativ för nyckelrymd och tabell

Sekundärt index

Användning av principen för nytt anslutningsförsök i Cassandra

Nästa steg

Feedback

Ytterligare resurser