Índice

01.

...

VISÃO

...

GERAL

Este documento tem objetivo apresentar como é possível obter dados de usuários, marcações, funcionários e dispositivos do do Clock in utilizando utilizando consulta ao BigQuery da Plataforma Carol Named Queries. Para saber mais sobre as Named Queries seguir os seguintes passos:

Clique aqui para acessar a documentação da TOTVS Plataforma Carol.
Clicar na lupa no lado direito superior ao lados das pastas

Digite a palavra named e clique na primeira opção "Named Queries" conforme abaixo

Após selecionar a opção você será direcionado para a página da documentação.

...

A Plataforma Carol disponibiliza o BigQuery como camada de armazenamento dos dados por padrão. O consumo de dados pode ser realizado através de comandos SQL.

O consumo de dados via comandos SQL pode ser efetuado através de requisições com resposta síncrona ou assíncrona utilizando API REST. Para consultas mais complexas, onde o tempo de resposta pode exceder o limite de espera (timeout), a opção de resultados assíncronos é a mais indicada.

02. AUTENTICAÇÃO

A Plataforma Carol disponibiliza duas formas de autenticação para uso de rotas privadas para Named Queries: OAuth2 e API Key. Mais detalhes acesse a documentação da Plataforma Carol conforme a seguir:

Clique aqui para acessar a documentação da TOTVS Plataforma Carol.
Clique na Aba "Documentação"
No Menu a esquerda procure pela opção "Processos Gerais", depois "Autenticação e Login"
Na tela ao centro da opção "Autenticação e Login" irá demonstrar a documentação para obter mais detalhes.

03. PAGINAÇÃO

A Plataforma Carol disponibiliza a opção do page size / offset.

Para obter os 5 primeiros registros da primeira pagina utilizando o offset=0 e pageSize=5.

Bloco de código
- curl -X POST 'https://api.carol.ai/api/v3/queries/named/<NOME_DA_NAMED_QUERY> ?offset=0 &pageSize=5' -H 'X-Auth-Key: <KEY>' -H 'X-Auth-ConnectorId: <CON_ID>'

Para obter os 5 registros da segunda página, utilizando o offset=5 e pageSize=5.

Bloco de código
- curl -X POST 'https://api.carol.ai/api/v3/queries/named/<NOME_DA_NAMED_QUERY> ?offset=5 &pageSize=5' -H 'X-Auth-Key: <KEY>' -H 'X-Auth-ConnectorId: <CON_ID>'

Caso houvessem mais registros, seria possível utilizar o offset=10 e pageSize=5.

Também é possível retornar todos os dados em uma única request. Isto não é recomendado pois a resposta pode ser lenta e podem haver limitação de quantidade de registros. Para tanto basta remover o campo offset e setar o campo pageSize=-1.

Bloco de código
- curl -X POST 'https://api.carol.ai/api/v3/queries/named/<NOME_DA_NAMED_QUERY> ?pageSize=-1' -H 'X-Auth-Key: <KEY>' -H 'X-Auth-ConnectorId: <CON_ID>'

04. FILTROS

Por padrão, Named Queries retornam todos os dados dos Data Models (local onde os dados estão), mas é possível utilizar filtros para obter apenas os dados necessários. No caso abaixo os campos mdmpersonid e mdmname foram utilizados como filtro. Sempre lembrando que os campos do Data Model sempre estão dentro do objeto mdmGoldenFieldAndValues. A Plataforma Carol retorna outros campos que fazem parte da estrutura interna dela mas que não parecem fazer sentido para este caso.

Bloco de código

- curl -X POST 
   'https://api.carol.ai/api/v3/queries/named/<NOME_DA_NAMED_QUERY>
      ?offset=0
      &pageSize=5
      &fields=mdmGoldenFieldAndValues.mdmpersonid,mdmGoldenFieldAndValues.mdmname'
   -H 'X-Auth-Key: <KEY>'
   -H 'X-Auth-ConnectorId: <CON_ID>'

05. NAMED QUERIES PARA CONSULTA

