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

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Esta página mostra como editar as configurações de processamento de fluxos de trabalho do SQL do Dataform para um repositório específico.

Talvez seja necessário editar 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 contém um arquivo de configurações de fluxo de trabalho exclusivo. 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 podem ser substituídas para atender melhor às suas necessidades editando o arquivo de configurações.

A partir do núcleo do Dataform 3.0.0, as configurações do fluxo de trabalho são armazenadas no arquivo workflow_settings.yaml por padrão. Nas versões anteriores do núcleo do Dataform, as configurações do fluxo de trabalho são armazenadas no arquivo dataform.json. O arquivo workflow_settings.yaml do núcleo do Dataform 3.0 é compatível com versões anteriores do dataform.json. Você pode continuar usando dataform.json para armazenar as configurações do fluxo de trabalho. Como prática recomendada, migre as configurações do fluxo de trabalho do repositório para o formato workflow_settings.yaml para compatibilidade futura.

Sobre workflow_settings.yaml

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

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

  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 maneira:

• defaultProject: o ID do projeto do BigQuery no Google Cloud.
• 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 locais de conjuntos de dados do BigQuery, consulte Locais de 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 precisa corresponder à 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 de dataform_assertions por padrão.

Para mais informações sobre as propriedades workflow_settings.yaml, consulte Configs reference for workflow settings 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 workflow_settings.yaml para as opções dataform.projectConfig acessíveis ao código são aplicáveis:

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

O exemplo de código abaixo mostra o objeto dataform.projectConfig referenciado 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 arquivo dataform.json de exemplo:

  {
    "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 maneira:

• warehouse: ponteiro para o BigQuery, onde o Dataform cria recursos.
• defaultDatabase: o ID do projeto do BigQuery no Google Cloud.
• defaultSchema: o conjunto de dados do BigQuery em que o Dataform cria recursos.
• defaultLocation: a região padrão do conjunto de dados do BigQuery. Para mais informações sobre os locais de conjuntos de dados do BigQuery, consulte Locais de 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 precisa corresponder à 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 de 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 configurar as configurações do Dataform, peça ao administrador para conceder a você o papel do IAM de Administrador do Dataform (roles/dataform.admin) nos repositórios. 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.

Configurar nomes de esquemas

Para configurar os nomes dos esquemas, edite 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:

  ...
  defaultDataset: mytables
  ...

{
  ...
  "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 modificar o valor dela 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 possa ser usada em um repositório, siga estas etapas:

...
vars:
  myVariableName: myVariableValue
...

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

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

{
"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 o espaço de trabalho de desenvolvimento do Dataform.
2. No painel Files, selecione um arquivo de definição de tabela SQLX.

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

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

   Substitua:

   • YOUR_VARIABLE pelo nome da variável, por exemplo, executionSetting.
   • SET_VALUE com um valor para a variável, por exemplo, staging.
   • CONDITION com uma condição para a 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 preparação:

  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!"
  )}

Migrar as configurações do fluxo de trabalho para workflow_settings.yaml

Para garantir que o arquivo de configurações do fluxo de trabalho seja compatível com versões futuras do framework principal do Dataform, migre as configurações do fluxo de trabalho do arquivo dataform.json para o arquivo workflow_settings.yaml.

O arquivo workflow_settings.yaml substitui o arquivo dataform.json.

Se o núcleo do Dataform for o único pacote de dependência no repositório, o arquivo workflow_settings.yaml também vai substituir o arquivo package.json. Para mais informações sobre como substituir package.json por workflow_settings.yaml, consulte Gerenciar o pacote principal do Dataform.

A tabela a seguir mostra o mapeamento das propriedades de configurações do fluxo de trabalho de dataform.json para workflow_settings.yaml:

Para migrar as configurações do fluxo de trabalho para workflow_settings.yaml, siga estas etapas:

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

   Acesse a página do Dataform

2. Selecione um repositório e um espaço de trabalho.

3. No painel Files, clique em addAdd e, em seguida, em Create file.

4. No campo Adicionar um caminho de arquivo, insira workflow_settings.yaml.

5. Selecione Criar arquivo.

6. No arquivo workflow_settings.yaml, adicione as configurações do arquivo dataform.json, mapeadas para o formato YAML.

7. No painel Files, clique no menu More ao lado de dataform.json e, em seguida, em Delete.

8. Para confirmar a exclusão de dataform.json, clique em Excluir.

O exemplo de código abaixo mostra as configurações do fluxo de trabalho definidas em um arquivo dataform.json:

{
  "warehouse": "bigquery",
  "defaultDatabase": "dataform-demos",
  "defaultLocation": "US",
  "defaultSchema": "dataform",
  "assertionSchema": "dataform_assertions"
  "vars": {
    "environmentName": "development"
  }
}

O exemplo de código a seguir mostra o arquivo dataform.json anterior convertido em workflow_settings.yaml:

defaultProject: dataform-demos
defaultLocation: US
defaultDataset: dataform
defaultAssertionDataset: dataform_assertions
vars:
    environmentName: "development"

A seguir

• Para saber como migrar o pacote principal do Dataform para workflow_settings.yaml, consulte Gerenciar o pacote principal do Dataform.

• Para saber mais sobre as configurações do projeto do Dataform, consulte a referência IProjectConfig.