Definir as configurações do fluxo de trabalho do Dataform

Nesta página, mostramos como editar as configurações de processamento do fluxo de trabalho SQL do Dataform para um repositório específico.

Edite o arquivo de configurações para renomear os esquemas ou adicionar variáveis de compilação personalizadas ao repositório.

Sobre as configurações do repositório

Cada repositório do Dataform tem um arquivo exclusivo de configurações de fluxo de trabalho. O arquivo contém o ID do projeto do Google Cloud e o esquema em que o Dataform publica recursos no BigQuery. O Dataform usa configurações padrão que você pode substituir para atender melhor às suas necessidades, editando o arquivo de configurações.

A partir do Dataform core 3.0, por padrão, as configurações do fluxo de trabalho são armazenadas no arquivo workflow_settings.yaml. Nas versões anteriores do Dataform Core, as configurações do fluxo de trabalho são armazenadas no arquivo dataform.json. O arquivo workflow_settings.yaml do Dataform core 3.0 é compatível com dataform.json. Você pode continuar usando dataform.json para definir as configurações do Dataform.

Sobre workflow_settings.yaml

O arquivo workflow_settings.yaml, introduzido no Dataform core 3.0, armazena as configurações de fluxo de trabalho do Dataform no formato YAML.

O exemplo de código a seguir mostra um exemplo de arquivo workflow_settings.yaml:

  defaultProject: my-gcp-project-id
  defaultDataset: dataform
  defaultLocation: australia-southeast2
  defaultAssertionDataset: dataform_assertions

No exemplo de código anterior, os pares de chave-valor são descritos da seguinte forma:

  • defaultProject: o ID do projeto do Google Cloud no BigQuery.
  • defaultDataset: o conjunto de dados do BigQuery em que o Dataform cria recursos, chamado dataform por padrão.
  • defaultLocation: a região padrão do conjunto de dados do BigQuery. Para mais informações sobre os locais dos conjuntos de dados do BigQuery, consulte Locais dos conjuntos de dados. Nesse local, o Dataform processa seu código e armazena os dados executados. Essa região de processamento precisa corresponder ao local dos conjuntos de dados do BigQuery, mas não à região do repositório do Dataform.
  • defaultAssertionDataset: o conjunto de dados do BigQuery em que o Dataform cria visualizações com resultados de declaração, chamado dataform_assertions por padrão.

Para mais informações sobre as propriedades workflow_settings.yaml, consulte a referência de configurações das configurações de fluxo de trabalho no GitHub.

É possível acessar as propriedades definidas em workflow_settings.yaml no código do Dataform como propriedades do objeto dataform.projectConfig.

Os seguintes mapeamentos das opções de workflow_settings.yaml para as opções de dataform.projectConfig acessíveis ao código se aplicam:

  • defaultProject => defaultDatabase
  • defaultDataset => defaultSchema
  • defaultAssertionDataset => assertionSchema
  • projectSuffix => databaseSuffix
  • datasetSuffix => schemaSuffix
  • namePrefix => tablePrefix

O exemplo de código a seguir mostra o objeto dataform.projectConfig chamado em uma instrução SELECT em uma visualização:

  config { type: "view" }
  SELECT ${when(
    !dataform.projectConfig.tablePrefix,
    "table prefix is set!",
    "table prefix is not set!"
  )}

Sobre dataform.json

O arquivo dataform.json armazena as configurações do fluxo de trabalho do Dataform no formato JSON.

O exemplo de código a seguir mostra um exemplo de arquivo dataform.json:

  {
    "warehouse": "bigquery",
    "defaultDatabase": "my-gcp-project-id",
    "defaultSchema": "dataform",
    "defaultLocation": "australia-southeast2",
    "assertionSchema": "dataform_assertions"
  }

No exemplo de código anterior, os pares de chave-valor são descritos da seguinte forma:

  • warehouse: ponteiro para o BigQuery, onde o Dataform cria recursos.
  • defaultDatabase: o ID do projeto do Google Cloud no BigQuery.
  • defaultSchema: o conjunto de dados do BigQuery em que o Dataform cria recursos, chamado dataform por padrão.
  • defaultLocation: a região padrão do conjunto de dados do BigQuery. Para mais informações sobre os locais dos conjuntos de dados do BigQuery, consulte Locais dos conjuntos de dados. Nesse local, o Dataform processa seu código e armazena os dados executados. Essa região de processamento precisa corresponder ao local dos conjuntos de dados do BigQuery, mas não à região do repositório do Dataform.
  • assertionSchema: o conjunto de dados do BigQuery em que o Dataform cria visualizações com resultados de declaração, chamado dataform_assertions por padrão.

É possível acessar as propriedades definidas em dataform.json no código do projeto como propriedades do objeto dataform.projectConfig.

Antes de começar

  1. Crie um repositório.

  2. Crie e inicialize um espaço de trabalho de desenvolvimento no seu repositório.

Funções exigidas

Para receber as permissões necessárias para definir as configurações do Dataform, peça ao administrador para conceder a você o papel do IAM Administrador do Dataform (roles/dataform.admin) nos repositórios. Para mais informações sobre como conceder papéis, consulte Gerenciar acesso.

