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, backups e muito mais.
Protocolo do Cassandra
O Azure Cosmos DB for Apache Cassandra é compatível com a API v3.11 da CQL (Linguagem de Consulta do Cassandra) (compatível com as versões 2.x anteriores). Os comandos, ferramentas, limitações e exceções do CQL compatíveis estão listados abaixo. 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 para Cassandra pode ser um desafio devido às diferenças de comportamento e/ou configuração, especialmente para as migrações lift-and-shift. Se um recurso crítico para seu aplicativo estiver listado como não compatível abaixo, 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 software livre puros com 100% de compatibilidade.
Driver do Cassandra
As seguintes versões de drivers do Cassandra são compatíveis com o Azure Cosmos DB for Apache 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 não para WHERE token(pk) > token(100).
** A função cast() não pode ser aninhada na API for Cassandra. Por exemplo, há suporte para SELECT cast(count as double) FROM myTable, mas não para SELECT avg(cast(count as double)) FROM myTable.
*** 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 |
No |
DROP FUNCTION |
No |
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 |
No |
INSERT |
Sim |
LIST PERMISSIONS |
Não |
LIST ROLES |
Não |
LIST USERS (preterido no Apache Cassandra nativo) |
Não |
REVOKE |
No |
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 |
Yes |
CONSISTENCY * |
N/D |
COPY |
Não |
DESCRIBE |
Sim |
cqlshExpand |
Não |
EXIT |
Sim |
LOGIN |
N/A (não há suporte para a função CQL USER, 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 maneira diferente no Azure Cosmos DB, confira aqui mais informações.
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 for Apache Cassandra não tem limites para o 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, todas as entidades ou linhas equivalentes não têm nenhum limite no número de colunas. No entanto, o tamanho total da entidade não deve ultrapassar 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 nenhuma sobrecarga de gerenciamento nem utilitários como o Coletor de Lixo, a JVM (Máquina Virtual Java) e o nodetool para gerenciar o cluster. Ferramentas como o cqlsh, que utiliza a compatibilidade binária CQLv4 oferecem suporte.
- O data explorer do portal do Azure, as métricas, os logs de diagnóstico, o PowerShell e a CLI são outros mecanismos compatíveis 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 for Apache Cassandra não funcionarão com as versões DSE (DataStax Enterprise) ou Cassandra 4.0 do CQLSH. Lembre-se de usar apenas as versões v3.11 do Apache Cassandra de software livre do CQLSH ao se conectar à API for Cassandra.
Windows:
- Instale o Python 3
- Instale o 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 a ajuda do pip de comando).
- Instalar o CQLSH usando PIP
pip3 install cqlsh==5.0.3
- Instalar o Python 2
- Execute o CQLSH usando o mecanismo de autenticação.
Observação
Você precisaria 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
Conexão 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
Conexão 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 que são executadas por meio de um SDK compatível com CQL v4, retornarão informações adicionais sobre erros e unidades de 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.
- Observação O valor de gc_grace_seconds deverá ser zero se for 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. O mapeamento de consistência está detalhado aqui.
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 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 o PowerShell, a CLI ou o portal. Para saber mais, confira o artigo como adicionar regiões. 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 com a exceção de 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 de taxa de transferência em 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 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. É possível 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 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 as solicitações no caso de limitação da taxa, são fornecidas as extensões spark e Java. 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
- Introdução à criação de uma conta da API for Cassandra, um banco de dados e uma tabela usando um aplicativo Java