Defina dependências

Este documento mostra como definir a relação entre objetos no seu fluxo de trabalho no Dataform declarando dependências.

Pode definir uma relação de dependência entre objetos de um fluxo de trabalho. Numa relação de dependência, a execução do objeto dependente depende da execução do objeto de dependência. Isto significa que o Dataform executa o dependente após a dependência. Pode definir a relação declarando dependências no ficheiro de definição SQLX do objeto dependente.

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

Pode definir a relação de dependência entre as seguintes ações do fluxo de trabalho:

Declarações de origens de dados
Declarações de origens de dados do BigQuery que lhe permitem referenciar estas origens de dados em definições de tabelas do Dataform e operações SQL. Pode definir uma declaração de origem de dados como uma dependência, mas não como um dependente.
Tabelas
Tabelas que cria no Dataform com base nas origens de dados declaradas ou noutras tabelas no seu fluxo de trabalho. O Dataform suporta os seguintes tipos de tabelas: tabela, tabela incremental, vista e vista materializada. Pode definir uma tabela como uma dependência e como um dependente.
Operações SQL personalizadas
Declarações SQL que o Dataform executa no BigQuery tal como estão, sem modificações. Pode definir uma operação SQL personalizada definida num ficheiro 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, tem de definir a propriedade hasOutput como true no ficheiro de definição SQLX da operação SQL personalizada.
Afirmações
Consultas de teste de qualidade de dados que pode usar para testar dados de tabelas. O Dataform executa validações sempre que atualiza o fluxo de trabalho e envia-lhe um alerta se alguma validação falhar. Pode definir uma afirmação definida num ficheiro type: assertion como uma dependência e como um dependente declarando dependências no bloco config.

Pode definir a relação de dependência das seguintes formas:

Antes de começar

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

Funções necessárias

Para receber as autorizações de que precisa para declarar dependências para tabelas, afirmações, declarações de origens de dados e operações SQL personalizadas, peça ao seu administrador para lhe conceder a função do IAM Editor do Dataform (roles/dataform.editor) nos espaços de trabalho. Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

Também pode conseguir as autorizações necessárias através de funções personalizadas ou outras funções predefinidas.

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

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

A função ref é uma função integrada do Dataform core que lhe permite fazer referência e depender automaticamente de qualquer tabela, declaração de origem de dados ou operação SQL personalizada com a propriedade hasOutput definida como true no seu fluxo de trabalho.

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

Para mais informações sobre a utilização da função ref numa definição de tabela, consulte o artigo Acerca das definições de tabelas.

O exemplo de código seguinte mostra a declaração da origem de dados source_data adicionada como um argumento da função ref no ficheiro 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 seguinte mostra o ficheiro SQLX de definição da tabela some_table adicionado como um argumento da função ref no ficheiro de definição SQLX de uma afirmação:custom_assertion.sqlx

// 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, executa custom_assertion assim que some_table é criado.

Declare dependências no bloco config

Para declarar dependências que não são referenciadas na definição da declaração SQL do dependente, mas que têm de ser executadas antes da tabela, da afirmação ou da operação SQL personalizada, siga estes passos:

  1. No espaço de trabalho de desenvolvimento, no painel Ficheiros, expanda o diretório definitions/.
  2. Selecione o ficheiro SQLX da tabela, da afirmação ou da operação SQL personalizada que quer editar.

  3. No bloco config do ficheiro, introduza o seguinte fragmento do código:

    dependencies: [ "DEPENDENCY", ]

    Substitua DEPENDENCY pela string de destino, por exemplo, o nome do ficheiro da ação que quer adicionar como dependência. Pode introduzir vários alvos, separados por vírgulas.

  4. Opcional: clique em Formatar.

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

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

Defina afirmações como dependências

Quando a ação do fluxo de trabalho B depende da ação do fluxo de trabalho A, que tem asserções, a falha das asserções da ação A não impede o Dataform de executar a ação B. Para executar a ação B apenas se as afirmações da ação A forem aprovadas, tem de definir as afirmações da ação A como dependências da ação B.

Pode definir afirmações como dependências de uma ação selecionada das seguintes formas:

Defina as afirmações selecionadas como dependências

Pode definir manualmente as afirmaçõ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 quiser que a ação B dependa apenas das afirmações selecionadas da ação A, pode adicionar essas afirmações selecionadas ao bloco config da ação B.

Pode definir manualmente as afirmações selecionadas como dependências para todos os tipos de ações, exceto declarações de origens de dados.

Defina as afirmações de uma ação de dependência selecionada como dependências

Pode definir o parâmetro includeDependentAssertions para definir automaticamente todas as afirmações diretas de uma ação de fluxo de trabalho de dependência selecionada como dependências da ação editada. O Dataform adiciona estas afirmações como dependências durante cada compilação da ação para verificar se as dependências estão atualizadas se as afirmações da ação de dependência mudarem.

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

Pode definir o parâmetro includeDependentAssertions para ações dos seguintes tipos:

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

Pode definir o parâmetro dependOnDependencyAssertions para definir automaticamente todas as afirmaçõ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 estas afirmações como dependências durante cada compilação da ação para verificar se as dependências estão atualizadas se as afirmações da ação de dependência mudarem.

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

Pode definir o parâmetro dependOnDependencyAssertions para ações dos seguintes tipos:

  • table
  • view
  • operations

Quando define o parâmetro dependOnDependencyAssertions e os parâmetros includeDependentAssertions num único ficheiro, o parâmetro includeDependentAssertions tem prioridade. Por exemplo, se definir dependOnDependencyAssertions como true, mas também definir includeDependentAssertions como false para uma ação de dependência selecionada, o Dataform não adiciona as afirmações dessa ação às dependências.

