Declarar uma fonte de dados

Neste documento, mostramos 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 que são externas ao Dataform, é possível tratar essas fontes como objetos do Dataform.

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

  • Faça referência ou resolva fontes declaradas da mesma forma que qualquer outra tabela no Dataform.
  • Ver as fontes declaradas no gráfico visualizado do Dataform.
  • Use o Dataform para gerenciar as descrições no nível da tabela e da coluna de tabelas criadas externamente.
  • Aciona 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 seu repositório.

Funções exigidas

Para receber 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 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 arquivo JavaScript no diretório definitions/, siga estas etapas:

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

    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 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 Arquivos, clique no arquivo JavaScript para declarações de fonte 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 está localizada.
    • RELATION_NAME: o nome da tabela ou visualização que você quer usar como fonte de dados. Depois, 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 fonte de dados no diretório definitions/. Para criar um arquivo SQLX no diretório definitions/, siga estas etapas:

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

    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 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 espaço de trabalho de desenvolvimento, no painel Arquivos, clique no arquivo SQLX para 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 está localizada.
    • NAME: o nome da tabela ou visualização que você quer usar como fonte de dados. Depois, você pode usar esse nome 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 amostra 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