...

**Parâmetros obrigatórios** para a consulta incluem `mdmOrgId`, `mdmTenantId`, `pageSize` e a `query` SQL a ser executada.**

Exemplo de Requisição de Consulta (CURL):

...

Bloco de código
language yml theme Midnight title Request
curl --location --request POST 'https://api.carol.ai/sql/v1/query/v1/query' \  --header 'accept: application/json' \  --header 'Authorization: {(SEUTOKEN})' \  --header 'Content-Type: application/json' \  --data-raw '{    "mdmOrgId": "{{carol_orgid}}",    "mdmTenantId": "{{carol_envid}}",    "query": "SELECT COUNT(*) FROM ingestion_stg_clockinmobile_clockinrecords",    "page": 1,    "pageSize": 100  }'

...

Bloco de código
language js theme Midnight title Response
{    "queryId": "carol-a654e18d03a34aa2aef75becba74-cb73-4b27-9ccf-f1dbb8342c13"  }

Obtenção dos Resultados (Polling):

Após a requisição de consulta, para obter os resultados, é necessário realizar o polling utilizando o endpoint v1/query/v1/query_polling (ou /api/v1/bigQuery/query_polling) e fornecer o queryId gerado.

Exemplo de Requisição de Resultados (CURL):

curl --location --request POST 'https://api.carol.ai/sql/v1/query/v1/query_polling' \ 

...

--header 'accept: application/json' \ 

...

--header 'Authorization:

...

 {{SEUTOKEN}}' \ 

...

--header 'Content-Type: application/json' \ 

...

--data-raw '{ 

...

  "queryId": "carol-a654e18d03a34aa2aef75becba74-cb73-4b27-9ccf-f1dbb8342c13" 

...

}'

Se a consulta ainda estiver em processamento, a resposta indicará:

{ 

...

  "queryPending": true 

...

}

Quando os resultados estiverem prontos, a resposta incluirá o esquema (schema) e as linhas (rows):

{ 

...

  "schema": { ... }, 

...

  "rows": [ ... ],

...

  "totalRows": 1, 

...

  "totalRowsPage": 1, 

...

  "lastPage": true, 

...

  "pageSize": 100 

...

}

Nomenclatura de Tabelas

O consumo de dados via SQL permite a consulta de dados originais (tabelas staging) ou dados processados (Data Models/Golden Records).

Staging Tables: Utilize o formato stg<nome_do_conector><nome_da_tabela>. Exemplo: stg_protheusclockinmobile_carol_ct1clockinrecords.

Data Models (Golden Records): Utilize o nome do Data Model exatamente como apresentado na Carol UI (não utilize o label). Exemplo (Data Model de Marcações do Clock In): clockinrecords (se este for o nome do Data Model).

04

...

Para ter acesso ao BigQuery via PyCarol, você precisará da versão PyCarol ≥ 2.47.4 e uma Service Account com acesso ao BigQuery.

É possível consultar tanto registros de staging quanto Data Models.

Exemplo de Consulta a Data Models (usando dm_clockinrecords como exemplo):

...

.

...

with open(SA_FILEPATH, "r") as file: 
        service_account = json.loads(file.read()) 
    return service_account 

carol = Carol() 
sql = pycarol.SQL(carol) 
result = sql.query(TEST_QUERY1, method="bigquery", service_account=service_account, dataframe=True)

...

OTIMIZAÇÃO DAS CONSULTAS

Queries não otimizadas podem gerar custos adicionais no BigQuery, impactar gravemente a aplicação que concorre por recursos de slots e gerar resultados lentos. É crucial garantir um desempenho eficiente das consultas.

...

04.01. Armazenamento e Processamento do BigQuery

O BigQuery usa Partitioning (Particionamento) e Clustering (Agrupamento em Cluster) para melhorar o desempenho e reduzir a quantidade de dados lidos.

Partitioning: Divide a tabela em segmentos físicos (partições) com base, geralmente, no tempo de ingestão ou em uma coluna de unidade de tempo. Consultas que filtram a coluna de particionamento podem reduzir o total de dados lidos.
Clustering: Ordena os dados automaticamente com base no conteúdo de até quatro colunas (geralmente colunas de alta cardinalidade e não temporais). O clustering melhora o desempenho das consultas em cláusulas WHERE, agregações e cláusulas JOIN utilizando as colunas clusterizadas. É possível definir Partitioning e Clustering em uma única tabela.

...

04.02. Otimizações em SQL

Para garantir que o BigQuery utilize corretamente o particionamento e leia menos dados, siga esta regra:

...

O cenário abaixo NÃO efetua o filtro de partições não referenciadas, pois a data é obtida por subconsulta:

SELECT * FROM A WHERE A_date >= (SELECT B_date FROM B LIMIT 1)

O cenário otimizado, que trata corretamente a partição e irá ler menos dados, utiliza uma variável declarada (constante) para o filtro de data:

DECLARE dateB TIMESTAMP;

...

SET dateB = (SELECT B_date FROM B LIMIT 1);

...

SELECT * FROM A WHERE A_date >= dateB;

...

04

...

.03. Agente de Otimização de SQL

O Agente de Otimização SQL é uma ferramenta integrada à Plataforma Carol que auxilia a melhorar a performance de queries SQL. Ele analisa consultas, sugere melhorias e aponta pontos de atenção para otimização.

...

É importante lembrar que o agente não substitui a revisão humana, mas serve como uma ferramenta de apoio para melhorar performance e legibilidade. As otimizações são baseadas em boas práticas para o dialeto selecionado.

...

05. CRIAÇÃO DE VIEWS COM SHARED DATA

O módulo Shared Data permite o compartilhamento de dados entre Tenants, inclusive de Organizações diferentes.

...

Compartilhando o Data Model clockinrecords e selecionando colunas específicas:{

{
"description" : "Sharing Clockin Records table",

...

"mdmTenantIdDestination" : "d8010a66659540c3a7859bf538161f95",

...

"name" : "clockinrecords",

...

"views" : [

...

  {

...

    "name" : "clockinrecords",

...

    "query" : "select image, devicecode, imei, appname, piscode, mdmname, mdmeventdate from `carol-b57a7e74a1764003aa98.b57a7e74a1764003aa987288a610456e.clockinrecords`"

...

  }

...

]

...

}

Acesso na Tenant Destino:

...