Para obter a lista completa de Named Queries disponíveis no ambiente, basta entrar em Explore e depois em Named Queries. A lista será apresentada. Nesta área é possível editar, excluir e incluir novas Named Queries. Sempre lembrando que elas vão retornar os registros dos Data Models.

...

Bloco de código
- curl -X POST 'https://api.carol.ai/api/v3/queries/named/userList ?offset=0 &pageSize=5 &fields=mdmGoldenFieldAndValues' -H 'X-Auth-Key: <KEY>' -H 'X-Auth-ConnectorId: <CON_ID>'

Bloco de código

- {
  "count": 5,
  "totalHits": 11,
  "took": 12,
  "hits": [
    {
      "mdmGoldenFieldAndValues": {
        "mdmshouldsendwelcomeemail": true,
        "mdmphonenumber": "1232321",
				//....
      }
    },
    {
      "mdmGoldenFieldAndValues": {
        // ...
      }
    },
  ],
  "aggs": {}
}

...

Bloco de código
- curl -X POST 'https://api.carol.ai/api/v3/queries/named/clockinrecordsListByPeriod ?offset=0 &pageSize=5 &fields=mdmGoldenFieldAndValues' -H 'X-Auth-Key: <KEY>' -H 'X-Auth-ConnectorId: <CON_ID>'

Bloco de código
Response similar a da consulta de usuários

...

Bloco de código
- curl -X POST 'https://api.carol.ai/api/v3/queries/named/employeeList ?offset=0 &pageSize=5 &fields=mdmGoldenFieldAndValues' -H 'X-Auth-Key: <KEY>' -H 'X-Auth-ConnectorId: <CON_ID>'

Bloco de código
Response similar a da consulta de usuários

...

Bloco de código
- curl -X POST 'https://api.carol.ai/api/v3/queries/named/deviceList ?offset=0 &pageSize=5 &fields=mdmGoldenFieldAndValues' -H 'X-Auth-Key: <KEY>' -H 'X-Auth-ConnectorId: <CON_ID>'

Bloco de código
Response similar a da consulta de usuários

...

Para verificar quais são os filtros das Named Queries, basta entrar na área citada anteriormente e executar uma Named Query para testes. Ao executar, a Carol apresentará quais são os filtros. Também é possível adicionar novos filtros. Segue abaixo exemplo de como enviar valores para os filtros via requisições HTTP POST.

Bloco de código

- curl -X POST 
   'https://api.carol.ai/api/v3/queries/named/<NOME_DA_NAMED_QUERY>
      ?offset=0
      &pageSize=5
      &fields=mdmGoldenFieldAndValues'
   -H 'X-Auth-Key: <KEY>'
   -H 'X-Auth-ConnectorId: <CON_ID>'
   -d '{ "key1": "value1", "key2": "value2" }'

06. EXEMPLO DE USO PARA CONSULTA DE MARCAÇÕES DE PONTO:

Segue abaixo um exemplo prático de como testar e usar uma NAMED QUERY, além de dicas de uso.

06.1. Consultando e testando a NAMED QUERY que pretende usar:

1- Faça Login no seu Ambiente ({organização}.carol.ai/{ambiente});

2- Acesse a opção Explorer no menu da latera esquerda;

3- Dentro do Explorer, acesse a opção Editor.

Image Removed

1- Verifique se está na opção RT em +;

2- Verifique se abriu uma nova aba como RT;

3- No menu lateral esquerdo, também selecione a opção RT;

4- Digite o nome da NamedQuery que pretende utilizar;

5- De duplo clique sobre o nome e ela será aberta para consulta na tela direita;

6, 7 e 8- No caso desta NamedQuery (clockinrecordsListByPeriod), ela permite realizar filtros no Data Model CLOCK IN RECORDS usando os campos de código do dispositivo, período de data da marcação de ponto e a partir de qual número NSR;

9- Você pode testar a NamedQuery pressionando o botão RUN.

Image Removed

1- Preencha os filtros desejados e execute a consulta.

Image Removed

Assim pode consultar/exportar os dados retornados da consulta:

Image Removed

06.2. Exemplo da montagem de uma requisição:

