Carol

Árvore de páginas

A plataforma Carol permite habilitar o recurso SQL para acessar os dados disponíveis na camada de armazenamento Carol Data Storage (CDS). Nesta documentação será apresentado como efetuar a habilitação deste recurso.

Índice


Visão Geral


A plataforma Carol permite habilitar o recurso de acesso aos dados armazenados na camada CDS através da linguagem SQL. Este recurso permite a exploração dos dados utilizando recursos ligados ao SQL, para maiores detalhes quanto aos recursos disponíveis, consulta a documentação do Presto: https://prestodb.io/docs/current/sql.html.

É importante destacar que os dados armazenados na camada CDS são dados imutáveis. Desta forma, quando um registro recebe uma nova versão, ele será armazenado em duplicidade até que o Data Model ou Staging Table seja consolidado.

Enquanto o Data Model ou a Staging Table não é consolidada, é possível efetuar a consulta consolidando os dados em tempo de query, fazendo com que a aplicação que consome esses dados não sofra impactos.

Alguns pontos adicionais que devem ser considerados:

  • Se os dados não estiverem consolidados poderá haver resultados duplicados. Válido apenas para dados que sofrem alteração (mutáveis).
  • Por questões de performance, os Data Models e/ou Staging Tables devem ser compactados frequentemente. A compactação hoje ocorre em conjunto com a task de consolidação de um Data Model ou Staging Table.
  • Atributos nested possuem processo de consulta mais complexo e são mais lentos para efetuar consultas.
  • Alteração de schema requer que o Data Model ou a Staging Table seja consolidado e o schema SQL seja recriado. Hoje esse processo ainda é manual.
  • Durante o processo de consolidação consultas como count(*) podem flutuar e retornar um valor acima do correto. A solução para essa situação é utilizar a consolidação em momento de query.



Habilitando acesso SQL à um ambiente/tenant

O primeiro passo é a criação de um token de autenticação, dessa forma você poderá chamar os endpoints necessários para habilitar o acesso SQL no ambiente. Este processo é descrito neste capítulo: 2. Autenticação.

Após possuir um token de autenticação, você pode executar os passos para habilitar o acesso SQL:


Habilitando SQL ambiente
curl 'https://api.carol.ai/api/v1/admin/tenants/4c2c9090e7c611e893bf0e900682978b' -X PUT -H 'accept: application/json' -H 'content-type: application/json' -H 'authorization: TOKEN_AQUI' --data-binary '{"mdmSQLonCDSEnabled":"true"}'


Para validar se o ambiente possui o SQL habilitado, você pode executar o comando abaixo:

curl 'https://api.carol.ai/api/v2/tenants/domain/clockin' -H 'accept: application/json' -H 'content-type: application/json'


Obs.: Substitua `clockin` pelo nome do seu ambiente.


A response é algo conforme abaixo:


{
"mdmAllowSmsLogin": false,
"mdmAllowSmsUsage": false,
"mdmCarolCustomerCode": "TOTVSRH",
"mdmCreated": "2018-11-14T04:32:52.499Z",
"mdmCreatedUser": "",
"mdmDataDecorationEnabled": false,
"mdmDescription": {
"en-US": "services-rh-product"
},
"mdmEnableAddressCleansing": true,
"mdmEnableSSO": false,
"mdmEntityType": "mdmTenant",
"mdmExternalLoginConfiguration": {},
"mdmId": "4c2c9090e7c611e893bf0e900682978b",
"mdmIsPublicData": false,
"mdmLabel": {
"en-US": "clockin"
},
"mdmLastUpdated": "2021-06-13T19:23:15.800Z",
"mdmLocale": "pt-BR",
"mdmMappingsPending": false,
"mdmName": "clockin",
"mdmOrgId": "d541c79d98344e7ca15c2bff90c5d71f",
"mdmProcessingPriority": 0,
"mdmQueueSuffix": "",
"mdmRealtimeDisabled": true,
"mdmSQLonCDSEnabled": true,
"mdmSendEmailSmsCode": false,
"mdmSmsProvider": "TWILIO",
"mdmStatus": "ACTIVE",
"mdmStopProcessing": false,
"mdmSubdomain": "clockin",
"mdmSubscriptionDeletesEnabled": false,
"mdmTag": "DEVELOPMENT",
"mdmTenantId": "8cd6e43115e9416eb23609486fa053e3",
"mdmUpdatedUser": "[email protected]",
"mdmWhiteListDomains": [
"totvs.com",
"totvslabs.com",
"totvs.com.br"
],
"tenantType": "DEVELOPMENT"
}


O parâmetro `mdmSQLonCDSEnabled` deverá estar com o valor `true`.



O acesso SQL aos dados não requer duplicidade ou sincronismo dos dados. A Carol utiliza tecnologias Hive e Presto que permitir acessar os mesmos dados já disponíveis na camada Carol Data Storage (CDS) através de linguagem SQL. O processo de habilitar e desabilitar o acesso através de SQL deve ocorrer dentro de alguns segundos/minutos após a execução do endpoint para habilitar o recurso.


Os dois próximos capítulos mostram como criar/apagar as tabelas SQL para Data Models e Staging Tables. O parâmetro acima (mdmSQLonCDSEnabled) faz a criação e manutenção dessas tabelas automaticamente. Ou seja, quando uma Staging Table ou Data Model é alterado, a tabela SQL reflete automaticamente os ajustes.

Data Model

