funzionalità di Apache Cassandra supportate da Azure Cosmos DB for Apache Cassandra

2025-06-06

SI APPLICA A: Cassandra

Azure Cosmos DB è il servizio di database multi-modello distribuito globalmente di Microsoft. È possibile comunicare con Azure Cosmos DB for Apache Cassandra tramite i driver client Cassandra open source compatibili con il protocollo di trasmissione Cassandra Query Language (CQL) Binary Protocol v4.

Usando Azure Cosmos DB for Apache Cassandra, è possibile sfruttare i vantaggi delle API di Apache Cassandra e le funzionalità aziendali offerte da Azure Cosmos DB. Le funzionalità aziendali includono la distribuzione globale, il partizionamento con scalabilità orizzontale automatica, le garanzie di disponibilità e latenza, la crittografia dei dati inattivi e i backup.

Protocollo Cassandra

Azure Cosmos DB per Apache Cassandra è compatibile con l'API Cassandra Query Language (CQL) v3.11. È retrocompatibile con la versione 2.x. I comandi, gli strumenti, le limitazioni e le eccezioni supportati sono elencati più avanti in questo articolo. I driver client che riconoscono questi protocolli dovrebbero essere in grado di collegarsi ad Azure Cosmos DB for Apache Cassandra.

Istanza gestita di Azure per Apache Cassandra

Per alcuni clienti, l'adattamento all'API per Cassandra può essere una sfida dovuta alle differenze di comportamento e configurazione, soprattutto per le migrazioni lift-and-shift. Se una funzionalità fondamentale per l'applicazione è elencata come non supportata più avanti in questo articolo, è consigliabile usare Istanza gestita di Azure per Apache Cassandra. Questo servizio è un servizio di Azure di prima parte per l'hosting e la gestione di cluster Apache Cassandra open source puri con 100% compatibilità.

Driver Cassandra

Azure Cosmos DB per Apache Cassandra supporta le versioni seguenti dei driver Cassandra:

Tipi di dati CQL

Azure Cosmos DB for Apache Cassandra supporta i tipi di dati CQL seguenti:

TIPO	Supportata
`ascii`	Sì
`bigint`	Sì
`blob`	Sì
`boolean`	Sì
`counter`	Sì
`date`	Sì
`decimal`	Sì
`double`	Sì
`float`	Sì
`frozen`	Sì
`inet`	Sì
`int`	Sì
`list`	Sì
`set`	Sì
`smallint`	Sì
`text`	Sì
`time`	Sì
`timestamp`	Sì
`timeuuid`	Sì
`tinyint`	Sì
`tuple`	Sì
`uuid`	Sì
`varchar`	Sì
`varint`	Sì
`tuples`	Sì
`udts`	Sì
`map`	Sì

Per la dichiarazione del tipo di dati è supportato il tipo statico.

Funzioni CQL

Azure Cosmos DB for Apache Cassandra supporta le funzioni CQL seguenti:

Comando	Supportata
`Token` *	Sì
`ttl` ***	Sì
`writetime` ***	Sì
`cast` **	Sì

Nota

* L'API per Cassandra supporta il token come proiezione/selettore e consente solo token(pk) sul lato sinistro di una clausola WHERE. Ad esempio, WHERE token(pk) > 1024 è supportato, ma WHERE token(pk) > token(100)non lo è. ** La cast() funzione non è annidabile nell'API per Cassandra. Ad esempio, SELECT cast(count as double) FROM myTable è supportato, ma SELECT avg(cast(count as double)) FROM myTablenon lo è. I timestamp personalizzati e il TTL specificati con l'opzione USING vengono applicati a livello di riga (e non per cella).

Funzioni di aggregazione:

Comando	Supportata
`avg`	Sì
`count`	Sì
`min`	Sì
`max`	Sì
`sum`	Sì

Nota

Le funzioni di aggregazione possono essere usate su colonne normali, ma le aggregazioni su colonne di clustering non sono supportate.

Funzioni di conversione BLOB:

Comando	Supportata
`typeAsBlob(value)`	Sì
`blobAsType(value)`	Sì

Funzioni UUID e timeuuid:

Comando	Supportata
`dateOf()`	Sì
`now()`	Sì
`minTimeuuid()`	Sì
`unixTimestampOf()`	Sì
`toDate(timeuuid)`	Sì
`toTimestamp(timeuuid)`	Sì
`toUnixTimestamp(timeuuid)`	Sì
`toDate(timestamp)`	Sì
`toUnixTimestamp(timestamp)`	Sì
`toTimestamp(date)`	Sì
`toUnixTimestamp(date)`	Sì

Comandi CQL

Azure Cosmos DB supporta i comandi di database seguenti negli account API per Cassandra.

