Compartilhar via

Recursos do Apache Cassandra com suporte no Azure Cosmos DB for Apache Cassandra

APLICA-SE AO: Cassandra

O Azure Cosmos DB é o serviço de banco de dados multimodelo distribuído globalmente da Microsoft. Você pode se comunicar com o Azure Cosmos DB for Apache Cassandra por meio dos drivers de cliente do Cassandra de software livre em conformidade com o protocolo de transmissão Protocolo Binário v4 da CQL (Linguagem de Consulta do Cassandra).

Ao usar o Azure Cosmos DB for Apache Cassandra, você pode aproveitar os benefícios das APIs do Apache Cassandra e as funcionalidades empresariais oferecidas pelo Azure Cosmos DB. As funcionalidades empresariais incluem distribuição global, particionamento com expansão automática, garantias de disponibilidade e latência, criptografia em repouso e backups.

Protocolo do Cassandra

O Azure Cosmos DB para Apache Cassandra é compatível com a API do Cassandra Query Language (CQL) v3.11. É compatível com versões anteriores da versão 2.x. Os comandos, ferramentas, limitações e exceções do CQL com suporte são listados posteriormente neste artigo. Qualquer driver de cliente que reconheça esses protocolos poderá se conectar ao Azure Cosmos DB for Apache Cassandra.

Instância Gerenciada do Azure para Apache Cassandra

Para alguns clientes, a adaptação à API do Cassandra pode ser um desafio devido a diferenças de comportamento e configuração, especialmente para migrações do tipo lift-and-shift. Se um recurso crítico para seu aplicativo estiver listado como sem suporte posteriormente neste artigo, considere usar a Instância Gerenciada do Azure para Apache Cassandra. Esse é um serviço interno do Azure para hospedar e manter clusters do Apache Cassandra de código aberto puros com 100% de compatibilidade.

Driver do Cassandra

O Azure Cosmos DB para Apache Cassandra dá suporte às seguintes versões de drivers do Cassandra:

Tipos de dados CQL

O Azure Cosmos DB for Apache Cassandra dá suporte aos seguintes tipos de dados CQL:

Tipo Com suporte
ascii Sim
bigint Sim
blob Sim
boolean Sim
counter Sim
date Sim
decimal Sim
double Sim
float Sim
frozen Sim
inet Sim
int Sim
list Sim
set Sim
smallint Sim
text Sim
time Sim
timestamp Sim
timeuuid Sim
tinyint Sim
tuple Sim
uuid Sim
varchar Sim
varint Sim
tuples Sim
udts Sim
map Sim

Static tem suporte para a declaração de tipo de dados.

Funções do CQL

O Azure Cosmos DB for Apache Cassandra dá suporte às seguintes funções CQL:

Comando Com suporte
Token * Sim
ttl *** Sim
writetime *** Sim
cast ** Sim

Observação

* A API for Cassandra dá suporte ao token como projeção/seletor e só permite o token(pk) no lado esquerdo de uma cláusula where. Por exemplo, há suporte para WHERE token(pk) > 1024, mas WHERE token(pk) > token(100) para . ** A função cast() não pode ser aninhada na API para Cassandra. Por exemplo, há suporte para SELECT cast(count as double) FROM myTable, mas SELECT avg(cast(count as double)) FROM myTable para . *** Os carimbos de data/hora personalizados e o TTL especificado com a opção USING são aplicados em um nível de linha (e não por célula).

Funções de agregação:

Comando Com suporte
avg Sim
count Sim
min Sim
max Sim
sum Sim

Observação

As funções de agregação funcionam em colunas regulares, mas não há suporte para agregações em colunas de clustering.

Funções de conversão de blob:

Comando Com suporte
typeAsBlob(value) Sim
blobAsType(value) Sim

Funções UUID e timeuuid:

Comando Com suporte
dateOf() Sim
now() Sim
minTimeuuid() Sim
unixTimestampOf() Sim
toDate(timeuuid) Sim
toTimestamp(timeuuid) Sim
toUnixTimestamp(timeuuid) Sim
toDate(timestamp) Sim
toUnixTimestamp(timestamp) Sim
toTimestamp(date) Sim
toUnixTimestamp(date) Sim

Comandos da CQL

O Azure Cosmos DB dá suporte aos comandos de banco de dados a seguir nas contas da API for Cassandra.

