Delen via

Apache Cassandra-functies die worden ondersteund door Azure Cosmos DB voor Apache Cassandra

  • Artikel

VAN TOEPASSING OP: Cassandra

Azure Cosmos DB is de wereldwijd gedistribueerde multimodel-databaseservice van Microsoft. U kunt communiceren met Azure Cosmos DB voor Apache Cassandra via de cassandra-querytaal (CQL) Binary Protocol v4 wire protocol conform opensource Cassandra-clientstuurprogramma's.

Met behulp van Azure Cosmos DB voor Apache Cassandra kunt u profiteren van de voordelen van de Apache Cassandra-API's en de bedrijfsmogelijkheden die Azure Cosmos DB biedt. De enterprise-mogelijkheden zijn onder andere wereldwijde distributie, automatische scale-out partitionering, beschikbaarheid- en latentiegaranties, versleuteling van gegevens in rust, back-ups en nog veel meer.

Cassandra-protocol

Azure Cosmos DB voor Apache Cassandra is compatibel met Cassandra Query Language (CQL) v3.11 API (achterwaarts compatibel met versie 2.x). De ondersteunde CQL-opdrachten, hulpprogramma's, beperkingen en uitzonderingen worden hieronder vermeld. Elk clientstuurprogramma dat deze protocollen begrijpt, moet verbinding kunnen maken met Azure Cosmos DB voor Apache Cassandra.

Azure Managed Instance voor Apache Cassandra

Voor sommige klanten kan aanpassing aan API voor Cassandra een uitdaging zijn vanwege verschillen in gedrag en/of configuratie, met name voor lift-and-shift-migraties. Als een functie die essentieel is voor uw toepassing wordt vermeld zoals hieronder niet wordt ondersteund, kunt u overwegen Om Azure Managed Instance voor Apache Cassandra te gebruiken. Dit is een eigen Azure-service voor het hosten en onderhouden van pure opensource Apache Cassandra-clusters met 100% compatibiliteit.

Cassandra-stuurprogramma

De volgende versies van Cassandra-stuurprogramma's worden ondersteund door Azure Cosmos DB voor Apache Cassandra:

CQL-gegevenstypen

Azure Cosmos DB voor Apache Cassandra ondersteunt de volgende CQL-gegevenstypen:

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

Statisch wordt ondersteund als declaratie van het gegevenstype.

CQL-functies

Azure Cosmos DB voor Apache Cassandra ondersteunt de volgende CQL-functies:

Opdracht Ondersteund
Token * Ja
ttl *** Ja
writetime *** Ja
cast ** Ja

Notitie

* API voor Cassandra ondersteunt token als projectie/selector en staat alleen token(pk) toe aan de linkerkant van een where-component. WHERE token(pk) > 1024 wordt bijvoorbeeld ondersteund, maar WHERE token(pk) > token(100) wordt niet ondersteund.
** De cast() functie kan niet worden genest in DE API voor Cassandra. SELECT cast(count as double) FROM myTable wordt bijvoorbeeld ondersteund, maar SELECT avg(cast(count as double)) FROM myTable wordt niet ondersteund.
Aangepaste tijdstempels en TTL die met de USING optie zijn opgegeven, worden toegepast op rijniveau (en niet per cel).

Statistische functies:

Opdracht Ondersteund
avg Ja
count Ja
min Ja
max Ja
sum Ja

Notitie

Statistische functies werken in gewone kolommen, maar aggregaties in clusterkolommen worden niet ondersteund.

Blob-conversiefuncties:

Opdracht Ondersteund
typeAsBlob(value) Ja
blobAsType(value) Ja

UUID- en timeuuid-functies:

Opdracht Ondersteund
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-opdrachten

Azure Cosmos DB ondersteunt de volgende databaseopdrachten in API voor Cassandra-accounts.

Opdracht Ondersteund
ALLOW FILTERING Ja
ALTER KEYSPACE N.v.t (PaaS-service, replicatie intern beheerd)
ALTER MATERIALIZED VIEW Ja
ALTER ROLE No
ALTER TABLE Ja
ALTER TYPE No
ALTER USER Nr.
BATCH Ja (alleen niet-geregistreerde batches)
COMPACT STORAGE N.v.t. (PaaS-service)
CREATE AGGREGATE Nee
CREATE CUSTOM INDEX (SASI) Nr.
CREATE INDEX Ja (inclusief benoemde indexen , maar volledige FROZEN-verzameling wordt niet ondersteund)
CREATE FUNCTION Nee
CREATE KEYSPACE (replicatie-instellingen genegeerd) Ja
CREATE MATERIALIZED VIEW Ja
CREATE TABLE Ja
CREATE TRIGGER No
CREATE TYPE Ja
CREATE ROLE Nr.
CREATE USER (Afgeschaft in systeemeigen Apache Cassandra) Nr.
DELETE Ja
DISTINCT No
DROP AGGREGATE Nee
DROP FUNCTION No
DROP INDEX Ja
DROP KEYSPACE Ja
DROP MATERIALIZED VIEW Ja
DROP ROLE No
DROP TABLE Ja
DROP TRIGGER No
DROP TYPE Ja
DROP USER (Afgeschaft in systeemeigen Apache Cassandra) Nee
GRANT No
INSERT Ja
LIST PERMISSIONS No
LIST ROLES Nr.
LIST USERS (Afgeschaft in systeemeigen Apache Cassandra) Nee
REVOKE No
SELECT Ja
UPDATE Ja
TRUNCATE Ja
USE Ja