Comando	Supportata
`ALLOW FILTERING`	Sì
`ALTER KEYSPACE`	N/d (servizio PaaS, replica gestita internamente)
`ALTER MATERIALIZED VIEW`	Sì
`ALTER ROLE`	NO
`ALTER TABLE`	Sì
`ALTER TYPE`	NO
`ALTER USER`	NO
`BATCH`	Sì (solo batch non registrato)
`COMPACT STORAGE`	N/d (servizio PaaS)
`CREATE AGGREGATE`	NO
`CREATE CUSTOM INDEX (SASI)`	NO
`CREATE INDEX`	Sì (inclusi gli indici denominati ma la raccolta FROZEN completa non è supportata)
`CREATE FUNCTION`	NO
`CREATE KEYSPACE` (impostazioni di replica ignorate)	Sì
`CREATE MATERIALIZED VIEW`	Sì
`CREATE TABLE`	Sì
`CREATE TRIGGER`	NO
`CREATE TYPE`	Sì
`CREATE ROLE`	NO
`CREATE USER` (deprecato in Apache Cassandra nativo)	NO
`DELETE`	Sì
`DISTINCT`	NO
`DROP AGGREGATE`	NO
`DROP FUNCTION`	NO
`DROP INDEX`	Sì
`DROP KEYSPACE`	Sì
`DROP MATERIALIZED VIEW`	Sì
`DROP ROLE`	NO
`DROP TABLE`	Sì
`DROP TRIGGER`	NO
`DROP TYPE`	Sì
`DROP USER` (deprecato in Apache Cassandra nativo)	NO
`GRANT`	NO
`INSERT`	Sì
`LIST PERMISSIONS`	NO
`LIST ROLES`	NO
`LIST USERS` (deprecato in Apache Cassandra nativo)	NO
`REVOKE`	NO
`SELECT`	Sì
`UPDATE`	Sì
`TRUNCATE`	Sì
`USE`	Sì

Transazioni leggere (LWT)

Componente	Supportata
`DELETE IF EXISTS`	Sì
`DELETE conditions`	Sì
`INSERT IF NOT EXISTS`	Sì
`UPDATE IF EXISTS`	Sì
`UPDATE IF NOT EXISTS`	Sì
`UPDATE conditions`	Sì

Nota

Le transazioni leggere non sono attualmente supportate per gli account con scritture multi-regione abilitate.

Comandi della shell CQL

Azure Cosmos DB supporta i comandi di database seguenti negli account API per Cassandra.

