Testar tabelas com declarações

Este documento mostra como usar o núcleo do Dataform para criar asserções de tabela do Dataform e testar o código do fluxo de trabalho.

Sobre as declarações

Uma declaração é uma consulta de teste de qualidade de dados que encontra linhas que violam uma ou mais condições especificadas na consulta. Se a consulta retornar linhas, a declaração vai falhar. O Dataform executa declarações sempre que atualiza seu fluxo de trabalho SQL e alerta você se alguma delas falhar.

O Dataform cria automaticamente visualizações no BigQuery que contêm os resultados das consultas de declaração compiladas. Conforme configurado no arquivo de configurações do fluxo de trabalho, o Dataform cria essas visualizações em um esquema de declarações em que é possível inspecionar os resultados das declarações.

Por exemplo, para o esquema dataform_assertions padrão, o Dataform cria uma visualização no BigQuery com o 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.

É possível criar declarações das seguintes maneiras:

Antes de começar

  1. No Console do Google Cloud, acesse a página Dataform.

    Acesse a página do Dataform

  2. Selecione ou crie um repositório.

  3. Selecione ou crie um espaço de trabalho de desenvolvimento.

  4. Defina uma tabela.

Funções exigidas

Para receber as permissões necessárias para criar declarações, peça ao administrador que conceda a você o Papel do IAM de editor de formulário de dados (roles/dataform.editor) nos espaços de trabalho. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

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 cria a tabela, é possível conferir se a declaração foi transmitida na guia Logs de execução do fluxo de trabalho do seu espaço de trabalho.

É possível criar as seguintes declarações no bloco config de uma tabela:

  • nonNull

    Essa condição afirma que as colunas especificadas não são nulas em todas as linhas da tabela. Essa condição é usada para colunas que nunca podem ser nulas.

    O exemplo de código abaixo mostra uma declaração nonNull no bloco config de uma tabela:

config {
  type: "table",
  assertions: {
    nonNull: ["user_id", "customer_id", "email"]
  }
}
SELECT ...

  • rowConditions

    Essa condição afirma que todas as linhas da tabela seguem a lógica personalizada que você define. Cada condição de linha é uma expressão SQL personalizada, e cada linha da tabela é avaliada de acordo com cada condição de linha. A declaração falhará se qualquer linha de tabela resultar em false.

    O exemplo de código a seguir mostra uma declaração rowConditions personalizada no bloco config 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 afirma que, em uma coluna especificada, nenhuma linha da tabela tem o mesmo valor.

    O exemplo de código abaixo mostra uma declaração uniqueKey no bloco config de uma visualização:

config {
  type: "view",
  assertions: {
    uniqueKey: ["user_id"]
  }
}
SELECT ...

  • uniqueKeys

    Essa condição afirma que, nas colunas especificadas, nenhuma linha da tabela tem o mesmo valor. A declaração falha se houver mais de uma linha na tabela com os mesmos valores para todas as colunas especificadas.

    O exemplo de código abaixo mostra uma declaração uniqueKeys no bloco config 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:

  1. No espaço de trabalho de desenvolvimento, no painel Files, selecione um arquivo SQLX de definição de tabela.
  2. No bloco config do arquivo de tabela, insira assertions: {}.
  3. Em assertions: {}, adicione suas declarações.
  4. Opcional: clique em Formato.

O exemplo de código abaixo 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

As declarações manuais são consultas SQL gravadas 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 falhará.

Para adicionar declarações manuais em um novo arquivo SQLX, siga estas etapas:

  1. No painel Arquivos, ao lado de definitions/, clique no menu Mais.
  2. Selecione Criar arquivo.

  3. No campo Adicionar um caminho de arquivo, insira o nome do arquivo seguido de .sqlx. Por exemplo, definitions/custom_assertion.sqlx.

    Os nomes de arquivo só podem incluir números, letras, hifens e sublinhados.

  4. Selecione Criar arquivo.

  5. No painel Files, clique no novo arquivo.

  6. No arquivo, insira:

    config {
  type: "assertion"
}

  7. Abaixo do bloco config, escreva sua consulta SQL ou várias consultas.

  8. Opcional: clique em Formato.

