Referência do núcleo do Dataform

Este documento descreve os métodos, as propriedades e as opções de configuração do núcleo do Dataform. É possível usar o núcleo do Dataform em arquivos SQLX e JavaScript.

assert()

assert (name: string, query?: AContextable)

Adiciona uma declaraçã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 ao avaliar o código SQL com contexto, como em arquivos SQLX ou ao usar um argumento Contextable com o núcleo do Dataform.

database () => string
Retorna o banco de dados desse conjunto de dados, se aplicável.
name () => string
Retorna o nome dessa tabela.
ref (ref: Resolvable | string[], rest: string[]) => string
Faz referência a outra ação, adicionando-a como uma dependência a essa ação, retornando um SQL válido para ser usado em uma expressão from.

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

Essa função também pode ser chamada usando argumentos individuais para os valores "database", "schema" e "name". Quando apenas dois valores são fornecidos, o banco de dados padrão é usado e os valores são interpretados como "schema" e "name". Quando apenas um valor é fornecido, o banco de dados e o esquema padrão são usados, 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 a essa ação.
self () => string
Equivale a resolve(name()).

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

Contextable

Os argumentos com contexto podem transmitir um valor simples para o tipo genérico T ou uma função chamada com o objeto de contexto para esse tipo de operação.

T | (ctx: Context) => T

Dataform

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

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

declare()

declare (dataset: dataform.ITarget)

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

Disponível apenas no diretório /definitions.

Exemplo:

// definitions/file.js

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

IActionConfig

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

tags string[]

Uma lista de tags definidas pelo usuário com que a ação precisa ser marcada.
dependencies Resolvable| Resolvable[]

Dependências da ação.
disabled boolean

Se definido como verdadeiro, essa ação não será executada. No entanto, a ação ainda pode ser usada. Útil para desativar temporariamente ações corrompidas.

IAssertionConfig

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

database string
O banco de dados (ID do projetoGoogle Cloud ) em que criar a visualização correspondente a essa declaração.
description string
Uma descrição dessa declaração.
disabled boolean
Se for definido como true, essa ação não será executada. A ação ainda pode ser usada. Útil para desativar temporariamente ações corrompidas.
hermetic boolean
Declara se a ação é hermética. Uma ação é hermética se todas as dependências dela forem declaradas explicitamente.

Se essa ação depender de dados de uma fonte 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) em que criar a visualização correspondente a essa declaração.
tags string[]
Uma lista de tags definidas pelo usuário aplicadas a essa ação.

IBigQueryOptions

Opções de data warehouse específicas do BigQuery.

additionalOptions
Pares de chave-valor para as opções de tabela, visualização e visualização materializada.

Algumas opções, por exemplo, partitionExpirationDays, têm campos dedicados de verificação de tipo/validade. Para essas opções, use os campos dedicados.

Os valores de string precisam ser encapsulados entre aspas duplas, por exemplo: additionalOptions: {numeric_option: "5", string_option: '"string-value"'}

Se o nome da opção tiver caracteres especiais, encapsule o nome entre aspas, por exemplo: additionalOptions: { "option-name": "value" }.
clusterBy string[]
As chaves para agrupar partições.
labels
Pares de chave-valor para rótulos do BigQuery.

Se o nome do rótulo tiver caracteres especiais, por exemplo, hifens, coloque o nome entre aspas, por exemplo, labels: { "label-name": "value" }.
partitionBy string
A chave para particionar a tabela. Normalmente, o nome de um carimbo de data/hora ou da coluna de data.
partitionExpirationDays number
O número de dias em que o BigQuery armazena dados em cada partição. A configuração se aplica a todas as partições de uma tabela, mas é calculada de maneira independente para cada partição com base no tempo de partição.
requirePartitionFilter boolean
Declara se a tabela particionada exige um filtro de predicado de cláusula WHERE que filtre a coluna de particionamento.
updatePartitionFilter string
Filtro baseado em SQL para quando atualizações incrementais são aplicadas.

IColumnsDescriptor

Descreve as colunas em uma tabela.

{ [name]: string | IRecordDescriptor }

IDeclarationConfig

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

