Características de Apache Cassandra admitidas por Azure Cosmos DB for Apache Cassandra

  • Artículo

SE APLICA A: Cassandra

Azure Cosmos DB es un servicio de base de datos con varios modelos y de distribución global de Microsoft. Puede comunicarse con Azure Cosmos DB for Apache Cassandra mediante el protocolo de conexión Cassandra Query Language (CQL) Binary Protocol v4 compatible con los controladores de código abierto del cliente de Cassandra.

Con Azure Cosmos DB for Apache Cassandra, puede disfrutar de las ventajas de las API de Apache Cassandra y de las funcionalidades empresariales que ofrece Azure Cosmos DB. Entre las funcionalidades empresariales se incluyen las siguientes: distribución global, creación de particiones de escalado horizontal automático, garantías de disponibilidad y latencia, cifrado en reposo y copias de seguridad, entre otras.

Protocolo Cassandra

Azure Cosmos DB for Apache Cassandra es compatible con la versión 3.11 de la API Cassandra Query Language (CQL) (compatible con versiones anteriores, en este caso con la versión 2.x). A continuación se enumeran los comandos, las herramientas, las limitaciones y las excepciones de CQL. Cualquier controlador de cliente que reconozca estos protocolos podrá conectarse a Azure Cosmos DB for Apache Cassandra.

Azure Managed Instance para Apache Cassandra

Para algunos clientes, adaptarse a la API para Cassandra puede ser un desafío debido a las diferencias en el comportamiento o a la configuración, especialmente para las migraciones mediante lift-and-shift. Si una característica crítica para la aplicación se muestra como no admitida a continuación, considere la posibilidad de usar Azure Managed Instance for Apache Cassandra. Se trata de un servicio de Azure de primera entidad para hospedar y mantener clústeres de Apache Cassandra de código abierto puro con compatibilidad del 100 %.

Controlador Cassandra

Azure Cosmos DB for Apache Cassandra admite las siguientes versiones de los controladores Cassandra:

Tipos de datos CQL

Azure Cosmos DB for Apache Cassandra admite los siguientes tipos de datos CQL:

Tipo Compatible
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í

Se admite static para la declaración de tipos de datos.

Funciones de CQL

Azure Cosmos DB for Apache Cassandra admite las siguientes funciones de CQL:

Get-Help Compatible
Token * Sí
ttl *** Sí
writetime *** Sí
cast ** Sí

Nota

* La API para Cassandra admite el token como proyección o selector y solo permite token(pk) en el lado izquierdo de una cláusula WHERE. Por ejemplo, se admite WHERE token(pk) > 1024, pero WHERE token(pk) > token(100)no se admite.
** La función cast() no es anidable en la API para Cassandra. Por ejemplo, se admite SELECT cast(count as double) FROM myTable, pero SELECT avg(cast(count as double)) FROM myTableno se admite.
*** Las marcas de tiempo y el TTL personalizados especificados con la opción USING se aplican a nivel de fila (y no por celda).

Funciones de agregado:

Get-Help Compatible
avg Sí
count Sí
min Sí
max Sí
sum Sí

Nota

Las funciones de agregación funcionan en columnas normales, pero no se admiten agregados en columnas de agrupación en clústeres.

Funciones de conversión de blobs:

Get-Help Compatible
typeAsBlob(value) Sí
blobAsType(value) Sí

Funciones UUID y timeuuid:

Get-Help Compatible
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í

Comandos de CQL

Azure Cosmos DB admite los siguientes comandos de base de datos en las cuentas de la API para Cassandra.

