Declarar uma fonte de dados

Este documento mostra como declarar fontes de dados do BigQuery com o Dataform Core.

É possível declarar qualquer tipo de tabela do BigQuery como uma fonte de dados no Dataform. Ao declarar fontes de dados do BigQuery externas ao Dataform, você pode tratar essas fontes como objetos do Dataform.

A declaração de fontes de dados é opcional, mas pode ser útil quando você quiser fazer o seguinte:

  • Fazer referência ou resolver fontes declaradas da mesma forma que qualquer outra tabela no Dataform.
  • Visualizar fontes declaradas no gráfico do Dataform.
  • Usar o Dataform para gerenciar as descrições de tabelas e colunas de tabelas criadas externamente.
  • Acionar invocações de fluxo de trabalho que incluem todos os dependentes de uma fonte de dados externa.

É possível declarar fontes de dados usando arquivos JavaScript ou SQLX. Em um arquivo JavaScript, é possível declarar várias fontes de dados por arquivo. Em um arquivo SQLX, é possível declarar uma fonte de dados por arquivo.

Antes de começar

Antes de declarar uma fonte de dados, crie e inicialize um espaço de trabalho de desenvolvimento no repositório.

Funções exigidas

Para conseguir as permissões necessárias para declarar uma fonte de dados, peça ao administrador que conceda a você o papel do IAM 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 personalizados papéis ou outros predefinidos papéis.

Criar um arquivo JavaScript para várias declarações de fontes de dados

Armazene arquivos JavaScript para declarações de fontes de dados no diretório definitions/. Para criar um novo arquivo JavaScript no diretório definitions/, siga estas etapas:

  1. Noconsole, acesse a página Dataform. Google Cloud

    Acessar a página do Dataform

  2. Selecione um repositório.

  3. Selecione um espaço de trabalho de desenvolvimento.

  4. No painel Arquivos, ao lado de definitions/, clique no menu Mais.

  5. Selecione Criar arquivo.

  6. No painel Criar novo arquivo, faça o seguinte:

    1. No campo Adicionar um caminho de arquivo, depois de definitions/, insira o nome do arquivo seguido por .js. Por exemplo, definitions/declarations.js.

      Os nomes de arquivos só podem incluir números, letras, hifens e sublinhados.

    2. Selecione Criar arquivo.

Adicionar uma declaração a um arquivo JavaScript

É possível declarar várias fontes de dados por arquivo JavaScript. Para adicionar uma nova declaração, siga estas etapas:

  1. No espaço de trabalho de desenvolvimento, no painel Arquivos, clique no arquivo JavaScript para declarações de fontes de dados.

  2. No arquivo, para cada fonte de dados, adicione o seguinte snippet de código:

      declare({
    database: "DATABASE_PROJECT_ID",
    schema: "BIGQUERY_SCHEMA",
    name: "RELATION_NAME",
  });

    Substitua:

    • DATABASE_PROJECT_ID: o ID do projeto que contém a fonte de dados.
    • BIGQUERY_SCHEMA: o conjunto de dados do BigQuery em que a fonte de dados existe.
    • RELATION_NAME: o nome da tabela ou visualização que você quer usar como fonte de dados. Você pode usar esse nome mais tarde para fazer referência à fonte de dados no Dataform.

Criar um arquivo SQLX para declaração de fonte de dados

Armazene arquivos SQLX para declarações de fontes de dados no diretório definitions/. Para criar um novo arquivo SQLX no diretório definitions/, siga estas etapas:

  1. Noconsole, acesse a página Dataform. Google Cloud

    Acessar a página do Dataform

  2. Selecione um repositório.

  3. Selecione um espaço de trabalho de desenvolvimento.

  4. No painel Arquivos, ao lado de definitions/, clique no menu Mais.

  5. Selecione Criar arquivo.

  6. No painel Criar novo arquivo, faça o seguinte:

    1. No campo Adicionar um caminho de arquivo, depois de definitions/, insira o nome do arquivo seguido por .sqlx. Por exemplo, definitions/dataset-declaration.sqlx.

      Os nomes de arquivos só podem incluir números, letras, hifens e sublinhados.

    2. Selecione Criar arquivo.

Declarar uma fonte de dados

É possível declarar uma fonte de dados por arquivo de declaração SQLX. Para declarar uma fonte de dados no bloco de configuração de um arquivo SQLX, siga estas etapas:

  1. No espaço de trabalho de desenvolvimento, no painel Arquivos, clique no arquivo SQLX para declaração de fonte de dados.

  2. No arquivo, digite este snippet de código:

    config {
  type: "declaration",
  database: "DATABASE",
  schema: "SCHEMA",
  name: "NAME",
}

    Substitua:

    • DATABASE: o ID do projeto que contém a fonte de dados.
    • SCHEMA: o conjunto de dados do BigQuery em que a fonte de dados existe.
    • NAME: o nome da tabela ou visualização que você quer usar como fonte de dados. Você pode usar esse nome mais tarde para fazer referência à fonte de dados no Dataform.

  3. Opcional: clique em Formatar.

O exemplo de código a seguir mostra uma declaração de exemplo da tabela shakespeare no conjunto de dados samples do projeto bigquery-public-data como uma fonte de dados:

    config {
      type: "declaration",
      database: "bigquery-public-data",
      schema: "samples",
      name: "shakespeare",
    }

A seguir