Referência do Dataform Core

Este documento descreve 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 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, 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 desse 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"})

defaultLocation

A propriedade defaultLocation especifica o local padrão do conjunto de dados do BigQuery. O Dataform usa esse local para processar seu código e armazenar os resultados. Esse local de processamento precisa corresponder à localização dos seus conjuntos de dados do BigQuery. No entanto, ele não precisa corresponder ao local do repositório do Dataform.

Se você não definir a propriedade defaultLocation, o Dataform vai determinar o local com base nos conjuntos de dados referenciados pela consulta SQL. Isso funciona da seguinte maneira:

  • Se a consulta fizer referência a conjuntos de dados do mesmo local, o Dataform vai usar esse local.
  • Se a consulta fizer referência a conjuntos de dados de dois ou mais locais diferentes, um erro vai ocorrer. Para mais detalhes sobre essa limitação, consulte Replicação de conjuntos de dados entre regiões.
  • Se a consulta não fizer referência a nenhum conjunto de dados, o local padrão do Dataform será a multirregião US. Para escolher um local diferente, defina a propriedade defaultLocation. Como alternativa, use a variável de sistema @@location na consulta.

Para mais informações, consulte Especificar locais.

IActionConfig

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

tags string[]

Uma lista de tags definidas pelo usuário para rotular a ação.
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 com problemas.

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 asserçã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 corrompidas.
hermetic boolean
Declara se essa 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 essa declaraçã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 table, view e visualização materializada.

Algumas opções, como 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, coloque-o entre aspas, por exemplo: additionalOptions: { "option-name": "value" }.
clusterBy string[]
As chaves usadas 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 forma independente para cada partição com base no tempo de partição.
requirePartitionFilter boolean
Declara se a tabela particionada requer um filtro de predicado de cláusula WHERE que filtra a coluna de particionamento.
updatePartitionFilter string
Filtro baseado em SQL para quando as atualizações incrementais são aplicadas.
iceberg IIcebergOptions
Opções específicas do Apache Iceberg para tabelas gerenciadas do Iceberg.

IIcebergOptions

Opções específicas do Apache Iceberg para tabelas gerenciadas do Iceberg.

connection string

Opcional. O nome do recurso da sua conexão do Cloud Storage, que fornece credenciais para ler e gravar no armazenamento externo. Ele pode ser formatado das seguintes maneiras:

  • PROJECT_ID.LOCATION.CONNECTION_ID

    Substitua os seguintes valores:
    • PROJECT_ID: o ID do projeto do Google Cloud
    • LOCATION: o nome do local da conexão
    • CONNECTION_ID: o nome ou ID da conexão
  • projects/PROJECT_ID/locations/LOCATION/connections/CONNECTION_ID
  • DEFAULT

O valor padrão é DEFAULT. Para mais informações, consulte a Visão geral da conexão padrão.

file_format string

Opcional. O formato do arquivo para os dados da tabela.

Somente PARQUET é aceito. O padrão é PARQUET.

bucket_name string

Obrigatório no nível da tabela ou do fluxo de trabalho. O nome do bucket do Cloud Storage em que os dados da tabela estão armazenados.

É preciso fornecer bucket_name no bloco config do arquivo de definição da tabela ou definir um padrão no nível do fluxo de trabalho no arquivo workflow_settings.yaml. Se nenhum deles for fornecido, a compilação vai falhar. Para mais informações, consulte Configurar padrões no nível do fluxo de trabalho para tabelas do Iceberg .

table_folder_root string

Opcional. O nome da pasta de primeiro nível dentro do bucket do Cloud Storage em que os dados da tabela são armazenados.

Se você não definir essa propriedade, o Dataform vai usar o padrão no nível do fluxo de trabalho de workflow_settings.yaml, se estiver definido. Caso contrário, o padrão será _dataform.

table_folder_subpath string

Opcional. Uma subpasta dentro de tableFolderRoot.

Se você não definir essa propriedade, o Dataform vai usar o padrão no nível do fluxo de trabalho de workflow_settings.yaml, se houver um definido. Se nem a propriedade nem um padrão no nível do fluxo de trabalho forem definidos, o subcaminho vai usar DATASET_NAME/TABLE_NAME como padrão.

Esses valores constroem o URI do Cloud Storage no seguinte formato: gs://BUCKET_NAME/TABLE_FOLDER_ROOT/TABLE_FOLDER_SUBPATH.

