Crie tabelas

No Dataform, uma tabela é um dos tipos de objetos que compõem um fluxo de trabalho. Pode criar tabelas que fazem referência a dados das origens de dados declaradas para o seu fluxo de trabalho ou de outras tabelas no seu fluxo de trabalho. O Dataform compila as definições das tabelas em SQL em tempo real. Quando aciona a execução, o Dataform executa o código SQL e cria as tabelas definidas no BigQuery.

Pode criar os seguintes tipos de tabelas num ficheiro type: "table" SQLX:

Também pode definir partições e clusters da tabela.

Para manter um registo da finalidade de uma tabela ou da respetiva relação com outras tabelas no seu fluxo de trabalho, pode adicionar documentação à tabela ou às colunas selecionadas.

Para testar os dados numa tabela em relação a condições específicas, pode criar consultas de teste de qualidade dos dados denominadas afirmações. O Dataform executa validações sempre que atualiza o fluxo de trabalho e envia-lhe alertas se alguma validação falhar.

Para substituir o esquema, a base de dados e o nome predefinidos de uma tabela selecionada, pode substituir as definições da tabela.

Para desativar a criação de tabelas ou executar uma declaração SQL antes ou depois da criação de tabelas, pode configurar ações adicionais.

Para organizar as tabelas no BigQuery depois de as executar, pode adicionar etiquetas do BigQuery. Para saber mais, consulte o artigo Introdução às etiquetas.

Para restringir o acesso aos dados ao nível da coluna da tabela, pode adicionar etiquetas de políticas do BigQuery. Para saber mais, consulte o artigo Introdução ao controlo de acesso ao nível da coluna.

Além de definir tabelas num ficheiro type: "table" SQLX, pode criar tabelas vazias definindo uma consulta SQL personalizada num ficheiro type: "operations" SQLX. Pode querer criar uma tabela vazia para que um serviço diferente a possa preencher com dados.

Antes de começar

  1. Na Google Cloud consola, aceda à página Dataform.

    Aceder ao Dataform

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

  3. Opcional: declare uma origem de dados.

Funções necessárias

Para receber as autorizações de que precisa para concluir as tarefas neste documento, peça ao seu administrador para lhe conceder a função de IAM 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.

Criar uma tabela

Esta secção mostra como criar tabelas com o Dataform core no Dataform.

Acerca das definições de tabelas

Para definir uma tabela, define o tipo de tabela e escreve uma declaração SELECT num ficheiro SQLX.type: "table" Em seguida, o Dataform compila o código principal do Dataform em SQL, executa o código SQL e cria as tabelas definidas no BigQuery.

Numa declaração SELECT do Dataform core, define a estrutura da tabela e faz referência a outros objetos do seu fluxo de trabalho.

Além de definir tabelas num ficheiro type: "table" SLQX, pode criar tabelas vazias definindo uma consulta SQL personalizada num ficheiro type: "operations" SQLX. Para mais informações, consulte Crie uma tabela vazia.

Referencie dependências com ref

Para fazer referência a uma ação do fluxo de trabalho numa declaração SELECT e adicioná-la automaticamente como uma dependência, use a função ref. O Dataform executa as dependências antes das tabelas que dependem delas para verificar a ordenação correta do pipeline.

A função ref é uma função principal do Dataform integrada que é essencial para a gestão de dependências no Dataform. A função ref permite-lhe fazer referência e depender automaticamente dos seguintes objetos definidos no seu fluxo de trabalho do Dataform, em vez de codificar os nomes do esquema e da tabela:

O Dataform usa a função ref para criar uma árvore de dependências de todas as tabelas a serem criadas ou atualizadas.

Após a compilação, o Dataform adiciona declarações de texto padrão à declaração SQL, como CREATE, REPLACE, INSERT ou MERGE.

O exemplo de código seguinte mostra uma definição de tabela com a utilização da função ref:

config { type: "table" }

SELECT
  order_date AS date,
  order_id AS order_id,
  order_status AS order_status,
  SUM(item_count) AS item_count,
  SUM(amount) AS revenue

FROM ${ref("store_clean")}