O exemplo de código a seguir mostra uma declaração manual em um arquivo SQLX que afirma 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

Definir declarações como dependências

Quando a ação do fluxo de trabalho B depende da ação do fluxo de trabalho A que tem declarações, a falha das declarações da ação A não impede que o Dataform execute a ação B. Para executar a ação B somente se as declarações de ação A forem bem-sucedidas, é necessário definir as declarações de ação A como dependências da ação B.

É possível definir declarações como dependências de uma ação selecionada das seguintes maneiras:

Definir as declarações selecionadas como dependências

É possível definir manualmente as declarações selecionadas como dependências adicionando-as a dependencies: [ "" ] no bloco config da ação editada.

Por exemplo, se a ação B depender da ação A e você quiser que a ação B dependa apenas das declarações selecionadas da ação A, adicione essas declarações selecionadas ao bloco config da ação B.

É possível definir manualmente as declarações de dependências de algumas declarações de ação, exceto as declarações de fontes de dados.

Definir as declarações de uma ação de dependência selecionada como dependências

É possível definir o parâmetro includeDependentAssertions para definir automaticamente todas as declarações diretas de uma ação de fluxo de trabalho de dependência selecionada como dependências da ação editada. O Dataform adiciona essas declarações como dependências durante cada compilação da ação para garantir que as dependências estão atualizadas se as declarações da ação de dependência mudarem.

Por exemplo, se a ação C depender das ações A e B, mas você quiser que a ação C dependa apenas das declarações da ação A, é possível editar a ação C e definir o parâmetro includeDependentAssertions para definir automaticamente todas as declarações da ação A como dependências da ação C.

É possível definir o parâmetro includeDependentAssertions para ações dos seguintes tipos:

  • table
  • view
  • operations
Definir as declarações de todas as ações de dependência como dependências

É possível definir o parâmetro dependOnDependencyAssertions para definir automaticamente todas as declarações diretas de todas as ações de dependência da ação editada como dependências adicionais da ação editada. O Dataform adiciona essas declarações como dependências durante cada compilação da ação para garantir que as dependências estão atualizadas se as declarações da ação de dependência mudarem.

Por exemplo, se a ação C depender das ações A e B, você poderá editar a ação C e definir o parâmetro dependOnDependencyAssertions para definir automaticamente todas as declarações das ações A e B como dependências da ação C.

É possível definir o parâmetro dependOnDependencyAssertions para ações dos seguintes tipos:

  • table
  • view
  • operations

Quando você define os parâmetros dependOnDependencyAssertions e includeDependentAssertions em um único arquivo, o parâmetro includeDependentAssertions tem prioridade. Por exemplo, se você definir dependOnDependencyAssertions como true, mas também definir includeDependentAssertions como false para uma ação de dependência selecionada, o Dataform não vai adicionar declarações dessa ação às dependências.

O exemplo de código abaixo mostra os parâmetros dependOnDependencyAssertions e includeDependentAssertions definidos no mesmo arquivo de definição de tabela:

// filename is tableName.sqlx

config {
type: "table",
dependOnDependencyAssertions: true,
dependencies: [ "actionA", {name: "actionB", includeDependentAssertions: false} ]
}

SELECT * FROM ${ref("actionC")}

No exemplo de código anterior, o Dataform adiciona todas as declarações diretas de actionA e actionC às dependências de tableName durante a compilação.

Definir as declarações selecionadas como dependências

Para executar uma ação de fluxo de trabalho somente quando as declarações selecionadas forem bem-sucedidas, adicione a declaração selecionada a dependencies: [ "" ] no bloco config da ação editada.