Só passando a NamedQuery, sem usar filtros

Request:

Bloco de código

language	yml
theme	Midnight

- curl -X 'POST' \
  'https://api.carol.ai/api/v3/queries/named/clockinrecordsListByPeriod?indexType=MASTER&offset=0&pageSize=10&sortBy=mdmGoldenFieldAndValues.mdmeventdate&sortOrder=DESC&scrollable=false' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \    
  -H 'X-Auth-Key: {sua chave aqui}' \
  -H 'X-Auth-ConnectorId: {seu ConnectorId aqui}' \    '

Response:

Bloco de código

language	yml
theme	Midnight

{
  "count": 10,
  "totalHits": 15646,
  "took": 14,
  "hits": [
    {...}
	...
	]
}

Usando filtro passando um NSR, um único Device e um Período (UTC), não preciso passar todos, poderia por exemplo não passar DEVICE e viria marcações do período de todos DEVICES, ou o NSR e pegar todos registros, mas no caso do NSR eu poderia acabar consumindo registros que ainda não tiveram NSR gerado pela plataforma:

Request:

Bloco de código

language	yml
theme	Midnight

- curl -X 'POST' \
  'https://api.carol.ai/api/v3/queries/named/clockinrecordsListByPeriod?indexType=MASTER&offset=0&pageSize=10&sortBy=mdmGoldenFieldAndValues.mdmeventdate&sortOrder=DESC&scrollable=false' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'X-Auth-Key: {sua chave aqui}' \
  -H 'X-Auth-ConnectorId: {seu ConnectorId aqui}' \
  -d '{
  "nsrCode": "748",
  "deviceCode": "BE1C11B2-5DEC-4878-88E6-175981481398",
  "initialDate": "2024-08-01T03:00:00.000-03:00",
  "finalDate": "2024-09-01T03:00:00.000-03:00",
}'

Response:

Bloco de código

language	yml
theme	Midnight