O processo para habilitar o recurso de SQL ocorre manualmente para Data Models, e o processo é feito individualmente para cada Data Model. Em uma versão futura, o acesso SQL para os dados no CDS estará disponível por padrão para todos os Data Models. Para habilitar, execute o comando a seguir no Swagger:


Localização: Entity Template → generateSqlTables


curl -X POST "https://api.carol.ai/api/v3/admin/entities/templates/generateSqlTables/clockinrecords" -H "accept: application/json" -H "Authorization: TOKEN_AQUI"


Caso seja necessário efetuar a eliminação da tabela de acesso aos dados através de SQL, você pode utilizar os comandos abaixo:



Staging Table

O processo para habilitar o recurso SQL também ocorre de forma manual para Staging Tables, e elas são habilitadas individualmente. Em uma versão futura, o acesso SQL para os dados no CDS estará habilitado por padrão para todos as Staging Tables. Para habilitar  o recurso, execute o comando a seguir no Swagger:


Localização: Staging → generateSqlTables


curl -X POST "https://api.carol.ai/api/v3/staging/generateSqlTables/clockinrecords?connectorId=33dd1190ff2c11e8858be609736e2a59" -H "accept: application/json" -H "Authorization: TOKEN_AQUI"


Caso seja necessário efetuar a eliminação da tabela de acesso aos dados através de SQL, você pode utilizar os comandos abaixo:


Queries com consolidação em tempo de execução

Uma forma de controlar o problema de consolidação dos dados é através de uma consulta que realiza a consolidação em tempo de execução da consulta. A consulta abaixo explora um recurso de row_number no Presto e permite enumerar as versões dos registros, através da chave primária da Carol (mdmId).


Com essa query, conseguimos garantir que não teremos duplicidade considerando a chave primária na Carol (mdmId):


Consolidação em tempo de execução
SELECT * FROM (
  SELECT row_number() OVER (PARTITION BY mdmid ORDER BY mdmstagingcounter DESC, mdmcounterforentity DESC) ranking, * 
  FROM dm_clockinrecords d
)
WHERE ranking = 1 and (mdmDeleted = false or mdmDeleted is null)
ORDER BY mdmstagingcounter DESC, mdmcounterforentity DESC
LIMIT 100

Ranking functions

A query utiliza a função de ranking "row_number" para que caso haja empate (mesmo `mdmID` com mesmo `mdmstagingcounter` e `mdmcounterforentity`) não seja retornado o mesmo registro duas vezes. Utilizando o `row_number` há a garantia de que a sequencia não será repetida.

Atenção

Caso o Data Model ou Staging Table tenha apenas dados transacionais, e estes não possuem alteração, não é necessário executar a consulta de consolidação em tempo de execução. Alguns exemplos de dados que normalmente não precisam da consolidação em tempo de execução: logs, mensagens de dispositivos IoT, dados de Telemetria, dados de transações financeiras (quando o status não pode ser alterado).


Em uma versão futura a Carol deverá absorver a consolidação em tempo de execução através de views.


SQL Delta Lake vs SQL CDS

Alguns projetos experimentais chegaram a trabalhar com o SQL Delta Lake, que possui a consolidação no momento de escrita dos dados, o que torna a disponibilização dos dados um pouco lenta (podendo chegar até uma hora).


O SQL descrito nesta documentação disponibiliza os dados no momento de escrita, sem efetuar a consolidação dos dados. A consolidação ocorre através de tarefas agendadas na plataforma ou durante a query, conforme descrito neste capítulo (podendo ser disponibilizado através de views para tornar o processo transparente).


Caso você esteja migrando do SQL Delta Lake para o SQL CDS, você poderá sofrer os impactos abaixo:

  • Atributos date/date time/timestamp: no Delta Lake o valor é armazenado como um Unix timestamp. No CDS é armazenado como um valor ISO. Você deverá compatibilizar o uso desses atributos para o formato correto.
  • Atributos com o prefixo `mdm_` no nome: o Delta Lake removia o prefixo `mdm_`, no CDS o prefixo é mantido. Consultas deverão ter os atributos compatibilizados.


Dados disponíveis na camada SQL

Quando a camada SQL para acessar os dados no CDS está habilitada, as seguintes tabelas são criadas:

  • staging tables: nome segue formato "stg_CONNECTORID_stagingTableName"
  • data models: nome segue formato "dm_dataModelName"
  • dados rejeitados: nome segue formato "dm_dataModelName_rej"


Próximos passos


O próximo capítulo detalha como abrir um Web Socket com a plataforma Carol para obter os resultados de queries.




Habilitando SQL over CDS na plataforma CAROL

Ao Acessar a plataforma, na versão atual há uma feature na plataforma para habilitar a camada SQL over CDS na plataforma. um Tenant Admin pode também habilitgar essa camada.


1. Após efetuar o loggin, clicar no ícone de usuário do canto superior esquerdo:


2. Dentro da lista, selecionar a opção "Tenant Admin":



3. Na seção "Settings", procurar a flag "Enable SQL over CDS":


4. Marque  a flag como truee em seguida clicar no botão "Save".


5. Uma vez concluído, note que serão geradas duas tasks. Antes de qualquer ação utilizando a camada, é essencial aguardar ambas as queries finalizarem.


  • Generate Staging SQL Tables: Processa as staging tables na camada CDS.
  • Generate Data Model SQL Tables: processa todos os Data Models.



Uma vez finalizadas, a camada já esta ativada na tenant. Para mais detalhes, acessar a documentação: 6. Habilitando camada SQL na Carol