Para definir uma declaração selecionada como uma dependência de uma ação de fluxo de trabalho selecionada, siga estas etapas:

  1. No espaço de trabalho de desenvolvimento, abra definitions/ no painel Files.
  2. Selecione um arquivo SQLX de ação do fluxo de trabalho.
  3. No bloco config do arquivo de ação, insira dependencies: [ "" ].

  4. Em dependencies: [ "" ], insira o nome da declaração de ação ou o nome de arquivo da declaração manual que você quer definir como uma dependência em um dos seguintes formatos:

    nonNull

    config {
  type: "ACTION_TYPE",
  dependencies: [ "ACTION_DATASET_NAME_ACTION_NAME_assertions_nonNull"]
}

    Substitua:

    • ACTION_TYPE: o tipo de ação do fluxo de trabalho: table, view ou operations.
    • ACTION_DATASET_NAME: o nome do conjunto de dados em que a ação é definida. O conjunto de dados padrão é definido no arquivo de configurações do fluxo de trabalho.
    • ACTION_NAME: o nome da ação em que a declaração é definida.

    rowConditions

    config {
  type: "ACTION_TYPE",
  dependencies: [ "ACTION_DATASET_NAME_ACTION_NAME_assertions_rowConditions"]
}

    Substitua:

    • ACTION_TYPE: o tipo de ação do fluxo de trabalho: table, view ou operations.
    • DATASET_NAME: o nome do conjunto de dados em que a ação é definida. O conjunto de dados padrão é definido no arquivo de configurações do fluxo de trabalho.
    • ACTION_NAME: o nome da ação em que a declaração é definida.

    uniqueKey

    config {
  type: "ACTION_TYPE",
  dependencies: [ "ACTION_DATASET_NAME_ACTION_NAME_assertions_uniqueKey_INDEX"]
}

    Substitua:

    • ACTION_TYPE: o tipo de ação do fluxo de trabalho: table, view ou operations.
    • DATASET_NAME: o nome do conjunto de dados em que a tabela é definida. O conjunto de dados padrão é definido no arquivo de configurações do fluxo de trabalho.
    • ACTION_NAME: o nome da tabela em que a declaração é definida.
    • INDEX: o índice da matriz de chaves definidas na asserção uniqueKey que você quer adicionar como uma dependência. Por exemplo, 0 ou 1. Se apenas uma matriz de chaves for definida na declaração, o índice será 0.

    uniqueKeys

    config {
  type: "ACTION_TYPE",
  dependencies: [ "ACTION_DATASET_NAME_ACTION_NAME_assertions_uniqueKeys_INDEX"]
}

    Substitua:

    • ACTION_TYPE: o tipo de ação do fluxo de trabalho: table, view ou operations.
    • DATASET_NAME: o nome do conjunto de dados em que a tabela é definida. O conjunto de dados padrão é definido no arquivo de configurações do fluxo de trabalho.
    • ACTION_NAME: o nome da tabela em que a declaração é definida.
    • INDEX: o índice da matriz de chaves definidas na asserção uniqueKeys que você quer adicionar como uma dependência, por exemplo, 0 ou 1. Se apenas uma matriz de chaves for definida na declaração, o índice será 0.

    declaração manual

    config {
  type: "ACTION_TYPE",
  dependencies: [ "MANUAL_ASSERTION_NAME"]
}

    Substitua:

    • ACTION_TYPE: o tipo de ação do fluxo de trabalho: table, view ou operations.
    • MANUAL_ASSERTION_NAME o nome da declaração manual.

  5. Para adicionar outra declaração como uma dependência à tabela editada, repita a etapa 4.

  6. Opcional: clique em Formato.

O exemplo de código a seguir mostra as declarações adicionadas à tabela A, definida 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 da tabela A adicionadas como dependências à tabela B:

config {
  type: "table",
  dependencies: [ "dataform_A_assertions_uniqueKey_0",  "dataform_A_assertions_nonNull"]
}

O exemplo de código a seguir mostra uma declaração manual definida no arquivo manualAssertion.sqlx, adicionado como uma dependência a uma visualização:

config {
  type: "view",
  dependencies: [ "manualAssertion"]
}