{
  "count": 6,
  "totalHits": 6,
  "took": 4,
  "hits": [
    {
      "mdmDeleted": false,
      "mdmSourceOperation": "SQL_PROCESS",
      "mdmCounterForEntity": 1724761025743000,
      "mdmGoldenFieldAndValues": {
        "clockinmode": "1",
        "smssent": "2024-08-27T03:32:34.990Z",
        "supervisorcode": "[email protected]",
        "isautotimezone": "2",
        "selfclockin": true,
        "lastgpsdatetime": "2024-08-21T12:15:29.000-03:00",
        "nsrprocesseddatetime": "2024-08-21T15:22:25.440Z",
        "devicetimezonechangeindicator": "1",
        "score": "6",
        "supervisorname": "[email protected]",
        "appname": "Clock In",
        "eventdatestr": "2024-08-21T12:15:00.000-03:00",
        "updatedatetimeautomatically": false,
        "lastmomentgpsdatetimeobtained": "2024-08-21T12:15:29.322-03:00",
        "employeegeofencecoordinatesoptional": "no coordinates",
        "receiptimage": "https://totvsclockin.carol.ai/teste/go/728ywobccj",
        "mdmname": "Colaborador Exemplo",
        "devicedescription": "[email protected]",
        "datetimechanged": false,
        "image": "https://totvsclockin.carol.ai/teste/go/raxoohcav9",
        "nsrcode": "753",
        "coordinatesaccuracy": 6,
        "diffgpsdevicetime": "0",
        "collectiveagreement": "99999999999999999",
        "gpslevel": "0",
        "locationcode": "4",
        "licensestatus": "OK",
        "mdmStagingAuditId": "f5ac249636ec0e34",
        "fraudscore": 0.0026708,
        "statusanalysisdate": "2024-08-21T21:09:10.514Z",
        "receiptsentmode": "Nothing",
        "readphonestateenabled": false,
        "gmt": "-03:00",
        "devicecode": "BE1C11B2-5DEC-4878-88E6-175981481398",
        "georeferencestate": "filled",
        "mdmTaskId": "b0a898893037441fbc3cd42d8353f9c2",
        "imagehash": "-0.131479, 0.0294967, 0.0692975, -0.0225383, -0.0269747, -0.0752967, -0.0515807, -0.120229, 0.180412, -0.125723, 0.218578, -0.00439189, -0.253444, -0.118369, 0.002121, 0.117364, -0.0208364, -0.0767907, -0.0751632, -0.0915777, 0.0742972, 0.0451878, 0.0465591, 0.0654342, -0.0633498, -0.339759, -0.0660675, -0.115597, 0.02133, -0.0735729, -0.0318694, 0.0118895, -0.103082, -0.113205, 0.0400811, 0.112948, -0.0746193, -0.0700653, 0.198791, -0.00607182, -0.119064, -0.0749938, 0.0507131, 0.272417, 0.158889, 0.0524132, 0.0531848, -0.0839153, 0.15459, -0.277452, 0.152825, 0.0625031, 0.183316, 0.0599122, 0.20305, -0.146557, 0.0588035, 0.193805, -0.266038, 0.158633, 0.077579, -0.0514593, -0.104153, -0.00862041, 0.249977, 0.166787, -0.132382, -0.0749751, 0.200977, -0.136508, -0.062053, 0.0602444, -0.0952025, -0.207354, -0.218461, 0.0460927, 0.363987, 0.223373, -0.219258, 0.00230355, -0.0482604, 0.00519569, 0.0950405, 0.0393352, -0.0476836, -0.0534268, -0.0686621, -0.0298764, 0.111147, 0.0586453, -0.0532365, 0.272703, 0.0270942, -0.0053324, 0.0387958, 0.0122857, -0.130904, -0.0270901, -0.152075, -0.124179, 0.116132, -0.0682318, 0.0681907, 0.0567057, -0.219154, 0.198706, -0.0320844, 0.0369035, 0.0939216, -0.0129052, -0.104225, 0.0190724, 0.131557, -0.237321, 0.196939, 0.105615, 0.103404, 0.166686, 0.040076, 0.0371103, 0.0908808, -0.0865782, -0.173796, -0.0864644, 0.0326179, -0.0310395, 0.0630728, 0.0668265",
        "isuserinsidegeofenceenum": "1",
        "statusanalysis": "OK",
        "externalservicestatuscode": 0,
        "coordinates": {
          "lon": -48.38827807460761,
          "lat": -22.370139551369817
        },
        "datetimeprovider": "ntp",
        "fakegpslocation": false,
        "devicesynchistorycode": "1724253342422",
        "mdmtaxid": "755",
        "locationdescription": "Joinville",
        "clockinsessionstatus": "logged-in",
        "mdmeventdate": "2024-08-21T15:15:00.000Z",
        "imei": "",
        "gmtfromclockinscoordinates": "-03:00",
        "mdmpersonid": "12345678910"
      },
      "mdmConstraintPending": false,
      "mdmEntityType": "clockinrecordsGolden",
      "mdmStagingRecordIds": [
        "99eb05dd32446c8dd11d0171d995160e"
      ],
      "mdmSourceType": "SQL",
      "mdmMergePending": false,
      "mdmLastUpdated": "2024-08-27T12:17:05Z",
      "mdmTenantId": "1ff0fbe4de2143bbab686413a3c359ca",
      "mdmMasterCount": 1,
      "mdmStagingCounter": "1724729567118246",
      "mdmCreated": "2024-08-27T12:17:05Z",
      "mdmSourceOperationTaskId": "b0a898893037441fbc3cd42d8353f9c2",
      "mdmSourceEntityNames": [
        "bf2ace1f69f34529850e3b983feb8271_clockinrecords"
      ],
      "mdmEntityTemplateId": "7dd4da9d15294d46a6da8e27f179690f",
      "mdmId": "ca04aa98aed7b20e5eb450a397c7ea99"
    },
    {...}, 
    {...}, 
    {...},
    {...},
    {...}
  ],
  "aggs": {}
}