Também é possível receber as permissões necessárias com papéis personalizados ou outros papéis predefinidos.

Configurar nomes de esquemas

Para configurar nomes de esquemas, é necessário editar as propriedades defaultDataset e defaultAssertionSchema no arquivo workflow_settings.yaml ou as propriedades defaultSchema e assertionSchema no arquivo dataform.json.

Para configurar o nome de um esquema, siga estas etapas:

workflow_settings.yaml

  1. No espaço de trabalho de desenvolvimento, no painel Arquivos, clique no arquivo workflow_settings.yaml.

  2. Edite o valor de defaultDataset, defaultAssertionSchema ou ambos.

O exemplo de código a seguir mostra um nome defaultDataset personalizado definido no arquivo workflow_settings.yaml:

  ...
  defaultDataset: mytables
  ...

dataform.json

  1. No espaço de trabalho de desenvolvimento, no painel Arquivos, clique no arquivo dataform.json.

  2. Edite o valor de defaultSchema, assertionSchema ou ambos.

O exemplo de código abaixo mostra um nome defaultSchema personalizado definido no arquivo dataform.json:

{
  ...
  "defaultSchema": "mytables",
  ...
}

Criar variáveis de compilação personalizadas

As variáveis de compilação contêm valores que podem ser modificados com substituições de compilação em uma configuração de lançamento ou em uma solicitação da API Dataform.

Depois de definir uma variável de compilação em workflow_settings.yaml e adicioná-la às tabelas selecionadas, é possível usar a modificação do valor em uma configuração de lançamento ou substituições de compilação da API Dataform para executar tabelas condicionalmente.

Para mais informações sobre como executar tabelas condicionalmente usando variáveis de compilação, consulte Introdução ao ciclo de vida do código no Dataform.

Para criar uma variável de compilação que pode ser usada em um repositório, siga estas etapas:

workflow_settings.yaml

  1. Acesse seu espaço de trabalho de desenvolvimento do Dataform.
  2. No painel Files, selecione o arquivo workflow_settings.yaml.

  3. Insira o seguinte snippet de código:

    "vars": {
  "YOUR_VARIABLE":"VALUE"
}

    Substitua:

    • YOUR_VARIABLE por um nome para a variável.
    • VALUE pelo valor padrão da variável de compilação.

O exemplo de código a seguir mostra a variável de compilação myVariableName definida como myVariableValue no arquivo workflow_settings.yaml:

...
vars:
  myVariableName: myVariableValue
...

O exemplo de código abaixo mostra o arquivo workflow_settings.yaml com a variável de compilação executionSetting definida como dev:

defaultProject: default_bigquery_database
defaultLocation: us-west1
defaultDataset: dataform_data,
vars:
executionSetting: dev

dataform.json

  1. Acesse seu espaço de trabalho de desenvolvimento do Dataform.
  2. No painel Files, selecione o arquivo dataform.json.

  3. Insira o seguinte snippet de código:

    "vars": {
  "YOUR_VARIABLE":"VALUE"
}

    Substitua:

    • YOUR_VARIABLE por um nome para a variável.
    • VALUE pelo valor padrão da variável de compilação.

O exemplo de código a seguir mostra a variável de compilação myVariableName definida como myVariableValue no arquivo dataform.json:

{
  ...
  "vars": {
    "myVariableName": "myVariableValue"
  },
  ...
}

O exemplo de código abaixo mostra o arquivo dataform.json com a variável de compilação executionSetting definida como dev:

{
"warehouse": "bigquery",
"defaultSchema": "dataform_data",
"defaultDatabase": "default_bigquery_database".
"defaultLocation":"us-west-1",
"vars": {
"executionSetting":"dev"
}
}

Adicionar uma variável de compilação a uma tabela

Para adicionar uma variável de compilação a um arquivo de definição de tabela SQLX, siga estas etapas:

  1. Acesse seu espaço de trabalho de desenvolvimento do Dataform.
  2. No painel Arquivos, selecione um arquivo de definição de tabela SQLX.

  3. No arquivo, insira uma cláusula when neste formato:

    ${when(dataform.projectConfig.vars.YOUR_VARIABLE === "SET_VALUE", "CONDITION")}

    Substitua:

    • YOUR_VARIABLE pelo nome da sua variável, por exemplo, executionSetting.
    • SET_VALUE por um valor para a variável, por exemplo, staging.
    • CONDITION por uma condição para execução da tabela.

O exemplo de código a seguir mostra um arquivo SQLX de definição de tabela com uma cláusula when e a variável executionSetting que executa 10% dos dados na configuração de execução de preparo:

  select
    *
  from ${ref("data")}
  ${when(
    dataform.projectConfig.vars.executionSetting === "staging",
    "where mod(farm_fingerprint(id) / 10) = 0",
  )}

O exemplo de código a seguir mostra um arquivo SQLX de definição de visualização com uma cláusula when e a variável myVariableName:

  config { type: "view" }
  SELECT ${when(
    dataform.projectConfig.vars.myVariableName === "myVariableValue",
    "myVariableName is set to myVariableValue!",
    "myVariableName is not set to myVariableValue!"
  )}

A seguir