O exemplo de código seguinte mostra os parâmetros dependOnDependencyAssertions e includeDependentAssertions definidos no mesmo ficheiro de definição da 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 afirmações diretas de actionA e actionC às dependências de tableName durante a compilação.

Defina as afirmações selecionadas como dependências

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

Para definir uma afirmação selecionada como uma dependência de uma ação de fluxo de trabalho selecionada, siga estes passos:

  1. No espaço de trabalho de desenvolvimento, no painel Ficheiros, expanda definitions/.
  2. Selecione um ficheiro SQLX de ação do fluxo de trabalho.
  3. No bloco config do ficheiro de ações, introduza dependencies: [ "" ].

  4. Em dependencies: [ "" ], introduza o nome da declaração de ação ou o nome do ficheiro da declaração manual que quer definir como uma dependência num dos seguintes formatos:

    nonNull

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

    Substitua o seguinte:

    • ACTION_TYPE: o tipo de ação do fluxo de trabalho: table, view ou operations.
    • ACTION_DATASET_NAME: o nome do conjunto de dados no qual a ação está definida. O conjunto de dados predefinido é definido no ficheiro de definições do fluxo de trabalho.
    • ACTION_NAME: o nome da ação na qual a declaração está definida.

    rowConditions

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

    Substitua o seguinte:

    • ACTION_TYPE: o tipo de ação do fluxo de trabalho: table, view ou operations.
    • DATASET_NAME: o nome do conjunto de dados no qual a ação está definida. O conjunto de dados predefinido é definido no ficheiro de definições do fluxo de trabalho.
    • ACTION_NAME: o nome da ação na qual a afirmação está definida.

    uniqueKey

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

    Substitua o seguinte:

    • ACTION_TYPE: o tipo de ação do fluxo de trabalho: table, view ou operations.
    • DATASET_NAME: o nome do conjunto de dados no qual a tabela está definida. O conjunto de dados predefinido é definido no ficheiro de definições do fluxo de trabalho.
    • ACTION_NAME: o nome da tabela na qual a afirmação está definida.
    • INDEX: o índice da matriz de chaves definida na declaração uniqueKey que quer adicionar como dependência, por exemplo, 0 ou 1. Se apenas for definido um conjunto de chaves na declaração, o índice é 0.

    uniqueKeys

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

    Substitua o seguinte:

    • ACTION_TYPE: o tipo de ação do fluxo de trabalho: table, view ou operations.
    • DATASET_NAME: o nome do conjunto de dados no qual a tabela está definida. O conjunto de dados predefinido é definido no ficheiro de definições do fluxo de trabalho.
    • ACTION_NAME: o nome da tabela na qual a afirmação está definida.
    • INDEX: o índice da matriz de chaves definida na declaração uniqueKeys que quer adicionar como dependência, por exemplo, 0 ou 1. Se apenas for definido um conjunto de chaves na declaração, o índice é 0.

    afirmação manual

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

    Substitua o seguinte:

    • 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 afirmação como uma dependência à tabela editada, repita o passo 4.

  6. Opcional: clique em Formatar.

O seguinte exemplo de código mostra asserções adicionadas à tabela A, que está definida no conjunto de dados dataform:

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

O seguinte exemplo de código mostra as afirmaçõ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 seguinte mostra uma declaração manual definida no ficheiro manualAssertion.sqlx e adicionada como uma dependência a uma vista:

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

O exemplo de código seguinte mostra o ficheiro manual_assertion e as afirmaçõ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 ...

Defina as afirmações de uma ação selecionada como dependências

Para executar uma ação de fluxo de trabalho apenas quando todas as afirmaçõ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 afirmações diretas da ação de dependência selecionada às dependências durante a compilação. O valor predefinido é false.

Para definir todas as afirmações de uma ação de dependência selecionada como dependências, siga estes passos:

  1. No espaço de trabalho de desenvolvimento, no painel Ficheiros, expanda definitions/.
  2. Selecione um ficheiro SQLX de ação do fluxo de trabalho.

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

    No quarteirão config

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

    Substitua o seguinte:

    • 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 afirmações que quer definir como dependências da ação editada.

    No extrato SELECT

      config { type: "ACTION_TYPE" }

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

    Substitua o seguinte:

    • 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 afirmações que quer definir como dependências da ação editada.

  4. Opcional: clique em Formatar.

O seguinte exemplo de código mostra tableC, que depende de viewA, tableB e de todas as afirmaçõ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 de tableC durante a compilação.

Defina as afirmações de todas as ações de dependência como dependências

Para executar uma ação de fluxo de trabalho apenas quando todas as afirmaçõ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 afirmações diretas das ações de dependência como dependências durante a compilação. O valor predefinido é false.

Quando define o parâmetro dependOnDependencyAssertions e os parâmetros includeDependentAssertions num único ficheiro, o parâmetro includeDependentAssertions tem prioridade para a ação de dependência para a qual está definido.

Para definir todas as afirmações de uma ação de dependência selecionada como dependências, siga estes passos:

  1. No espaço de trabalho de desenvolvimento, no painel Ficheiros, expanda definitions/.
  2. Selecione um ficheiro SQLX de ação do fluxo de trabalho.

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

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

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

  4. Opcional: clique em Formatar.

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

// 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 afirmações diretas de sometableA, sometableB, sometableC e sometableD como dependências de sometableE durante a compilação.

Referencie uma tabela com um nome de tabela substituído

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

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

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

Para mais informações sobre a substituição de nomes de tabelas, consulte Substitua as definições da tabela.

O que se segue?