Tutorial: Migrar seus dados para uma API para a conta Cassandra

2025-07-08

APLICA-SE A: Cassandra

Como desenvolvedor, você pode ter cargas de trabalho Cassandra existentes que estão sendo executadas no local ou na nuvem. Talvez você queira migrá-los para o Azure. Você pode migrar essas cargas de trabalho para uma API para a conta Cassandra no Azure Cosmos DB. Este tutorial fornece instruções sobre diferentes opções disponíveis para migrar dados do Apache Cassandra para a API da conta Cassandra no Azure Cosmos DB.

Este tutorial abrange as seguintes tarefas:

Planejar a migração.
Atender aos pré-requisitos para migração.
Migre dados usando o cqlshCOPY comando.
Migre dados usando o Spark.

Se não tiver uma subscrição do Azure, crie uma conta gratuita antes de começar.

Pré-requisitos de migração

Estime suas necessidades de taxa de transferência: Antes de migrar dados para a API da conta Cassandra no Azure Cosmos DB, estime as necessidades de taxa de transferência da sua carga de trabalho. Em geral, comece com a taxa de transferência média exigida pelas operações de criação, leitura, atualização e exclusão (CRUD). Inclua então a largura de banda extra necessária para as operações de extração, transformação e carga (ETL) ou operações flutuantes. Precisa dos seguintes detalhes para planear a migração:
- Tamanho dos dados existentes ou o tamanho estimado dos dados: define o requisito de tamanho e débito de base de dados mínimos. Se você estimar o tamanho dos dados para um novo aplicativo, poderá supor que os dados estejam distribuídos uniformemente pelas linhas. Você pode estimar o valor multiplicando pelo tamanho dos dados.
- Taxa de transferência necessária: taxa de transferência aproximada das operações de leitura (consulta/obter) e gravação (atualização/exclusão/inserção). Esse valor é necessário para calcular as unidades de solicitação necessárias, juntamente com o tamanho dos dados em estado estacionário.
- O esquema: Conecte-se ao cluster Cassandra existente através cqlshdo e exporte o esquema de Cassandra:
```
cqlsh [IP] "-e DESC SCHEMA" > orig_schema.cql
```
  Depois de identificar os requisitos de sua carga de trabalho existente, crie uma conta, um banco de dados e contêineres do Azure Cosmos DB de acordo com os requisitos de taxa de transferência coletados.
- Determine a cobrança da unidade de solicitação (RU) para uma operação: Você pode determinar as RUs usando qualquer um dos SDKs suportados pela API para Cassandra. Este exemplo mostra a versão do .NET dos encargos de obter RU.
```
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}");
  }
```
Alocar o débito necessário: o Azure Cosmos DB pode dimensionar automaticamente o armazenamento e débito à medida que os requisitos aumentam. Você pode estimar suas necessidades de taxa de transferência usando a calculadora RU do Azure Cosmos DB.
Crie tabelas na API para a conta Cassandra: Antes de começar a migrar dados, pré-crie todas as suas tabelas a partir do portal do Azure ou do cqlsh. Se você estiver migrando para uma conta do Azure Cosmos DB que tenha taxa de transferência no nível de banco de dados, forneça uma chave de partição ao criar os contêineres.
Aumentar o débito: a duração da migração de dados depende da quantidade de débito que aprovisionou para as tabelas no Azure Cosmos DB. Aumente a taxa de transferência durante a migração. Com uma maior taxa de transferência, pode evitar a limitação de velocidade e migrar em menos tempo. Depois de concluir a migração, diminua a taxa de transferência para reduzir custos. Também recomendamos que você tenha a conta do Azure Cosmos DB na mesma região do banco de dados de origem.
Habilite o TLS (Transport Layer Security): O Azure Cosmos DB tem requisitos e padrões de segurança rigorosos. Habilite o TLS quando interagir com sua conta. Ao usar a Cassandra Query Language (CQL) com Secure Shell, você pode fornecer informações TLS.

Opções de migração de dados

Você pode mover dados de cargas de trabalho Cassandra existentes para o Azure Cosmos DB usando o cqlshCOPY comando ou o Spark.

Migrar dados usando o comando cqlsh COPY

Aviso

Use apenas o comando CQL COPY para migrar pequenos conjuntos de dados. Para mover grandes conjuntos de dados, migre dados usando o Spark.

