Referência principal do Dataform

Este documento descreve os métodos, as propriedades e as opções de configuração do Dataform core. Pode usar o Dataform core em ficheiros SQLX e JavaScript.

assert()

assert (name: string, query?: AContextable)

Adiciona uma asserção do Dataform ao gráfico compilado.

Disponível apenas no diretório /definitions.

Exemplo:

// definitions/file.js

assert("name").query(ctx => "select 1");

CommonContext

Os métodos de contexto estão disponíveis quando avalia código SQL contextualizável, como em ficheiros SQLX, ou quando usa um argumento Contextable com o Dataform core.

database () => string
Devolve a base de dados deste conjunto de dados, se aplicável.
name () => string
Devolve o nome desta tabela.
ref (ref: Resolvable | string[], rest: string[]) => string
Faz referência a outra ação, adicionando-a como uma dependência a esta ação, devolvendo SQL válido para ser usado numa expressão from.

Esta função pode ser chamada com um objeto Resolvable, por exemplo: ${ref({ name: "name", schema: "schema", database: "database" })}

Esta função também pode ser chamada através de argumentos individuais para os valores "database", "schema" e "name". Quando são fornecidos apenas dois valores, é usada a base de dados predefinida e os valores são interpretados como "schema" e "name". Quando é fornecido apenas um valor, são usados a base de dados e o esquema predefinidos, com o valor fornecido interpretado como"name".

${ref("database", "schema", "name")} ${ref("schema", "name")} ${ref("name")}
resolve (ref: Resolvable | string[], rest: string[]) => string
Semelhante a ref, mas não adiciona a ação referenciada como uma dependência desta ação.
self () => string
Equivalente a resolve(name()).

Devolve uma string SQL válida que pode ser usada para referenciar a tabela produzida por esta ação.
schema () => string
Devolve o esquema deste conjunto de dados.

Contextualizável

Os argumentos contextualizáveis podem transmitir um valor simples para o respetivo tipo genérico T ou uma função que é chamada com o objeto de contexto para este tipo de operação.

T | (ctx: Context) => T

Dataform

Variável global que contém o objeto IProjectConfig. Obrigatório para obter propriedades IProjectConfig, por exemplo:

dataform.projectConfig.vars.myVariableName === "myVariableValue"

declare()

declare (dataset: dataform.ITarget)

Declara o conjunto de dados como uma origem de dados do Dataform.

Disponível apenas no diretório /definitions.

Exemplo:

// definitions/file.js

declare({name: "a-declaration"})

IActionConfig

Define etiquetas do Dataform e dependências aplicadas a uma ação do fluxo de trabalho.

tags string[]

Uma lista de etiquetas definidas pelo utilizador com as quais a ação deve ser etiquetada.
dependencies Resolvable| Resolvable[]

Dependências da ação.
disabled boolean

Se estiver definida como verdadeira, esta ação não é executada. No entanto, ainda pode depender da ação. Útil para desativar temporariamente ações danificadas.

IAssertionConfig

Opções de configuração para assertion tipos de ações.

database string
A base de dados (Google Cloud ID do projeto) na qual criar a visualização correspondente para esta afirmação.
description string
Uma descrição desta afirmação.
disabled boolean
Se estiver definido como true, esta ação não é executada. A ação ainda pode ser usada como base. Útil para desativar temporariamente ações com problemas.
hermetic boolean
Declara se esta ação é hermética. Uma ação é hermética se todas as respetivas dependências forem declaradas explicitamente.

Se esta ação depender de dados de uma origem que não seja declarada como uma dependência, defina hermetic como false. Caso contrário, defina como true.

schema string
O esquema (conjunto de dados do BigQuery) no qual criar a visualização correspondente para esta afirmação.
tags string[]
Uma lista de etiquetas definidas pelo utilizador aplicadas a esta ação.

IBigQueryOptions

Opções de armazém específicas do BigQuery.

additionalOptions
Pares de chave-valor para as opções table, view e materialized view.

Algumas opções, por exemplo, partitionExpirationDays, têm campos dedicados de tipo/validade verificados. Para estas opções, use os campos dedicados.

Os valores de string têm de estar encapsulados em aspas duplas, por exemplo: additionalOptions: {numeric_option: "5", string_option: '"string-value"'}

