Referência principal do Dataform

Este documento descreve os métodos, as propriedades e as opções de configuração de Núcleo do Dataform. É possível usar o Dataform Core no 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

Métodos de contexto estão disponíveis ao avaliar códigos SQL contextuais. como em arquivos SQLX ou ao usar 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 desta 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 o 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 o como uma dependência dessa ação.
self () => string
Equivale a resolve(name()).

Retorna uma string SQL válida que pode ser usada para fazer referência à tabela. produzida por esta ação.
schema () => string
Retorna o esquema deste conjunto de dados.

Contexto

Os argumentos contextualizáveis podem transmitir um valor simples para o tipo genérico deles T ou uma função chamada com o objeto de contexto para esta 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 e dependências do Dataform aplicada a uma ação do 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 pode ainda não dependam deles. Ú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) no qual criar a visualização correspondente dessa declaração.
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 temporariamente desativando ações interrompidas.
hermetic boolean
Declara se essa ação é hermética. Uma ação é hermética se todas as dependências forem declaradas explicitamente.

Se a ação depende de dados de uma fonte que não foi declarada como dependência, em seguida, defina hermetic como false. Caso contrário, defina como true.

schema string
O esquema (conjunto de dados do BigQuery) em que a criação a visualização correspondente dessa declaração.
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 a tabela, a visualização e de visualização materializada.

Algumas opções, como partitionExpirationDays, tem campos dedicados de tipo/validade verificados. 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, por exemplo, hifens, em seguida, cite o nome dela, por exemplo, labels: { "label-name": "value" }.
partitionBy string
A chave pela qual 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 cada partição. A configuração se aplica a todas as partições em uma tabela, mas é calculado de modo independente para cada partição com base o tempo de partição.
requirePartitionFilter boolean
declara se a tabela particionada requer um WHERE; filtro de predicado de cláusula que filtra a coluna de particionamento.
updatePartitionFilter string
Filtro baseado em SQL para quando atualizações incrementais sejam 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) no qual criar a tabela de origem existe.
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. Ações de dependência serão executadas antes das ações dependentes. Normalmente, ela não é definida, 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 se todas as dependências são declaradas explicitamente. Se a ação depender dados de uma fonte que não tenha sido declarada como dependência, hermetic precisa ser definido explicitamente como false. Caso contrário, se a ação depender apenas dos dados de dados declarados explicitamente dependências, ele precisa ser definido 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 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 projeto do Google Cloud) no qual criar a saída desta ação.
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 a 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 a 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 se todas as dependências forem declaradas explicitamente.

Se a ação depende de dados de uma fonte que não foi declarada como dependência, em seguida, defina hermetic como false. Caso contrário, defina como true.
schema string
O esquema (conjunto de dados do BigQuery) em que a criação a saída desta ação.
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, 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 para projetar o código 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 anexado a todos os bancos de dados (ID do projeto do Google Cloud).
schemaSuffix string
Opcional. O sufixo que precisa ser anexado a todo o 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 para 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 a seguir mostra a variável de compilação personalizada myVariableName. definidas nas configurações do fluxo de trabalho com o propriedade projectConfig.vars, acessado 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 modificar as definições de configuração do projeto para conferir os resultados de compilação individual, consulte a O recurso REST projects.locations.repositories.compilationResults#CodeCompilationConfig em 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 essa 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 em um struct, objeto ou registro.
description string
Uma descrição do struct, objeto ou 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 NULL valores para essas colunas.
rowConditions string[]
Condições gerais que devem ser válidas para todas as linhas da tabela.

Se definido, a declaração correspondente falhará se qualquer 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. da tabela com os mesmos valores para todas essas colunas.
uniqueKeys []
Combinações de colunas, sendo que cada uma constitui um índice de chave exclusiva da tabela.

Se definido, a declaração resultante falhará se houver mais de uma linha no da 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 serão criadas automaticamente e executar como uma dependência desta 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) para criar a saída dessa ação.
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 se todas as dependências são declaradas explicitamente.

Se a ação depende de dados de uma fonte que não foi declarada como dependência, em seguida, 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 que são 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 criar a saída desta ação.
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 configurados, os registros com chaves exclusivas correspondentes são atualizados em vez de novas linhas serem inseridas.

ITableContext

Métodos de contexto estão disponíveis ao avaliar códigos SQL contextuais. como em arquivos SQLX ou ao usar um Contextable com o núcleo do Dataform.

incremental () => boolean
Retorna verdadeiro quando o contexto atual indica que a tabela será construída 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 desta 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 o 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, 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 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.

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

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.