columns IColumnsDescriptor
Uma descrição das colunas na tabela.
database string
O banco de dados (ID do projetoGoogle Cloud ) em que a tabela de origem precisa ser criada.
description string
Uma descrição da tabela.
schema string
O esquema (conjunto de dados do BigQuery) em que a tabela de origem existe.

IDependenciesConfig

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

dependencies Resolvable| Resolvable[]

Uma ou mais dependências explícitas para essa ação. As ações de dependência serão executadas antes das ações dependentes. Normalmente, isso não é definido, porque a maioria das dependências é declarada como um subproduto do uso da função ref.
hermetic boolean

Declara se a ação é hermética ou não. Uma ação é hermética se todas as dependências dela forem declaradas explicitamente. Se essa ação depender de dados de uma fonte que não foi declarada como dependência, hermetic precisará ser definido explicitamente como false. Caso contrário, se essa ação depender apenas de dados de dependências declaradas explicitamente, ela precisa ser definida como true.

IDocumentableConfig

Define descrições de um conjunto de dados e suas 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 de fluxo de trabalho SQL.

type string

O tipo de ação.
name string

O nome da ação.

IOperationConfig

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

columns IColumnsDescriptor
Uma descrição das colunas na tabela.
database string
O banco de dados (ID do projetoGoogle Cloud ) em que a saída dessa ação será criada.
description string
Uma descrição da tabela.
disabled boolean
Se for definido como true, essa ação não será executada. A ação ainda pode ser usada. Útil para desativar temporariamente ações corrompidas.
hasOutput boolean
Declara que essa ação operations cria uma tabela que pode ser referenciada usando a função ref.

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

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

Se essa ação depender de dados de uma fonte 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) em que criar a saída dessa ação.
tags string[]
Uma lista de tags definidas pelo usuário aplicadas a essa ação.

IProjectConfig

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

defaultDatabase string
Obrigatório. O banco de dados padrão (ID do projetoGoogle Cloud ).
defaultSchema string
Obrigatório. O esquema padrão (ID do conjunto de dados do BigQuery).
defaultLocation string
Obrigatório. O local padrão do BigQuery a ser usado. Para mais informações sobre os locais do BigQuery, consulte https://cloud.google.com/bigquery/docs/locations.
assertionSchema string
Obrigatório. O esquema padrão (ID do conjunto de dados do BigQuery) para declarações.
vars map (key: string, value: string)
Opcional. Variáveis definidas pelo usuário que são disponibilizadas ao código do projeto durante a compilação. Um objeto com uma lista de pares "key": value. Exemplo: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
databaseSuffix string
Opcional. O sufixo que precisa ser anexado a todos os nomes de banco de dados (ID do projetoGoogle Cloud ).
schemaSuffix string
Opcional. O sufixo que precisa ser anexado a todos os nomes de esquema (ID do conjunto de dados do BigQuery).
tablePrefix string
Opcional. O prefixo que precisa ser adicionado a todos os nomes de tabela.
warehouse string
Obrigatório. Precisa ser definido como bigquery.

É possível definir propriedades IProjectConfig nas configurações do fluxo de trabalho no nível do repositório.

É possível substituir as propriedades defaultSchema e defaultDatabase para tabelas individuais.

É possível acessar todas as propriedades IProjectConfig em uma instrução SELECT SQL em um arquivo SQLX ou JavaScript.

O exemplo de código abaixo mostra a variável de compilação personalizada myVariableName definida nas configurações do fluxo de trabalho com a propriedade projectConfig.vars, acessada em uma instrução SELECT em um arquivo 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 como substituir as configuraçõ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 um struct, objeto ou registro em uma tabela com colunas aninhadas.

bigqueryPolicyTags string | string[]
Identificadores completos das tags de política do BigQuery aplicadas a esta coluna. O identificador completo de uma tag de política do BigQuery inclui o nome, o local e a taxonomia do projeto.

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

O BigQuery aceita uma tag por coluna.
columns IColumnsDescriptor
Uma descrição das colunas no struct, objeto ou registro.
description string
Uma descrição da struct, do objeto ou do registro.

ITableAssertions

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

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