O exemplo de código a seguir mostra o arquivo manual_assertion e as asserçõ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 ...

Definir declarações de uma ação selecionada como dependências

Para executar uma ação de fluxo de trabalho somente quando todas as declarações diretas de uma ação de dependência selecionada forem bem-sucedidas, defina o parâmetro includeDependentAssertions como true na ação editada. O Dataform adiciona automaticamente declarações diretas da ação de dependência selecionada às dependências durante a compilação. O valor padrão é false.

Para definir todas as declarações de uma ação de dependência selecionada como dependências, siga estas etapas:

  1. No espaço de trabalho de desenvolvimento, abra definitions/ no painel Files.
  2. Selecione um arquivo SQLX de ação do fluxo de trabalho.

  3. No arquivo, defina o parâmetro includeDependentAssertions como true de uma das seguintes maneiras:

    No bloco config

    config {
type: "ACTION_TYPE",
dependencies: [{name: "dEPENDENCY_ACTION_NAME", includeDependentAssertions: true}]
}

    Substitua:

    • ACTION_TYPE: o tipo de ação do fluxo de trabalho: table, view ou operations.
    • DEPENDENCY_ACTION_NAME: o nome da ação de dependência que você quer definir como dependências da ação editada.

    Na instrução SELECT

      config { type: "ACTION_TYPE" }

  SELECT * FROM ${ref({name: "DEPENDENCY_ACTION_NAME", includeDependentAssertions: true})}

    Substitua:

    • ACTION_TYPE: o tipo de ação do fluxo de trabalho: table, view ou operations.
    • DEPENDENCY_ACTION_NAME: o nome da ação de dependência que você quer definir como dependências da ação editada.

  4. Opcional: clique em Formato.

O exemplo de código abaixo mostra tableC que depende de viewA, tableB e todas as declarações de tableB:

// filename is tableC.sqlx

config {
type: "table",
dependencies: ["viewA", {name: "tableB", includeDependentAssertions: true}]
}

SELECT * FROM ...

No exemplo de código anterior, o Dataform adiciona automaticamente todas as afirmações diretas de tableB como dependências a tableC durante a compilação.

Definir as declarações de todas as ações de dependência como dependências

Para executar uma ação de fluxo de trabalho somente quando todas as declarações diretas de todas as ações de dependência forem bem-sucedidas, defina o parâmetro dependOnDependencyAssertions como true na ação editada. O Dataform adiciona automaticamente declarações diretas de ações de dependência como dependências durante a compilação. O valor padrão é false.

Quando você define o parâmetro dependOnDependencyAssertions e os parâmetros includeDependentAssertions em um único arquivo, o parâmetro includeDependentAssertions tem prioridade para a ação de dependência para a qual ele foi definido.

Para definir todas as declarações de uma ação de dependência selecionada como dependências, siga estas etapas:

  1. No espaço de trabalho de desenvolvimento, abra definitions/ no painel Files.
  2. Selecione um arquivo SQLX de ação do fluxo de trabalho.

  3. No arquivo, defina o parâmetro dependOnDependencyAssertions como true no seguinte formato:

    config {
type: "ACTION_TYPE",
dependOnDependencyAssertions: true,
dependencies: [ "dependency1", "dependency2" ]
}

    Substitua ACTION_TYPE: o tipo de ação do fluxo de trabalho. Os valores aceitos incluem table, view e operations.

  4. Opcional: clique em Formato.

O exemplo de código abaixo mostra sometableE que depende de sometableA, sometabletableB, sometableC e sometableD e todas as afirmações diretas de tabelas de dependência:

// filename is sometableE.sqlx

config {
type: "table",
dependOnDependencyAssertions: true,
dependencies: [ "sometableA", "sometableB" ]
}

SELECT * FROM ${ref("sometableC")}
SELECT * FROM ${ref("sometableD")}

No exemplo de código anterior, o Dataform adiciona automaticamente todas as declarações diretas de sometableA, sometableB, sometableC e sometableD como dependências de sometableE durante a compilação.

A seguir