Referência do núcleo do Dataform

Neste documento, descrevemos os métodos, as propriedades e as opções de configuração do Dataform Core. É possível usar o Dataform Core em arquivos 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 ao avaliar código SQL contextualizável, como em arquivos SQLX, ou ao usar um argumento Contextable com o Dataform Core.

database	() => string
	Retorna o banco de dados deste 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 esta 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, e 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 deste conjunto de dados.

Contextable

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"

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

tags	string[]
	Uma lista de tags definidas pelo usuário com que a ação deve ser rotulada.
dependencies	Resolvable| Resolvable[]
	Dependências da ação.
disabled	boolean
	Se definido como "true", essa ação não será executada. No entanto, ainda é possível depender da ação. Útil para desativar temporariamente ações com falha.

IAssertionConfig

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

database	string
	O banco de dados (ID do projetoGoogle Cloud ) em que a visualização correspondente para essa declaração será criada.
description	string
	Uma descrição dessa declaração.
disabled	boolean
	Se for definida como true, a ação não será executada. Ainda é possível depender da ação. Útil para desativar temporariamente ações com falha.
hermetic	boolean
	Declara se esta 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 foi 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 a visualização correspondente para esta asserção será criada.
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 tabela, visualização e visualização materializada. Algumas opções, como partitionExpirationDays, têm campos dedicados de tipo/validade verificados. Para essas opções, use os campos dedicados. Os valores de string precisam estar entre aspas duplas, por exemplo: additionalOptions: {numeric_option: "5", string_option: '"string-value"'} Se o nome da opção tiver caracteres especiais, coloque-o entre aspas, por exemplo: additionalOptions: { "option-name": "value" }.
clusterBy	string[]
	As chaves para agrupar partições por.
labels
	Pares de chave-valor para rótulos do BigQuery. Se o nome do rótulo tiver caracteres especiais, como hífens, 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 as 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 será criada existe.
description	string
	Uma descrição da tabela.
schema	string
	O esquema (conjunto de dados do BigQuery) em que a tabela de origem está.

IDependenciesConfig

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

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 permanece indefinido 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 uma 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 deverá ser definida como true.

IDocumentableConfig

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

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.

type	string
	O tipo da 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 desta ação será criada.
description	string
	Uma descrição da tabela.
disabled	boolean
	Se for definida como true, a ação não será executada. Ainda é possível depender da ação. Útil para desativar temporariamente ações com falha.
hasOutput	boolean
	Declara que esta ação operations cria uma tabela que pode ser referenciada usando a função ref. Se definido 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 esta 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 foi 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 desta 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 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 asserçõ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 deve ser adicionado a todos os nomes de banco de dados (ID do projetoGoogle Cloud ).
schemaSuffix	string
	Opcional. O sufixo que deve ser anexado a todos os nomes de esquema (ID do conjunto de dados do BigQuery).
tablePrefix	string
	Opcional. O prefixo que deve ser adicionado a todos os nomes de tabelas.
warehouse	string
	Obrigatório. Precisa ser definido como bigquery.

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

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

Você pode acessar todas as propriedades IProjectConfig em uma instrução SELECT SQL em um arquivo SQLX ou JavaScript.

O exemplo de código a seguir mostra a variável de compilação personalizada myVariableName definida nas configurações de 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 uma struct, um objeto ou um registro em uma tabela com colunas aninhadas.

bigqueryPolicyTags	string | string[]
	Identificadores completos das tags de política do BigQuery aplicadas a esta coluna. Um identificador completo de uma tag de política do BigQuery inclui o nome do projeto, o local e a taxonomia. Por exemplo: "projects/1/locations/eu/taxonomies/2/policyTags/3" O BigQuery aceita uma tag por coluna.
columns	IColumnsDescriptor
	Uma descrição das colunas dentro da struct, do objeto ou do 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 vai falhar se alguma linha contiver valores NULL para essas colunas.
rowConditions	string[]
	Condições gerais que precisam ser válidas para todas as linhas da tabela. Se definido, a declaração correspondente falhará se alguma linha violar alguma dessas condições.
uniqueKey	string | string[]
	Colunas que constituem o índice de chave exclusiva da tabela. Se definido, a declaração resultante vai 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 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
	Declarações a serem executadas na tabela. Se configuradas, as declarações relevantes serão criadas e executadas automaticamente 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 definida como true, a ação não será executada. Ainda é possível depender da ação. Útil para desativar temporariamente ações com falha.
hermetic	boolean
	Declara se esta 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 foi 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 é view. Se for definido como "true", 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 vai ignorar a opção full-refresh. Isso é útil para tabelas criadas com dados temporários, para verificar se os dados históricos nunca são 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 serão atualizados em vez de novas linhas serem inseridas.

ITableContext

Os métodos de contexto estão disponíveis ao avaliar código SQL contextualizável, como em arquivos SQLX, ou ao usar um argumento Contextable com o Dataform Core.

incremental	() => boolean
	Retorna "true" 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 esta ação, retornando 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, resolve a referência fornecida para que ela 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 e o esquema de destino de uma ação de fluxo de trabalho.

database	string
	O banco de dados em que a saída dessa ação deve ser criada. Precisa ser definido como BigQuery.
schema	string
	O esquema em que a saída dessa 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 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");

Resolvable

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 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 uma tabela incremental.