Comando Com suporte
ALLOW FILTERING Sim
ALTER KEYSPACE N/A (serviço PaaS, replicação gerenciada internamente)
ALTER MATERIALIZED VIEW Sim
ALTER ROLE Não
ALTER TABLE Sim
ALTER TYPE Não
ALTER USER Não
BATCH Sim (somente lote não registrado)
COMPACT STORAGE N/D (serviço PaaS)
CREATE AGGREGATE Não
CREATE CUSTOM INDEX (SASI) Não
CREATE INDEX Sim (incluindo índices nomeados, mas não há suporte para a coleção FROZEN completa)
CREATE FUNCTION Não
CREATE KEYSPACE(configurações de replicação ignoradas) Sim
CREATE MATERIALIZED VIEW Sim
CREATE TABLE Sim
CREATE TRIGGER Não
CREATE TYPE Sim
CREATE ROLE Não
CREATE USER (preterido no Apache Cassandra nativo) Não
DELETE Sim
DISTINCT Não
DROP AGGREGATE Não
DROP FUNCTION Não
DROP INDEX Sim
DROP KEYSPACE Sim
DROP MATERIALIZED VIEW Sim
DROP ROLE Não
DROP TABLE Sim
DROP TRIGGER Não
DROP TYPE Sim
DROP USER (preterido no Apache Cassandra nativo) Não
GRANT Não
INSERT Sim
LIST PERMISSIONS Não
LIST ROLES Não
LIST USERS (preterido no Apache Cassandra nativo) Não
REVOKE Não
SELECT Sim
UPDATE Sim
TRUNCATE Sim
USE Sim

Transações leves (LWT)

Componente Com suporte
DELETE IF EXISTS Sim
DELETE conditions Sim
INSERT IF NOT EXISTS Sim
UPDATE IF EXISTS Sim
UPDATE IF NOT EXISTS Sim
UPDATE conditions Sim

Observação

Atualmente, transações leves não são compatíveis com contas que têm o recurso de gravações em várias regiões habilitado.

Comandos do Shell CQL

O Azure Cosmos DB dá suporte aos comandos de banco de dados a seguir nas contas da API for Cassandra.

Comando Com suporte
CAPTURE Sim
CLEAR Sim
CONSISTENCY * N/D
COPY Não
DESCRIBE Sim
cqlshExpand Não
EXIT Sim
LOGIN N/A (a função USER CQL não tem suporte, portanto LOGIN , é redundante)
PAGING Sim
SERIAL CONSISTENCY * N/D
SHOW Sim
SOURCE Sim
TRACING N/A (A API for Cassandra tem o suporte do Azure Cosmos DB – Use o log de diagnósticos para solucionar problemas)

Observação

A consistência funciona de forma diferente no Azure Cosmos DB. Para obter mais informações, consulte Apache Cassandra e Azure Cosmos DB para os níveis de consistência do Apache Cassandra.

Suporte a JSON

Comando Com suporte
SELECT JSON Sim
INSERT JSON Sim
fromJson() Não
toJson() Não

Limites do API for Cassandra

O Azure Cosmos DB para Apache Cassandra não tem limites no tamanho dos dados armazenados em uma tabela. Centenas de terabytes ou petabytes de dados podem ser armazenados, com a garantia de que os limites de chave de partição sejam respeitados. Da mesma forma, cada entidade ou equivalente de linha não tem limites no número de colunas. O tamanho total da entidade não deve exceder 2 MB. Os dados por chave de partição não podem exceder 20 GB como em todas as outras APIs.

Ferramentas

O Azure Cosmos DB for Apache Cassandra é uma plataforma de serviço gerenciado. A plataforma não requer sobrecarga de gerenciamento ou utilitários, como Coletor de Lixo (Garbage Collector), JVM (Máquina Virtual Java) e ferramenta de gerenciamento de nós para gerenciar o cluster. Ferramentas como cqlsh que usam a compatibilidade Binária do CQLv4 são suportadas.

  • O data explorer do portal do Azure, as métricas, o diagnóstico de log, o PowerShell e a CLI são outros mecanismos com suporte para gerenciar a conta.

Shell do CQL

Você pode se conectar à API for Cassandra no Azure Cosmos DB usando o CQLSH instalado em um computador local. Ele vem com o Apache Cassandra 3.11 e fica pronto para o uso definindo as variáveis de ambiente. As seções a seguir incluem instruções de instalação, configuração e conexão com a API for Cassandra no Azure Cosmos DB, no Windows ou no Linux por meio do CQLSH.

Aviso

As conexões com o Azure Cosmos DB para Apache Cassandra não funcionam com as versões do DataStax Enterprise (DSE) ou Cassandra 4.0 do CQLSH. Certifique-se de usar apenas as versões do Apache Cassandra de software livre v3.11 do CQLSH ao se conectar à API do Cassandra.