Comando	Supportata
`CAPTURE`	Sì
`CLEAR`	Sì
`CONSISTENCY` *	N/D
`COPY`	NO
`DESCRIBE`	Sì
`cqlshExpand`	NO
`EXIT`	Sì
`LOGIN`	N/D (la funzione `USER` CQL non è supportata, quindi `LOGIN` è ridondante)
`PAGING`	Sì
`SERIAL CONSISTENCY` *	N/D
`SHOW`	Sì
`SOURCE`	Sì
`TRACING`	N/D (l'API per Cassandra è supportata da Azure Cosmos DB: usare la registrazione diagnostica per la risoluzione dei problemi)

Nota

La coerenza funziona in modo diverso in Azure Cosmos DB. Per altre informazioni, vedere Apache Cassandra e Azure Cosmos DB per i livelli di coerenza di Apache Cassandra.

Supporto JSON

Comando	Supportata
`SELECT JSON`	Sì
`INSERT JSON`	Sì
`fromJson()`	NO
`toJson()`	NO

Limiti dell'API per Cassandra

Azure Cosmos DB per Apache Cassandra non presenta limiti alle dimensioni dei dati archiviati in una tabella. Possono essere archiviati centinaia di terabyte o petabyte di dati, a patto che siano rispettati i limiti della chiave di partizione. Analogamente, ogni entità o un equivalente di riga non ha limiti al numero di colonne. Le dimensioni totali dell'entità non devono superare 2 MB. I dati per chiave di partizione non possono superare i 20 GB come in tutte le altre API.

Strumenti

Azure Cosmos DB for Apache Cassandra è una piattaforma di servizi gestiti. La piattaforma non richiede alcun sovraccarico di gestione o utilità, ad esempio Garbage Collector, Java Virtual Machine (JVM) e lo strumento node per gestire il cluster. Sono supportati strumenti come cqlsh quelli che usano la compatibilità binaria CQLv4.

Esplora dati, metriche, diagnostica dei log, PowerShell e interfaccia della riga di comando del portale di Azure sono altri meccanismi supportati per gestire l'account.

Shell CQL

Per connettersi all'API per Cassandra in Azure Cosmos DB, è possibile usare CQLSH installato in un computer locale. Questa utilità è inclusa in Apache Cassandra 3.11 e per usarla è sufficiente impostare le variabili di ambiente. Le sezioni seguenti includono le istruzioni per installare, configurare e connettersi all'API per Cassandra in Azure Cosmos DB, in Windows o Linux, tramite CQLSH.

Avviso

Le connessioni ad Azure Cosmos DB per Apache Cassandra non funzionano con DataStax Enterprise (DSE) o con le versioni cassandra 4.0 di CQLSH. Assicurarsi di usare solo le versioni v3.11 open source di Apache Cassandra di CQLSH quando ci si connette all'API di Cassandra.

Finestre:

Installare Python 3.
Installare PIP.
1. Prima di installare PIP, scaricare il file get-pip.py .
2. Avvia una finestra del prompt dei comandi, se non è già aperta. A tale scopo, aprire la barra di ricerca di Windows, digitare cmd e selezionare l'icona.
3. Eseguire quindi il comando seguente per scaricare il file get-pip.py :
```
curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py 
```
Installare PIP in Windows:
```
python get-pip.py
```
Verificare l'installazione del pip. Cercare un messaggio del passaggio 3 per verificare la cartella in cui è stato installato PIP. Passare quindi a tale cartella ed eseguire il comando pip help.
Installare CQLSH usando PIP:
```
pip3 install cqlsh==5.0.3
```
Installare Python 2.
Eseguire il CQLSH usando il meccanismo di autenticazione.

Nota

È necessario impostare le variabili di ambiente in modo che puntino alla cartella Python 2.

Installare in 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

Connettersi con 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

Connettersi con 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

Tutte le operazioni CRUD eseguite tramite un SDK compatibile con CQL v4 restituiscono informazioni aggiuntive sugli errori e sulle unità richiesta utilizzate. Per garantire l'uso più efficiente del throughput provvisto, i comandi DELETE e UPDATE devono essere gestiti tenendo conto della governance delle risorse.

Nota

Il gc_grace_seconds valore deve essere zero, se specificato.

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

Mapping coerente

Azure Cosmos DB for Apache Cassandra consente di scegliere la coerenza per le operazioni di lettura. Per altre informazioni, vedere Mapping dei livelli di coerenza.

Gestione di ruoli e privilegi

Azure Cosmos DB supporta il controllo degli accessi in base al ruolo di Azure per il provisioning, la rotazione delle chiavi, la visualizzazione delle metriche e le chiavi/password di lettura/scrittura e sola lettura ottenibili tramite il portale di Azure. Azure Cosmos DB non supporta i ruoli per le attività CRUD.

Opzioni di Keyspace e tabella

Le opzioni per nome dell'area, classe, replication_factor e data center nel CREATE KEYSPACE comando vengono attualmente ignorate. Il sistema usa il metodo di replica della distribuzione globale sottostante di Azure Cosmos DB per aggiungere le aree. Se è necessaria la presenza di dati tra aree, è possibile abilitarla a livello di account con PowerShell, l'interfaccia della riga di comando o il portale di Azure. Per altre informazioni, vedere Aggiungere aree all'account del database.

L'opzione durable_writes non può essere disabilitata perché Azure Cosmos DB assicura che ogni scrittura sia durevole. In ogni area Azure Cosmos DB replica i dati nel set di repliche composto da quattro repliche. La configurazione di questo set di repliche non può essere modificata.

Tutte le opzioni vengono ignorate durante la creazione della tabella, ad eccezione gc_grace_secondsdi , che deve essere impostata su zero. Keyspace e tabella hanno un'opzione aggiuntiva denominata cosmosdb_provisioned_throughput con un valore minimo di 400 UR/sec. La throughput del keyspace consente la condivisione del throughput tra più tabelle. È utile per scenari in cui non tutte le tabelle utilizzano il throughput con provisioning. Il ALTER TABLE comando consente di modificare la velocità effettiva con provisioning tra le aree.

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 ;

Indice secondario

L'API per Cassandra supporta indici secondari in tutti i tipi di dati, tranne i tipi di raccolta Frozen, i tipi Decimal e Variant.

Utilizzo dei criteri di ripetizione delle connessioni di Cassandra

Azure Cosmos DB è un sistema governato da risorse. È possibile eseguire alcune operazioni in un determinato secondo in base alle unità richiesta utilizzate dalle operazioni. Se un'applicazione supera tale limite in un determinato secondo, le richieste sono limitate alla frequenza e vengono generate eccezioni. L'API per Cassandra in Azure Cosmos DB converte queste eccezioni in errori di overload per il protocollo nativo di Cassandra.

Per assicurarsi che l'applicazione possa intercettare e ripetere le richieste in caso di limitazione della frequenza, vengono fornite le estensioni Spark e Java . Quando ci si connette all'API per Cassandra in Azure Cosmos DB, vedere anche gli esempi di codice Java per i driver Datastax versione 3 e versione 4. Sei si usano altri SDK per accedere all'API per Cassandra in Azure Cosmos DB, creare un criterio per ripetere il tentativo in caso di tali eccezioni. In alternativa, abilitare la ripetizione dei tentativi lato server per l'API per Cassandra.

Passaggi successivi

Introduzione alla creazione di un'API per l'account Cassandra, il database e una tabella usando un'applicazione Java

Condividi tramite

funzionalità di Apache Cassandra supportate da Azure Cosmos DB for Apache Cassandra

Protocollo Cassandra

Istanza gestita di Azure per Apache Cassandra

Driver Cassandra

Tipi di dati CQL

Funzioni CQL

Comandi CQL

Transazioni leggere (LWT)

Comandi della shell CQL

Supporto JSON

Limiti dell'API per Cassandra

Strumenti

Shell CQL

Mapping coerente

Gestione di ruoli e privilegi

Opzioni di Keyspace e tabella

Indice secondario

Utilizzo dei criteri di ripetizione delle connessioni di Cassandra

Passaggi successivi

Commenti e suggerimenti

Risorse aggiuntive