Lichtgewicht transacties (LWT)

Onderdeel Ondersteund
DELETE IF EXISTS Ja
DELETE conditions Ja
INSERT IF NOT EXISTS Ja
UPDATE IF EXISTS Ja
UPDATE IF NOT EXISTS Ja
UPDATE conditions Ja

Notitie

Lichtgewicht transacties worden momenteel niet ondersteund voor accounts waarvoor schrijfbewerkingen in meerdere regio's zijn ingeschakeld.

CQL Shell-opdrachten

Azure Cosmos DB ondersteunt de volgende databaseopdrachten in API voor Cassandra-accounts.

Opdracht Ondersteund
CAPTURE Ja
CLEAR Ja
CONSISTENCY * N.v.t.
COPY Nr.
DESCRIBE Ja
cqlshExpand No
EXIT Ja
LOGIN N.v.t. (DE CQL-functie USER wordt niet ondersteund, dus LOGIN is redundant)
PAGING Ja
SERIAL CONSISTENCY * N.v.t.
SHOW Ja
SOURCE Ja
TRACING N/B (API voor Cassandra wordt ondersteund door Azure Cosmos DB: diagnostische logboekregistratie gebruiken voor probleemoplossing)

Notitie

Consistentie werkt anders in Azure Cosmos DB. Zie hier voor meer informatie.

JSON-ondersteuning

Opdracht Ondersteund
SELECT JSON Ja
INSERT JSON Ja
fromJson() No
toJson() Nr.

API voor Cassandra-limieten

Azure Cosmos DB voor Apache Cassandra heeft geen limieten voor de grootte van gegevens die zijn opgeslagen in een tabel. Er kunnen honderden terabytes of petabytes aan gegevens worden opgeslagen terwijl de partitiesleutellimieten worden gerespecteerd. Evenzo heeft elke entiteit of rij-equivalent geen limieten voor het aantal kolommen. De totale omvang van de entiteit mag echter niet groter zijn dan 2 MB. De gegevens per partitiesleutel mogen niet groter zijn dan 20 GB, zoals in alle andere API's.

Hulpprogramma's

Azure Cosmos DB voor Apache Cassandra is een beheerd serviceplatform. Het platform vereist geen beheeroverhead of hulpprogramma's zoals Garbage Collector, Java Virtual Machine (JVM) en nodetool om het cluster te beheren. Hulpprogramma's zoals cqlsh die gebruikmaken van binaire CQLv4-compatibiliteit, worden ondersteund.

  • Andere ondersteunde mechanismen voor het beheren van het account zijn Data Explorer, metrische gegevens, logboekdiagnose, PowerShell en CLI in de Azure-portal.

CQL-shell

U kunt verbinding maken met de API voor Cassandra in Azure Cosmos DB met behulp van de CQLSH die op een lokale computer is geïnstalleerd. Het wordt geleverd met Apache Cassandra 3.11 en werkt standaard door de omgevingsvariabelen in te stellen. De volgende secties bevatten de instructies voor het installeren, configureren en verbinding maken met API voor Cassandra in Azure Cosmos DB, in Windows of Linux met behulp van CQLSH.

Waarschuwing

Verbindingen met Azure Cosmos DB voor Apache Cassandra werken niet met DataStax Enterprise (DSE) of Cassandra 4.0-versies van CQLSH. Zorg ervoor dat u alleen opensourceversies van v3.11 van Apache Cassandra van CQLSH gebruikt wanneer u verbinding maakt met DE API voor Cassandra.

Windows:

  1. Python 3 installeren
  2. PIP installeren
    1. Voordat u PIP installeert, downloadt u het get-pip.py-bestand.
    2. Start een opdrachtprompt als deze nog niet is geopend. Hiervoor opent u de zoekbalk van Windows, typt u cmd en selecteert u het pictogram.
    3. Voer vervolgens de volgende opdracht uit om het get-pip.py-bestand te downloaden:
    curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py
  3. PIP installeren in Windows