Se o nome da opção contiver carateres especiais, coloque o nome entre aspas, por exemplo: additionalOptions: { "option-name": "value" }.
clusterBy string[]
As chaves pelas quais agrupar partições por.
labels
Pares de chave-valor para etiquetas do BigQuery.

Se o nome da etiqueta contiver carateres especiais, por exemplo, hífenes, coloque o nome entre aspas, por exemplo, labels: { "label-name": "value" }.
partitionBy string
A chave pela qual particionar a tabela. Normalmente, o nome de uma data/hora ou da coluna de data.
partitionExpirationDays number
O número de dias durante os quais o BigQuery armazena dados em cada partição. A definição aplica-se a todas as partições numa tabela, mas é calculada independentemente para cada partição com base na hora da partição.
requirePartitionFilter boolean
Declara se a tabela particionada requer um filtro de predicado da cláusula WHERE que filtra a coluna de particionamento.
updatePartitionFilter string
Filtro baseado em SQL para quando são aplicadas atualizações incrementais.

IColumnsDescriptor

Descreve as colunas numa tabela.

{ [name]: string | IRecordDescriptor }

IDeclarationConfig

Opções de configuração para declaration tipos de ações.

columns IColumnsDescriptor
Uma descrição das colunas na tabela.
database string
A base de dados (ID do projetoGoogle Cloud ) na qual criar a tabela de origem existe.
description string
Uma descrição da tabela.
schema string
O esquema (conjunto de dados do BigQuery) no qual a tabela de origem existe.

IDependenciesConfig

Define as dependências de uma ação do fluxo de trabalho.

dependencies Resolvable| Resolvable[]

Uma ou mais dependências explícitas para esta ação. As ações de dependência são executadas antes das ações dependentes. Normalmente, esta opção permanece não definida, porque a maioria das dependências é declarada como um subproduto da utilização da função ref.
hermetic boolean

Declara se esta ação é hermética ou não. Uma ação é hermética se todas as respetivas dependências forem declaradas explicitamente. Se esta ação depender de dados de uma origem que não tenha sido declarada como uma dependência, então hermetic deve ser explicitamente definido como false. Caso contrário, se esta ação depender apenas de dados de dependências declaradas explicitamente, deve ser definida como true.

IDocumentableConfig

Define descrições de um conjunto de dados e das respetivas colunas.

columns IColumnsDescriptor

Uma descrição das colunas no conjunto de dados.
description string

Uma descrição do conjunto de dados.

INamedConfig

Define o tipo e o nome de uma ação do fluxo de trabalho.

type string

O tipo de ação.
name string

O nome da ação.

IOperationConfig

Opções de configuração para operations tipos de ações.

columns IColumnsDescriptor
Uma descrição das colunas na tabela.
database string
A base de dados (Google Cloud ID do projeto) na qual criar o resultado desta ação.
description string
Uma descrição da tabela.
disabled boolean
Se estiver definido como true, esta ação não é executada. A ação ainda pode ser usada como base. Útil para desativar temporariamente ações danificadas.
hasOutput boolean
Declara que esta ação operations cria uma tabela que é referenciável através da função ref.

Se estiver definido como true, esta ação cria uma tabela com o nome configurado, usando a função de contexto self().

Por exemplo: create or replace table ${self()} as select ...
hermetic boolean
Declara se esta ação é hermética. Uma ação é hermética se todas as respetivas dependências forem declaradas explicitamente.

Se esta ação depender de dados de uma origem que não seja declarada como uma dependência, defina hermetic como false. Caso contrário, defina como true.
schema string
O esquema (conjunto de dados do BigQuery) no qual criar o resultado desta ação.
tags string[]
Uma lista de etiquetas definidas pelo utilizador aplicadas a esta ação.

IProjectConfig

Contém as definições de compilação de um repositório do Dataform.

defaultDatabase string
Obrigatório. A base de dados predefinida (Google Cloud ID do projeto).
defaultSchema string
Obrigatório. O esquema predefinido (ID do conjunto de dados do BigQuery).
defaultLocation string
Obrigatório. A localização predefinida do BigQuery a usar. Para mais informações sobre as localizações do BigQuery, consulte: https://cloud.google.com/bigquery/docs/locations.
assertionSchema string
Obrigatório. O esquema predefinido (ID do conjunto de dados do BigQuery) para asserções.
vars map (key: string, value: string)
Opcional. Variáveis definidas pelo utilizador que são disponibilizadas ao código do projeto durante a compilação. Um objeto que contém uma lista de pares "key": value. Exemplo: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
databaseSuffix string
Opcional. O sufixo que deve ser anexado a todos os nomes de bases de dados (Google Cloud ID do projeto).
schemaSuffix string
Opcional. O sufixo que deve ser anexado a todos os nomes de esquemas (ID do conjunto de dados do BigQuery).
tablePrefix string
Opcional. O prefixo que deve ser anexado a todos os nomes das tabelas.
warehouse string
Obrigatório. Tem de ser definido como bigquery.

Pode definir propriedades IProjectConfig nas definições do fluxo de trabalho ao nível do repositório.

Pode substituir as propriedades defaultSchema e defaultDatabase para tabelas individuais.

Pode aceder a todas as propriedades do IProjectConfig numa declaração SQL SELECT num ficheiro SQLX ou JavaScript.

O exemplo de código seguinte mostra a myVariableNamevariável de compilação personalizada definida nas definições do fluxo de trabalho com a propriedade projectConfig.vars, acedida numa declaração SELECT num ficheiro SQLX:

  config { type: "view" }
  SELECT ${when(
    dataform.projectConfig.vars.myVariableName === "myVariableValue",
    "myVariableName is set to myVariableValue!",
    "myVariableName is not set to myVariableValue!"
  )}

Para mais informações sobre a substituição das definições de configuração do projeto para resultados de compilação individuais, consulte o recurso REST projects.locations.repositories.compilationResults#CodeCompilationConfig na API Dataform.

IRecordDescriptor

Descreve uma struct, um objeto ou um registo numa tabela com colunas aninhadas.

bigqueryPolicyTags string | string[]
Identificadores completos das etiquetas de políticas do BigQuery aplicadas a esta coluna. Um identificador completo de uma etiqueta de política do BigQuery inclui o nome do projeto, a localização e a taxonomia.

Por exemplo: "projects/1/locations/eu/taxonomies/2/policyTags/3"

O BigQuery suporta uma etiqueta por coluna.
columns IColumnsDescriptor
Uma descrição das colunas na estrutura, no objeto ou no registo.
description string
Uma descrição da struct, do objeto ou do registo.

ITableAssertions

Opções para criar afirmações como parte de uma definição de tabela.

nonNull string | string[]
Colunas que nunca podem ser NULL.

Se estiver definida, a asserção correspondente falha se alguma linha contiver valores NULL para estas colunas.
rowConditions string[]
Condições gerais que devem ser verdadeiras para todas as linhas da tabela.

Se estiver definida, a declaração correspondente falha se alguma linha violar alguma destas condições.
uniqueKey string | string[]
Colunas que constituem o índice de chave único da tabela.

Se estiver definido, a asserção resultante falha se existir mais do que uma linha na tabela com os mesmos valores para todas estas colunas.
uniqueKeys []
Combinações de colunas, cada uma das quais constitui um índice de chave único da tabela.

Se estiver definida, a asserção resultante falha se existir mais do que uma linha na tabela com os mesmos valores para todas as colunas nas chaves únicas.

ITableConfig

Opções de configuração para ações table, incluindo os tipos de tabelas table, view e incremental.

Extende IActionConfig, IDependenciesConfig, IDocumentableConfig, INamedConfig e ITargetableConfig.

assertions ITableAssertions
Afirmações a executar na tabela.

Se estiverem configuradas, as afirmações relevantes são criadas automaticamente e executadas como uma dependência desta tabela.
bigquery IBigQueryOptions
Opções de armazém específicas do BigQuery.
columns IColumnsDescriptor
Uma descrição das colunas na tabela.
database string
A base de dados (Google Cloud ID do projeto) na qual criar o resultado desta ação.
description string
Uma descrição da tabela.
disabled boolean
Se estiver definido como true, esta ação não é executada. A ação ainda pode ser usada como base. Útil para desativar temporariamente ações danificadas.
hermetic boolean
Declara se esta ação é hermética. Uma ação é hermética se todas as respetivas dependências forem declaradas explicitamente.