Usando filtro passando um NSR, um único Device e um Período (UTC), não preciso passar todos, poderia por exemplo não passar DEVICE e viria marcações do período de todos DEVICES, ou o NSR e pegar todos registros, mas no caso do NSR eu poderia acabar consumindo registros que ainda não tiveram NSR gerado pela plataforma:

Request:

Bloco de código

language	yml
theme	Midnight

- curl -X 'POST' \
  'https://api.carol.ai/api/v3/queries/named/clockinrecordsListByPeriod?indexType=MASTER&offset=0&pageSize=10&sortBy=mdmGoldenFieldAndValues.mdmeventdate&sortOrder=DESC&scrollable=false' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'X-Auth-Key: {sua chave aqui}' \
  -H 'X-Auth-ConnectorId: {seu ConnectorId aqui}' \
  -d '{
  "nsrCode": "748",
  "deviceCode": "BE1C11B2-5DEC-4878-88E6-175981481398",
  "initialDate": "2024-08-01T03:00:00.000-03:00",
  "finalDate": "2024-09-01T03:00:00.000-03:00",
}'

Response:

Bloco de código

language	yml
theme	Midnight

{
  "count": 6,
  "totalHits": 6,
  "took": 9,
  "hits": [
    {
      "mdmGoldenFieldAndValues": {
        "eventdatestr": "2024-08-14T17:40:00.000-03:00",
        "mdmeventdate": "2024-08-14T20:40:00.000Z"
      }
    },
    {
      "mdmGoldenFieldAndValues": {
        "eventdatestr": "2024-08-14T17:42:00.000-03:00",
        "mdmeventdate": "2024-08-14T20:42:00.000Z"
      }
    },
    {
      "mdmGoldenFieldAndValues": {
        "eventdatestr": "2024-08-21T08:49:00.000-03:00",
        "mdmeventdate": "2024-08-21T11:49:00.000Z"
      }
    },
    {
      "mdmGoldenFieldAndValues": {
        "eventdatestr": "2024-08-21T08:55:00.000-03:00",
        "mdmeventdate": "2024-08-21T11:55:00.000Z"
      }
    },
    {
      "mdmGoldenFieldAndValues": {
        "eventdatestr": "2024-08-21T08:57:00.000-03:00",
        "mdmeventdate": "2024-08-21T11:57:00.000Z"
      }
    },
    {
      "mdmGoldenFieldAndValues": {
        "eventdatestr": "2024-08-21T12:15:00.000-03:00",
        "mdmeventdate": "2024-08-21T15:15:00.000Z"
      }
    }
  ],
  "aggs": {}
}

...

opção "Autenticação e Login" irá demonstrar a documentação para obter mais detalhes.

03. CONSUMO DE DADOS VIA API REST (BigQuery)

Para realizar o consumo de dados do BigQuery através da Plataforma Carol, utilizamos requisições API REST, sendo a modalidade assíncrona a mais robusta para evitar erros de tempo de espera excedido.

03.01. Requisição de Consulta (Assíncrona)

O *endpoint* `v1/query/v1/query` (ou

...

Request:

Bloco de código

language	yml
theme	Midnight

- curl -X 'POST' \
  'https://api.carol.ai/api/v4/queries/named/clockinrecordsListByPeriod?indexType=MASTER&offset=0&pageSize=10&sortBy=mdmGoldenFieldAndValues.mdmeventdate&sortOrder=ASC&scrollable=false&fields=mdmGoldenFieldAndValues.eventdatestr%2CmdmGoldenFieldAndValues.mdmeventdate' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'X-Auth-Key: {sua chave aqui}' \
  -H 'X-Auth-ConnectorId: {seu ConnectorId aqui}' \   
  -d '{
  "nsrCode": "748",
  "deviceCode": "BE1C11B2-5DEC-4878-88E6-175981481398",
  "initialDate": "2024-08-01T03:00:00.000-03:00",
  "finalDate": "2024-09-01T03:00:00.000-03:00",
}'

Response:

Bloco de código

language	yml
theme	Midnight

