Recursos do Apache Cassandra compatíveis com a API do Cassandra do Azure Cosmos DBApache Cassandra features supported by Azure Cosmos DB Cassandra API

O Azure Cosmos DB é o serviço de banco de dados multimodelo distribuído globalmente da Microsoft.Azure Cosmos DB is Microsoft's globally distributed multi-model database service. Você pode se comunicar com a API do Cassandra do Azure Cosmos DB por meio de drivers de cliente do Cassandra de software livre em conformidade com o protocolo de transmissão do Protocolo Binário v4 da CQL.You can communicate with the Azure Cosmos DB Cassandra API through the CQL Binary Protocol v4 wire protocol compliant open-source Cassandra client drivers.

Ao usar a API do Cassandra do Azure Cosmos DB, você pode aproveitar os benefícios das APIs do Apache Cassandra, bem como as funcionalidades empresariais que o Azure Cosmos DB fornece.By using the Azure Cosmos DB Cassandra API, you can enjoy the benefits of the Apache Cassandra APIs as well as the enterprise capabilities that Azure Cosmos DB provides. 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.The enterprise capabilities include global distribution, automatic scale out partitioning, availability and latency guarantees, encryption at rest, backups, and much more.

Protocolo do CassandraCassandra protocol

A API do Cassandra do Azure Cosmos DB é compatível com a API da CQL (Linguagem de Consulta do Cassandra) v3.11 (compatível com a versão 2.x anterior).The Azure Cosmos DB Cassandra API is compatible with Cassandra Query Language (CQL) v3.11 API (backward-compatible with version 2.x). Os comandos, ferramentas, limitações e exceções do CQL compatíveis estão listados abaixo.The supported CQL commands, tools, limitations, and exceptions are listed below. Qualquer driver de cliente que compreenda esses protocolos deve ser capaz de conectar-se à API do Cassandra do Azure Cosmos DB.Any client driver that understands these protocols should be able to connect to Azure Cosmos DB Cassandra API.

Driver do CassandraCassandra driver

As seguintes versões de drivers Cassandra são compatíveis com a API do Cassandra do Azure Cosmos DB:The following versions of Cassandra drivers are supported by Azure Cosmos DB Cassandra API:

Tipos de dados CQLCQL data types

A API do Cassandra do Azure Cosmos DB é compatível com os seguintes tipos de dados do CQL:Azure Cosmos DB Cassandra API supports the following CQL data types:

ComandoCommand Com suporteSupported
asciiascii SimYes
BIGINTbigint SimYes
blobblob SimYes
booleanoboolean SimYes
contadorcounter SimYes
datedate SimYes
decimaldecimal SimYes
doubledouble SimYes
FLOATfloat SimYes
frozenfrozen SimYes
inetinet SimYes
INTint SimYes
listlist SimYes
setset SimYes
SMALLINTsmallint SimYes
texttext SimYes
timetime SimYes
timestamptimestamp SimYes
timeuuidtimeuuid SimYes
TINYINTtinyint SimYes
tupletuple SimYes
uuiduuid SimYes
varcharvarchar SimYes
varintvarint SimYes
tuplestuples SimYes
udtsudts SimYes
mapmap SimYes

Static tem suporte para a declaração de tipo de dados.Static is supported for data type declaration.

Funções do CQLCQL functions

A API do Cassandra do Azure Cosmos DB é compatível com as seguintes funções do CQL:Azure Cosmos DB Cassandra API supports the following CQL functions:

ComandoCommand Com suporteSupported
Token *Token * SimYes
ttlttl SimYes
writetimewritetime SimYes
Conversãocast NãoNo

* API do Cassandra dá suporte ao token como uma projeção/seletor e só permite token(pk) no lado esquerdo de uma cláusula where.* Cassandra API supports token as a projection/selector, and only allows token(pk) on the left-hand side of a where clause. Por exemplo, WHERE token(pk) > 1024 tem suporte, mas WHERE token(pk) > token(100) não.For example, WHERE token(pk) > 1024 is supported, but WHERE token(pk) > token(100) is not supported.

Funções de agregação:Aggregate functions:

ComandoCommand Com suporteSupported
Minmin SimYes
maxmax SimYes
avgavg SimYes
countcount SimYes

Funções de conversão de blob:Blob conversion functions:

ComandoCommand Com suporteSupported
typeAsBlob(value)typeAsBlob(value) SimYes
blobAsType(value)blobAsType(value) SimYes

