Faça a gestão de um repositório

Este documento mostra como fazer o seguinte no Dataform:

• Configure as definições do fluxo de trabalho do Dataform.
• Faça a gestão do pacote principal do Dataform.
• Controle as versões do seu código.

Antes de começar

1. Crie um repositório.
2. Opcional: associe o 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 necessárias

Para receber as autorizações de que precisa para concluir as tarefas neste documento, peça ao seu administrador que lhe conceda as seguintes funções de IAM:

• Configure as definições do Dataform e faça a gestão da localização do pacote principal do Dataform: Administração do Dataform (roles/dataform.admin) em repositórios.
• Atualize o pacote principal do Dataform e use o controlo de versões no Dataform: Editor do Dataform (roles/dataform.editor) em 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.

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

Esta secção mostra como editar as definições de processamento do fluxo de trabalho do Dataform para um repositório específico.

Pode querer editar o ficheiro de definições para mudar o nome dos esquemas ou adicionar variáveis de compilação personalizadas ao seu repositório.

Acerca das definições do repositório

Cada repositório do Dataform contém um ficheiro de definições de fluxo de trabalho exclusivo. O ficheiro contém o ID do projeto Google Cloud e o esquema no qual o Dataform publica recursos no BigQuery. O Dataform usa predefinições que pode substituir para melhor satisfazer as suas necessidades editando o ficheiro de definições.

A partir do Dataform core 3.0.0, as definições do fluxo de trabalho são armazenadas no ficheiro workflow_settings.yaml por predefinição. Nas versões anteriores do Dataform core, as definições do fluxo de trabalho são armazenadas no ficheiro dataform.json. Ambos os ficheiros de configuração têm de estar no diretório raiz do repositório. O ficheiro Dataform core 3.0 workflow_settings.yaml é retrocompatível com o ficheiro dataform.json. Pode continuar a usar o ficheiro dataform.json para armazenar as definições do fluxo de trabalho. Como prática recomendada, deve migrar as definições do fluxo de trabalho do repositório para o formato workflow_settings.yaml para compatibilidade futura.

Acerca de workflow_settings.yaml

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

O seguinte exemplo de código mostra um ficheiro 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 forma:

• defaultProject: o ID do projeto do BigQuery Google Cloud .
• defaultDataset: o conjunto de dados do BigQuery no qual o Dataform cria recursos, denominado dataform por predefinição.

• defaultLocation (opcional): a localização do conjunto de dados do BigQuery predefinido. O Dataform usa esta localização para processar o seu código e armazenar os resultados. Esta localização de processamento tem de corresponder à localização dos seus conjuntos de dados do BigQuery. No entanto, não tem de corresponder à localização do repositório do Dataform.

  Se não definir o parâmetro defaultLocation, o Dataform determina a localização com base nos conjuntos de dados a que a sua consulta SQL faz referência. Funciona da seguinte forma:

  • Se a sua consulta fizer referência a conjuntos de dados da mesma localização, o Dataform usa essa localização.
  • Se a sua consulta fizer referência a conjuntos de dados de duas ou mais localizações diferentes, ocorre um erro. Para ver detalhes acerca desta limitação, consulte o artigo Replicação de conjuntos de dados entre regiões.
  • Se a sua consulta não fizer referência a nenhum conjunto de dados, a localização predefinida do Dataform é a multirregião US. Para escolher uma localização diferente, defina a localização predefinida. Em alternativa, use a @@location variável do sistema na sua consulta. Para mais informações, consulte o artigo Especifique localizações.

• defaultAssertionDataset: o conjunto de dados do BigQuery no qual o Dataform cria vistas com resultados de validação, denominado dataform_assertions por predefinição.

Para mais informações sobre as propriedades workflow_settings.yaml, consulte WorkflowSettings no GitHub.

Pode aceder às propriedades definidas em workflow_settings.yaml no seu código do Dataform como propriedades do objeto dataform.projectConfig.

Aplicam-se os seguintes mapeamentos das opções workflow_settings.yaml para as opções dataform.projectConfig acessíveis por código:

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

O seguinte exemplo de código mostra o objeto dataform.projectConfig referenciado numa declaração SELECT numa vista:

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

Acerca de dataform.json

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

O seguinte exemplo de código mostra um ficheiro 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 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 no qual o Dataform cria recursos.

• defaultLocation (opcional): a localização do seu conjunto de dados predefinido do BigQuery. O Dataform usa esta localização para processar o seu código e armazenar os resultados. Esta localização de processamento tem de corresponder à localização dos seus conjuntos de dados do BigQuery. No entanto, não tem de corresponder à localização do repositório do Dataform.

  Se não definir o parâmetro defaultLocation, o Dataform determina a localização com base nos conjuntos de dados a que a sua consulta SQL faz referência. Funciona da seguinte forma:

  • Se a sua consulta fizer referência a conjuntos de dados da mesma localização, o Dataform usa essa localização.
  • Se a sua consulta fizer referência a conjuntos de dados de duas ou mais localizações diferentes, ocorre um erro. Para ver detalhes acerca desta limitação, consulte o artigo Replicação de conjuntos de dados entre regiões.
  • Se a sua consulta não fizer referência a nenhum conjunto de dados, a localização predefinida do Dataform é a multirregião US. Para escolher uma localização diferente, defina a localização predefinida. Em alternativa, use a @@location variável do sistema na sua consulta. Para mais informações, consulte o artigo Especifique localizações.

• assertionSchema: o conjunto de dados do BigQuery no qual o Dataform cria vistas com resultados de validação, denominado dataform_assertions por predefinição.

Pode aceder às propriedades definidas no ficheiro dataform.json no código do projeto como propriedades do objeto dataform.projectConfig.

Configure os nomes dos esquemas

Para configurar os nomes dos esquemas, tem de editar as propriedades defaultDataset e defaultAssertionSchema no ficheiro workflow_settings.yaml ou as propriedades defaultSchema e assertionSchema no ficheiro dataform.json.

Para configurar o nome de um esquema, siga estes passos:

  ...
  defaultDataset: mytables
  ...

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

Crie variáveis de compilação personalizadas

As variáveis de compilação contêm valores que pode modificar com substituições de compilação numa configuração de lançamento ou num pedido da API Dataform.

Depois de definir uma variável de compilação em workflow_settings.yaml e adicioná-la às tabelas selecionadas, pode modificar o respetivo valor numa configuração de lançamento ou nas substituições de compilação da API Dataform para executar tabelas condicionalmente.

Para mais informações sobre a execução condicional de tabelas através de variáveis de compilação, consulte o artigo Introdução ao ciclo de vida do código no Dataform.

Para criar uma variável de compilação que possa usar num repositório, siga estes passos:

...
vars:
  myVariableName: myVariableValue
...

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

{
  ...