IColumnsDescriptor

Descreve as colunas de 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 está.
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 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 essa 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 explicitamente definido como false. Caso contrário, se essa ação depender apenas de dados de dependências declaradas explicitamente, ela precisará 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 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. A ação ainda pode ser usada. Útil para desativar temporariamente ações com falha.
hasOutput boolean
Declara que essa 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 essa 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 está 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 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
Opcional. O local padrão do BigQuery em que o Dataform cria tabelas.
assertionSchema string
Obrigatório. O esquema padrão (ID do conjunto de dados do BigQuery) para as 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 banco de dados (ID do projeto doGoogle 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 deve ser adicionado a todos os nomes de tabelas.
defaultIcebergConfig object
Opcional. Padrões no nível do fluxo de trabalho para tabelas gerenciadas do Apache Iceberg. Contém os seguintes campos:
  • bucketName: opcional. O nome padrão do bucket do Cloud Storage.
  • tableFolderRoot: opcional. O nome padrão da pasta de primeiro nível dentro do bucket do Cloud Storage.
  • tableFolderSubpath: opcional. O nome padrão de uma subpasta em tableFolderRoot.
Para mais informações, consulte Configurar padrões no nível do fluxo de trabalho para tabelas do Iceberg.
preserveGovernanceControls boolean
Opcional. Se definido como true, o Dataform preserva automaticamente as políticas de dados e as tags de governança de dados do BigQuery (pré-lançamento) em todas as execuções de fluxo de trabalho para todas as tabelas no repositório.
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.

É possível acessar todas as propriedades de IProjectConfig em uma instrução SELECT do 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 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 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 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 dentro da struct, do objeto ou do registro.
description string
Uma descrição da estrutura, do objeto ou do registro.

ITableAssertions

Opções para criar asserçõ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 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 vai falhar se alguma linha violar qualquer uma dessas condições.
uniqueKey string | string[]
Colunas que constituem o í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 essas colunas.
uniqueKeys []
Combinações de colunas, cada uma constituindo um índice de chave exclusivo da tabela.

Se definido, a asserçã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
As declarações que serão 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 armazenamento 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. A ação ainda pode ser usada. Útil para desativar temporariamente ações com falha.
hermetic boolean
Declara se essa ação é hermética. Uma ação será 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 definido como verdadeiro, uma visualização materializada será criada.
onSchemaChange onSchemaChange
Válido apenas quando o tipo de tabela é incremental.

A ação realizada depois que o Dataform verifica a consulta SELECT para determinar se colunas foram adicionadas ou removidas.

Esse recurso está na visualização.
preserveGovernanceControls boolean
Opcional. Se definido como true, o Dataform faz backup e reaplica as políticas de dados e as tags de governança de dados do BigQuery (pré-lançamento) ao recriar uma tabela, visualização ou tabela incremental durante uma atualização completa. Substitui os padrões no nível do fluxo de trabalho definidos em workflow_settings.yaml.
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 base em 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 desta 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 junção 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 o código SQL contextualizável, como em arquivos SQLX, ou ao usar um argumento Contextable com o Dataform Core.

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 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 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 . Equivale 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 será criada. Precisa ser definido como BigQuery.
schema string

O esquema em que a saída dessa ação será criada.

onSchemaChange

Depois de definir a propriedade onSchemaChange, o Dataform verifica a consulta SELECT para determinar se colunas foram adicionadas ou removidas. Em seguida, o Dataform realiza a ação especificada pelo valor da propriedade onSchemaChange. É possível definir a ação como uma das seguintes opções:

  • IGNORE (padrão): ignora as colunas adicionadas e mostra um erro para colunas ausentes. Se onSchemaChange não estiver definido, esse será o comportamento padrão quando o esquema mudar.
  • FAIL: interrompe a ação se o Dataform detectar alguma mudança no esquema, o que ajuda a manter a consistência.
  • EXTEND: adiciona novas colunas da consulta à tabela incremental e valores de NULL para registros anteriores. Mostra um erro se uma coluna for removida ou estiver ausente do esquema original na consulta. Use essa configuração para adicionar novas colunas às tabelas incrementais durante o ambiente de execução.

  • SYNCHRONIZE: adiciona novas colunas da consulta à tabela incremental e adiciona valores NULL para registros anteriores. Remove as colunas que estavam no esquema original, mas que agora estão ausentes da consulta atual.

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 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.