Condividi tramite


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

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 *
ttl ***
writetime ***
cast **

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 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
count
min
max
sum

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)
blobAsType(value)

Funzioni UUID e timeuuid:

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

Comandi CQL

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

Comando Supportata
ALLOW FILTERING
ALTER KEYSPACE N/d (servizio PaaS, replica gestita internamente)
ALTER MATERIALIZED VIEW
ALTER ROLE No
ALTER TABLE
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)
CREATE MATERIALIZED VIEW
CREATE TABLE
CREATE TRIGGER No
CREATE TYPE
CREATE ROLE No
CREATE USER (deprecato in Apache Cassandra nativo) No
DELETE
DISTINCT No
DROP AGGREGATE No
DROP FUNCTION No
DROP INDEX
DROP KEYSPACE
DROP MATERIALIZED VIEW
DROP ROLE No
DROP TABLE
DROP TRIGGER No
DROP TYPE
DROP USER (deprecato in Apache Cassandra nativo) No
GRANT No
INSERT
LIST PERMISSIONS No
LIST ROLES No
LIST USERS (deprecato in Apache Cassandra nativo) No
REVOKE No
SELECT
UPDATE
TRUNCATE
USE

Transazioni leggere (LWT)

Componente Supportata
DELETE IF EXISTS
DELETE conditions
INSERT IF NOT EXISTS
UPDATE IF EXISTS
UPDATE IF NOT EXISTS
UPDATE conditions

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
CLEAR
CONSISTENCY * N/D
COPY No
DESCRIBE
cqlshExpand No
EXIT
LOGIN N/D (la funzione CQL USER non è supportata, per cui LOGIN è ridondante)
PAGING
SERIAL CONSISTENCY * N/D
SHOW
SOURCE
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
INSERT JSON
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:

  1. Installare Python 3
  2. Installare PIP
    1. Prima di installare PIP, scaricare il file get-pip.py.
    2. 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.
    3. Quindi, per scaricare il file -pip.py, eseguire il comando seguente:
    curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py 
    
  3. Installare PIP su Windows
python get-pip.py
  1. 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).
  2. Installare CQLSH con PIP
pip3 install cqlsh==5.0.3
  1. Installare Python 2
  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