Para ter certeza de que seu arquivo .csv contém a estrutura de arquivo correta, use o COPY TO comando para exportar dados diretamente da tabela Cassandra de origem para um arquivo .csv. cqlsh Verifique se está conectado à tabela de origem usando as credenciais apropriadas.
```
COPY exampleks.tablename TO 'data.csv' WITH HEADER = TRUE;   
```
Agora obtenha as informações da cadeia de conexão da sua API para a conta Cassandra:
1. Entre no portal do Azure e vá para sua conta do Azure Cosmos DB.
2. Abra o painel Cadeia de Conexão . Aqui você vê todas as informações que você precisa para se conectar à sua API para a conta Cassandra de cqlsh.
Inicie sessão em cqlsh utilizando as informações de conexão fornecidas pelo portal do Azure.
Use o comando CQL COPY FROM para copiar data.csv. Este arquivo ainda está localizado no diretório raiz do usuário onde cqlsh está instalado.
```
COPY exampleks.tablename FROM 'data.csv' WITH HEADER = TRUE;
```

Nota

A API para Cassandra suporta o protocolo versão 4, que foi fornecido com Cassandra 3.11. Pode haver problemas se você usar versões posteriores do protocolo com nossa API. Com uma versão de protocolo posterior, o COPY FROM comando pode entrar em um loop e retornar linhas duplicadas.

Adicione protocol-version ao cqlsh comando:

cqlsh <USERNAME>.cassandra.cosmos.azure.com 10350 -u <USERNAME> -p <PASSWORD> --ssl --protocol-version=4

Adicionar opções de limitação de taxa de transferência ao comando CQL COPY

O COPY comando em cqlsh oferece suporte a vários parâmetros para controlar o ritmo de ingestão de documentos no Azure Cosmos DB.

A configuração padrão para o COPY comando tenta ingerir dados em um ritmo rápido. Ele não leva em conta o comportamento de limitação de taxa do Azure Cosmos DB. Reduza CHUNKSIZE ou INGESTRATE dependendo da taxa de transferência configurada na coleção.

Recomendamos a seguinte configuração (no mínimo) para uma coleção em 20.000 RUs se o tamanho do documento ou registro for de 1 KB:

CHUNKSIZE = 100
INGESTRATE = 500
MAXATTEMPTS = 10

Comandos de exemplo

Copie dados da API para Cassandra para um arquivo .csv local:

COPY standard1 (key, "C0", "C1", "C2", "C3", "C4") TO 'backup.csv' WITH PAGESIZE=100 AND MAXREQUESTS=1 ;

Copie dados de um arquivo .csv local para a API do Cassandra:

COPY standard2 (key, "C0", "C1", "C2", "C3", "C4") FROM 'backup.csv' WITH CHUNKSIZE=100 AND INGESTRATE=100 AND MAXATTEMPTS=10;

Importante

Apenas a versão de código aberto do Apache Cassandra é suportada CQLSH COPY . As versões do CQLSH Datastax Enterprise (DSE) podem encontrar erros.

Migrar dados utilizando o Spark

Para migrar dados para a API da conta Cassandra com o Spark, siga estas etapas:

Provisione um cluster do Azure Databricks ou um cluster do Azure HDInsight.
Mova dados para a API de destino do ponto de extremidade Cassandra. Para obter mais informações, consulte Migrar dados de Cassandra para uma conta do Azure Cosmos DB para Apache Cassandra.

Se você tiver dados que residem em um cluster existente em máquinas virtuais do Azure ou em qualquer outra nuvem, recomendamos que use trabalhos do Spark para migrar os dados. Configure o Spark como intermediário para ingestão única ou regular. Você pode acelerar essa migração usando a conectividade do Azure ExpressRoute entre seu ambiente local e o Azure.

Migração em direto

Se você precisar de uma migração sem tempo de inatividade de um cluster Apache Cassandra nativo, recomendamos configurar gravações duplas e uma carga de dados em massa separada para migrar dados históricos. A implementação desse padrão é mais simples quando você usa um proxy de gravação dupla de código aberto para permitir alterações mínimas no código do aplicativo. Para obter mais informações, consulte Migrar dados ao vivo do Apache Cassandra para o Azure Cosmos DB para Apache Cassandra.

Clean up resources (Limpar recursos)

Quando os recursos não forem mais necessários, você poderá excluir o grupo de recursos, a conta do Azure Cosmos DB e todos os recursos relacionados. Para fazer isso, selecione o grupo de recursos para a máquina virtual, selecione Excluir e confirme o nome do grupo de recursos a ser excluído.

Próximo passo

Neste tutorial, você aprendeu como migrar seus dados para uma API para a conta Cassandra no Azure Cosmos DB. Agora você pode aprender sobre outros conceitos no Azure Cosmos DB:

Tunable data consistency levels in Azure Cosmos DB (Níveis de consistência de dados ajustáveis no Azure Cosmos DB)