{
  "count": 6,
  "totalHits": 6,
  "took": 9,
  "hits": [
    {
      "mdmGoldenFieldAndValues": {
        "eventdatestr": "2024-08-14T17:40:00.000-03:00",
        "mdmeventdate": "2024-08-14T20:40:00.000Z"
      }
    },
    {
      "mdmGoldenFieldAndValues": {
        "eventdatestr": "2024-08-14T17:42:00.000-03:00",
        "mdmeventdate": "2024-08-14T20:42:00.000Z"
      }
    },
    {
      "mdmGoldenFieldAndValues": {
        "eventdatestr": "2024-08-21T08:49:00.000-03:00",
        "mdmeventdate": "2024-08-21T11:49:00.000Z"
      }
    },
    {
      "mdmGoldenFieldAndValues": {
        "eventdatestr": "2024-08-21T08:55:00.000-03:00",
        "mdmeventdate": "2024-08-21T11:55:00.000Z"
      }
    },
    {
      "mdmGoldenFieldAndValues": {
        "eventdatestr": "2024-08-21T08:57:00.000-03:00",
        "mdmeventdate": "2024-08-21T11:57:00.000Z"
      }
    },
    {
      "mdmGoldenFieldAndValues": {
        "eventdatestr": "2024-08-21T12:15:00.000-03:00",
        "mdmeventdate": "2024-08-21T15:15:00.000Z"
      }
    }
  ],
  "aggs": {}
}

06.3. Para mais informações

...

Autenticação:
- Clique aqui para acessar a documentação da TOTVS Plataforma Carol.
- Clique na Aba "Documentação"
- No Menu a esquerda procure pela opção "Processos Gerais", depois "Autenticação e Login"
- Na tela ao centro da opção "Autenticação e Login" irá demonstrar a documentação para obter mais detalhes.
Consumindo Dados TOTVS Carol: consulta a documentação "Named Query" na documentação da Plataforma Carol sugerida no item 01.
docs.carol.ai

...

`/api/v1/bigQuery/query`)

...

é

...

responsável

...

por

...

criar

...

uma

...

*task*

...

de

...

consumo

...

de

...

dados

...

que

...

será

...

repassada

...

ao

...

BigQuery.

...

**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

theme	Eclipse

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

...

 
--header 'accept: application/json' \

...

 
--header 'Authorization: 2df9b50c4a8b4918871b04fe9768f4ec' \

...

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

...

 
--data-raw '{

...

"mdmOrgId": "{{carol_orgid}}",

...

  "mdmTenantId": "{{carol_envid}}",

...

  "query": "SELECT COUNT(*) FROM mdbusinesspartnergroup",

...

"page": 1,

...

"pageSize":

...

