Definir dependências

Neste documento, mostramos como definir a relação entre objetos no fluxo de trabalho do Dataform declarando dependências.

É possível definir uma relação de dependência entre objetos de um fluxo de trabalho. Em uma relação de dependência, a execução de um objeto depende da execução de outro. Isso significa que o Dataform executa o dependente depois da dependência. Para definir a relação, declare dependências no arquivo de definição SQLX do objeto dependente.

As declarações de dependência formam uma árvore de dependências do fluxo de trabalho que determina a ordem em que o Dataform executa as ações.

É possível definir a relação de dependência entre as seguintes ações de fluxo de trabalho:

Declarações de fonte de dados
Declarações de fontes de dados do BigQuery que permitem referenciar essas fontes em definições de tabelas do Dataform e operações SQL. É possível definir uma declaração de fonte de dados como uma dependência, mas não como um dependente.
Tabelas
Tabelas criadas no Dataform com base nas fontes de dados declaradas ou em outras tabelas no seu fluxo de trabalho. O Dataform é compatível com os seguintes tipos de tabelas: tabela, tabela incremental, visualização e visualização materializada. É possível definir uma tabela como dependência e como dependente.
Operações SQL personalizadas
Instruções SQL que o Dataform executa no BigQuery sem modificação. É possível definir uma operação SQL personalizada definida em um arquivo type: operations como uma dependência e como um dependente. Para declarar uma operação SQL personalizada como uma dependência na função ref, defina a propriedade hasOutput como true no arquivo de definição SQLX da operação SQL personalizada
.
Declarações
Consultas de teste de qualidade de dados que podem ser usadas para testar dados de tabelas. O Dataform executa declarações sempre que atualiza seu fluxo de trabalho e alerta você se alguma declaração falhar. É possível definir uma asserção definida em um arquivo type: assertion como uma dependência e como um dependente declarando dependências no bloco config.

É possível definir a relação de dependência das seguintes maneiras:

Antes de começar

  1. Crie e inicialize um espaço de trabalho de desenvolvimento no seu repositório.
  2. Opcional: declarar uma fonte de dados.
  3. Crie pelo menos duas ações de fluxo de trabalho: tabelas, asserções, declarações de fonte de dados ou operações.

Funções exigidas

Para receber as permissões necessárias para declarar dependências de tabelas, asserções, declarações de fonte de dados e operações SQL personalizadas, peça ao administrador que conceda a você o papel do IAM Editor do Dataform (roles/dataform.editor) em 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 usando papéis personalizados ou outros papéis predefinidos.

Declarar uma dependência como um argumento da função ref

Para referenciar e declarar automaticamente uma dependência em uma instrução SELECT, adicione a dependência como um argumento da função ref.

A função ref é uma função integrada do núcleo do Dataform que permite referenciar e depender automaticamente de qualquer tabela, declaração de fonte de dados ou operação SQL personalizada com a propriedade hasOutput definida como true no seu fluxo de trabalho.

Para mais informações sobre a função ref, consulte Referência de métodos de contexto principal do Dataform.

Para mais informações sobre como usar a função ref em uma definição de tabela, consulte Sobre definições de tabela.

O exemplo de código a seguir mostra a declaração da fonte de dados source_data adicionada como um argumento da função ref no arquivo de definição incremental_table.sqlx SQLX de uma tabela incremental:

// filename is incremental_table.sqlx

config { type: "incremental" }

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

No exemplo de código anterior, source_data é declarado automaticamente como uma dependência de incremental_table.

O exemplo de código a seguir mostra o arquivo SQLX de definição de tabela some_table adicionado como um argumento da função ref no arquivo de definição custom_assertion.sqlx SQLX de uma asserção:

// filename is custom_assertion.sqlx

config { type: "assertion" }

SELECT
  *
FROM
  ${ref("some_table")}
WHERE
  a is null
  or b is null
  or c is null

No exemplo de código anterior, some_table é declarado automaticamente como uma dependência de custom_assertion. Durante a execução, o Dataform executa some_table primeiro e, em seguida, custom_assertion quando some_table é criado.

Declarar dependências no bloco config

Para declarar dependências que não são referenciadas na definição da instrução SQL do dependente, mas precisam ser executadas antes da tabela, da asserção ou da operação SQL personalizada, siga estas etapas:

  1. No espaço de trabalho de desenvolvimento, no painel Arquivos, abra o diretório definitions/.
  2. Selecione a tabela, a asserção ou o arquivo SQLX de operação SQL personalizada que você quer editar.

  3. No bloco config do arquivo, insira o seguinte snippet de código:

    dependencies: [ "DEPENDENCY", ]

    Substitua DEPENDENCY pela string de destino, por exemplo, o nome do arquivo da ação que você quer adicionar como uma dependência. É possível inserir vários destinos separados por vírgulas.

  4. Opcional: clique em Formatar.

O exemplo de código a seguir mostra a tabela some_table e a asserção some_assertion adicionadas como dependências ao bloco config de um arquivo de definição de tabela:

config { dependencies: [ "some_table", "some_assertion" ] }

Definir asserções como dependências

Quando a ação de fluxo de trabalho B depende da ação A, que tem asserções, a falha das asserçõ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 da ação A forem aprovadas, defina as declarações da ação A como dependências da ação B.

É possível definir asserçõ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 à linha 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 asserções selecionadas como dependências para todos os tipos de ação, exceto declarações de fonte de dados.

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

Você pode definir o parâmetro includeDependentAssertions para definir automaticamente todas as asserçõ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 verificar se as dependências estão atualizadas caso as declarações da ação de dependência mudem.

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 asserções da ação A, edite a ação C e defina o parâmetro includeDependentAssertions para definir automaticamente todas as asserçõ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
Defina as asserções de todas as ações de dependência como dependências

Você pode 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 asserções como dependências durante cada compilação da ação para verificar se as dependências estão atualizadas caso as asserções da ação de dependência mudem.

Por exemplo, se a ação C depende das ações A e B, edite a ação C e defina 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 o parâmetro dependOnDependencyAssertions e os parâmetros 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 as declarações dessa ação às dependências.

O exemplo de código a seguir 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 asserções diretas de actionA e actionC às dependências de tableName durante a compilação.

Definir asserções selecionadas como dependências

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

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

  1. No espaço de trabalho de desenvolvimento, no painel Arquivos, abra definitions/.
  2. Selecione um arquivo SQLX de ação de 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 do 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:

    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 está 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 asserção é definida.
    • INDEX: o índice da matriz de chaves definida 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 está 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 asserção é definida.
    • INDEX: o índice da matriz de chaves definida 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 Formatar.

O exemplo de código a seguir mostra asserções adicionadas à tabela A, que é definida no conjunto de dados dataform:

config {
  type: "table",
  assertions: {
    uniqueKey: ["user_id"],
    nonNull: ["user_id", "customer_id"],
  }
}