Funções UUID e timeuuid:UUID and timeuuid functions:

ComandoCommand Com suporteSupported
dateOf()dateOf() SimYes
now()now() SimYes
minTimeuuid()minTimeuuid() SimYes
unixTimestampOf()unixTimestampOf() SimYes
toDate(timeuuid)toDate(timeuuid) SimYes
toTimestamp(timeuuid)toTimestamp(timeuuid) SimYes
toUnixTimestamp(timeuuid)toUnixTimestamp(timeuuid) SimYes
toDate(timestamp)toDate(timestamp) SimYes
toUnixTimestamp(timestamp)toUnixTimestamp(timestamp) SimYes
toTimestamp(date)toTimestamp(date) SimYes
toUnixTimestamp(date)toUnixTimestamp(date) SimYes

Comandos da CQLCQL commands

O Azure Cosmos DB dá suporte aos seguintes comandos de banco de dados em contas da API do Cassandra.Azure Cosmos DB supports the following database commands on Cassandra API accounts.

ComandoCommand Com suporteSupported
ALLOW FILTERINGALLOW FILTERING SimYes
ALTER KEYSPACEALTER KEYSPACE N/A (serviço PaaS, replicação gerenciada internamente)N/A (PaaS service, replication managed internally)
ALTER MATERIALIZED VIEWALTER MATERIALIZED VIEW NãoNo
ALTER_ROLEALTER ROLE NãoNo
ALTER TABLEALTER TABLE SimYes
ALTER TYPEALTER TYPE NãoNo
ALTER USERALTER USER NãoNo
BATCHBATCH Sim (somente lote não registrado)Yes (unlogged batch only)
COMPACT STORAGECOMPACT STORAGE N/D (serviço PaaS)N/A (PaaS service)
CREATE AGGREGATECREATE AGGREGATE NãoNo
CREATE CUSTOM INDEX (SASI)CREATE CUSTOM INDEX (SASI) NãoNo
CREATE INDEXCREATE INDEX Sim (sem especificar o nome do índice, e não há suporte para os índices em chaves de cluster ou a coleção FROZEN completa)Yes (without specifying index name, and indexes on clustering keys or full FROZEN collection not supported)
CREATE FUNCTIONCREATE FUNCTION NãoNo
CREATE KEYSPACE (configurações de replicação ignorada)CREATE KEYSPACE (replication settings ignored) SimYes
CREATE MATERIALIZED VIEWCREATE MATERIALIZED VIEW NãoNo
CREATE TABLECREATE TABLE SimYes
CREATE TRIGGERCREATE TRIGGER NãoNo
CREATE TYPECREATE TYPE SimYes
CREATE ROLECREATE ROLE NãoNo
CREATE USER (preterido no Apache Cassandra nativo)CREATE USER (Deprecated in native Apache Cassandra) NãoNo
Delete (excluir)DELETE SimYes
DELETE (transações leves com IF CONDITION)DELETE (lightweight transactions with IF CONDITION) SimYes
DISTINTODISTINCT NãoNo
DROP AGGREGATEDROP AGGREGATE NãoNo
.DROP FUNCTIONDROP FUNCTION NãoNo
DROP INDEXDROP INDEX SimYes
DROP KEYSPACEDROP KEYSPACE SimYes
DROP MATERIALIZED VIEWDROP MATERIALIZED VIEW NãoNo
DROP ROLEDROP ROLE NãoNo
DROP TABLEDROP TABLE SimYes
DROP_TRIGGERDROP TRIGGER NãoNo
DROP TYPEDROP TYPE SimYes
DROP USER (preterido no Apache Cassandra nativo)DROP USER (Deprecated in native Apache Cassandra) NãoNo
GRANTGRANT NãoNo
INSERTINSERT SimYes
INSERT (transações leves com IF CONDITION)INSERT (lightweight transactions with IF CONDITION) SimYes
LIST PERMISSIONSLIST PERMISSIONS NãoNo
LIST ROLESLIST ROLES NãoNo
LIST USERS (preterido no Apache Cassandra nativo)LIST USERS (Deprecated in native Apache Cassandra) NãoNo
REVOKEREVOKE NãoNo
SELECTSELECT SimYes
SELECT (transações leves com IF CONDITION)SELECT (lightweight transactions with IF CONDITION) NãoNo
UPDATEUPDATE SimYes
UPDATE (transações leves com IF CONDITION)UPDATE (lightweight transactions with IF CONDITION) NãoNo
TRUNCATETRUNCATE NãoNo
USEUSE SimYes