python get-pip.py
  1. Controleer de PIP-installatie (zoek een bericht uit stap 3 om te bevestigen in welke map PIP is geïnstalleerd en navigeer naar die map en voer de opdracht pip Help uit).
  2. CQLSH installeren met PIP
pip3 install cqlsh==5.0.3
  1. Python 2 installeren
  2. Voer de CQLSH uit met behulp van het verificatiemechanisme.

Notitie

U moet de omgevingsvariabelen instellen om te verwijzen naar de map Python 2.

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

Verbinding maken met 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

Verbinding maken met 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

Alle CRUD-bewerkingen die worden uitgevoerd via een SDK die compatibel is met CQL v4 retourneren, extra informatie over fouten en verbruikte aanvraageenheden. De opdrachten DELETE en UPDATE moeten worden afgehandeld met resourcebeheer om te zorgen voor het meest efficiënte gebruik van de ingerichte doorvoer.

  • Let wel: de waarde gc_grace_seconds moet nul zijn als deze is opgegeven.
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}"); 
        }

Consistentietoewijzing

Azure Cosmos DB voor Apache Cassandra biedt de keuze uit consistentie voor leesbewerkingen. Hier vindt u de details van de consistentietoewijzing.

Machtigings- en rolbeheer

Azure Cosmos DB biedt Azure-RBAC (op rollen gebaseerd toegangsbeheer voor Azure) voor inrichten, wisselen van sleutels, weergeven van metrische gegevens, en wachtwoorden voor lezen/schrijven, en wachtwoorden met het kenmerk alleen-lezen die kunnen worden verkregen via Azure Portal. Azure Cosmos DB biedt geen ondersteuning voor rollen voor CRUD-activiteiten.

Opties voor Keyspace en tabel

De opties region name, class, replication_factor en datacenter in de opdracht CREATE KEYSPACE worden momenteel genegeerd. Het systeem maakt gebruik van de onderliggende replicatiemethode voor globale distributie van Azure Cosmos DB om de regio's toe te voegen. Als u wilt dat gegevens in meerdere regio's aanwezig zijn, kunt u dit op accountniveau inschakelen met PowerShell, CLI of de portal. Raadpleeg het artikel Regio's toevoegen voor meer informatie. Durable_writes kan niet worden uitgeschakeld omdat in Azure Cosmos DB elke schrijfbewerking gegarandeerd duurzaam is. Met Azure Cosmos DB worden de gegevens in elke regio gerepliceerd in de hele replicaset die bestaat uit vier replica’s, en de configuratie van deze replicaset kan niet worden gewijzigd.

Alle opties worden genegeerd bij het maken van de tabel, met uitzondering van gc_grace_seconds, die moeten worden ingesteld op nul. Keyspace en tabel hebben een extra optie genaamd cosmosdb_provisioned_throughput, met een minimumwaarde van 400 RU/s. De Keyspace-doorvoer staat delen van doorvoer in meerdere tabellen toe, en is handig voor scenario’s waarbij geen van de tabellen gebruikmaakt van de ingerichte doorvoer. De opdracht Alter Table maakt het wijzigen van ingerichte doorvoer mogelijk in alle regio’s.

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 ;

Secundaire index

API voor Cassandra ondersteunt secundaire indexen voor alle gegevenstypen, behalve bevroren verzamelingstypen, decimale en varianttypen.

Gebruik van het Cassandra-beleid voor opnieuw proberen

Azure Cosmos DB is een systeem voor resourcebeheer. U kunt een bepaald aantal bewerkingen in een bepaalde seconde uitvoeren op basis van de aanvraageenheden die door de bewerkingen worden gebruikt. Als een toepassing deze limiet in een opgegeven seconde overschrijdt, gelden er beperkingen voor aanvragen en worden er uitzonderingen gegenereerd. De API voor Cassandra in Azure Cosmos DB vertaalt deze uitzonderingen op overbelaste fouten in het systeemeigen Cassandra-protocol. De Spark- en Java-extensies worden geboden om ervoor te zorgen dat de toepassing aanvragen kan onderscheppen en opnieuw kan proberen wanneer er sprake is van een beperking. Zie ook Java-codevoorbeelden voor datastax-stuurprogramma's van versie 3 en versie 4 , wanneer u verbinding maakt met API voor Cassandra in Azure Cosmos DB. Als u andere SDK's gebruikt om toegang te krijgen tot API voor Cassandra in Azure Cosmos DB, maakt u een beleid voor opnieuw proberen om het opnieuw te proberen op deze uitzonderingen. U kunt ook nieuwe pogingen aan de serverzijde inschakelen voor API voor Cassandra.

Volgende stappen