Referência principal do Dataform

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

assert()

assert	(name: string, query?: AContextable)
	Adiciona uma declaração do Dataform ao grafo 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 na avaliação do código SQL contextualizável, 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 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 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 ela 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 deste conjunto de dados.

Contexto

Os argumentos contextuais 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"

Declarar()

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 tags do Dataform e dependências aplicadas a uma ação de fluxo de trabalho SQL.

tags	string[]
	Uma lista de tags definidas pelo usuário com as quais a ação deve ser rotulada.
dependencies	Resolvable| Resolvable[]
	Dependências da ação.
disabled	boolean
	Se definida como verdadeira, esta ação não será executada. No entanto, a ação ainda pode depender da ação. Ú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 projeto do Google Cloud) em que a visualização correspondente para essa declaração será criada.
description	string
	Uma descrição dessa declaração.
disabled	boolean
	Se definida como true, esta ação não será executada. Ainda é possível depender da ação. Útil para desativar temporariamente ações corrompidas.
hermetic	boolean
	Declara se essa ação é hermética. Uma ação é hermética quando todas as dependências são declaradas explicitamente. Se essa ação depender de dados de uma fonte que não foi declarada como dependência, defina hermetic como false. Caso contrário, defina como true.
schema	string
	O esquema (conjunto de dados do BigQuery) em que a visualização correspondente para esta declaração será criada.
tags	string[]
	Uma lista de tags definidas pelo usuário aplicadas a esta ação.

IBigQueryOptions

Opções de 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, como partitionExpirationDays, têm campos dedicados de tipo/validade marcados. 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 contiver caracteres especiais, coloque o nome entre aspas, por exemplo: additionalOptions: { "option-name": "value" }.
clusterBy	string[]
	As chaves pelas quais partições de cluster serão usadas.
labels
	Pares de chave-valor para rótulos do BigQuery. Se o nome do rótulo tiver caracteres especiais, como hifens, entre em citação, por exemplo, labels: { "label-name": "value" }.
partitionBy	string
	A chave usada para particionar a tabela. Normalmente, o nome de um carimbo de data/hora ou a coluna de data.
partitionExpirationDays	number
	O número de dias em que o BigQuery armazena dados em cada partição. Essa configuração se aplica a todas as partições em uma tabela, mas é calculada de modo independente para cada partição com base no tempo de partição.
requirePartitionFilter	boolean
	Declara se a tabela particionada requer um filtro de predicado da cláusula WHERE que filtre a coluna de particionamento.
updatePartitionFilter	string
	Filtro baseado em SQL para quando atualizações incrementais forem aplicadas.

IColumnsDescriptor

Descreve 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 projeto do Google Cloud) em que a tabela de origem será criada.
description	string
	Uma descrição da tabela.
schema	string
	O esquema (conjunto de dados do BigQuery) em que está a tabela de origem.

IDependenciesConfig

Define as dependências de uma ação do 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 seria definido, porque a maioria das dependências é declarada como um subproduto do uso da função ref.
hermetic	boolean
	Declara se a ação é ou não hermética. Uma ação é hermética quando todas as dependências são 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, defina como true.

IDocumentableConfig

Define as descrições de um conjunto de dados e suas colunas.

columns	IColumnsDescriptor
	Uma descrição de colunas dentro do 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 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 projeto do Google Cloud) em que a saída dessa ação será criada.
description	string
	Uma descrição da tabela.
disabled	boolean
	Se definida como true, esta ação não será executada. Ainda é possível depender da ação. Ú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 criará 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 essa ação é hermética. Uma ação é hermética quando todas as dependências são declaradas explicitamente. Se essa ação depender de dados de uma fonte que não foi declarada como dependência, defina hermetic como false. Caso contrário, defina como true.
schema	string
	O esquema (conjunto de dados do BigQuery) em que a saída desta ação será criada.
tags	string[]
	Uma lista de tags definidas pelo usuário aplicadas a esta 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 projeto do Google 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 locais do BigQuery, acesse 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 para o 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 bancos de dados (ID do projeto do Google 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 anexado a todos os nomes de tabelas.
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 em tabelas individuais.

É possível acessar todas as propriedades IProjectConfig em uma instrução SQL SELECT 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 saber mais sobre como modificar as 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 um struct, objeto ou registro em uma tabela com colunas aninhadas.

bigqueryPolicyTags	string | string[]
	Identificadores completos das tags de política do BigQuery aplicados a esta coluna. Um identificador completo de uma tag de política do BigQuery inclui nome, local e 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 em um struct, objeto ou registro.
description	string
	Uma descrição do 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 definida, a declaração correspondente falhará se qualquer linha contiver valores NULL para essas colunas.
rowConditions	string[]
	Condições gerais que devem ser válidas para todas as linhas da tabela. Se definida, 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 definida, a declaração resultante falhará se houver mais de uma linha na tabela com os mesmos valores para todas essas colunas.
uniqueKeys	[]
	Combinações de colunas, cada uma constituindo um índice de chave exclusivo da tabela. Se definida, a declaração resultante falhará se houver mais de uma linha na tabela com os mesmos valores para todas as colunas na(s) chave(s) exclusiva(s).

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
	Declarações a serem executadas na tabela. Se configuradas, as declarações relevantes são criadas e executadas automaticamente como uma dependência dessa tabela.
bigquery	IBigQueryOptions
	Opções de warehouse específicas do BigQuery.
columns	IColumnsDescriptor
	Uma descrição das colunas na tabela.
database	string
	O banco de dados (ID do projeto do Google Cloud) em que a saída dessa ação será criada.
description	string
	Uma descrição da tabela.
disabled	boolean
	Se definida como true, esta ação não será executada. Ainda é possível depender da ação. Útil para desativar temporariamente ações corrompidas.
hermetic	boolean
	Declara se essa ação é hermética. Uma ação é hermética quando todas as dependências são declaradas explicitamente. Se essa ação depender de dados de uma fonte que não foi declarada como dependência, defina hermetic como false. Caso contrário, defina como true.
materialized	boolean
	Válido apenas quando o tipo de tabela é view. Se definido como verdadeiro, uma visualização materializada será criada.
protected	boolean
	Permitido apenas para o tipo de tabela incremental . Se definida como verdadeira, a execução dessa ação ignorará a opção full-refresh. Isso é útil para tabelas criadas a partir de dados temporários para garantir que os dados históricos nunca sejam perdidos.
schema	string
	O esquema (conjunto de dados do BigQuery) em que a saída desta ação será criada.
tags	string[]
	Uma lista de tags definidas pelo usuário aplicadas a esta 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 na avaliação do código SQL contextualizável, 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 padrão do banco de dados é 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 em 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 do fluxo de trabalho SQL.

database	string
	O banco de dados em que a saída desta ação será criada. Precisa ser definido como BigQuery.
schema	string
	O esquema em que a saída desta ação deve ser criada.

operar();

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");

Resolva

Uma resolução 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 compatíveis.

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.