Suporte a JSONJSON Support

ComandoCommand Com suporteSupported
SELECT JSONSELECT JSON SimYes
INSERT JSONINSERT JSON SimYes
fromJson()fromJson() NãoNo
toJson()toJson() NãoNo

Limites de API do CassandraCassandra API limits

A API do Cassandra do Azure Cosmos DB não tem limites para o tamanho dos dados armazenados em uma tabela.Azure Cosmos DB Cassandra API does not have any limits on the size of data stored in a table. Centenas de terabytes ou petabytes de dados podem ser armazenados, com a garantia de que os limites de chave de partição sejam respeitados.Hundreds of terabytes or Petabytes of data can be stored while ensuring partition key limits are honored. Da mesma forma, todas as entidades ou linhas equivalentes não têm nenhum limite no número de colunas.Similarly, every entity or row equivalent does not have any limits on the number of columns. No entanto, o tamanho total da entidade não deve ultrapassar 2 MB.However, the total size of the entity should not exceed 2 MB. Os dados por chave de partição não podem exceder 20 GB, como em todas as outras APIs.The data per partition key cannot exceed 20 GB as in all other APIs.

FerramentasTools

A API do Cassandra do Azure Cosmos DB é uma plataforma de serviço gerenciado.Azure Cosmos DB Cassandra API is a managed service platform. Ela 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.It does not require any management overhead or utilities such as Garbage Collector, Java Virtual Machine(JVM), and nodetool to manage the cluster. Ela dá suporte a ferramentas como o cqlsh, que utiliza a compatibilidade binária CQLv4.It supports tools such as cqlsh that utilizes Binary CQLv4 compatibility.

  • 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.Azure portal's data explorer, metrics, log diagnostics, PowerShell, and CLI are other supported mechanisms to manage the account.

Shell CQL hospedado (versão prévia)Hosted CQL shell (preview)

Você pode abrir um shell Cassandra nativo hospedado (CQLSH v5.0.1) diretamente do Data Explorer no portal do Azure ou no Azure Cosmos Explorer.You can open a hosted native Cassandra shell (CQLSH v5.0.1) directly from the Data Explorer in the Azure portal or the Azure Cosmos explorer. Antes de habilitar o shell CQL, você deve habilitar o recurso Notebooks em sua conta (se ainda não estiver habilitado, será solicitado ao clicar em Open Cassandra Shell).Before enabling the CQL shell, you must enable the Notebooks feature in your account (if not already enabled, you will be prompted when clicking on Open Cassandra Shell). Marque a nota destacada em Habilitar notebooks para as contas Azure Cosmos DB para as Regiões do Azure.Check the highlighted note in Enable notebooks for Azure Cosmos DB accounts for supported Azure Regions.

Abrir CQLSH

Você também pode conectar a API do Cassandra no Azure Cosmos DB usando o CQLSH instalado em um computador local.You can also connect to the Cassandra API in Azure Cosmos DB by using the CQLSH installed on a local machine. Ele vem com o Apache Cassandra 3.1.1 e fica pronto para o uso definindo as variáveis de ambiente.It comes with Apache Cassandra 3.1.1 and works out of the box by setting the environment variables. As seções a seguir incluem instruções para instalar, configurar e conectar a API do Cassandra no Azure Cosmos DB, no Windows ou no Linux usando o CQLSH.The following sections include the instructions to install, configure, and connect to Cassandra API in Azure Cosmos DB, on Windows or Linux using CQLSH.

Observação

As conexões com a API do Cassandra do Azure Cosmos DB não funcionarão com as versões DSE (DataStax Enterprise) do CQLSH.Connections to Azure Cosmos DB Cassandra API will not work with DataStax Enterprise (DSE) versions of CQLSH. Lembre-se de usar apenas as versões do Apache Cassandra de software livre do CQLSH ao se conectar à API do Cassandra.Please ensure you use only the open source Apache Cassandra versions of CQLSH when connecting to Cassandra API.

Windows:Windows:

se estiver usando o Windows, recomendamos que você habilite o sistema de arquivos do Windows para Linux.If using windows, we recommend you enable the Windows filesystem for Linux. Em seguida, você pode seguir os comandos do Linux abaixo.You can then follow the linux commands below.

UNIX/Linux/Mac: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 http://www.apache.org/dist/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

# Export the SSL variables:
export SSL_VERSION=TLSv1_2
export SSL_VALIDATE=false

