Skip to main content

Carol In Memory

O Carol In Memory é uma aplicação de extração e envio de dados da plataforma Carol para o MotherDuck, utilizando BigQuery e Cloud Storage. O projeto é encapsulado como um Carol App, permitindo agendamento de execuções e facilitando a distribuição para clientes da plataforma TOTVS Carol. A utilização do MotherDuck foi escolhida pela facilidade em prover alternativas de Analytics aos usuários.

Fluxo do Processo​

A seguir, é apresentado o fluxo geral da aplicação Carol In Memory:

  1. BigQuery Entities – As entidades (queries) configuradas são executadas diretamente no projeto em que o app está instalado.
  2. GCS Export Job – O resultado das queries é exportado como arquivos .parquet para um bucket do Google Cloud Storage.
  3. MotherDuck – Os arquivos parquet são importados para o Motherduck utilizando CREATE TABLE AS SELECT FROM parquet.
  4. MotherDuck – Os dados são persistidos no banco de dados configurado no MotherDuck.

Parâmetros de Configuração​

Load Strategy (STRING)​

Define a estratégia de carga:

  • FULL_LOAD: Executa uma carga completa, removendo todo o histórico de dados e carregando novamente.
  • INCREMENTAL: Executa a carga completa, porém não removendo todo o histórico de dados. A lógica incremental deve ser implementada na query no parâmetro entities.

Slack Webhook URL (STRING)​

Webhook para notificação de falhas ou erros de execução via Slack. Exemplo:

https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX

Use Flight Server (BOOLEAN)​

Define se será utilizado o Flight Server embutido do Carol App para conexão com ferramentas como o Looker Studio:

  • true: ativa o servidor para exposição dos dados.
  • false: padrão, não utiliza o Flight Server.
Importante

Observação: Este recurso ainda está em desenvolvimento!

Data Entities​

Entities (STRING)​

JSON com as queries que serão exportadas. Exemplo:

{
  "shd_ViewsAnalytics": "SELECT * FROM shd_ViewsAnalytics WHERE date >= CURRENT_DATE() - 7",
  "shd_Orders": "SELECT id, total, customer FROM shd_Orders"
}

Cada chave representa o nome da entidade no destino MotherDuck, e o valor é a query SQL executada no BigQuery.

Load All Tables (BOOLEAN)​

Se ativado (true), ignora o campo Entities e extrai todas as tabelas do projeto Carol, incluindo:

  • Tabelas de ingestão (staging)
  • Tabelas de datamodels
  • Tabelas compartilhadas e personalizadas

MotherDuck​

MotherDuck Database (STRING)​

Nome do banco de dados padrão para conexão no MotherDuck. Exemplo:

meu_banco_padrao
Importante

Em todos os casos de implementação, o banco de dados padrão deve existir. Porém, os dados sempre serão exportados para um banco de dados que será criado em tempo de execução, de nome o Id da tenant que está executando o processo.

Motherduck Databases

MotherDuck Token (STRING)​

Token com permissão de leitura e escrita no MotherDuck. Deve ser gerado na interface do MotherDuck e informado no campo. Exemplo (truncado):

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Observação: É necessário possuir uma conta e instância ativas no MotherDuck para utilizar esse recurso.

Execução remota via API e acionamento sob demanda​

É possível realizar uma execução remota do Processo do Carol App, podendo dinâmicamente apontar tabelas ou queries a serem exportadas para o MotherDuck. Esse procedimento é útil quando queremos sincronizar parte das tabelas de um ambiente, não precisando ajustar o parâmetro entities ou load all tables.

Para isso, é necessário utilizar a API da plataforma Carol abaixo, com método POST.

curl -X 'POST' \
  'https://api.carol.ai/api/v3/tasks/new' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer TOKEN' \
  -d '{[...]}'

O body a ser enviado é o abaixo, onde está sinalizado o que deve ser alterado para cada execução. Os Ids informados na requisição são obtíveis por meio da interface da plataforma Carol ou pelas API disponibilizadas.

{
  "mdmData": {
    "mdmResourcesCleanUp": false, 
    "mdmAiAlgorithmName": "inmemoryexport",
    "mdmAiProcessName": "Carol_In_Memory_Export",
    "mdmAppSettingsOverride": {
      "MOTHERDUCK_TOKEN": "XYZ", <-- Adicionar o seu token MotherDuck.
      "entities": "{\"TEST\": \"SELECT * FROM `carol-XYZ.XYZXPTO`.`minha_tabela`\"}" <-- Adicionar as entidades a serem exportadas.
    },
    "mdmAiProcessId": "7959d113dc0f419dbb286z85878603a7",  <-- Inserir o AI Process Id real da tenant que irá processar a requisição.
    "mdmTenantId": "3c79b6af74e4481db019b32e1a3bfbt6",  <-- Inserir Tenant Id real da tenant que irá processar a requisição.
    "mdmName": "carolinmemory",
    "mdmAiProcessType": "BATCH",
    "mdmTenantAppId": "129eb2dc9d514f40a5bd7891dff374c6"  <-- Inserir o App Id real da tenant que irá processar a requisição.
  },
  "mdmEntityType": "mdmTask",
  "mdmTaskLevel": "mdmTenant",
  "mdmTaskType": "AI_PROCESS",
  "mdmTenantId": "3c79b6af74e4481db019b32e1a3bfbt6"  <-- Inserir Tenant Id real da tenant que irá processar a requisição.
}