CAPL-8686
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 |
|---|---|
|
|
Data/hora em microssegundos de quando o dado foi recebido pela plataforma Carol. Registros enviados na mesma requisição recebem o mesmo valor. |
|
|
Identificador único do registro, determinado pelos valores dos atributos definidos no crosswalk (chave primária) da staging table. |
|
|
Data/hora de criação do registro. Como a Carol trata os dados de forma imutável, recebe o mesmo valor de |
|
|
Data/hora da última atualização do registro. Como a Carol trata os dados de forma imutável, recebe o mesmo valor de |
|
|
Identificador interno da tenant proprietária do dado (tenant "dona" do registro). |
|
|
Identificador do conector ao qual o registro pertence. |
|
|
Concatenação do |
|
|
Indica logicamente se o registro foi excluído ( |
|
|
Chave de auditoria única gerada durante o recebimento dos dados pela Carol, permitindo rastreamento e recuperação de logs. |
|
|
Identificador do batch enviado pelo SmartLink. Inicialmente compatível apenas com a linha de produto Protheus (Release Outubro/2023). |
|
|
Sequência do batch enviado pelo SmartLink. Inicialmente compatível apenas com a linha de produto Protheus (Release Outubro/2023). |
|
|
Representação em formato datetime do atributo |
|
|
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 |
|---|---|
|
|
Data/hora em microssegundos de quando o golden record foi processado pelo motor de SQL Processing. |
|
|
Data/hora em microssegundos de quando o registro foi recebido na camada de staging da plataforma Carol. |
|
|
Identificador único do golden record, gerado a partir do |
|
|
Data/hora de criação do golden record. Como a Carol trata os dados de forma imutável, recebe o mesmo valor de |
|
|
Data/hora da última atualização do golden record. Como a Carol trata os dados de forma imutável, recebe o mesmo valor de |
|
|
Identificador interno da tenant proprietária do dado (tenant "dona" do registro). |
|
|
Nome do data model com o sufixo |
|
|
Identificação do conector e da staging table de origem, referenciada na pipeline SQL pelo alias |
|
|
Conteúdo utilizado no cálculo da chave interna do registro (mdmId). O preenchimento/manutenção deste atributo é de responsabilidade da pipeline SQL Processing. |
|
|
Lista de identificadores ( |
|
|
Atributo legado, sem uso funcional atual. Está em processo de depreciação. |
|
|
Atributo legado, sem uso funcional atual. Está em processo de depreciação. |
|
|
Indica logicamente se o golden record foi excluído ( |
|
|
Representação datetime do atributo |
|
|
Data/hora em que o golden record foi efetivamente gravado no BigQuery. É a partição padrão dos data models. |
|
|
Identificador de auditoria do registro de staging associado. Para ser preenchido, a pipeline deve utilizar a tag |
|
|
Identificador da task responsável por gerar o golden record. Contém internamente a versão da pipeline executada. |
|
|
Identificador do batch proveniente do registro da staging table. Para ser preenchido, a pipeline deve utilizar a tag |
|
|
Sequência do batch proveniente do registro da staging table. Para ser preenchido, a pipeline deve utilizar a tag |
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 com
descriptionpreenchido 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.