Neste documento, mostramos como definir tabelas com o núcleo do Dataform no Dataform.
Sobre as definições de tabela
Para definir uma tabela, defina o tipo dela e grave uma instrução SELECT
em um arquivo 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.
Em uma instrução SELECT
principal do Dataform, você define a estrutura da tabela e
faz referência a outros objetos do fluxo de trabalho SQL.
Além de definir tabelas em um arquivo SLQX type: "table"
, é possível criar
tabelas vazias definindo uma consulta SQL personalizada em um arquivo SQLX type: "operations"
.
Para saber mais, consulte Criar uma tabela vazia.
Dependências de referência com ref
Para fazer referência a um objeto de fluxo de trabalho SQL em uma instrução SELECT
e adicioná-lo
automaticamente como uma dependência, use a função ref
. O Dataform executa
dependências antes das tabelas que dependem delas para garantir a ordem correta do pipeline.
A função ref
é uma função integrada fundamental do Dataform
fundamental para o gerenciamento de dependências no Dataform. A função ref
permite
fazer referência e depender automaticamente dos seguintes objetos definidos no
fluxo de trabalho SQL do Dataform, em vez de codificar o esquema e os nomes da tabela:
- tabelas de todos os tipos de tabelas compatíveis
- declarações da fonte de dados
- operações SQL personalizadas com a propriedade
hasOutput
definida comotrue
.
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 instruções boilerplate, como
CREATE
, REPLACE
, INSERT
ou MERGE
à instrução SQL.
O exemplo de código a seguir mostra uma definição de tabela com o uso 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
, forneça o nome da tabela ou da declaração da fonte de dados de que você quer depender. Normalmente, é o nome do arquivo SQLX em que essa tabela ou declaração de fonte de dados está definida.
Se um nome de tabela for substituído, use o nome substituído na função ref
.
Por exemplo, faça referência a uma tabela com config { name: "overridden_name" }
como ref("overridden_name")
. Para mais informações sobre a modificação de nomes de tabelas, consulte Definir outras configurações de tabelas.
Quando você tem várias tabelas com o mesmo nome em esquemas diferentes, é possível referenciar uma tabela específica fornecendo dois argumentos para a função ref
: nome do esquema e nome da tabela.
O exemplo de código a seguir mostra a função ref
com dois argumentos para especificar uma tabela em um esquema específico:
config { type: "table" }
SELECT * FROM ${ref("schema", "store_clean")}
Também é possível adicionar dependências de tabela manualmente ao bloco config
para tabelas, declarações, declarações de fonte de dados ou operações SQL personalizadas que não são referenciadas em uma função ref
na instrução SELECT
. O Dataform
executa essas dependências antes das tabelas dependentes.
O exemplo de código a seguir mostra uma dependência de tabela no bloco config
:
config { dependencies: [ "unreferenced_table" ] }
SELECT * FROM ...
Para mais informações sobre gerenciamento de dependências no fluxo de trabalho SQL, consulte Declarar dependências.
Referenciar outras tabelas com resolve
A função resolve
permite referenciar uma tabela ou declaração de fonte de dados em uma instrução SELECT
,
como a função ref
, mas não adiciona a referência como uma dependência. Isso
significa que o objeto referenciado usando resolve
não afeta a execução
da tabela que usa resolve
.
Para mais informações sobre as funções principais integradas do Dataform, consulte a Referência principal do Dataform.
Antes de começar
- Crie e inicialize um espaço de trabalho de desenvolvimento no seu repositório.
- Opcional: declare uma origem de dados.
Funções exigidas
Para receber as permissões necessárias para definir uma tabela,
peça ao administrador para conceder a você o
papel do IAM de Editor do Dataform (roles/dataform.editor
) nos espaços de trabalho.
Para mais informações sobre como conceder papéis, consulte Gerenciar acesso.
Talvez você também consiga receber as permissões necessárias por meio de papéis personalizados ou outros papéis predefinidos.
Criar um arquivo SQLX para definição de tabela
Armazene arquivos SQLX de definição de tabela no diretório definitions/
. Para criar um
novo arquivo SQLX no diretório definitions/
, siga estas etapas:
No console do Cloud, acesse a página Dataform.
Para abrir um repositório, clique no nome dele.
Para abrir um espaço de trabalho de desenvolvimento, clique no nome dele.
No painel Arquivos, ao lado de
definitions/
, clique no menu Mais.Clique em Criar arquivo.
No campo Add a file path, insira o nome do arquivo seguido de
.sqlx
apósdefinitions/
. Por exemplo,definitions/my-table.sqlx
.Os nomes de arquivos só podem incluir números, letras, hifens e sublinhados.
Clique em Criar arquivo.
Definir o tipo de tabela
Para criar uma definição de tipo de tabela, siga estas etapas:
- No espaço de trabalho de desenvolvimento, no painel Files, expanda o
diretório
definitions/
. - Selecione o arquivo SQLX de definição de tabela que você quer editar.
No arquivo, digite o seguinte snippet de código:
config { type: "TABLE_TYPE" }
Substitua TABLE_TYPE por um dos seguintes tipos de tabela:
table
incremental
view
Opcional: para definir uma visualização materializada, insira a propriedade
materialized
emtype: "view"
no seguinte formato:config { type: "view", materialized: true }
Para mais informações, consulte a referência principal do
ITableConfig
Dataform.Opcional: clique em Formatar.
Definir a estrutura e as dependências da tabela
Para escrever uma instrução SELECT
de definição de tabela e definir a estrutura e as dependências da tabela, siga estas etapas:
- No espaço de trabalho de desenvolvimento, no painel Files, expanda
o diretório
definitions/
. - Selecione o arquivo SQLX de definição de tabela que você quer editar.
- Abaixo do bloco
config
, escreva uma instruçãoSELECT
. - Opcional: clique em Formatar.
O exemplo de código a seguir mostra uma definição de tabela com uma instruçã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
Adicionar dependências manuais de tabelas
Para adicionar dependências de tabela que não são mencionadas na instrução SELECT
,
mas precisam ser executadas antes da tabela atual, siga estas etapas:
- No espaço de trabalho de desenvolvimento, no painel Files, expanda
o diretório
definitions/
. - Selecione o arquivo SQLX de definição de tabela que você quer editar.
No bloco
config
da tabela, insira o seguinte snippet de código:dependencies: [ "DEPENDENCY_TABLE", ]
Substitua DEPENDENCY_TABLE pelo nome do arquivo da tabela que você quer adicionar como dependência. Você pode inserir vários nomes de arquivos.
Opcional: clique em Formatar.
O exemplo de código a seguir mostra duas tabelas adicionadas como dependências manuais ao bloco config
de um arquivo de definição de tabela:
config { dependencies: [ "some_table", "some_other_table" ] }
A seguir
- Para saber como configurar tabelas incrementais, consulte Configurar tabelas incrementais.
- Para saber como configurar clusters e partições de tabelas, consulte Criar clusters e partições de tabelas.
- Para saber como adicionar documentação às tabelas, consulte a página Adicionar documentação da tabela.
- Para saber como testar dados da tabela com declarações, consulte Testar tabelas com declarações.
- Para saber como definir tabelas com JavaScript, consulte Criar fluxos de trabalho SQL com JavaScript.
- Para saber como definir outras configurações da tabela, consulte Definir outras configurações da tabela.