Issue Type Icon CAPL-8854

Inclusão de metadados na coluna descrição do Big Query

Description

01 - STAKEHOLDER (quem valida e esclarece):
02 - PROBLEMA (cenário e/ou dor):

Atualmente, todas as tabelas da Carol (Staging Tables e Data Models) possuem um conjunto padrão de campos de metadados, documentados oficialmente na plataforma.
No entanto, essas informações não são automaticamente refletidas no campo description das colunas no BigQuery, o que obriga os usuários a consultar documentação externa para entender o significado dos campos.

Além disso, é importante reforçar que toda a aplicação automatizada desses metadados deve considerar e respeitar a estrutura das tabelas de ingestion, como por exemplo:

carol-00273701fcb348b3ae6a.00273701fcb348b3ae6aae0c42e041e9.ingestion_clockinattempts

Ou seja, o processo precisa abranger tanto para staging quanto para datamodel, as tabelas cujo padrão de nomenclatura siga, por exemplo, o padrão ingestion*, garantindo que o schema dessas tabelas receba as descrições corretamente no momento do provisionamento.

A demanda é que essas descrições passem a ser aplicadas automaticamente durante o provisionamento das tabelas, garantindo que:

  • o schema já nasça documentado;

  • as descrições fiquem visíveis no BigQuery e, consequentemente, na Carol;

  • o usuário tenha documentação embutida diretamente nos dados.


03 - OBJETIVO (solução proposta):

Automatizar, no processo de provisionamento de tabelas da Carol, a inclusão das descrições oficiais dos campos de metadados no schema do BigQuery, conforme documentação da Carol.

Abaixo as colunas e descrições, retiradas da documentação oficial (https://docs.carol.ai/docs/intro#meta-informa%C3%A7%C3%B5es-nos-dados-metadata)

Metadados – Staging Tables

Campo

Descrição (BigQuery description)

mdmCounterForEntity

Data/hora em microssegundos de quando o dado foi recebido pela plataforma Carol. Registros enviados na mesma requisição recebem o mesmo valor.

mdmId

Identificador único do registro, determinado pelos valores dos atributos definidos no crosswalk (chave primária) da staging table.

mdmCreated

Data/hora de criação do registro. Como a Carol trata os dados de forma imutável, recebe o mesmo valor de mdmCounterForEntity.

mdmLastUpdated

Data/hora da última atualização do registro. Como a Carol trata os dados de forma imutável, recebe o mesmo valor de mdmCounterForEntity.

mdmTenantId

Identificador único da tenant na plataforma Carol.

mdmConnectorId

Identificador do conector ao qual o registro pertence.

mdmEntityType

Concatenação do connectorId com o nome da staging table.

mdmDeleted

Indica logicamente se o registro foi excluído (true) ou não (false ou null).

mdmAuditId

Chave de auditoria única gerada durante o recebimento dos dados pela Carol, permitindo rastreamento e recuperação de logs.

mdmBatchId

Identificador do batch enviado pelo SmartLink. Inicialmente compatível apenas com a linha de produto Protheus (Release Outubro/2023).

mdmBatchIdSequence

Sequência do batch enviado pelo SmartLink. Inicialmente compatível apenas com a linha de produto Protheus (Release Outubro/2023).

mdmCounterForEntityDATETIME

Representação em formato datetime do atributo mdmCounterForEntity. Atualmente não é recomendada para operações; utilizar mdmCounterForEntity ou _ingestionDatetime.

_ingestionDatetime

Data/hora em que o registro foi efetivamente gravado no BigQuery. É a partição padrão das staging tables e deve ser usada para otimização de pipelines SQL.

Metadados – Data Models

Campo

Descrição (BigQuery description)

mdmCounterForEntity

Data/hora em microssegundos de quando o golden record foi processado pelo motor de SQL Processing.

mdmStagingCounter

Data/hora em microssegundos de quando o registro foi recebido na camada de staging da plataforma Carol.

mdmId

Identificador único do golden record, gerado a partir do mdmId da staging area combinado com o nome do data model.

mdmCreated

Data/hora de criação do golden record. Como a Carol trata os dados de forma imutável, recebe o mesmo valor de mdmCounterForEntity.

mdmLastUpdated

Data/hora da última atualização do golden record. Como a Carol trata os dados de forma imutável, recebe o mesmo valor de mdmCounterForEntity.

mdmEntityType

Nome do data model com o sufixo Golden.

mdmSourceEntityNames

Identificação do conector e da staging table de origem, referenciada na pipeline SQL pelo alias stg.

mdmStagingRecord

Lista de identificadores (mdmId) dos registros da staging table que originaram este golden record.

mdmDeleted

Indica logicamente se o golden record foi excluído (true) ou não (false ou null).

mdmCounterForEntityDATETIME

Representação datetime do atributo mdmCounterForEntity. Recomenda-se utilizar mdmCounterForEntity ou _ingestionDatetime para operações e partições.

_ingestionDatetime

Data/hora em que o golden record foi efetivamente gravado no BigQuery. É a partição padrão dos data models.

mdmStagingAuditId

Identificador de auditoria do registro de staging associado. Para ser preenchido, a pipeline deve utilizar a tag --metadata-v2--.

mdmTaskId

Identificador da task responsável por gerar o golden record. Contém internamente a versão da pipeline executada.

mdmBatchId

Identificador do batch proveniente do registro da staging table. Para ser preenchido, a pipeline deve utilizar a tag --metadata-v2--.

mdmBatchIdSequence

Sequência do batch proveniente do registro da staging table. Para ser preenchido, a pipeline deve utilizar a tag --metadata-v2--.

04 - QUEM PODE USAR (perfis de usuários):
05 - ASSETS (links e arquivos relevantes):
06 - CRITÉRIOS DE ACEITE:

  • Todas as tabelas provisionadas passem a ter os campos de metadados _ingestionDateTime, _extraAttributes e mdmCounterForEntity__DATETIME__ com description preenchido automaticamente;

  • As descrições sigam exatamente o padrão definido acima;

  • A documentação fique disponível diretamente no BigQuery e na Carol, sem necessidade de consulta externa.

Done

Details

Created: 21 January 2026, 12:58 Updated: 9 February 2026, 12:48