# Connect to Azure Cosmos DB API for Cassandra:
cqlsh <YOUR_ACCOUNT_NAME>.cassandra.cosmosdb.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.All CRUD operations that are executed through a CQL v4 compatible SDK will return extra information about error and request units consumed. 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.The DELETE and UPDATE commands should be handled with resource governance taken into consideration, to ensure the most efficient use of the provisioned throughput.

  • Observação O valor de gc_grace_seconds deverá ser zero se for especificado.Note gc_grace_seconds value must be zero if specified.
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ênciaConsistency mapping

A API do Cassandra do Azure Cosmos DB fornece a opção de consistência para operações de leitura.Azure Cosmos DB Cassandra API provides choice of consistency for read operations. O mapeamento de consistência está detalhado aqui.The consistency mapping is detailed here.

Gerenciamento de funções e de permissõesPermission and role management

O Azure Cosmos DB dá suporte ao controle de acesso baseado em função (RBAC) para provisionamento, revezamento de chaves, visualização de métricas e senhas/chaves de leitura/gravação e somente leitura que podem ser obtidas por meio do portal do Azure.Azure Cosmos DB supports role-based access control (RBAC) for provisioning, rotating keys, viewing metrics and read-write and read-only passwords/keys that can be obtained through the Azure portal. O Azure Cosmos DB não dá suporte a funções para atividades CRUD.Azure Cosmos DB does not support roles for CRUD activities.

Opções de tabela e de keyspaceKeyspace and Table options

As opções para nome da região, classe, replication_factor e datacenter no comando "CREATE KEYSPACE" são ignoradas atualmente.The options for region name, class, replication_factor, and datacenter in the "Create Keyspace" command are ignored currently. O sistema usa o método de replicação de distribuição global subjacente do Azure Cosmos DB para adicionar as regiões.The system uses the underlying Azure Cosmos DB's global distribution replication method to add the regions. 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.If you need the cross-region presence of data, you can enable it at the account level with PowerShell, CLI, or portal, to learn more, see the how to add regions article. Durable_writes não podem ser desabilitadas porque o Azure Cosmos DB garante que cada gravação seja durável.Durable_writes can't be disabled because Azure Cosmos DB ensures every write is durable. 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.In every region, Azure Cosmos DB replicates the data across the replica set that is made up of four replicas and this replica set configuration can't be modified.

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.All the options are ignored when creating the table, except gc_grace_seconds, which should be set to 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.The Keyspace and table have an extra option named "cosmosdb_provisioned_throughput" with a minimum value of 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.The Keyspace throughput allows sharing throughput across multiple tables and it is useful for scenarios when all tables are not utilizing the provisioned throughput. O comando ALTER TABLE permite alterar a taxa de transferência provisionada entre as regiões.Alter Table command allows changing the provisioned throughput across the regions.

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árioSecondary Index

A API do Cassandra dá suporte a índices secundários em todos os tipos de dados, exceto tipos de coleção frozen, tipos variante e decimal.Cassandra API supports secondary indexes on all data types except frozen collection types, decimal and variant types.

Uso da política de nova tentativa de conexão do CassandraUsage of Cassandra retry connection policy

O Azure Cosmos DB é um sistema controlado por recursos.Azure Cosmos DB is a resource governed system. Isso significa que 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.This means you can do a certain number of operations in a given second based on the request units consumed by the operations. Se um aplicativo exceder esse limite em um determinado segundo, as solicitações serão limitadas por taxa e exceções serão geradas.If an application exceeds that limit in a given second, requests are rate-limited and exceptions will be thrown. A API do Cassandra do Azure Cosmos DB converte essas exceções em erros de sobrecarga no protocolo nativo do Cassandra.The Cassandra API in Azure Cosmos DB translates these exceptions to overloaded errors on the Cassandra native protocol. 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.To ensure that your application can intercept and retry requests in case of rate limitation, the spark and the Java extensions are provided. Consulte também exemplos de código Java dos drivers Datastax versão 3 e versão 4 ao conectar a API do Cassandra no Azure Cosmos DB.See also Java code samples for version 3 and version 4 Datastax drivers, when connecting to Cassandra API in Azure Cosmos DB. Se você usar outros SDKs para acessar API do Cassandra no Azure Cosmos DB, crie uma política de conexão para tentar novamente ao encontrar essas exceções.If you use other SDKs to access Cassandra API in Azure Cosmos DB, create a connection policy to retry on these exceptions.

Próximas etapasNext steps