100 
}'
```

Exemplo de Resposta com ID da Requisição:

{

...

"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:

...

2df9b50c4a8b4918871b04fe9768f4ec'

...

\

...

--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_protheus_carol_ct1.
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. CONSUMO DE DADOS VIA PyCarol

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):

import

...

pycarol
SA_FILEPATH

...

=

...

"/home/jro/wk/totvs/sa.json"

...

TEST_QUERY1

...

=

...

"""

...

SELECT *
FROM `dm_clockinrecords`
LIMIT 100
"""

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)

...

A PyCarol também suporta o uso de syntactic sugar para referenciar tabelas de staging sem inserir o connector id.

05. 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.

...

05.

...

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.

...

05.

...

02.

...

Otimizações em SQL

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

Em tabelas particionadas, o atributo da partição deve ser a primeira condicional informada na query.
A condição no atributo da partição deve conter apenas constantes.

Exemplo de Otimização (Evitando o cenário que NÃO filtra partições não referenciadas):

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;

...

05.

...

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.

Como utilizar (via VS Code com extensão Carol BigQuery):

Abra o arquivo de query SQL com a extensão .csql no VS Code.
Após a execução da query (clicando em Carol - Run Query ou usando F5):
Um botão Otimizar SQL aparecerá na parte inferior do editor.
Ao clicar, o agente de IA retorna:
Sugestões de melhoria automáticas: Refaz a query aplicando boas práticas.
Dicas e alertas: Pontos de atenção que o usuário deve avaliar manualmente.

É 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.

06. CRIAÇÃO DE VIEWS COM SHARED DATA

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

O compartilhamento ocorre através de views dentro do BigQuery, sem duplicar os dados. Isso é particularmente útil para clientes que desejam consumir apenas um subconjunto específico dos dados do TOTVS Clock In (Data Models ou Staging Tables), garantindo que o consumo seja feito no formato desejado.

A Tenant que acessa os dados compartilhados (destino) paga apenas pelo uso de slots conforme consultas ou dados forem processados nas views de compartilhamento.
O recurso permite que os dados sejam utilizados por pipelines SQL ou em Insights.
Criação de Views

Ao definir a View no Shared Data, você deve definir na Query quais dados serão compartilhados.

OBSERVAÇÃO IMPORTANTE: Não é permitido utilizar select * from tabela como conteúdo das views de Shared Data. Esses compartilhamentos são frágeis e podem colocar em risco o vazamento de novos dados adicionados na tabela origem.

Exemplo de Documento de Configuração de Compartilhamento (Tenant Origem clockinTestWeb para Tenant Destino poffo):

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:

Na Tenant destino, a view de acesso aos dados terá o prefixo shd e a estrutura de nome {sharing_group}_{view_name}.

Exemplo de consulta na Tenant destino:

select

...

*

...

from

...

shd_clockinrecords_clockinrecords

...

Apenas os atributos informados no Sharing Group estarão disponíveis na view.

07. INFORMAÇÕES ADICIONAIS

Dúvidas Adicionais:

Qualquer dúvida adicional deve ser direcionada via Ticket.

Documentação da Plataforma Carol:

Para mais detalhes sobre as funcionalidades da Plataforma Carol e recursos avançados (como Autenticação e

...

etc), é indicado o acesso à documentação disponível na URL: https://docs.carol.ai/.

Atalhos

Árvore de páginas

Versões comparadas

Versão antiga 2

Nova versão 3

Chave

01.

VISÃO

GERAL

02. AUTENTICAÇÃO

03. PAGINAÇÃO

04. FILTROS

05. NAMED QUERIES PARA CONSULTA

06. EXEMPLO DE USO PARA CONSULTA DE MARCAÇÕES DE PONTO:

06.1. Consultando e testando a NAMED QUERY que pretende usar:

06.2. Exemplo da montagem de uma requisição:

03. CONSUMO DE DADOS VIA API REST (BigQuery)

03.01. Requisição de Consulta (Assíncrona)

06.3. Para mais informações

04. CONSUMO DE DADOS VIA PyCarol

05. OTIMIZAÇÃO DAS CONSULTAS

05.

01. Armazenamento e Processamento do BigQuery

05.

02.

Otimizações em SQL

05.

03. Agente de Otimização de SQL

06. CRIAÇÃO DE VIEWS COM SHARED DATA

07. INFORMAÇÕES ADICIONAIS

Dúvidas Adicionais:

Documentação da Plataforma Carol:

Atalhos

Árvore de páginas

Histórico da Página

Versões comparadas

Versão antiga 2

Nova versão 3

Chave

01.

VISÃO

GERAL

02. AUTENTICAÇÃO

03. PAGINAÇÃO

04. FILTROS

05. NAMED QUERIES PARA CONSULTA

06. EXEMPLO DE USO PARA CONSULTA DE MARCAÇÕES DE PONTO:

06.1. Consultando e testando a NAMED QUERY que pretende usar:

06.2. Exemplo da montagem de uma requisição:

03. CONSUMO DE DADOS VIA API REST (BigQuery)

03.01. Requisição de Consulta (Assíncrona)

06.3. Para mais informações

04. CONSUMO DE DADOS VIA PyCarol

05. OTIMIZAÇÃO DAS CONSULTAS

05.

01. Armazenamento e Processamento do BigQuery

05.

02.

Otimizações em SQL

05.

03. Agente de Otimização de SQL

06. CRIAÇÃO DE VIEWS COM SHARED DATA

07. INFORMAÇÕES ADICIONAIS

Dúvidas Adicionais:

Documentação da Plataforma Carol: