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

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

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

Sobre as configurações do repositório

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

A partir do Dataform core 3.0.0, as configurações de fluxo de trabalho são armazenadas no arquivo workflow_settings.yaml por padrão. Nas versões anteriores do Dataform Core, as configurações de fluxo de trabalho são armazenadas no arquivo dataform.json. O arquivo workflow_settings.yaml do Dataform core 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. Recomendamos que você migrar 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 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, que têm o nome 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 os Locais dos conjuntos de dados. Nele, o Dataform processa seu código e o armazena dados executados. Essa região de processamento precisa corresponder ao local dos conjuntos de dados do BigQuery, mas não precisa a 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, chamados dataform_assertions por padrão.

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

Você pode acessar as propriedades definidas no workflow_settings.yaml no seu Código do Dataform como propriedades do dataform.projectConfig objeto.

Os seguintes mapeamentos das opções de workflow_settings.yaml para o código acessível dataform.projectConfig opções 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 um 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, em que 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.
  • 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 dos conjuntos de dados. Nele, o Dataform processa seu código e o armazena dados executados. Essa região de processamento precisa corresponder ao local dos conjuntos de dados do BigQuery, mas não precisa a 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, chamados dataform_assertions por padrão.

Você pode acessar as propriedades definidas em dataform.json no código do projeto como propriedades do dataform.projectConfig objeto.

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 ter as permissões necessárias para definir as configurações do Dataform, peça ao administrador para conceder a você 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 conseguir as permissões necessárias com papéis personalizados ou outros papéis predefinidos.

Configurar nomes de esquemas

Para configurar nomes de esquemas, é preciso editar defaultDataset e defaultAssertionSchema propriedades em o arquivo workflow_settings.yaml ou o arquivo 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 em o 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 em o arquivo workflow_settings.yaml:

  ...
  defaultDataset: mytables
  ...

dataform.json

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

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

O exemplo de código a seguir mostra um nome defaultSchema personalizado definido no Arquivo dataform.json:

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

Criar variáveis de compilação personalizadas

Variáveis de compilação contêm valores que podem ser modificados substituições em uma configuração de versão ou em uma solicitação da API Dataform.

Depois de definir uma variável de compilação no workflow_settings.yaml e adicioná-la a tabelas selecionadas, é possível usar a modificação de seu valor em uma configuração de versão ou Substituições de compilação da API Dataform para executar tabelas condicionalmente.

Para mais informações sobre como executar tabelas condicionalmente 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 abaixo mostra o conjunto de variáveis de compilação myVariableName. como myVariableValue no arquivo workflow_settings.yaml:

...
vars:
  myVariableName: myVariableValue
...

O exemplo de código a seguir mostra o arquivo workflow_settings.yaml com o A variável de compilação executionSetting foi 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 abaixo mostra o conjunto de variáveis de compilação myVariableName. como myVariableValue no arquivo dataform.json:

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

O exemplo de código a seguir mostra o arquivo dataform.json com o A variável de compilação executionSetting foi 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 um when. e a variável executionSetting, que executa 10% dos dados na configuração de execução do 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 um 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 seu arquivo de configurações de fluxo de trabalho seja compatível com versões do framework principal do Dataform, migre seu 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 Dataform core for o único pacote de dependência no seu 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 Gerencie o pacote principal do Dataform.

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

Propriedade em dataform.json Propriedade em workflow_settings.yaml Descrição
assertionSchema defaultAssertionDataset Obrigatório. O conjunto de dados padrão para declarações.
defaultDatabase defaultProject Obrigatório. O nome padrão do projeto do Google Cloud.
defaultLocation defaultLocation Obrigatório. O local padrão do BigQuery onde o Dataform vai criar tabelas. Para mais informações sobre locais do BigQuery, consulte Locais de conjuntos de dados.
defaultSchema defaultDataset Obrigatório. O conjunto de dados padrão.
databaseSuffix projectSuffix Opcional. O sufixo a ser anexado a todas as referências de projetos do Google Cloud.
schemaSuffix datasetSuffix Opcional. O sufixo a ser anexado a todos os conjuntos de dados de ação.
tablePrefix namePrefix Opcional. O prefixo que será anexado a todos os nomes de ações.
vars vars Opcional. Variáveis definidas pelo usuário que são disponibilizadas para o código do projeto durante a compilação. Um objeto com uma lista de pares key: value.
warehouse - Obrigatório em dataform.json. Precisa ser definido como bigquery. Indisponível no seguinte país: workflow_settings.yaml.
- dataformCoreVersion Indisponível no seguinte país: dataform.json. Ignorada em workflow_settings.yaml por padrão para novos repositórios. Para mais informações, consulte Gerenciar o pacote principal do Dataform.

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.

    Acessar a página do Dataform

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

  3. No painel Arquivos, clique em addAdd, e clique em Criar arquivo.

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

  5. Clique em Criar arquivo.

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

  7. No painel Arquivos, clique no menu Mais ao lado de dataform.json. e clique em Excluir.

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

O exemplo de código a seguir mostra as configurações de 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 abaixo mostra o arquivo dataform.json anterior. convertido para workflow_settings.yaml:

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

A seguir