Get-Help Compatible
ALLOW FILTERING Sí
ALTER KEYSPACE N/A (servicio PaaS, replicación administrada internamente)
ALTER MATERIALIZED VIEW Sí
ALTER ROLE No
ALTER TABLE Sí
ALTER TYPE No
ALTER USER No
BATCH Sí (solo proceso por lotes no registrado)
COMPACT STORAGE N/A (servicio PaaS)
CREATE AGGREGATE No
CREATE CUSTOM INDEX (SASI) No
CREATE INDEX Sí (incluidos los índices con nombre pero no se admite la colección FROZEN completa).
CREATE FUNCTION No
CREATE KEYSPACE (configuración de replicación ignorada) Sí
CREATE MATERIALIZED VIEW Sí
CREATE TABLE Sí
CREATE TRIGGER No
CREATE TYPE Sí
CREATE ROLE No
CREATE USER (en desuso en Apache Cassandra nativo) No
DELETE Sí
DISTINCT No
DROP AGGREGATE N.º
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 (en desuso en Apache Cassandra nativo) No
GRANT No
INSERT Sí
LIST PERMISSIONS No
LIST ROLES No
LIST USERS (en desuso en Apache Cassandra nativo) No
REVOKE No
SELECT Sí
UPDATE Sí
TRUNCATE Sí
USE Sí

Transacciones ligeras (LWT)

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

Actualmente no se admiten transacciones ligeras para las cuentas que tienen habilitada la escritura en varias regiones.

Comandos de shell de CQL

Azure Cosmos DB admite los siguientes comandos de base de datos en las cuentas de la API para Cassandra.

Get-Help Compatible
CAPTURE Sí
CLEAR Sí
CONSISTENCY * N/D
COPY No
DESCRIBE Sí
cqlshExpand No
EXIT Sí
LOGIN N/D (no se admite la función USER de CQL, por lo tanto LOGIN es redundante)
PAGING Sí
SERIAL CONSISTENCY * N/D
SHOW Sí
SOURCE Sí
TRACING N/D (la API para Cassandra está respaldada por Azure Cosmos DB; use el registro de diagnóstico para solucionar problemas)

Nota:

La coherencia funciona de forma diferente en Azure Cosmos DB; consulte aquí para más información.

Compatibilidad con JSON

Get-Help Compatible
SELECT JSON Sí
INSERT JSON Sí
fromJson() No
toJson() No

Límites de la API para Cassandra

Azure Cosmos DB for Apache Cassandra no tiene ningún límite en cuanto al tamaño de los datos almacenados en una tabla. Se pueden almacenar cientos de terabytes o petabytes de datos, con la seguridad de que se cumplirán los límites de la clave de partición. Del mismo modo, cada entidad o fila equivalente no tiene ningún límite en el número de columnas. Aunque el tamaño total de la entidad no debe superar los 2 MB. Los datos por clave de partición no pueden superar los 20 GB, al igual que en todas las demás API.

Herramientas

Azure Cosmos DB for Apache Cassandra es una plataforma de servicio administrada. La plataforma no requiere ninguna administración adicional ni utilidades tales como el recolector de elementos no utilizados, Java Virtual Machine (JVM) o nodetool para administrar el clúster. Se admiten herramientas como cqlsh, que utilizan la compatibilidad con archivos binarios de CQLv4.

  • Para administrar la cuenta se admiten otros mecanismos, como el explorador de datos de Azure Portal, las métricas, los diagnósticos de registro, PowerShell y la CLI.

Shell de CQL

Puede conectarse a la API para Cassandra en Azure Cosmos DB mediante el CQLSH instalado en un equipo local. Viene con Apache Cassandra 3.11, y funciona de serie estableciendo las variables de entorno. En las secciones siguientes se incluyen las instrucciones para instalar, configurar y conectarse a la API para Cassandra en Azure Cosmos DB, en Windows o Linux con CQLSH.

Advertencia

Las conexiones a Azure Cosmos DB for Apache Cassandra no funcionarán con las versiones de DataStax Enterprise (DSE) de CQLSH o Cassandra 4.0. Asegúrese de usar solo las versiones de Apache Cassandra de código abierto 3.11 de CQLSH al conectarse a la API para Cassandra.

Windows:

  1. Instale Python 3.
  2. Instale PIP.
    1. Antes de instalar PIP, descargue el archivo get-pip.py.
    2. Inicie un símbolo del sistema si aún no está abierto. Para ello, abra la barra de búsqueda de Windows, escriba cmd y seleccione el icono.
    3. A continuación, ejecute el siguiente comando para descargar el archivo get-pip.py:
    curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py
  3. Instalación de PIP en Windows
python get-pip.py
  1. Compruebe la instalación de PIP (busque un mensaje del paso 3 para confirmar en qué carpeta se instaló PIP y vaya a esa carpeta y ejecute el comando pip help).
  2. Instalación de CQLSH mediante PIP
pip3 install cqlsh==5.0.3
  1. Instale Python 2.
  2. Ejecute CQLSH mediante el mecanismo de autenticación.

Nota

Tendría que establecer las variables de entorno para que apunten a la carpeta Python 2.

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

Conectar 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

Conectar 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

Cuando se ejecutan mediante un SDK compatible con CQL v4, todas las operaciones CRUD devuelven información adicional sobre el error o las unidades de solicitud consumidas. Los comandos DELETE y UPDATE se deben controlar teniendo en cuenta la gobernanza de recursos para garantizar el uso más eficaz del rendimiento aprovisionado.

  • Tenga en cuenta que el valor gc_grace_seconds debe ser cero si se especifica.
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}"); 
        }

Asignación de coherencia

Azure Cosmos DB for Apache Cassandra ofrece opciones de coherencia para las operaciones de lectura. La asignación de coherencia se detalla aquí.

Administración de permisos y roles

Azure Cosmos DB admite el control de acceso basado en rol de Azure para el aprovisionamiento, la rotación de claves, la vista de las métricas y las claves o contraseñas de lectura y escritura y de solo lectura que se pueden obtener a través de Azure Portal. Azure Cosmos DB no admite roles para las actividades de CRUD.

Opciones de espacio de claves y de tabla

Actualmente se omiten las opciones de nombre de región, clase, factor de replicación y centro de datos del comando "Create Keyspace". El sistema utiliza el método de replicación de distribución global subyacente de Azure Cosmos DB para agregar las regiones. Si necesita la presencia de datos entre regiones, puede habilitarla en el nivel de cuenta con PowerShell, la CLI o el portal. Para más información, consulte el artículo sobre cómo agregar regiones. Durable_writes no se puede deshabilitar porque Azure Cosmos DB garantiza que todas las escrituras son duraderas. En todas las regiones, Azure Cosmos DB replica los datos en el conjunto de réplicas que se compone de cuatro réplicas, y la configuración de este conjunto no se puede modificar.

Todas las opciones se omiten al crear la tabla, excepto gc_grace_seconds, que debe establecerse en cero. El espacio de claves y la tabla tienen una opción adicional denominada "cosmosdb_provisioned_throughput" con un valor mínimo de 400 RU/s. El rendimiento del espacio de claves permite compartir el rendimiento entre varias tablas y resulta útil para los escenarios en los que no todas las tablas usan el rendimiento aprovisionado. El comando ALTER TABLE permite cambiar el rendimiento aprovisionado en todas las regiones.

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 ;

Índice secundario

La API para Cassandra admite índices secundarios en todos los tipos de datos excepto en los tipos de colección inmovilizados, los tipos decimal y variant.

Uso de la directiva de reintentos de conexión de Cassandra

Azure Cosmos DB es un sistema gobernado por recursos. Puede realizar un determinado número de operaciones en un segundo determinado en función de las unidades de solicitud utilizadas por las operaciones. Si una aplicación supera ese límite en un segundo determinado, como las solicitudes tienen una frecuencia limitada, se producirán excepciones. La API de Cassandra de Azure Cosmos DB traslada estas excepciones como errores sobrecargados en el protocolo nativo de Cassandra. Para asegurarse de que la aplicación pueda interceptar y reintentar las solicitudes en caso de limitación de frecuencia, se proporcionan las extensiones de Spark y Java. Vea también ejemplos de código de Java para la versión 3 y la versión 4 de los controladores Datastax al conectarse a la API para Cassandra en Azure Cosmos DB. Si usa otros SDK para acceder a la API para Cassandra en Azure Cosmos DB, cree una directiva de reintentos para volver a intentarlo después de estas excepciones. Como alternativa, habilite los reintentos del lado servidor para la API para Cassandra.

Pasos siguientes