GROUP BY 1, 2

Na função ref, indica o nome da declaração da tabela ou da origem de dados da qual quer depender. Normalmente, é o nome do ficheiro SQLX no qual essa declaração de tabela ou origem de dados está definida.

Se um nome de tabela for substituído, use o nome substituído na função ref. Por exemplo, referencie uma tabela com config { name: "overridden_name" } como ref("overridden_name"). Para mais informações, consulte os artigos Substitua as definições da tabela e Faça referência a uma tabela com um nome de tabela substituído.

Quando tem várias tabelas com o mesmo nome em esquemas diferentes, pode fazer referência a uma tabela específica fornecendo dois argumentos à função ref: o nome do esquema e o nome da tabela.

O seguinte exemplo de código mostra a função ref com dois argumentos para especificar uma tabela num esquema específico:

config { type: "table" }
SELECT * FROM ${ref("schema", "store_clean")}

Também pode adicionar dependências de tabelas manualmente ao bloco config para tabelas, declarações, origens de dados ou operações SQL personalizadas que não sejam referenciadas numa função ref na declaração SELECT. O Dataform executa estas dependências antes das tabelas dependentes.

O seguinte exemplo de código mostra uma dependência de tabela no bloco config:

config { dependencies: [ "unreferenced_table" ] }
SELECT * FROM ...

Para mais informações sobre a gestão de dependências no seu fluxo de trabalho, consulte o artigo Defina dependências.

Referencie outras tabelas com resolve

A função resolve permite-lhe fazer referência a uma declaração de tabela ou origem de dados numa declaração SELECT, como a função ref, mas não adiciona a referência como uma dependência. Isto significa que o objeto referenciado através da função resolve não afeta a execução da tabela que usa a função resolve.

Para mais informações sobre as funções core do Dataform integradas, consulte a referência core do Dataform.

Crie um ficheiro SQLX para uma definição de tabela

Armazene ficheiros SQLX de definição de tabelas no diretório definitions/. Para criar um novo ficheiro SQLX no diretório definitions/, siga estes passos:

  1. Na Google Cloud consola, aceda à página Dataform.

    Aceder ao Dataform

  2. Para abrir um repositório, clique no respetivo nome.

  3. Para abrir um espaço de trabalho de desenvolvimento, clique no nome do espaço de trabalho.

  4. No painel Ficheiros, junto a definitions/, clique em Mais.

  5. Clique em Criar ficheiro.

  6. No campo Adicionar um caminho do ficheiro, introduza o nome do ficheiro seguido de .sqlx após definitions/. Por exemplo, definitions/my-table.sqlx.

    Os nomes de ficheiros só podem incluir números, letras, hífenes e sublinhados.

  7. Clique em Criar ficheiro.

Defina o tipo de tabela

Para criar uma nova definição do tipo de tabela, siga estes passos:

  1. No espaço de trabalho de desenvolvimento, no painel Ficheiros, expanda o diretório definitions/.
  2. Selecione o ficheiro SQLX de definição da tabela que quer editar.

  3. No ficheiro, introduza o seguinte fragmento do código:

    config { type: "TABLE_TYPE" }

    Substitua TABLE_TYPE por um dos seguintes tipos de tabelas:

    • table
    • incremental
    • view

  4. Opcional: para definir uma vista materializada, introduza a propriedade materialized em type: "view" no seguinte formato:

    config {
  type: "view",
  materialized: true
}

    Para mais informações, consulte o artigo ITableConfig.

  5. Opcional: clique em Formatar.

Defina a estrutura e as dependências da tabela

Para escrever uma declaração SELECT de definição de tabela e definir a estrutura da tabela e as dependências, siga estes passos:

  1. No espaço de trabalho de desenvolvimento, no painel Ficheiros, expanda o diretório definitions/.
  2. Selecione o ficheiro SQLX de definição da tabela que quer editar.
  3. Abaixo do bloco config, escreva uma declaração SELECT.
  4. Opcional: clique em Formatar.

O exemplo de código seguinte mostra uma definição de tabela com uma declaração SELECT e a função ref:

config { type: "table" }
SELECT
  customers.id AS id,
  customers.first_name AS first_name,
  customers.last_name AS last_name,
  customers.email AS email,
  customers.country AS country,
  COUNT(orders.id) AS order_count,
  SUM(orders.amount) AS total_spent
FROM
  dataform-samples.dataform_sample.crm_customers AS customers
  LEFT JOIN ${ref('order_stats')} orders
    ON customers.id = orders.customer_id

WHERE
  customers.id IS NOT NULL
  AND customers.first_name <> 'Internal account'
  AND country IN ('UK', 'US', 'FR', 'ES', 'NG', 'JP')

GROUP BY 1, 2, 3, 4, 5

Adicione dependências de tabelas manuais

Para adicionar dependências de tabelas que não são referenciadas na declaração SELECT, mas que têm de ser executadas antes da tabela atual, siga estes passos:

  1. No espaço de trabalho de desenvolvimento, no painel Ficheiros, expanda o diretório definitions/.
  2. Selecione o ficheiro SQLX de definição da tabela que quer editar.

  3. No bloco config da tabela, introduza o seguinte fragmento do código:

    dependencies: [ "DEPENDENCY_TABLE", ]

    Substitua DEPENDENCY_TABLE pelo nome do ficheiro da tabela que quer adicionar como dependência. Pode introduzir vários nomes de ficheiros.

  4. Opcional: clique em Formatar.

O exemplo de código seguinte mostra duas tabelas adicionadas como dependências de tabelas manuais ao bloco config de um ficheiro de definição de tabelas:

config { dependencies: [ "some_table", "some_other_table" ] }

Substitua as definições da tabela

Pode substituir o esquema, a base de dados e o nome predefinidos de uma tabela selecionada.

Por predefinição, uma tabela segue a configuração do esquema e da base de dados que definiu em workflow_settings.yaml. O nome de uma tabela é igual ao nome do ficheiro SQLX de definição da tabela.

Para substituir o esquema e o nome de uma tabela selecionada, siga estes passos:

  1. Aceda ao seu espaço de trabalho de desenvolvimento.

  2. No painel Ficheiros, expanda definitions/.

  3. Abra um ficheiro de definição de tabela SQLX.

  4. No bloco config, introduza o seguinte fragmento do código:

     {
   schema: "OVERRIDDEN_SCHEMA",
   database: "OVERRIDDEN_DATABASE",
   name: "OVERRIDDEN_NAME"
 }

    Substitua o seguinte:

    • OVERRIDDEN_SCHEMA: o conjunto de dados do BigQuery no qual quer criar a tabela.

    • OVERRIDDEN_DATABASE: o ID do projeto do BigQuery no qual quer criar a tabela.

    • OVERRIDDEN_NAME: o nome da tabela, que é diferente do nome do ficheiro de definição da tabela SQLX.

  5. Opcional: clique em Formatar.

Para mais informações, consulte o artigo Faça referência a uma tabela com um nome de tabela substituído.

Crie partições e clusters de tabelas

Esta secção mostra como usar o Dataform core para criar partições e clusters de tabelas. O BigQuery suporta tabelas particionadas e agrupamento de tabelas. Para mais informações, consulte os artigos Introdução às tabelas particionadas e Criar e usar tabelas agrupadas.

Crie uma partição de tabela

Para criar uma partição de tabela, siga estes passos:

  1. Aceda ao seu espaço de trabalho de desenvolvimento.
  2. No painel Ficheiros, expanda definitions/.
  3. Abra um ficheiro SQLX de definição de tabela.

  4. No bloco config, adicione o bloco bigquery abaixo da declaração do tipo de tabela no seguinte formato:

    config {
  type: "table",
  bigquery: {
  }
}

  5. No bloco bigquery, introduza o seguinte fragmento do código:

        partitionBy: "PARTITION_EXPRESSION"

    Substitua PARTITION_EXPRESSION por uma expressão para particionar a tabela.

  6. Opcional: clique em Formatar.

O exemplo de código seguinte mostra a partição de uma tabela por hora num ficheiro SQLX de definição de tabela:

