Sobre as declarações
Uma declaração é uma consulta de teste de qualidade de dados que encontra linhas que violam uma ou mais regras especificadas na consulta. Se a consulta retornar alguma linha, a declaração falhará. O Dataform executa declarações sempre que atualiza o fluxo de trabalho SQL e avisa se alguma declaração falhar.
O Dataform cria automaticamente visualizações no BigQuery que contêm os resultados de consultas de declaração compiladas. Conforme configurado no arquivo dataform.json, o Dataform cria essas visualizações em um esquema de declarações em que é possível inspecionar os resultados da declaração.
Por exemplo, para o esquema dataform_assertions
padrão, o Dataform
cria uma visualização no BigQuery no seguinte formato:
dataform_assertions.assertion_name
.
É possível criar declarações para todos os tipos de tabela do Dataform: tabelas, tabelas incrementais, visualizações e visualizações materializadas.
Você pode criar declarações das seguintes maneiras:
Adicione declarações integradas ao bloco de configuração de uma tabela.
É possível adicionar declarações integradas ao bloco
config
de uma tabela e especificar as condições.Adicione declarações manuais em um arquivo SQLX separado.
Você grava manualmente declarações personalizadas em um arquivo SQLX separado para casos de uso avançados ou conjuntos de dados não criados pelo Dataform.
Antes de começar
No console do Google Cloud, acesse a página do Dataform.
Selecione ou crie um repositório.
Selecione ou crie um espaço de trabalho de desenvolvimento.
Funções exigidas
Para receber as permissões necessárias para criar declarações,
peça ao administrador para conceder a você o papel do IAM de
Editor do Dataform (roles/dataform.editor
) nos espaços de trabalho.
Para mais informações sobre como conceder papéis, consulte Gerenciar acesso.
Também é possível conseguir as permissões necessárias por meio de papéis personalizados ou de outros papéis predefinidos.
Criar declarações integradas
É possível adicionar declarações integradas do Dataform ao bloco config
de uma
tabela. O Dataform executa essas declarações após a criação da tabela. Depois que o Dataform publica a tabela, é possível inspecionar a declaração.
É possível criar as seguintes declarações no bloco config
de uma tabela:
nonNull
Essa condição declara que as colunas especificadas não são nulas em todas as linhas da tabela. Esta condição é usada para colunas que jamais podem ser nulas.
O exemplo de código a seguir mostra uma declaração
nonNull
no blococonfig
de uma tabela:
config {
type: "table",
assertions: {
nonNull: ["user_id", "customer_id", "email"]
}
}
SELECT ...
rowConditions
Essa condição declara que todas as linhas da tabela seguem a lógica personalizada que você definiu. Cada condição de linha é uma expressão SQL personalizada, e cada linha da tabela é avaliada em relação a cada condição de linha. A declaração falhará se alguma linha da tabela violar qualquer condição de linha.
O exemplo de código abaixo mostra uma declaração
rowConditions
personalizada no blococonfig
de uma tabela incremental:
config {
type: "incremental",
assertions: {
rowConditions: [
'signup_date is null or signup_date > "2022-08-01"',
'email like "%@%.%"'
]
}
}
SELECT ...
uniqueKey
Essa condição declara que, em uma coluna especificada, nenhuma linha da tabela tem o mesmo valor.
O exemplo de código a seguir mostra uma declaração
uniqueKey
no blococonfig
de uma visualização:
config {
type: "view",
assertions: {
uniqueKey: ["user_id"]
}
}
SELECT ...
uniqueKeys
Essa condição declara que, nas colunas especificadas, nenhuma linha da tabela tem o mesmo valor. A declaração falhará se houver mais de uma linha na tabela com os mesmos valores para todas as colunas especificadas.
O exemplo de código a seguir mostra uma declaração
uniqueKeys
no blococonfig
de uma tabela:
config {
type: "table",
assertions: {
uniqueKeys: [["user_id"], ["signup_date", "customer_id"]]
}
}
SELECT ...
Adicionar declarações ao bloco config
Para adicionar declarações ao bloco de configuração de uma tabela, siga estas etapas:
- No espaço de trabalho de desenvolvimento, no painel Arquivos, selecione um arquivo SQLX de definição de tabela.
- No bloco
config
do arquivo da tabela, insiraassertions: {}
. - Dentro de
assertions: {}
, adicione suas declarações. - Opcional: clique em Formatar.
O exemplo de código a seguir mostra as condições adicionadas no bloco config
:
config {
type: "table",
assertions: {
uniqueKey: ["user_id"],
nonNull: ["user_id", "customer_id"],
rowConditions: [
'signup_date is null or signup_date > "2019-01-01"',
'email like "%@%.%"'
]
}
}
SELECT ...
Criar declarações manuais com SQLX
Declarações manuais são consultas SQL que você escreve em um arquivo SQLX dedicado. Uma consulta SQL de declaração manual precisa retornar zero linhas. Se a consulta retornar linhas quando executada, a declaração vai falhar.
Para adicionar declarações manuais em um novo arquivo SQLX, siga estas etapas:
- No painel Files, ao lado de
definitions/
, clique no menu More. - Clique em Criar arquivo.
No campo Adicionar um caminho de arquivo, insira o nome do arquivo seguido de
.sqlx
. Por exemplo,definitions/custom_assertion.sqlx
.Os nomes de arquivos podem incluir apenas números, letras, hifens e sublinhados.
Clique em Criar arquivo.
No painel Arquivos, clique no novo arquivo.
No arquivo, digite:
config { type: "assertion" }
Abaixo do bloco
config
, escreva sua consulta SQL ou várias.Opcional: clique em Formatar.
O exemplo de código a seguir mostra uma declaração manual em um arquivo SQLX que declara
que os campos a
, b
e c
nunca são NULL
em sometable
:
config { type: "assertion" }
SELECT
*
FROM
${ref("sometable")}
WHERE
a IS NULL
OR b IS NULL
OR c IS NULL
Adicionar declarações como dependências
Quando a tabela B
depende da tabela A
que tem declarações, a falha das declarações A
da tabela não impede que o Dataform crie a tabela B
. Para executar
a tabela B
somente se as declarações A
da tabela forem transmitidas, adicione essas declarações como
dependências a dependencies: [ "" ]
no bloco config
da tabela B
.
O exemplo de código a seguir mostra declarações adicionadas à tabela A
no conjunto de dados dataform
:
config {
type: "table",
assertions: {
uniqueKey: ["user_id"],
nonNull: ["user_id", "customer_id"],
}
}
O exemplo de código a seguir mostra as declarações A
da tabela adicionadas como dependências
à tabela B
:
config {
type: "table",
dependencies: [ "dataform_A_assertions_uniqueKey_0", "dataform_A_assertions_nonNull"]
}
Para executar uma tabela somente quando determinadas declarações manuais forem transmitidas, adicione o
arquivo SQLX de declaração manual a dependencies: [ "" ]
no bloco config
.
O exemplo de código abaixo mostra uma declaração manual definida no
arquivo manualAssertion
, adicionada como dependência a uma visualização:
config {
type: "view",
dependencies: [ "manualAssertion"]
}
Para adicionar um arquivo de declaração ou uma tabela com declarações no bloco config
como uma
dependência de tabela, siga estas etapas:
- No espaço de trabalho de desenvolvimento, no painel Files, expanda
definitions/
. - Selecione um arquivo SQLX da tabela.
- No bloco
config
do arquivo da tabela, insiradependencies: [ "" ]
. - Dentro de
dependencies: [ "" ]
, insira o nome da declaração da tabela ou o nome do arquivo da declaração manual que você quer definir como dependência em um dos seguintes formatos:
nonNull
config {
type: "table",
dependencies: [ "TABLE_DATASET_NAME_TABLE_NAME_assertions_nonNull"]
}
Substitua:
- DATASET_NAME pelo nome do conjunto de dados em que a tabela está definida.
O conjunto de dados padrão é definido no
workflow_settings.yaml file
. - TABLE_NAME pelo nome da tabela em que a declaração está definida.
rowConditions
config {
type: "table",
dependencies: [ "TABLE_DATASET_NAME_TABLE_NAME_assertions_rowConditions"]
}
Substitua:
- DATASET_NAME pelo nome do conjunto de dados em que a tabela está definida.
O conjunto de dados padrão é definido no
workflow_settings.yaml file
. - TABLE_NAME pelo nome da tabela em que a declaração está definida.
uniqueKey
config {
type: "table",
dependencies: [ "TABLE_DATASET_NAME_TABLE_NAME_assertions_uniqueKey_INDEX"]
}
Substitua:
- DATASET_NAME pelo nome do conjunto de dados em que a tabela está definida.
O conjunto de dados padrão é definido no
workflow_settings.yaml file
. - TABLE_NAME pelo nome da tabela em que a declaração está definida.
- INDEX pelo índice da matriz de chaves definida na
declaração
uniqueKey
que você quer adicionar como dependência. Por exemplo,0
ou1
. Se apenas uma matriz de chaves for definida na declaração, o índice será0
.
uniqueKeys
config {
type: "table",
dependencies: [ "TABLE_DATASET_NAME_TABLE_NAME_assertions_uniqueKeys_INDEX"]
}
Substitua:
- DATASET_NAME pelo nome do conjunto de dados em que a tabela está definida.
O conjunto de dados padrão é definido no
workflow_settings.yaml file
. - TABLE_NAME pelo nome da tabela em que a declaração está definida.
- INDEX pelo índice da matriz de chaves definida na
declaração
uniqueKeys
que você quer adicionar como dependência. Por exemplo,0
ou1
. Se apenas uma matriz de chaves for definida na declaração, o índice será0
.
declaração manual
config {
type: "table",
dependencies: [ "MANUAL_ASSERTION_NAME"]
}
Substitua:
- MANUAL_ASSERTION_NAME é o nome da declaração manual.
- Para adicionar outra declaração como uma dependência da tabela editada, repita a Etapa 4.
- Opcional: clique em Formatar.
O exemplo de código a seguir mostra o arquivo manual_assertion
e as declarações da tabela sometable
adicionadas como dependências a uma tabela:
config {
type: "table",
dependencies: [ "manual_assertion", "dataform_sometable_assertions_nonNull" , "dataform_sometable_assertions_rowConditions"]
}
SELECT * FROM ${ref("referenced_table")} LEFT JOIN ...
A seguir
- Para saber mais sobre os tipos de declaração, consulte API Dataform.
- Para saber como definir declarações com JavaScript, consulte Criar fluxos de trabalho SQL com JavaScript.
- Para saber como executar fluxos de trabalho manualmente, consulte Execução do gatilho.