Operações de criação

Este documento mostra como definir operações SQL personalizadas num ficheiro SQLX dedicado.

O Dataform pode executar operações SQL personalizadas que não se enquadram no modelo do Dataform de publicação de uma tabela ou escrita de uma afirmação. Pode definir comandos SQL personalizados para o Dataform executar no BigQuery.

Antes de começar

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

    Aceda à página do formulário de dados

  2. Selecione ou crie um repositório.

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

Funções necessárias

Para obter as autorizações de que precisa para definir uma operação SQL personalizada, 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.

Crie um ficheiro para a definição de operação personalizada

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

  1. Aceda ao seu espaço de trabalho de desenvolvimento.
  2. No painel Ficheiros, junto a definitions/, clique no menu Mais.
  3. Clique em Criar ficheiro.

  4. No campo Adicionar um caminho do ficheiro, introduza o nome do ficheiro seguido de .sqlx após definitions/. Por exemplo, definitions/sample-operation.sqlx.

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

  5. Clique em Criar ficheiro.

Defina uma operação de SQL personalizada

Pode definir uma operação SQL personalizada num ficheiro SQLX de type: operations. Pode escrever qualquer declaração SQL do BigQuery num ficheiro operations. O Dataform executa as suas operações SQL personalizadas no BigQuery sem modificação.

Pode definir várias operações SQL personalizadas num ficheiro SQLX. O BigQuery executa todas as operações num ficheiro no mesmo contexto e cria o SQL de execução juntando todas as operações com um ponto e vírgula (;).

Para definir várias operações SQL personalizadas quando usar a estrutura Dataform de código aberto com um armazém de dados que não seja o BigQuery, separe as operações com ---.

Para definir uma operação SQL personalizada num ficheiro SQLX dedicado, siga estes passos:

  1. No seu espaço de trabalho de desenvolvimento, selecione o ficheiro SQLX para a definição da operação personalizada.

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

    config { type: "operations" }

  3. Fora do bloco config, escreva a sua operação SQL.

  4. Opcional: clique em Formatar.

O seguinte exemplo de código mostra várias operações SQL personalizadas definidas num ficheiro operations:

config { type: "operations" }

DELETE FROM dataset.table WHERE country = 'GB';

DELETE FROM dataset.table WHERE country = 'FR';

O seguinte exemplo de código mostra uma operação SQL personalizada que cria manualmente uma vista:

config { type: "operations" }
CREATE OR REPLACE VIEW dataset.table AS (SELECT 1 AS TEST)

Crie uma tabela de saída referenciável

Pode criar manualmente uma tabela numa operação SQL personalizada que pode referenciar noutros scripts. Para criar uma tabela disponível para outros scripts, tem de declarar que a operação tem um resultado.

Para que o nome da tabela de saída corresponda ao nome do ficheiro operations, pode usar a função self na operação CREATE.

Para criar uma tabela numa operação personalizada e disponibilizá-la a outros scripts, siga estes passos:

  1. No espaço de trabalho de desenvolvimento, selecione o ficheiro SQLX para a definição de operações personalizadas.

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

    config {
 type: "operations",
 hasOutput: true
}

  3. Para fazer corresponder o nome da tabela de saída ao nome do ficheiro, escreva uma operação SQL CREATE com a função self no seguinte formato:

    CREATE OR REPLACE TABLE ${self()} AS (CUSTOM_SQL_QUERY)

    Substitua CUSTOM_SQL_QUERY pela declaração SQL de definição da tabela SELECT.

  4. Opcional: clique em Formatar.

Referencie uma tabela de resultados de uma operação SQL personalizada

  • Para fazer referência a uma tabela de saída de operação SQL personalizada numa definição SQLX de uma tabela diferente, introduza o nome do ficheiro da tabela de saída na função ref.

O exemplo de código seguinte mostra uma operação SQL personalizada num ficheiro custom_SQL_operation_table.sqlx que cria uma tabela referenciável denominada custom_SQL_operation_table:

// filename is custom_SQL_operation_table.sqlx
config {
type: "operations",
hasOutput: true
}
CREATE OR REPLACE VIEW ${self()} AS (SELECT 1 AS TEST)

O seguinte exemplo de código mostra a referência ao elemento custom\_SQL\_operation\_table table num ficheiro SQLX de definição de tabela:

config { type: "table" }
SELECT * FROM ${ref("custom_SQL_operation_table")}

Crie uma tabela vazia

Pode querer criar uma tabela vazia para que um serviço diferente a possa preencher com dados. Pode criar uma tabela vazia numa operação SQL personalizada com a função CREATE TABLE. Para poder referenciar a tabela vazia noutras definições de ações do fluxo de trabalho, por exemplo, tabelas e vistas, pode adicionar a propriedade hasOutput:true ao bloco config da operação de tabela vazia.

  • Para criar uma tabela vazia, use a função CREATE TABLE num ficheiro type: "operations" no seguinte formato:
config {
  type: "operations",
  hasOutput: true  // optional, lets you reference the empty table
}

CREATE TABLE ${self()} (

)

O exemplo de código seguinte mostra uma operação SQL personalizada que cria uma tabela vazia com um número inteiro e uma coluna de string. Não é possível fazer referência à tabela vazia criada por outras ações do fluxo de trabalho:

config {
  type: "operations"
}

CREATE TABLE ${self()} (
  x INT64,
  y STRING
)

O que se segue?