Declarar uma fonte de dados

Este documento mostra como declarar origens de dados do BigQuery com o núcleo do Dataform.

É possível declarar qualquer tipo de tabela do BigQuery como uma origem de dados no Dataform. Declarar fontes de dados do BigQuery que são externas ao Dataform permite tratar essas fontes de dados como objetos do Dataform.

Declarar fontes de dados é opcional, mas pode ser útil quando você quer:

  • Faça referência ou resolva origens declaradas da mesma forma que qualquer outra tabela no Dataform.
  • Confira as fontes declaradas no gráfico do Dataform.
  • Use o Dataform para gerenciar as descrições de tabelas e colunas 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 receber as permissões necessárias para declarar uma origem de dados, peça ao administrador que conceda a você o papel do IAM Editor de formulário de dados (roles/dataform.editor) nos 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 por meio de papéis personalizados ou de outros papéis predefinidos.

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

Armazene arquivos JavaScript para declarações de fonte de dados no diretório definitions/. Para criar um novo arquivo JavaScript no diretório definitions/, 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.

  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/, digite o nome do arquivo seguido de .js. Por exemplo, definitions/declarations.js.

      Os nomes de arquivo 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 Files, clique no arquivo JavaScript para ver as declarações de fontes de dados.

  2. No arquivo, para cada fonte de dados, adicione este 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 a fonte de dados. Você pode usar esse nome 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 origem de dados no diretório definitions/. Para criar um novo arquivo SQLX no diretório definitions/, 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.

  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/, digite o nome do arquivo seguido de .sqlx. Por exemplo, definitions/dataset-declaration.sqlx.

      Os nomes de arquivo 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 seu espaço de trabalho de desenvolvimento, no painel Files, clique no arquivo SQLX para a declaração da 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 a fonte de dados. Você pode usar esse nome para fazer referência à fonte de dados no Dataform.

  3. Opcional: clique em Formato.

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