BigQuery
A plataforma Carol disponibiliza o BigQuery como camada de armazenamento dos dados por padrão. Você pode utilizar a documentação do BigQuery para obter mais detalhes quanto aos recursos disponíveis e como implementar em suas consultas.
Consumindo dados usando SQL (Bigquery)
A Carol permite efetuar o consumo de dados através de comandos SQL, o que pode ser realizado através de requisições com resposta de resultados síncrona ou assíncrona utilizando API REST. Em requisições em que o resultado da consulta é síncrono, como o tempo de resposta está diretamente relacionado à complexidade da consulta em SQL, podem ocorrer erros de tempo de espera excedido, sendo a opção de resultados assíncronos indicada nestes casos.
Requisições
Autenticação
Consulte a documentação relacionada ao fluxo de Autenticação.
Resposta Assíncrona
Para obtenção dos resultados da consulta posteriormente à requisição de consulta realizada.
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
}'
{
"queryId": "carol-a654e18d03a34aa2aef75becba74-cb73-4b27-9ccf-f1dbb8342c13"
}
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"
}'
{
"queryPending": true
}
{
"schema": {
"f0_": "INTEGER"
},
"rows": [
{
"f0_": 65044949
}
],
"totalRows": 1,
"totalRowsPage": 1,
"lastPage": true,
"pageSize": 100
}
Nomenclatura de Tabelas
O consumo de dados usando SQL permite a consulta de dados originais inseridos na plataforma Carol, estes podem estar armazenados em tabelas staging ou suas derivações a partir de processos ETL, e permite também a consulta de dados processados na forma de Data Model (golden records).
Staging Tables
Deve ser utilizado o seguinte formato quando a consulta fizer referência a uma tabela staging:
stg<nome_do_conector><nome_da_tabela>
stg_protheus_carol_ct1 stg_protheus_carol_ct1_analitica stg_datasul_carol_emsuni_empresa
Data Models
Deve ser utilizado o nome do data model tal como apresentado na Carol UI (não utilizar o label) quando a consulta fizer referência a um data model:
arpaymentstype organization mdbusinesspartnerdocreference
PyCarol
Para ter acesso ao BigQuery através do PyCarol você vai precisar:
- PyCarol ≥ 2.47.4
- Uma Service Account com acesso ao BigQuery
Ambos registros de staging e data model podem ser consultados. Abaixo temos um exemplo de consulta aos modelos:
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)
Abaixo temos um exemplo de consulta para staging tables:
TEST_QUERY1 = """
SELECT *
FROM `stg_CONNECTORID_TABLENAME`
LIMIT 100
"""
Você pode usar o syntactic sugar para não ter que inserir o connector id:
test_query = """
SELECT mdmId
FROM {{clockinmobile.clockinrecords}}
UNION ALL
SELECT mdmId
FROM {{clockinrecords}}
LIMIT 100
"""
Na consulta acima, o PyCarol vai substituir {{clockinmobile.clockinrecords}} por stg_CONNECTORID_clockinrecords automaticamente.
API de consulta de CNPJ
Este tutorial descreve como efetuar a consulta de dados na Carol para obter dados mestres de empresas provenientes da Receita Federal do Brasil.
Para usar a API de consulta de CNPJs é necessário criar acesso na plataforma Carol. Para conseguir o acesso, abrir um ticket em suporte.carol@totvs.com.br com assunto “Acesso API CNPJ”. Você irá receber um email com um convite para criar um usuário e senha na plataforma Carol.
Para consultar o CNPJ (53113791000122) da TOTVS por exemplo, podemos usar a seguinte chamada:
curl -X POST "https://app.carol.ai/api/v3/queries/named/findCompany?indexType=MASTER&pageSize=10&sortOrder=ASC&scrollable=false" -H "accept: application/json" -H "Authorization: TOKEN" -H "content-type: application/json" -d "{\"cnpj\":\"53113791000122\"}"
A resposta será:
{
"count": 1,
"totalHits": 1,
"took": 6,
"hits": [
{
"mdmGoldenFieldAndValues": {
"mdmsituationdate": "2005-11-03T00:00:00.000Z",
"mdmisheadquarters": true,
"industrybr": "6201501",
"mdmsituationdescription": "",
"mdmaddress": [
{
"mdmstate": "SP",
"mdmzipcode": "02511000",
"mdmaddress3": "CASA VERDE",
"mdmaddress2": "",
"mdmcity": "SAO PAULO",
"mdmaddress1": "AVENIDA BRAZ LEME 1000"
}
],
"situationreasoncode": "00",
"registerdate": "1983-12-13T00:00:00.000Z",
"empty_registerdate": false,
"mdmisactive": true,
"sharecapital": 1382508564.43,
"mdmtaxid": "53113791000122",
"empty_mdmsituationdate": false,
"mdmphone": [
{
"mdmphonenumber": "",
"mdmphonetype": "phone2"
},
{
"mdmphonenumber": "1139817000",
"mdmphonetype": "phone1"
}
],
"cnaebr": "6201501",
"legalnaturecode": "2046",
"roottaxid": "53113791",
"legalnaturedescription": "Sociedade Anônima Aberta",
"mdmdba": "TOTVS S/A",
"mdmname": "TOTVS S.a.",
"companysize": "DEMAIS"
}
}
],
"aggs": {}
}
O resultado estará em $.hits.[].mdmGoldenFieldAndValues.
Note que na chamada da API é necessário enviar um TOKEN. Você pode ver como gerar esse token → clicando aqui
O connector ID pra gerar o TOKEN é 47b343909f214230b81195aa37a733bb
Os dados dessa API são os mesmo encontrados no portal da receita federal → clicando aqui
Estes dados são atualizados a cada mês. Significa que os dados de reposta podem estar em até um mês de atraso.