Se esta ação depender de dados de uma origem que não seja declarada como uma dependência, defina hermetic como false. Caso contrário, defina como true.
materialized boolean
Só é válido quando o tipo de tabela é view.

Se estiver definida como verdadeira, é criada uma vista materializada.
protected boolean
Apenas permitido para o tipo de tabela incremental .

Se for definido como verdadeiro, a execução desta ação ignora a opção full-refresh. Isto é útil para tabelas criadas a partir de dados transitórios, para verificar se os dados do histórico nunca são perdidos.
schema string
O esquema (conjunto de dados do BigQuery) no qual criar o resultado desta ação.
tags string[]
Uma lista de etiquetas definidas pelo utilizador aplicadas a esta ação.
type TableType
O tipo de tabela.
uniqueKey string[]
Chaves únicas para critérios de união para tabelas incrementais.

Se estiver configurado, os registos com chaves únicas correspondentes são atualizados em vez de serem inseridas novas linhas.

ITableContext

Os métodos de contexto estão disponíveis quando avalia código SQL contextualizável, como em ficheiros SQLX, ou quando usa um argumento Contextable com o Dataform core.

incremental () => boolean
Devolve true quando o contexto atual indica que a tabela vai ser criada de forma incremental.
name () => string
Devolve o nome totalmente qualificado desta tabela.
ref (ref: Resolvable | string[], rest: string[]) => string
Faz referência a outra ação, adicionando-a como uma dependência a esta ação, devolvendo SQL válido para ser usado numa expressão from.

Esta função pode ser chamada com um objeto Resolvable, por exemplo:

${ref({ name: "name", schema: "schema", database: "database" })}

Esta função também pode ser chamada através de argumentos individuais para os valores "database", "schema" e "name".

Quando são fornecidos apenas dois valores, é usada a base de dados predefinida e os valores são interpretados como "schema" e "name".

Quando é fornecido apenas um valor, é usado o esquema da base de dados predefinido, com o valor fornecido interpretado como"name".

${ref("database", "schema", "name")} ${ref("schema", "name")} ${ref("name")}
resolve (ref: Resolvable | string[], rest: string[]) => string
Semelhante a ref, mas, em vez de adicionar uma dependência, resolve a referência fornecida para que possa ser usada em SQL, por exemplo, numa expressão `from`.
self () => string
Equivalente a resolve(name()).

Devolve uma string SQL válida que pode ser usada para fazer referência à tabela produzida por esta ação.
when (cond: boolean, trueCase: string, falseCase: string) => string
Abreviação de uma condição if . Equivalente a cond ? trueCase : falseCase.

falseCase é opcional e a predefinição é uma string vazia.

ITarget

Uma referência a uma tabela no BigQuery.

database string
name string
schema string

ITargetableConfig

Define a base de dados e o esquema de destino de uma ação do fluxo de trabalho.

database string

A base de dados na qual a saída desta ação deve ser criada. Tem de estar definido como BigQuery.
schema string

O esquema no qual a saída desta ação deve ser criada.

operate()

operate (name: string, queries?: Contextable)

Define uma operação SQL.

Disponível apenas no diretório /definitions.

Exemplo:

// definitions/file.js

operate("an-operation", ["SELECT 1", "SELECT 2"])

publish()

publish (name: string, queryOrConfig?: Contextable | ITableConfig)

Cria uma tabela ou uma vista.

Disponível apenas no diretório /definitions.

Exemplo:

// definitions/file.js

publish("published-table", {
    type: "table",
    dependencies: ["a-declaration"],
  }).query(ctx => "SELECT 1 AS test");

Resolvível

Um resolvable pode ser o nome de uma tabela como string, ou o objeto que descreve o caminho completo para a relação.

string | ITarget

TableType

Tipos de ações de tabela suportados.

As tabelas do tipo view são criadas como vistas.

As tabelas do tipo table são criadas como tabelas.

As tabelas do tipo incremental têm de incluir uma cláusula where. Para mais informações, consulte o artigo Configure uma tabela incremental.