Windows:

  1. Instale o Python 3.

  2. Instale o PIP.

    1. Antes de instalar o PIP, baixe o arquivo get-pip.py .
    2. Abra uma janela do prompt de comando, se ainda não estiver aberta. Para fazer isso, abra a barra de pesquisa do Windows, digite cmd e selecione o ícone.
    3. Em seguida, execute o seguinte comando para baixar o arquivo get-pip.py :
    curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py

  3. Instale o PIP no Windows:

    python get-pip.py

  4. Verifique a instalação do PIP. Procure uma mensagem da etapa 3 para confirmar em qual pasta o PIP foi instalado. Em seguida, navegue até essa pasta e execute o comando pip help.

  5. Instale o CQLSH usando PIP:

    pip3 install cqlsh==5.0.3

  6. Instale o Python 2.

  7. Execute o CQLSH usando o mecanismo de autenticação.

Observação

Você precisa definir as variáveis de ambiente para apontar para a pasta Python 2.

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

Conecte-se ao 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

Conecte-se ao 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

Todas as operações CRUD executadas por meio de um SDK compatível com CQL v4 retornam informações extras sobre unidades de erro e solicitação consumidas. Para garantir o uso mais eficiente da taxa de transferência provisionada, os comandos DELETE e UPDATE devem ser tratados com a governança de recursos levada em consideração.

Observação

O gc_grace_seconds valor deve ser zero, se especificado.

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

Mapeamento de consistência

O Azure Cosmos DB for Apache Cassandra fornece a opção de consistência para operações de leitura. Para obter mais informações, consulte Mapeamento de níveis de consistência.

Gerenciamento de funções e de permissões

O Azure Cosmos DB dá suporte ao RBAC do Azure (controle de acesso baseado em função do Azure) para provisionamento, rotação de chaves, exibição de métricas e senhas/chaves de leitura/gravação e somente leitura que podem ser obtidas por meio do portal do Azure. O Azure Cosmos DB não dá suporte a funções para atividades CRUD.

Opções de tabela e de keyspace

As opções para nome da região, classe, replication_factor e datacenter no CREATE KEYSPACE comando são ignoradas no momento. O sistema usa o método de replicação de distribuição global subjacente do Azure Cosmos DB para adicionar as regiões. Se você precisar da presença entre regiões de dados, poderá habilitá-los no nível da conta com o PowerShell, a CLI ou o portal do Azure. Para obter mais informações, consulte Adicionar regiões à sua conta de banco de dados.

Durable_writes não podem ser desabilitadas porque o Azure Cosmos DB garante que cada gravação seja durável. Em todas as regiões, o Azure Cosmos DB replica os dados no conjunto de réplicas composto por quatro réplicas e essa configuração de conjunto de réplicas não pode ser modificada.

Todas as opções são ignoradas ao criar a tabela, exceto gc_grace_seconds, que deve ser definida como zero. O keyspace e a tabela têm uma opção extra nomeada cosmosdb_provisioned_throughput com um valor mínimo de 400 RU/s. A capacidade de processamento do Keyspace permite compartilhar a largura de banda entre múltiplas tabelas. É útil para cenários em que todas as tabelas não estejam usando a taxa de transferência provisionada. O ALTER TABLE comando permite alterar a taxa de transferência provisionada entre as regiões.

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 secundário

A API for Cassandra dá suporte a índices secundários em todos os tipos de dados, exceto tipos de coleção frozen, tipos variante e decimal.

Uso da política de nova tentativa de conexão do Cassandra

O Azure Cosmos DB é um sistema controlado por recursos. Você pode fazer algumas operações em um determinado segundo com base nas unidades de solicitação consumidas pelas operações. Se um aplicativo exceder esse limite em um determinado segundo, as solicitações serão limitadas por taxa e exceções serão geradas. A API for Cassandra no Azure Cosmos DB converte essas exceções em erros de sobrecarga no protocolo nativo do Cassandra.

Para garantir que seu aplicativo possa interceptar e repetir solicitações se houver limitação de taxa, as extensões spark e Java serão fornecidas. Confira também os exemplos de código Java dos drivers versão 3 e versão 4 do DataStax ao se conectar à API for Cassandra no Azure Cosmos DB. Se você usar outros SDKs para acessar a API for Cassandra no Azure Cosmos DB, crie uma política de repetição para repetir as operações ao encontrar essas exceções. Como alternativa, habilite as repetições do lado do servidor para a API for Cassandra.

Próximas etapas