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 por meio de papéis personalizados ou de 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 primeiro some_table e depois 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 asserçõ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 asserções selecionadas da ação A, adicione essas asserçõ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 origem de dados.

Definir as declaraçõ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 declarações da ação A, edite a ação C e defina 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
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 asserçõ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, é possível 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 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 as declaraçõ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 uma 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 declaraçã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 declaraçã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"],
  }
}

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 asserção manual definida no arquivo manualAssertion.sqlx e adicionada 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 as asserções de uma ação selecionada como dependências

Para executar uma ação de fluxo de trabalho somente quando todas as asserções diretas de uma ação de dependência selecionada forem aprovadas, defina o parâmetro includeDependentAssertions como true na ação editada. O Dataform adiciona automaticamente as asserçõ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 asserções de uma ação de dependência selecionada como dependências, 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 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 com as asserções 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 com as asserções que você quer definir como dependências da ação editada.

  4. Opcional: clique em Formatar.

O exemplo de código a seguir mostra tableC, que depende de viewA, tableB e todas as asserçõ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 asserções diretas de tableB como dependências de tableC durante a compilação.

Defina as asserçõ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 asserções diretas de todas as ações de dependência forem aprovadas, defina o parâmetro dependOnDependencyAssertions como true na ação editada. O Dataform adiciona automaticamente as asserções diretas das 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 em que ele está definido.

Para definir todas as asserções de uma ação de dependência selecionada como dependências, 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 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 são table, view e operations.

  4. Opcional: clique em Formatar.

O exemplo de código a seguir mostra sometableE, que depende de sometableA, sometabletableB, sometableC, sometableD e todas as asserções diretas das 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 asserções diretas de sometableA, sometableB, sometableC e sometableD como dependências de sometableE durante a compilação.

Referenciar uma tabela com um nome substituído

  • Para fazer referência a uma tabela com um nome substituído, na função ref, insira o nome substituído definido em name: "".

O exemplo de código a seguir faz referência a uma tabela com um nome substituído por overridden_name:

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

Para mais informações sobre como substituir nomes de tabelas, consulte Substituir configurações de tabela.

A seguir