Se definido, a declaração correspondente falhará se qualquer linha contiver valores NULL para essas colunas.
rowConditions string[]
Condições gerais que precisam ser verdadeiras para todas as linhas na tabela.

Se definido, a declaração correspondente falhará se alguma linha violar qualquer uma dessas condições.
uniqueKey string | string[]
Colunas que constituem o índice de chave exclusiva da tabela.

Se definido, a declaração resultante falhará se houver mais de uma linha na tabela com os mesmos valores para todas as colunas.
uniqueKeys []
Combinações de colunas, cada uma constituindo um índice de chave exclusivo da tabela.

Se definido, a declaração resultante falhará se houver mais de uma linha na tabela com os mesmos valores para todas as colunas nas chaves exclusivas.

ITableConfig

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

Estende IActionConfig, IDependenciesConfig, IDocumentableConfig, INamedConfig e ITargetableConfig.

assertions ITableAssertions
Ações a serem executadas na tabela.

Se configurado, as declarações relevantes são criadas automaticamente e executadas como uma dependência dessa tabela.
bigquery IBigQueryOptions
Opções de data warehouse específicas do BigQuery.
columns IColumnsDescriptor
Uma descrição das colunas na tabela.
database string
O banco de dados (ID do projetoGoogle Cloud ) em que a saída dessa ação será criada.
description string
Uma descrição da tabela.
disabled boolean
Se for definido como true, essa ação não será executada. A ação ainda pode ser usada. Útil para desativar temporariamente ações corrompidas.
hermetic boolean
Declara se a ação é hermética. Uma ação é hermética se todas as dependências dela forem declaradas explicitamente.

Se essa ação depender de dados de uma fonte que não seja declarada como uma dependência, defina hermetic como false. Caso contrário, defina como true.
materialized boolean
Válido apenas quando o tipo de tabela for view.

Se definida como verdadeira, uma visualização materializada será criada.
protected boolean
Permitido apenas para o tipo de tabela incremental .

Se definido como verdadeiro, a execução dessa ação ignora a opção full-refresh. Isso é útil para tabelas criadas com dados temporários, para garantir que os dados históricos nunca sejam perdidos.
schema string
O esquema (conjunto de dados do BigQuery) em que criar a saída dessa ação.
tags string[]
Uma lista de tags definidas pelo usuário aplicadas a essa ação.
type TableType
O tipo da tabela.
uniqueKey string[]
Chaves exclusivas para critérios de mesclagem de tabelas incrementais.

Se configurado, os registros com chaves exclusivas correspondentes são atualizados em vez de novas linhas serem inseridas.

ITableContext

Os métodos de contexto estão disponíveis ao avaliar o código SQL com contexto, como em arquivos SQLX ou ao usar um argumento Contextable com o núcleo do Dataform.

incremental () => boolean
Retorna verdadeiro quando o contexto atual indica que a tabela será criada de forma incremental.
name () => string
Retorna 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 essa ação, retornando um SQL válido para ser usado em uma expressão "from".

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

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

Essa função também pode ser chamada usando argumentos individuais para os valores "database", "schema" e "name".

Quando apenas dois valores são fornecidos, o banco de dados padrão é usado e os valores são interpretados como "schema" e "name".

Quando apenas um valor é fornecido, o esquema de banco de dados padrão é usado, 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, ele resolve a referência fornecida para que possa ser usada no SQL, por exemplo, em uma expressão "from".
self () => string
Equivale a resolve(name()).

Retorna uma string SQL válida que pode ser usada para referenciar a tabela produzida por essa 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 o padrão é uma string vazia.

ITarget

Uma referência a uma tabela no BigQuery.

database string
name string
schema string

ITargetableConfig

Define o banco de dados de destino e o esquema de uma ação de fluxo de trabalho SQL.

database string

O banco de dados em que a saída dessa ação precisa ser criada. Precisa ser definido como BigQuery.
schema string

O esquema em que a saída dessa ação precisa 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 visualização.

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 elemento 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 com suporte.

As tabelas do tipo view serão criadas como visualizações.

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

As tabelas do tipo incremental precisam incluir uma cláusula where. Para mais informações, consulte Configurar tabelas incrementais.