config {
  type: "table",
  bigquery: {
    partitionBy: "DATETIME_TRUNC(<timestamp_column>, HOUR)"
  }
}

O exemplo de código seguinte mostra a partição de uma tabela por um valor inteiro num ficheiro SQLX de definição de tabela:

config {
  type: "table",
  bigquery: {
    partitionBy: "RANGE_BUCKET(<integer_column>, GENERATE_ARRAY(0, 1000000, 1000))"
  }
}

Defina um filtro de partição

Para definir um filtro de partição, siga estes passos:

  1. Aceda ao seu espaço de trabalho de desenvolvimento.
  2. No painel Ficheiros, expanda definitions/.
  3. Abra um ficheiro SQLX de definição de tabela particionada.

  4. No bloco bigquery, introduza o seguinte fragmento do código:

    requirePartitionFilter : true

  5. Opcional: clique em Formatar.

O seguinte exemplo de código mostra um filtro de partição definido no bloco bigquery de um ficheiro SQLX de tabela particionada:

config {
  type: "table",
  bigquery: {
    partitionBy: "DATE(ts)",
    requirePartitionFilter : true
  }
}
SELECT CURRENT_TIMESTAMP() AS ts

Para mais informações sobre o filtro de partição no BigQuery, consulte o artigo Definir o atributo de filtro de partição obrigatório numa tabela particionada.

Defina um período de retenção para partições

Para controlar a retenção de todas as partições numa tabela particionada, siga estes passos:

  1. Aceda ao seu espaço de trabalho de desenvolvimento.
  2. No painel Ficheiros, expanda definitions/.
  3. Abra um ficheiro SQLX de definição de tabela particionada.

  4. No bloco bigquery, introduza o seguinte fragmento do código:

    partitionExpirationDays: NUMBER_OF_DAYS

    Substitua NUMBER_OF_DAYS pelo número de dias durante os quais quer reter as partições.

  5. Opcional: clique em Formatar.

O seguinte exemplo de código mostra um período de retenção para partições definido como 14 dias no bloco bigquery de um ficheiro SQLX de tabela particionada:

config {
  type: "table",
  bigquery: {
    partitionBy: "DATE(ts)",
    partitionExpirationDays: 14,
  }
}
SELECT CURRENT_TIMESTAMP() AS ts

Crie um cluster de tabelas

Para criar um cluster de tabelas, siga estes passos:

  1. Aceda ao seu espaço de trabalho de desenvolvimento.
  2. No painel Ficheiros, expanda definitions/.
  3. Abra um ficheiro SQLX de definição de tabela.

  4. No bloco bigquery, introduza o seguinte fragmento do código:

        clusterBy: ["CLUSTER_COLUMN"]

    Substitua CLUSTER_COLUMN pelo nome da coluna pela qual quer agrupar a tabela. Para mais informações, consulte clustering_column_list.

  5. Opcional: clique em Formatar.

O exemplo de código seguinte mostra uma tabela particionada agrupada por colunas name e revenue:

config {
  type: "table",
  bigquery: {
    partitionBy: "DATE(ts)",
    clusterBy: ["name", "revenue"]
  }
}
SELECT CURRENT_TIMESTAMP() as ts, name, revenue

Configure uma tabela incremental

Esta secção mostra como usar o Dataform core para configurar uma tabela incremental.

Acerca das tabelas incrementais

O Dataform atualiza as tabelas de forma diferente com base no tipo de tabela. Durante cada execução de uma tabela ou uma vista, o Dataform recompila a tabela ou a vista inteira desde o início.

Quando define uma tabela incremental, o Dataform cria a tabela incremental de raiz apenas pela primeira vez. Durante as execuções subsequentes, o Dataform só insere ou une novas linhas na tabela incremental de acordo com as condições que configurar.

O Dataform insere novas linhas apenas em colunas que já existem na tabela incremental. Se fizer alterações à consulta de definição da tabela incremental, por exemplo, adicionando uma nova coluna, tem de reconstruir a tabela de raiz. Para o fazer, da próxima vez que acionar uma execução da tabela, selecione a opção Executar com atualização completa.

