funzionalità di Apache Cassandra supportate da Azure Cosmos DB for Apache Cassandra
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 distribuzione globale, partizionamento di scalabilità automatica orizzontale, garanzie di disponibilità e latenza, crittografia dei dati inattivi, backup e molto altro ancora.
Protocollo Cassandra
Azure Cosmos DB for Apache Cassandra è compatibile con l'API Cassandra Query Language (CQL) v3.11 (compatibile con la versione 2.x precedente). Comandi CQL supportati, strumenti, limitazioni ed eccezioni sono elencate di seguito. 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ò risultare problematico a causa delle differenze di comportamento e/o configurazione, soprattutto per le migrazioni in modalità lift-and-shift. Se una funzionalità fondamentale per l'applicazione è elencata come non supportata di seguito, è consigliabile usare Istanza gestita di Azure per Apache Cassandra. Si tratta un servizio di Azure proprietario per l'hosting e la gestione di cluster Apache Cassandra open source puri con compatibilità al 100%.
Driver Cassandra
Le versioni seguenti dei driver di Cassandra sono supportate da Azure Cosmos DB for Apache Cassandra:
Tipi di dati CQL
Azure Cosmos DB for Apache Cassandra supporta i tipi di dati CQL seguenti:
| Type | 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 funzione cast() non è annidabile nell'API per Cassandra. Ad esempio, SELECT cast(count as double) FROM myTable è supportato, ma SELECT avg(cast(count as double)) FROM myTable non 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 abilitate in più aree.
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 CQL USER non è supportata, per cui 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 qui.
Supporto JSON
| Comando | Supportata |
|---|---|
SELECT JSON |
Sì |
INSERT JSON |
Sì |
fromJson() |
No |
toJson() |
No |
Limiti dell'API per Cassandra
Azure Cosmos DB for Apache Cassandra non prevede limiti per le 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. In modo analogo, ogni entità o riga equivalente non prevede limiti per il numero di colonne. La dimensione totale dell'entità non deve tuttavia superare i 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à come Garbage Collector, Java Virtual Machine(JVM) e nodetool per gestire il cluster. Supporta strumenti come cqlsh che utilizza la compatibilità binaria CQLv4.
- Esplora dati del portale di Azure, metriche, diagnostica log, PowerShell e interfaccia della riga di comando 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 for Apache Cassandra non funzioneranno con le versioni DataStax Enterprise (DSE) o Cassandra 4.0 di CQLSH. Assicurarsi di usare solo le versioni di CQLSH v3.11 open source per Apache Cassandra quando ci si connette all'API per Cassandra.
Windows:
- Installare Python 3
- Installare PIP
- Prima di installare PIP, scaricare il file get-pip.py.
- Avviare un prompt dei comandi se non è già aperto. A tale scopo, aprire la barra di ricerca di Windows, digitare cmd e selezionare l'icona.
- Quindi, per scaricare il file -pip.py, eseguire il comando seguente:
curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py - Installare PIP su Windows
python get-pip.py
- Verificare l'installazione di PIP (cercare un messaggio del passaggio 3 per confermare la cartella in cui è stato installato PIP e quindi passare a tale cartella ed eseguire il comando pip help).
- Installare CQLSH con 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.
Eseguire l'installazione su 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
Eseguire la connessione 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
Eseguire la connessione 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
Se eseguite tramite un SDK compatibile con CQL v4, tutte le operazioni CRUD restituiranno informazioni aggiuntive sull'errore e sulle unità richiesta consumate. Per garantire un uso estremamente efficiente delle unità elaborate di cui è stato effettuato il provisioning, i comandi DELETE e UPDATE devono essere gestiti tenendo in considerazione la governance delle risorse.
- Nota: se specificato, il valore di gc_grace_seconds deve essere zero.
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. Il mapping di coerenza è descritto in maniera dettagliata qui.
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 del comando "Create Keyspace" relative a nome di area, classe, fattore di replica e data center 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 di più aree, è possibile abilitarla a livello di account con PowerShell, l'interfaccia della riga di comando o il portale. Per altre informazioni, vedere l'articolo su come aggiungere aree. 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 di gc_grace_seconds, che deve essere impostata su zero. Keyspace e tabella includono un'altra opzione, denominata "cosmosdb_provisioned_throughput", con un valore minimo di 400 UR/s. Le unità elaborate di Keyspace possono essere condivise tra più tabelle e sono utili per gli scenari in cui nessuna tabella utilizza quelle di cui è stato effettuato il provisioning. Il comando Alter Table consente di cambiare le unità elaborate 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 un determinato numero di operazioni in un dato secondo in base alle unità richieste utilizzate dalle operazioni. Se un'applicazione supera tale limite in un dato secondo, la frequenza delle richieste viene limitata e verranno 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 sia in grado di intercettare e ripetere le richieste in caso di limitazione della frequenza, sono disponibili 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
- Per iniziare, creare un account API per Cassandra, un database e una tabella usando un'applicazione Java