Gerenciar um repositório

Este documento mostra como fazer o seguinte no Dataform:

• Configure as configurações do fluxo de trabalho do Dataform.
• Gerenciar o pacote principal do Dataform.
• Controle de versões do código.

Antes de começar

1. Selecione ou crie um repositório.

2. Opcional: conecte seu repositório a um repositório Git de terceiros.

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

Funções exigidas

Para conseguir as permissões necessárias a fim de concluir as tarefas neste documento, peça ao administrador para conceder a você os seguintes papéis do IAM:

• Configure as definições do Dataform e gerencie o local do pacote principal do Dataform: Administrador do Dataform (roles/dataform.admin) em repositórios.
• Atualize o pacote principal do Dataform e use o controle de versões no Dataform: 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 usando papéis personalizados ou outros papéis predefinidos.

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

Nesta seção, mostramos como editar as configurações de processamento do fluxo de trabalho do Dataform para um repositório específico.

É possível editar o arquivo de configurações para renomear os esquemas ou adicionar variáveis de compilação personalizadas ao seu repositório.

Sobre as configurações do repositório

Para todos os repositórios, uma conta de serviço personalizada é necessária para a execução do fluxo de trabalho e o modo estrito de agir como é aplicado. Não é possível usar o agente de serviço padrão do Dataform para executar fluxos de trabalho.

Cada repositório do Dataform contém um arquivo exclusivo de configurações de fluxo de trabalho. O arquivo contém o ID do projeto 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.

Desde o Dataform Core 3.0.0, as configurações de fluxo de trabalho são armazenadas no arquivo workflow_settings.yaml por padrão. Em versões anteriores do Dataform Core, as configurações de fluxo de trabalho eram armazenadas no arquivo dataform.json. Os dois arquivos de configuração precisam estar no diretório raiz do repositório. O arquivo workflow_settings.yaml do Dataform Core 3.0 é compatível com versões anteriores do arquivo dataform.json. Você pode continuar usando o arquivo dataform.json para armazenar as configurações do fluxo de trabalho. Como prática recomendada, migre as configurações de 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:

  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 BigQuery Google Cloud .
• defaultDataset: o conjunto de dados do BigQuery em que o Dataform cria recursos, chamado dataform por padrão.

• defaultLocation (opcional): o local padrão do conjunto de dados do BigQuery. O Dataform usa esse local para processar seu código e armazenar os resultados. Esse local de processamento precisa corresponder ao local dos seus conjuntos de dados do BigQuery. No entanto, não precisa corresponder ao local do repositório do Dataform.

  Se você não definir o parâmetro defaultLocation, o Dataform vai determinar o local com base nos conjuntos de dados referenciados pela consulta SQL. Isso funciona da seguinte maneira:

  • Se a consulta fizer referência a conjuntos de dados do mesmo local, o Dataform usará esse local.
  • Se a consulta fizer referência a conjuntos de dados de dois ou mais locais diferentes, um erro vai ocorrer. Para mais detalhes sobre essa limitação, consulte Replicação de conjuntos de dados entre regiões.
  • Se a consulta não fizer referência a nenhum conjunto de dados, o local padrão do Dataform será a multirregião US. Para escolher um local diferente, defina o local padrão. Como alternativa, use a variável de sistema @@location na sua consulta. Para mais informações, consulte Especificar locais.

• 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 propriedades workflow_settings.yaml, consulte WorkflowSettings 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 por código são válidos:

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

O exemplo de código a seguir 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:

  {
    "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: um ponteiro para o BigQuery, onde o Dataform cria recursos.
• defaultDatabase: o ID do projeto do BigQuery Google Cloud .
• defaultSchema: o conjunto de dados do BigQuery em que o Dataform cria recursos.

• defaultLocation (opcional): o local padrão do conjunto de dados do BigQuery. O Dataform usa esse local para processar seu código e armazenar os resultados. Esse local de processamento precisa corresponder ao local dos seus conjuntos de dados do BigQuery. No entanto, não precisa corresponder ao local do repositório do Dataform.

  Se você não definir o parâmetro defaultLocation, o Dataform vai determinar o local com base nos conjuntos de dados referenciados pela consulta SQL. Isso funciona da seguinte maneira:

  • Se a consulta fizer referência a conjuntos de dados do mesmo local, o Dataform usará esse local.
  • Se a consulta fizer referência a conjuntos de dados de dois ou mais locais diferentes, um erro vai ocorrer. Para mais detalhes sobre essa limitação, consulte Replicação de conjuntos de dados entre regiões.
  • Se a consulta não fizer referência a nenhum conjunto de dados, o local padrão do Dataform será a multirregião US. Para escolher um local diferente, defina o local padrão. Como alternativa, use a variável de sistema @@location na sua consulta. Para mais informações, consulte Especificar locais.

• 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.

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

Configurar nomes de esquema

Para configurar nomes de esquema, 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 de API do 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 de forma condicional.

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:

...
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 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 no seguinte formato:

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

   Substitua:

   • VARIABLE: o nome da variável. Por exemplo, executionSetting.
   • SET_VALUE: um valor para a variável. Por exemplo, staging.
   • CONDITION: 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 teste:

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

Configurar padrões no nível do fluxo de trabalho para tabelas Iceberg

É possível fornecer padrões no nível do fluxo de trabalho para tabelas gerenciadas do Apache Iceberg no arquivo workflow_settings.yaml. É possível definir valores padrão para o nome do bucket, a raiz da pasta da tabela e o subcaminho da pasta da tabela.

O Dataform usa esses valores padrão para construir o URI de armazenamento de uma tabela gerenciada do Iceberg se você não definir esses valores no bloco config do arquivo de definição da tabela.

Para configurar padrões no nível do fluxo de trabalho para as tabelas, adicione o bloco defaultIcebergConfig com os seguintes campos ao seu arquivo workflow_settings.yaml:

• bucketName: opcional. O nome padrão do bucket do Cloud Storage.
• tableFolderRoot: opcional. O nome padrão da pasta de primeiro nível no bucket do Cloud Storage.
• tableFolderSubpath: opcional. O nome padrão de uma subpasta em tableFolderRoot.

O exemplo de código a seguir mostra um arquivo workflow_settings.yaml com padrões no nível do fluxo de trabalho para tabelas gerenciadas do Iceberg:

defaultProject: "defaultProject"
defaultDataset: "defaultDataset"
defaultLocation: "us-central1"
defaultIcebergConfig:
  bucketName: "wsDefaultBucketName"
  tableFolderRoot: "wsDefaultTableFolderRoot"
  tableFolderSubpath: "wsDefaultTableFolderSubpath"

É possível acessar esses campos no código do Dataform como propriedades do objeto ProjectConfig:

dataform.ProjectConfig.defaultIcebergConfig.bucketName
dataform.ProjectConfig.defaultIcebergConfig.tableFolderRoot
dataform.ProjectConfig.defaultIcebergConfig.tableFolderSubpath

Para mais informações, consulte Criar tabelas gerenciadas do Apache Iceberg e as propriedades do bloco iceberg.

Migrar as configurações de 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 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 o arquivo package.json pelo 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 do arquivo dataform.json para o arquivo workflow_settings.yaml:

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

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

   Acesse o Dataform

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

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

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 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"