Seguem-se alguns exemplos de utilização comuns para tabelas incrementais:

Otimização do desempenho
Para alguns tipos de dados, como registos Web ou dados de estatísticas, pode querer processar apenas novos registos em vez de voltar a processar a tabela inteira.
Redução da latência
Pode usar tabelas incrementais para executar fluxos de trabalho de forma rápida, mas frequente, o que reduz a latência a jusante das tabelas de saída.
Instantâneos diários
Pode configurar uma tabela incremental para criar instantâneos diários dos dados da tabela, por exemplo, para a análise longitudinal das definições do utilizador armazenadas numa base de dados de produção.

Processe um subconjunto de linhas numa tabela incremental

Para determinar um subconjunto de linhas para o Dataform processar durante cada execução, adicione uma cláusula WHERE condicional ao ficheiro de definição SQLX da tabela incremental. Na cláusula WHERE, pode especificar uma condição incremental e uma condição não incremental. O Dataform aplica a condição incremental durante a execução da tabela sem uma atualização completa e a condição não incremental durante a execução com uma atualização completa.

Para configurar uma tabela incremental, siga estes passos:

  1. Aceda ao seu espaço de trabalho de desenvolvimento.
  2. No painel Ficheiros, expanda definitions/.
  3. Abra um ficheiro SQLX de definição de tabela incremental.

  4. Introduza uma cláusula WHERE no seguinte formato:

    config { type: "incremental" }

SELECT_STATEMENT

${when(incremental(), `WHERE INCREMENTAL_CONDITION`, `WHERE NON_INCREMENTAL_CONDITION`) }

    Substitua o seguinte:

    • SELECT_STATEMENT: a declaração SELECT que define a sua tabela.
    • INCREMENTAL_CONDITION: a condição que especifica na cláusula WHERE para selecionar linhas para o Dataform processar durante a execução da tabela sem uma atualização completa.
    • NON_INCREMENTAL_CONDITION: a condição especificada na cláusula WHERE para selecionar linhas para o Dataform processar durante a execução da tabela com uma atualização completa.

  5. Opcional: clique em Formatar.

O seguinte exemplo de código mostra uma tabela incremental que processa incrementalmente as linhas da tabela productiondb.logs:

config { type: "incremental" }

SELECT timestamp, message FROM ${ref("productiondb", "logs")}

${when(incremental(),
   `WHERE date > (SELECT MAX(date) FROM ${self()}) AND country = "UK"`,
   `WHERE country = "UK"`)}

O exemplo de código seguinte mostra uma tabela incremental que cria uma imagem instantânea da tabela productiondb.customers:

config { type: "incremental" }

SELECT CURRENT_DATE() AS snapshot_date, customer_id, name, account_settings FROM ${ref("productiondb", "customers")}

${when(incremental(), `WHERE snapshot_date > (SELECT MAX(snapshot_date) FROM ${self()})`) }

Una linhas numa tabela incremental

Para verificar se uma tabela incremental contém apenas uma linha correspondente a uma combinação de colunas selecionada, defina as colunas selecionadas como uniqueKey para unir linhas que tenham o mesmo valor uniqueKey. Quando atualiza a tabela, o Dataform une as linhas com o mesmo valor de uniqueKey em vez de as acrescentar.

Para configurar a união numa tabela incremental, siga estes passos:

  1. Aceda ao seu espaço de trabalho de desenvolvimento.
  2. No painel Ficheiros, expanda definitions/.
  3. Selecione um ficheiro SQLX de definição de tabela incremental

  4. No bloco config, defina as colunas selecionadas como uniqueKey no seguinte formato:

    uniqueKey: ["COLUMN_NAME"]

    Substitua COLUMN_NAME pelo nome de uma coluna selecionada.

  5. Opcional: clique em Formatar.

O seguinte exemplo de código mostra uma tabela incremental com a coluna transaction_id definida como uniqueKey para verificar se contém sempre uma linha:

config {
  type: "incremental",
  uniqueKey: ["transaction_id"]
}

