Uma das muitas vantagens de usar um banco de dados baseado em documentos, como o Couchbase, é a capacidade de usar um modelo de dados flexível para armazenar dados sem as restrições de um esquema rígido e predeterminado. Muitos clientes escolhem um banco de dados NoSQL para suportar a ingestão de dados de várias fontes. Mas e se você precisar que seus dados sejam transformados para que correspondam aos dados existentes? Talvez você precise de todos eles em um formato uniforme para fins de relatório. Seja qual for o motivo, esse é um uso perfeito para o Serviço de eventos no Couchbase.
Serviço de eventos do Couchbase
O serviço de eventos é um recurso interno do Couchbase Enterprise Edition que permite a aplicação de funções JavaScript, ou lambdasque respondem a eventos de mutação. Sempre que um documento é criado, modificado ou excluído, uma ação pode ser executada por execução de lógica comercial pura em seu JavaScript. Há várias ações que podem ser executadas, como enriquecimento de dados, chamada de fluxos de trabalho externos (por meio de chamadas à API RESTful) e eventos baseados em cronômetro (retomada da execução no futuro). Pense nos eventos como um banco de dados legado pósgatilho com esteroides.
Consolidação de dados
Neste exemplo simplificado, imagine que você acabou de adquirir duas novas fontes de dados de clientes. Esses dados podem ser provenientes de uma fonte normalizada, de um arquivo simples ou de ambos, e você deseja que esses dados correspondam aos dados de clientes existentes armazenados em um formato desnormalizado.
A primeira fonte de dados é um banco de dados normalizado (limpo e preciso) contendo clientes no Canadá. Cada registro de cliente aponta para um endereço de cobrança e um endereço de entrega, e cada endereço é normalizado para eliminar a redundância de dados de cidade e província:
A segunda fonte de dados é um arquivo simples que também contém clientes canadenses, mas que não rastreia endereços de cobrança e de envio separados. Como você pode ver, apenas um único elemento de dados de endereço é armazenado no registro do cliente:
Precisamos transformar esses dados à medida que eles chegam para que correspondam ao nosso banco de dados de clientes existente, que é desnormalizado, de modo que os endereços de cobrança e envio sejam anexados aos dados do cliente (da segunda fonte) como subdocumentos:
Vamos começar com fácil A primeira solução é a importação de arquivos simples. O processo de transformação desses dados envolve a cópia dos dados do cliente (nome, e-mail, telefone, nome da empresa) em um novo documento. Em seguida, os dados de endereço precisam ser copiados em subdocumentos para os endereços de faturamento e de correspondência. Como temos apenas um endereço por cliente, copiaremos esse endereço para o subdocumento de endereço de faturamento e de correspondência:
Código JavaScript para consolidar as tabelas
O código do Eventing para realizar isso é bastante simples:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 |
1 função Sobre a atualização(doc, meta) { 2 const novo_doc = {}; // Novo documento do cliente 3 const endereço = {}; // Novo documento de endereço 4 5 novo_doc['first_name'] = doc.primeiro_nome; 6 novo_doc['last_name'] = doc.sobrenome; 7 novo_doc['email'] = doc.e-mail; 8 novo_doc['telefone'] = doc.telefone; 9 novo_doc['company_name'] = doc.nome_da_empresa; 10 11 endereço['street_address_1'] = doc.street_address_1; 12 endereço['street_address_2'] = doc.street_address_2; 13 endereço['cidade'] = doc.cidade; 14 endereço["estado] = doc.província; 15 endereço['zip_code'] = doc.código postal; 16 17 // Adicionar documento de endereço ao documento do cliente como subdocumentos 18 novo_doc['billing_address'] = endereço; 19 novo_doc['mailing_address'] = endereço; 20 21 // Isso cria o novo documento no bucket de destino 22 dest_bkt[doc.e-mail] = novo_doc; 23 24 // Excluir o documento original - descomente abaixo 25 // excluir sch2[meta.id]; 26 27 registro("Doc created/updated" (Documento criado/atualizado), meta.id); 28 } |
O código acima deve ser fácil de entender, mesmo para programadores que não trabalham com JavaScript, mas vou dividi-lo por seção para ter certeza.
-
- Linha 1 acima é chamado sempre que um documento no compartimento de origem sofre mutação (é criado ou modificado). Veremos a seguir como definimos o compartimento de origem.
- As linhas 2 a 3 criam objetos JavaScript para manter o novo documento do cliente e o documento de endereço que serão usados como subdocumentos dentro do documento do cliente.
- Linhas 5-15 copiar as propriedades do documento original para os objetos de cliente e endereço.
- Linhas 18 e 19 atribuir o documento de endereço como subdocumentos do cliente para as propriedades de endereço de correspondência e de faturamento.
- Linha 22 realmente cria o documento no bucket de destino do Couchbase. Veremos a seguir como definimos o bucket de destino.
- Finalmente, linha 25 excluirá o documento original, embora ele esteja comentado aqui.
- Linha 27 registra a operação. Talvez você queira comentar/remover isso após o teste.
Configurar o ambiente
Para testar esse script, precisaremos configurar nosso ambiente do Couchbase. Em primeiro lugar, precisaremos de um cluster do Couchbase que execute o serviço de dados e o serviço de eventos. Ele pode ser pequeno, como um cluster de nó único em execução no Docker, ou um cluster maior de vários nós em execução no Capella.
Quando o cluster estiver em funcionamento, precisaremos criar os buckets para importar dados e um bucket de destino final. O serviço de eventos também requer um bucket de metadados. Crie os quatro buckets a seguir, cada um com a cota mínima exigida de 100 MB:
-
- esquema1
- esquema2
- cliente
- eventing_merge
Também recomendo ativar descarga para este exercício.
Criação de uma função de eventos
Agora precisamos criar a função de eventos. Selecione a função eventos e, em seguida, clique em Adicionar função. Use as seguintes configurações:
Em seguida, clique em Próximo: Adicionar código e substitua o padrão Sobre a atualização com o código acima. Clique em Salvar e Retorno. Neste ponto, o código foi armazenado, mas a função precisa ser implementada para que possa começar a processar os dados. Clique no nome da função para abrir suas configurações e implemente a função agora.
Criação de documentos JSON de teste
Agora, vamos testá-lo criando um documento na pasta esquema2 balde. Adicione um documento usando wile.e.coyote@acmecorp.com como a chave do documento e com o seguinte corpo de documento:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
{ "customer_id": nulo, "first_name": "Wile", "middle_name": "E", "last_name": "Coiote", "email": "wile.e.coyote@acmecorp.com", "título": "Gênio", "company_name": "Acme Corporation", "telefone": "123-555-1212", "street_address_1": "694 York Circle", "street_address_2": "", "cidade": "Hackettstown", "província": "NJ", "postal_code": "07840" } |
Em instantes, você verá que as estatísticas do evento indicam sucesso:
Agora dê uma olhada no cliente e você verá que o documento acima foi transformado. Observe como o endereço agora existe como subdocumentos dentro das propriedades endereço de cobrança e endereço de correspondência:
Transformação em subdocumentos
Agora vamos abordar a transformação mais complexa do esquema. A migração da estrutura relacional para corresponder à nossa estrutura de subdocumento é mais ou menos assim:
Precisaremos desnormalizar as tabelas de endereço e código postal em um único subdocumento, um para cada endereço de remessa/correio e outro para o endereço de cobrança. Nesse caso, os dados das três tabelas são armazenados em coleções dentro do bucket.
Código JavaScript para desnormalização
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 |
1 função Sobre a atualização(doc, meta) { 2 deixar novo_doc = {}; 3 deixar endereço da conta = {}; 4 deixar mail_addr = {}; 5 6 novo_doc['first_name'] = doc.primeiro_nome; 7 novo_doc['last_name'] = doc.sobrenome; 8 novo_doc['email'] = doc.e-mail; 9 novo_doc['telefone'] = doc.telefone; 10 novo_doc['company_name'] = doc.nome_da_empresa; 11 12 endereço da conta = bkt_addr[doc.billing_address_id]; 13 mail_addr = bkt_addr[doc.shipping_address_id]; 14 15 endereço da conta['cidade'] = bkt_pc[bkt_addr[doc.billing_address_id].código postal].cidade; 16 mail_addr['cidade'] = bkt_pc[bkt_addr[doc.shipping_address_id].código postal].cidade; 17 18 endereço da conta["estado] = bkt_pc[bkt_addr[doc.billing_address_id].código postal].província; 19 mail_addr["estado] = bkt_pc[bkt_addr[doc.shipping_address_id].código postal].província; 20 21 novo_doc['billing_address'] = endereço da conta; 22 novo_doc['mailing_address'] = mail_addr; 23 24 registro(novo_doc); 25 26 dest_bkt[doc.e-mail] = novo_doc; 27 28 // Excluir cliente existente (deixar endereço/código postal para outros clientes que compartilham isso) 29 // excluir bkt_cust[meta.id]; 30 registro("Doc created/updated" (Documento criado/atualizado), meta.id); 31 } |
Vamos decompor esse código novamente como antes.
-
- Linhas 2-4 criar objetos JavaScript para armazenar o novo documento, bem como os subdocumentos para os endereços de correspondência e de cobrança.
- Linhas 6-10 copie as propriedades do contato para o novo documento.
- Linhas 12 e 13 copie os dados de endereço da coleção de endereços usando a chave de documento armazenada na propriedade address_id do contato.
- Linhas 15-19 extrai os dados da cidade e da província da coleção de províncias, usando o province_id do documento de endereço como a chave do documento.
- Linhas 21 e 22 em seguida, anexe esses objetos de documento como subdocumentos ao novo documento de contato.
- Finalmente, linha 26 grava o novo documento no bucket de destino.
- Linha 29se não for comentado, excluirá o documento original do contato do bucket de origem. Observe que não queremos excluir também os documentos de endereço e província associados, pois eles podem ser usados por outros contatos.
Criação da função de eventos para desnormalização
Crie essa função de evento usando as seguintes configurações e cole o código acima para substituir o Sobre a atualização função. Quando terminar, vá em frente e implemente a função.
Para testar essa função, precisaremos criar coleções no esquema1 (use o padrão ) com os nomes: endereços, clientes, códigos postais. Em seguida, crie os seguintes documentos (nesta ordem, caso contrário, as pesquisas na função falharão):
Códigos postais com a ID do documento 43062:
|
1 2 3 4 5 |
{ "postal_code": "43062", "cidade": "Pataskala", "província": "OH" } |
Códigos postais com a ID do documento 23228:
|
1 2 3 4 5 |
{ "postal_code": "23228", "cidade": "Henrico", "província": "VA" } |
Endereços com a ID do documento 000071:
|
1 2 3 4 5 6 |
{ "address_id": "000071", "street_address_1": "85 Hartford Road", "street_address_2": "", "postal_code": "23228" } |
Endereços com a ID do documento 000086:
|
1 2 3 4 5 6 |
{ "address_id": "000086", "street_address_1": "460 Broad Dr.", "street_address_2": "", "postal_code": "43062" } |
Por fim, no clientes com a ID do documento blinded_by@science.com:
|
1 2 3 4 5 6 7 8 9 10 11 12 |
{ "customer_id": nulo, "first_name": "Thomas", "middle_name": nulo, "last_name": "Dolby", "email": "blinded_by@science.com", "título": nulo, "telefone": "867-5309", "billing_address_id": "000086", "shipping_address_id": "000071", "company_name": "A era de ouro da tecnologia sem fio" } |
Em pouco tempo, você verá que as estatísticas dessa função são bem-sucedidas:
E se você observar o documento no compartimento de clientes, verá a seguinte transformação com os dois endereços desnormalizados em subdocumentos.
Considerações finais
Este é um exemplo muito simplista. Em um ambiente de produção, você provavelmente adicionará código para tratar exceções.
Além disso, você pode aumentar o número de workers de 1 para o número de vCPUs se tiver um conjunto de dados grande e precisar de mais desempenho.
As funções de eventos usadas neste blog podem ser encontradas no seguinte repositório do github: https://github.com/djames42/cb_eventing_merge. Nesse repositório, há também alguns scripts (um script Bash e um script Python) que podem ser usados para criar um cluster de nó único com as funções de eventos e conjuntos de dados de amostra maiores pré-carregados.
Recursos
-
- Download: Baixar o Couchbase Server 7.1
- GitHub: https://github.com/djames42/cb_eventing_merge.
Referências
