Recursos do Apache Cassandra suportados pelo Azure Cosmos DB para Apache Cassandra
APLICA-SE A: 
Cassandra
A Base de Dados Cosmos do Azure é um serviço de bases de dados com vários modelos da Microsoft distribuído globalmente. Você pode se comunicar com o Azure Cosmos DB para Apache Cassandra por meio dos drivers de cliente Cassandra de código aberto compatíveis com o protocolo de conexão Cassandra Binary Language (CQL) v4.
Usando o Azure Cosmos DB para Apache Cassandra, você pode aproveitar os benefícios das APIs do Apache Cassandra e os recursos corporativos que o Azure Cosmos DB fornece. As funcionalidades empresariais incluem distribuição global, criação automática de partições de aumento horizontal, garantias de disponibilidade e latência, encriptação de dados inativos, cópias de segurança e mais.
Protocolo do Cassandra
O Azure Cosmos DB para Apache Cassandra é compatível com a API Cassandra Query Language (CQL) v3.11 (compatível com versões anteriores da versão 2.x). Os comandos, as ferramentas, as limitações e as exceções de CQL suportados encontram-se listados abaixo. Qualquer driver de cliente que entenda esses protocolos deve ser capaz de se conectar ao Azure Cosmos DB para Apache Cassandra.
Azure Managed Instance for Apache Cassandra
Para alguns clientes, a adaptação à API para Cassandra pode ser um desafio devido a diferenças de comportamento e/ou configuração, especialmente para migrações de elevação e mudança. Se um recurso crítico para seu aplicativo estiver listado como não suportado abaixo, considere usar a Instância Gerenciada do Azure para Apache Cassandra. Este é um serviço do Azure de primeira parte para hospedar e manter clusters Apache Cassandra puros de código aberto com 100% de compatibilidade.
Controlador do Cassandra
As seguintes versões dos drivers Cassandra são suportadas pelo Azure Cosmos DB para Apache Cassandra:
- Java 3.5 e posterior
- C# 3.5 e posterior
- Nodejs 3.5 e posterior
- Python 3.15 e posterior
- C++ 2.9
- PHP 1.3
- Gocql
Tipos de dados de CQL
O Azure Cosmos DB para Apache Cassandra suporta os seguintes tipos de dados CQL:
| Tipo | Suportado |
|---|---|
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 |
Estático é suportado para declaração de tipo de dados.
Funções de CQL
O Azure Cosmos DB para Apache Cassandra suporta as seguintes funções CQL:
| Command | Suportado |
|---|---|
Token * |
Sim |
ttl *** |
Sim |
writetime *** |
Sim |
cast ** |
Sim |
Nota
* API para Cassandra suporta token como uma projeção/seletor, e só permite token (pk) no lado esquerdo de uma cláusula where. Por exemplo, é suportado, WHERE token(pk) > 1024 mas WHERE token(pk) > token(100) não é suportado.
** A cast() função não é aninhada na API para Cassandra. Por exemplo, é suportado, SELECT cast(count as double) FROM myTable mas SELECT avg(cast(count as double)) FROM myTable não é suportado.
Os carimbos de data/hora personalizados e o TTL especificado com a USING opção são aplicados em um nível de linha (e não por célula).
Funções agregadas:
| Command | Suportado |
|---|---|
avg |
Sim |
count |
Sim |
min |
Sim |
max |
Sim |
sum |
Sim |
Nota
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:
| Command | Suportado |
|---|---|
typeAsBlob(value) |
Sim |
blobAsType(value) |
Sim |
Funções UUID e timeuuid:
| Command | Suportado |
|---|---|
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 de CQL
O Azure Cosmos DB dá suporte aos seguintes comandos de banco de dados na API para contas Cassandra.
| Command | Suportado |
|---|---|
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 (apenas lote não registado) |
COMPACT STORAGE |
N/A (serviço PaaS) |
CREATE AGGREGATE |
No |
CREATE CUSTOM INDEX (SASI) |
Não |
CREATE INDEX |
Sim (incluindo índices nomeados, mas a coleção FROZEN completa não é suportada) |
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 |
No |
CREATE USER (Preterido no Apache Cassandra nativo) |
Não |
DELETE |
Sim |
DISTINCT |
Não |
DROP AGGREGATE |
No |
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) |
No |
GRANT |
Não |
INSERT |
Sim |
LIST PERMISSIONS |
Não |
LIST ROLES |
Não |
LIST USERS (Preterido no Apache Cassandra nativo) |
No |
REVOKE |
Não |
SELECT |
Sim |
UPDATE |
Sim |
TRUNCATE |
Sim |
USE |
Sim |
Transações leves (LWT)
| Componente | Suportado |
|---|---|
DELETE IF EXISTS |
Sim |
DELETE conditions |
Sim |
INSERT IF NOT EXISTS |
Sim |
UPDATE IF EXISTS |
Sim |
UPDATE IF NOT EXISTS |
Sim |
UPDATE conditions |
Sim |
Nota
Atualmente, transações leves não são suportadas para contas com gravações em várias regiões habilitadas.
Comandos do CQL Shell
O Azure Cosmos DB dá suporte aos seguintes comandos de banco de dados na API para contas Cassandra.
| Command | Suportado |
|---|---|
CAPTURE |
Sim |
CLEAR |
Sim |
CONSISTENCY * |
N/A |
COPY |
Não |
DESCRIBE |
Sim |
cqlshExpand |
Não |
EXIT |
Sim |
LOGIN |
N/A (CQL função USER não é suportada, portanto LOGIN , é redundante) |
PAGING |
Sim |
SERIAL CONSISTENCY * |
N/A |
SHOW |
Sim |
SOURCE |
Sim |
TRACING |
N/A (API para Cassandra é apoiada pelo Azure Cosmos DB - use o log de diagnóstico para solução de problemas) |
Nota
A consistência funciona de forma diferente no Azure Cosmos DB, consulte aqui para obter mais informações.
Suporte JSON
| Command | Suportado |
|---|---|
SELECT JSON |
Sim |
INSERT JSON |
Sim |
fromJson() |
Não |
toJson() |
Não |
Limites da API para Cassandra
O Azure Cosmos DB para Apache Cassandra não tem limites para o tamanho dos dados armazenados em uma tabela. É possível armazenar centenas de terabytes ou de petabytes de dados sem desrespeitar os limites da chave de partição. Da mesma forma, cada entidade ou equivalente de linha não tem limites para o número de colunas. No entanto, a dimensão 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 para Apache Cassandra é uma plataforma de serviço gerenciado. A plataforma não requer nenhuma sobrecarga de gerenciamento ou utilitários como Garbage Collector, Java Virtual Machine (JVM) e nodetool para gerenciar o cluster. Ferramentas como cqlsh que utiliza compatibilidade binária CQLv4 são suportadas.
- O explorador de dados, métricas, diagnóstico de log, PowerShell e CLI do portal do Azure são outros mecanismos suportados para gerenciar a conta.
Shell CQL
Você pode se conectar à API para Cassandra no Azure Cosmos DB usando o CQLSH instalado em uma máquina local. Ele vem com Apache Cassandra 3.11 e funciona fora da caixa, definindo as variáveis de ambiente. As seções a seguir incluem as instruções para instalar, configurar e conectar-se à API para Cassandra no Azure Cosmos DB, no Windows ou Linux usando CQLSH.
Aviso
As conexões com o Azure Cosmos DB para Apache Cassandra não funcionarão com as versões DataStax Enterprise (DSE) ou Cassandra 4.0 do CQLSH. Certifique-se de usar apenas v3.11 versões de código aberto Apache Cassandra do CQLSH ao se conectar à API para Cassandra.
Windows:
- Instalar o Python 3
- Instalar PIP
- Antes de instalar o PIP, baixe o arquivo get-pip.py.
- Inicie um prompt de comando se ele ainda não estiver aberto. Para fazer isso, abra a barra de pesquisa do Windows, digite cmd e selecione o ícone.
- 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 - Instalar o PIP no Windows
python get-pip.py
- Verifique a instalação do PIP (procure uma mensagem da etapa 3 para confirmar em qual pasta o PIP foi instalado e, em seguida, navegue até essa pasta e execute o comando pip help).
- Instalar o CQLSH usando PIP
pip3 install cqlsh==5.0.3
- Instalar o Python 2
- Execute o CQLSH usando o mecanismo de autenticação.
Nota
Você precisaria definir as variáveis de ambiente para apontar para a pasta Python 2.
Instale em 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 com 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 com o 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 retornarão informações adicionais sobre unidades de erro e solicitação consumidas. Os comandos DELETE e UPDATE devem ser tratados com a governança de recursos levada em consideração, para garantir o uso mais eficiente da taxa de transferência provisionada.
- Tenha em atenção que, caso seja especificado, o valor gc_grace_seconds tem de ser 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}");
}
Mapeamento de consistência
O Azure Cosmos DB para Apache Cassandra oferece opções de consistência para operações de leitura. O mapeamento de consistência é detalhado aqui.
Gestão de permissões e funções
O Azure Cosmos DB dá suporte ao controle de acesso baseado em função do Azure (Azure RBAC) para provisionamento, rotação de chaves, métricas de exibição 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 oferece suporte a funções para atividades CRUD.
Opções de espaço de chave e tabela
As opções para nome da região, classe, replication_fator e datacenter no comando "Create Keyspace" são ignoradas atualmente. 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 de dados entre regiões, poderá habilitá-la no nível da conta com PowerShell, CLI ou portal, para saber mais, consulte o artigo Como adicionar regiões . Durable_writes não pode ser desabilitado porque o Azure Cosmos DB garante que cada gravação seja durável. Em cada região, o Azure Cosmos DB replica os dados no conjunto de réplicas que é 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 chamada "cosmosdb_provisioned_throughput" com um valor mínimo de 400 RU/s. A taxa de transferência do Keyspace permite o compartilhamento da taxa de transferência entre várias tabelas e é útil para cenários em que todas as tabelas não estão utilizando a taxa de transferência provisionada. O comando Alter Table 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 para Cassandra suporta índices secundários em todos os tipos de dados, exceto tipos de coleção congelada, decimais e variantes.
Utilização da política de ligação de repetição Cassandra
O Azure Cosmos DB é um sistema controlado por recursos. Você pode fazer um determinado número de 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 lançadas. A API para Cassandra no Azure Cosmos DB traduz essas exceções em erros sobrecarregados no protocolo nativo Cassandra. Para garantir que seu aplicativo possa intercetar e repetir solicitações em caso de limitação de taxa, o spark e as extensões Java são fornecidos. Consulte também exemplos de código Java para drivers Datastax versão 3 e versão 4, ao se conectar à API para Cassandra no Azure Cosmos DB. Se você usar outros SDKs para acessar a API para Cassandra no Azure Cosmos DB, crie uma política de repetição para repetir essas exceções. Como alternativa, habilite novas tentativas do lado do servidor para API para Cassandra.
Próximos passos
- Introdução à criação de uma API para a conta Cassandra, banco de dados e uma tabela usando um aplicativo Java