SELECT timestamp, action FROM weblogs.user_actions
${ when(incremental(), `WHERE timestamp > (SELECT MAX(timestamp) FROM ${self()})`) }

Filtre linhas numa tabela incremental

Numa tabela particionada incremental, para evitar que o Dataform analise toda a tabela para encontrar linhas correspondentes, defina updatePartitionFilter para considerar apenas um subconjunto de registos.

O seguinte exemplo de código mostra uma tabela particionada incremental com a união configurada através da definição das propriedades uniqueKey e updatePartitionFilter:

config {
  type: "incremental",
  uniqueKey: ["transaction_id"],
  bigquery: {
    partitionBy: "DATE(timestamp)",
    updatePartitionFilter:
        "timestamp >= timestamp_sub(current_timestamp(), interval 24 hour)"
  }
}

SELECT timestamp, action FROM weblogs.user_actions
${ when(incremental(), `WHERE timestamp > (SELECT MAX(timestamp) FROM ${self()})`) }

Evite análises completas de tabelas quando carrega dados de uma tabela particionada

Quando cria uma tabela incremental que faz referência a uma tabela particionada, recomendamos que crie a consulta da tabela para evitar análises completas da tabela particionada durante cada atualização incremental.

Pode limitar o número de partições que o BigQuery analisa para atualizar a tabela incremental usando uma expressão constante na consulta da tabela. Para transformar um valor da tabela particionada numa expressão constante, use scripts do BigQuery para declarar o valor como uma variável no bloco pre_operations. Em seguida, use a variável como uma expressão constante numa cláusula WHERE na consulta SELECT.

Com esta configuração, o Dataform atualiza a tabela incremental com base nas partições mais recentes da tabela particionada referenciada, sem analisar a tabela completa.

Para configurar uma tabela incremental que faça referência a uma tabela particionada e evite análises completas de tabelas, siga estes passos:

  1. Aceda ao seu espaço de trabalho de desenvolvimento.
  2. No painel Ficheiros, expanda definitions/.
  3. Selecione um ficheiro SQLX de definição de tabela incremental
  4. No bloco pre_operations, declare uma variável com scripts do BigQuery.
  5. Filtre a declaração SELECT que define a tabela com uma cláusula WHERE que faz referência à variável declarada.
  6. Opcional: clique em Formatar.

O exemplo de código seguinte mostra uma tabela incremental na qual a tabela raw_events referenciada é particionada por event_timestamp:

config {
  type: "incremental",
}

pre_operations {
  DECLARE event_timestamp_checkpoint DEFAULT (
    ${when(incremental(),
    `SELECT max(event_timestamp) FROM ${self()}`,
    `SELECT timestamp("2000-01-01")`)}
  )
}

SELECT
  *
FROM
  ${ref("raw_events")}
WHERE event_timestamp > event_timestamp_checkpoint

No exemplo de código anterior, a variável event_timestamp_checkpoint é definida no bloco pre_operations. A variável event_timestamp_checkpoint é, em seguida, usada como uma expressão constante na cláusula WHERE.

Recrie uma tabela incremental do zero com uma atualização completa

Pode forçar a reconstrução de uma tabela incremental do zero através da interface de linhas de comando com a opção --full-refresh ou da opção Executar com atualização completa quando aciona a execução de um fluxo de trabalho.

Quando seleciona a opção de atualização completa no espaço de trabalho de desenvolvimento ou através da CLI Dataform, o Dataform ignora o parâmetro ${when(incremental(), ... } durante a execução e recria a tabela com uma declaração CREATE OR REPLACE.

Proteja uma tabela incremental da atualização completa

Para proteger uma tabela incremental contra a recriação de raiz e uma potencial perda de dados, pode definir a tabela incremental como protected. Pode querer impedir a recriação de uma tabela incremental se a sua origem de dados for temporária.

Para marcar uma tabela incremental como protected, siga estes passos:

  1. Aceda ao seu espaço de trabalho de desenvolvimento.
  2. No painel Ficheiros, expanda definitions/.
  3. Selecione um ficheiro SQLX de definição de tabela incremental.
  4. No bloco config, introduza protected: true.
  5. Opcional: clique em Formatar.

O seguinte exemplo de código mostra uma tabela incremental marcada como protected:

config {
  type: "incremental",
  protected: true
}
SELECT ...

Adicione documentação da tabela

Esta secção mostra como adicionar descrições de uma tabela e das respetivas colunas e registos a um ficheiro SQLX do Dataform core.

Pode adicionar descrições de tabelas, colunas e registos a todos os tipos de tabelas no Dataform: tabelas, tabelas incrementais e vistas.

É recomendável documentar o seguinte:

  • A finalidade da tabela.
  • O conteúdo ou a função das colunas ou dos registos na tabela.
  • A relação da tabela e outras ações do seu fluxo de trabalho, por exemplo, as tabelas ou as vistas que dependem da tabela atual.
  • As afirmações aplicadas à tabela.
  • As pré-operações ou as pós-operações aplicadas à tabela.
  • O proprietário da tabela, ou seja, o utilizador que a criou. Estas informações podem ser úteis se vários membros da equipa trabalharem num fluxo de trabalho.

Adicione uma descrição da tabela

Para adicionar uma descrição a uma tabela num ficheiro SQLX, siga estes passos:

  1. Na Google Cloud consola, aceda à página Dataform.

    Aceder ao Dataform

  2. Selecione um repositório.

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

  4. No painel Ficheiros, clique no ficheiro SQLX de definição da tabela que quer editar.

  5. No bloco config do ficheiro, introduza a descrição da tabela no seguinte formato:

    description: "Description of the table",

  6. Opcional: clique em Formatar.

O exemplo de código seguinte mostra uma descrição da tabela adicionada ao bloco config de um ficheiro de definição de tabela SQLX:

config {
  type: "table",
  description: "Description of the table",
 }

Adicione descrições de colunas e registos

Para adicionar descrições de colunas e registos individuais a um ficheiro SQLX, siga estes passos:

  1. No bloco config do ficheiro de definição da tabela, introduza columns: {}.

  2. Dentro de columns: {}, introduza descrições de colunas no seguinte formato:

    column_name: "Description of the column",

  3. Em columns: {}, introduza as descrições dos registos no seguinte formato:

      record_name: {
      description: "Description of the record",
      columns: {
        record_column_name: "Description of the record column"
      }
}

  4. Opcional: clique em Formatar.

O exemplo de código seguinte mostra descrições de tabelas, colunas e registos no bloco config de um ficheiro de definição de tabelas SQLX:

config {
  type: "table",
  description: "Description of the table.",
  columns: {
    column1_name: "Description of the first column",
    column2_name: "Description of the second column",
    column3_name: "Description of the third column",
    record_name: {
      description: "Description of the record.",
      columns: {
       record_column1_name: "Description of the first record column",
       record_column2_name: "Description of the second record column",
      }
    }
  }
}
SELECT
  "first_column_value" AS column_1_name,
  "second_column_value" AS column_2_name,
  "third_column_value" AS column_3_name,
  STRUCT("first" AS record_column1_name,
    "second" AS record_column2_name) AS record_name

Reutilize a documentação de colunas com inclusões

Pode reutilizar descrições de colunas no Dataform no seu fluxo de trabalho de SQL com inclusões de JavaScript. Pode querer reutilizar a documentação das colunas se tiver várias colunas com o mesmo nome e descrição no seu fluxo de trabalho de SQL.

Pode definir uma constante com uma descrição de uma única coluna ou uma constante com um conjunto ou uma descrição de coluna para reutilizar as descrições de todas as colunas numa tabela. Para mais informações sobre como criar e usar inclusões no Dataform, consulte Reutilize código num único repositório com inclusões.

O seguinte exemplo de código mostra várias constantes com descrições de colunas individuais definidas no ficheiro JavaScript includes/docs.js:


// filename is includes/docs.js

const user_id = `A unique identifier for a user`;
const age = `The age of a user`;
const creation_date = `The date this user signed up`;
const user_tenure = `The number of years since the user's creation date`;
const badge_count = `The all-time number of badges the user has received`;
const questions_and_answer_count = `The all-time number of questions and answers the user has created`;
const question_count = `The all-time number of questions the user has created`;
const answer_count = `The all-time number of answers the user has created`;
const last_badge_received_at = `The time the user received their most recent badge`;
const last_posted_at = `The time the user last posted a question or answer`;
const last_question_posted_at = `The time the user last posted an answer`;
const last_answer_posted_at = `The time the user last posted a question`;

module.exports = {
   user_id,
   age,
   creation_date,
   user_tenure,
   badge_count,
   questions_and_answer_count,
   question_count,
   answer_count,
   last_badge_received_at,
   last_posted_at,
   last_question_posted_at,
   last_answer_posted_at,
};

O exemplo de código seguinte mostra as constantes user_id e age, definidas em includes/docs.js, usadas no ficheiro de definição da tabela SQLX definitions/my_table.sqlx para gerar documentação para colunas selecionadas na tabela:

config {
  type: "table",
  description: "Table description.",
  columns: {
    user_id: docs.user_id,
    column2_name: "Description of the second column",
    column3_name: "Description of the third column",
    age: docs.age,
  }
}

SELECT ...

O seguinte exemplo de código mostra uma constante com um conjunto de descrições de colunas definidas no ficheiro JavaScript includes/docs.js:


// filename is includes/docs.js

const columns = {
    user_id = `A unique identifier for a user`,
    age = `The age of a user`,
    creation_date = `The date this user signed up`,
    user_tenure = `The number of years since the user's creation date`,
    badge_count = `The all-time number of badges the user has received`,
    questions_and_answer_count = `The all-time number of questions and answers the user has created`,
    question_count = `The all-time number of questions the user has created`,
    answer_count = `The all-time number of answers the user has created`,
    last_badge_received_at = `The time the user received their most recent badge`,
    last_posted_at = `The time the user last posted a question or answer`,
    last_question_posted_at = `The time the user last posted an answer`,
    last_answer_posted_at = `The time the user last posted a question`,
}


module.exports = {
  columns
};

O exemplo de código seguinte mostra a constante columns, que está definida em includes/table_docs.js e é usada no ficheiro de definição da tabela definitions/my_table.sqlx SQLX para gerar documentação para todas as colunas na tabela:

config { type: "table",
description: "My table description",
columns: docs.columns
}

SELECT 1 AS one

Adicione etiquetas do BigQuery

Esta secção mostra como adicionar etiquetas a tabelas no Dataform.

O BigQuery suporta a adição de etiquetas a recursos. Para mais informações sobre as etiquetas no BigQuery, consulte o artigo Introdução às etiquetas.

Para adicionar uma etiqueta do BigQuery a uma tabela no Dataform, adicione a etiqueta ao bloco bigquery no bloco config do ficheiro SQLX de definição da tabela.

Para adicionar uma etiqueta do BigQuery a um ficheiro de definição de tabela, siga estes passos:

  1. Aceda ao seu espaço de trabalho de desenvolvimento.
  2. No painel Ficheiros, expanda definitions/.
  3. Selecione um ficheiro de definição de tabela SQLX.

  4. No bloco config, adicione uma etiqueta no seguinte formato:

    bigquery: {
    labels: {
      LABEL1: "VALUE_OF_LABEL1"
    }
  }

    Substitua o seguinte:

    • LABEL1: o nome da sua editora
    • VALUE_OF_LABEL1: o valor da sua etiqueta

  5. Opcional: para adicionar uma etiqueta com um nome que contenha carateres especiais, introduza o nome da etiqueta entre aspas ("").

  6. Opcional: clique em Formatar.

O seguinte exemplo de código mostra as etiquetas department:shipping e cost-center:logistics adicionadas ao bloco bigquery num ficheiro SQLX de definição de tabela particionada:

config {
  type: "table",
  bigquery: {
    partitionBy: "DATE(ts)",
    labels: {
      department: "shipping",
      "cost-center": "logistics"
    }
  }
}

SELECT CURRENT_TIMESTAMP() AS ts

O que se segue?