Referencia principal de Dataform

Este documento describe los métodos, las propiedades y las opciones de configuración de Dataform principal. Puedes usar Dataform Core en SQLX y archivos JavaScript.

assert()

assert (name: string, query?: AContextable)

Agrega una aserción de Dataform al grafo compilado.

Disponible solo en el directorio /definitions.

Ejemplo:

// definitions/file.js

assert("name").query(ctx => "select 1");

CommonContext

Los métodos de contexto están disponibles cuando se evalúa el código SQL contextual como dentro de los archivos SQLX, o cuando se usa un El argumento Contextable con el núcleo de Dataform.

database () => string
Muestra la base de datos de este conjunto de datos, si corresponde.
name () => string
Muestra el nombre de esta tabla.
ref (ref: Resolvable | string[], rest: string[]) => string
Hace referencia a otra acción, la agrega como dependencia a esta acción. que muestra un SQL válido para usar en una expresión from.

Esta función se puede llamar con un objeto Resolvable, por ejemplo: ${ref({ name: "name", schema: "schema", database: "database" })}

Esta función también se puede llamar usando argumentos individuales para la Valores "database", "schema" y "name". Cuando solo se proporcionan dos valores, se usa la base de datos predeterminada se interpretan como "schema" y "name". Cuando se proporciona un solo valor, se usan la base de datos y el esquema predeterminados por el valor proporcionado interpretado como `"name"`.

${ref("database", "schema", "name")} ${ref("schema", "name")} ${ref("name")}
resolve (ref: Resolvable | string[], rest: string[]) => string
Es similar a ref, pero no agrega los elementos que se mencionan. como una dependencia de esta acción.
self () => string
Equivale a resolve(name()).

Devuelve una cadena de SQL válida que puede usarse para hacer referencia a la tabla producidos por esta acción.
schema () => string
Muestra el esquema de este conjunto de datos.

Adaptable

Los argumentos contextuales pueden pasar un valor sin formato para su tipo genérico T o una función a la que se llama con el objeto de contexto para esto el tipo de operación.

T | (ctx: Context) => T

Dataform

Variable global que contiene el objeto IProjectConfig. Obligatorio para obtener propiedades IProjectConfig, por ejemplo:

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

declare()

declare (dataset: dataform.ITarget)

Declara el conjunto de datos como fuente de datos de Dataform.

Disponible solo en el directorio /definitions.

Ejemplo:

// definitions/file.js

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

IActionConfig

Define las etiquetas de Dataform y las dependencias aplican a una acción de flujo de trabajo de SQL.

tags string[]

Una lista de etiquetas definidas por el usuario con las que se debe etiquetar la acción.
dependencies Resolvable| Resolvable[]

Dependencias de la acción
disabled boolean

Si la estableces como verdadera, no se ejecutará esta acción. Sin embargo, la acción puede de las que todavía se depende. Útil para desactivar temporalmente las acciones fallidas.

IAssertionConfig

Opciones de configuración para los tipos de acción assertion.

database string
La base de datos (ID del proyecto de Google Cloud) en la que se creará la vista correspondiente para esta aserción.
description string
Es una descripción de esta aserción.
disabled boolean
Si se establece en true, esta acción no se ejecuta. Aún se puede depender de la acción. Útil para temporalmente desactivando las acciones fallidas.
hermetic boolean
Declara si esta acción es hermética. Una acción es hermética si todas sus dependencias se declaran explícitamente.

Si esta acción depende de datos de una fuente no declarada como dependencia y, luego, establece hermetic en false. De lo contrario, configúralo como true.

schema string
El esquema (conjunto de datos de BigQuery) en el que se creará la vista correspondiente para esta aserción.
tags string[]
Una lista de las etiquetas definidas por el usuario que se aplicaron a esta acción.

IBigQueryOptions

Opciones de almacén específicas de BigQuery.

additionalOptions
Pares clave-valor para las tablas table, view y vista materializada.

Algunas opciones, como partitionExpirationDays, tienen campos exclusivos de tipo/validez comprobados. Para estas opciones, usa los campos dedicados.

Los valores de la cadena deben estar encerrados entre comillas dobles, por ejemplo: additionalOptions: {numeric_option: "5", string_option: '"string-value"'}

Si el nombre de la opción contiene caracteres especiales, encapsula el nombre entre comillas por ejemplo: additionalOptions: { "option-name": "value" }.
clusterBy string[]
Las claves por las que se agrupan en clústeres las particiones.
labels
Pares clave-valor para etiquetas de BigQuery.

Si el nombre de la etiqueta contiene caracteres especiales, como guiones, luego, escribe su nombre entre comillas, por ejemplo, labels: { "label-name": "value" }.
partitionBy string
La clave para la particionar la tabla. Por lo general, es el nombre de una marca de tiempo o la columna de la fecha.
partitionExpirationDays number
La cantidad de días en los que BigQuery almacena datos cada partición. El parámetro de configuración se aplica a todas las particiones de una tabla, pero se calcula de forma independiente para cada partición según la hora de partición.
requirePartitionFilter boolean
Declara si la tabla particionada requiere un WHERE filtro de predicado de cláusula que filtra la columna de partición.
updatePartitionFilter string
Filtro basado en SQL para cuándo actualizaciones incrementales de seguridad de Google Cloud.

IColumnsDescriptor

Describe las columnas de una tabla.

{ [name]: string | IRecordDescriptor }

IDeclarationConfig

Opciones de configuración para los tipos de acción declaration.

columns IColumnsDescriptor
Es una descripción de las columnas de la tabla.
database string
La base de datos (ID del proyecto de Google Cloud) en la que se creará de que exista la tabla de origen.
description string
Es una descripción de la tabla.
schema string
El esquema (conjunto de datos de BigQuery) en el que existe la tabla de origen.

IDependenciesConfig

Define las dependencias de una acción de flujo de trabajo de SQL.

dependencies Resolvable| Resolvable[]

Una o más dependencias explícitas para esta acción. Acciones de la dependencia se ejecutará antes que las acciones dependientes. Por lo general, no se establece, ya que la mayoría de las dependencias se declaran como un subproducto del uso de la función ref.
hermetic boolean

Declara si esta acción es hermética o no. Una acción es hermética si declaran explícitamente todas sus dependencias. Si esta acción depende de datos de una fuente que no se declaró como dependencia, entonces hermetic debe configurarse explícitamente como false. De lo contrario, si esta acción solo depende de datos de declaraciones las dependencias, debe configurarse como true.

IDocumentableConfig

Define descripciones de un conjunto de datos y sus columnas.

columns IColumnsDescriptor

Es una descripción de las columnas dentro del conjunto de datos.
description string

Es una descripción del conjunto de datos.

INamedConfig

Define el tipo y nombre de una acción de flujo de trabajo de SQL.

type string

El tipo de acción.
name string

Es el nombre de la acción.

IOperationConfig

Opciones de configuración para los tipos de acción operations.

columns IColumnsDescriptor
Es una descripción de las columnas de la tabla.
database string
La base de datos (ID del proyecto de Google Cloud) en la que se creará el resultado de esta acción.
description string
Es una descripción de la tabla.
disabled boolean
Si se establece en true, esta acción no se ejecuta. Aún se puede depender de la acción. Útil para desactivar temporalmente las acciones fallidas.
hasOutput boolean
Declara que esta acción operations crea una tabla. al que se puede hacer referencia con la función ref.

Si se establece en true, esta acción crea una tabla con sus nombre configurado con la función de contexto self().

Por ejemplo: create or replace table ${self()} as select ...
hermetic boolean
Declara si esta acción es hermética. Una acción es hermética si todas sus dependencias se declaran explícitamente.

Si esta acción depende de datos de una fuente no declarada como dependencia y, luego, establece hermetic en false. De lo contrario, configúralo como true.
schema string
El esquema (conjunto de datos de BigQuery) en el que se creará el resultado de esta acción.
tags string[]
Una lista de las etiquetas definidas por el usuario que se aplicaron a esta acción.

IProjectConfig

Contiene parámetros de configuración de compilación de un repositorio de Dataform.

defaultDatabase string
Obligatorio. La base de datos predeterminada (ID del proyecto de Google Cloud).
defaultSchema string
Obligatorio. El esquema predeterminado (ID del conjunto de datos de BigQuery).
defaultLocation string
Obligatorio. La ubicación predeterminada de BigQuery a usar. Para obtener más información sobre las ubicaciones de BigQuery, consulta https://cloud.google.com/bigquery/docs/locations.
assertionSchema string
Obligatorio. El esquema predeterminado (ID del conjunto de datos de BigQuery) para las aserciones.
vars map (key: string, value: string)
Opcional. Variables definidas por el usuario que están disponibles para proyectar el código durante la compilación. Un objeto que contiene una lista de pares "key": value. Ejemplo: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
databaseSuffix string
Opcional. El sufijo que se debe agregar a todas las bases de datos (ID del proyecto de Google Cloud).
schemaSuffix string
Opcional. El sufijo que se debe agregar a todos los esquemas (ID del conjunto de datos de BigQuery).
tablePrefix string
Opcional. El prefijo que se debe anteponer a todos los nombres de la tabla.
warehouse string
Obligatorio. Se debe configurar en bigquery.

Puedes establecer propiedades de IProjectConfig en la configuración del flujo de trabajo a nivel del repositorio.

Puedes anular las propiedades defaultSchema y defaultDatabase de tablas individuales.

Puedes acceder a todas las propiedades IProjectConfig en una instrucción SELECT de SQL en un archivo SQLX o JavaScript.

En la siguiente muestra de código, se observa la variable de compilación personalizada myVariableName. en la configuración del flujo de trabajo con las propiedad projectConfig.vars, a la que se accede en una sentencia SELECT en un archivo SQLX:

  config { type: "view" }
  SELECT ${when(
    dataform.projectConfig.vars.myVariableName === "myVariableValue",
    "myVariableName is set to myVariableValue!",
    "myVariableName is not set to myVariableValue!"
  )}

Obtén más información para anular los parámetros de configuración del proyecto para obtener resultados de compilación individuales, consulta la projects.locations.repositories.compilationResults#CodeCompilationConfig recurso REST en API de Dataform.

IRecordDescriptor

Describe una struct, un objeto o un registro en una tabla que tiene columnas anidadas.

bigqueryPolicyTags string | string[]
Se aplicaron los identificadores completos de las etiquetas de política de BigQuery a esta columna. Un identificador completo de una etiqueta de política de BigQuery incluye el nombre del proyecto, la ubicación y la taxonomía,

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

BigQuery admite una etiqueta por columna.
columns IColumnsDescriptor
Es una descripción de las columnas dentro del struct, el objeto o el registro.
description string
Es una descripción de la struct, el objeto o el registro.

ITableAssertions

Opciones para crear aserciones como parte de una definición de tablas.

nonNull string | string[]
Columnas que nunca pueden ser NULL.

Si se configura, la aserción correspondiente falla si alguna fila contiene NULL valores para estas columnas.
rowConditions string[]
Condiciones generales que deben cumplirse en todas las filas de la tabla.

Si se configura, la aserción correspondiente falla si alguna fila infringe cualquiera de estas condiciones.
uniqueKey string | string[]
Columnas que constituyen el índice de clave único de la tabla.

Si se configura, la aserción resultante falla si hay más de una fila. en la tabla con los mismos valores en todas estas columnas.
uniqueKeys []
Combinaciones de columnas, cada una de las cuales constituye un índice de claves único de la tabla.

Si se configura, la aserción resultante falla si hay más de una fila en la tabla con los mismos valores en todas las columnas en las claves únicas.

ITableConfig

Opciones de configuración para acciones de table, como Tipos de tabla table, view y incremental.

Extiende IActionConfig, IDependenciesConfig, IDocumentableConfig, INamedConfig y ITargetableConfig.

assertions ITableAssertions
Aserciones que se ejecutarán en la tabla.

Si se configura, se crean aserciones relevantes automáticamente y ejecutarla como dependencia de esta tabla.
bigquery IBigQueryOptions
Opciones de almacén específicas de BigQuery.
columns IColumnsDescriptor
Es una descripción de las columnas de la tabla.
database string
La base de datos (ID del proyecto de Google Cloud) en el que se creará el resultado de esta acción.
description string
Es una descripción de la tabla.
disabled boolean
Si se establece en true, esta acción no se ejecuta. Aún se puede depender de la acción. Útil para desactivar temporalmente las acciones fallidas.
hermetic boolean
Declara si esta acción es hermética. Una acción es hermética si declaran explícitamente todas sus dependencias.

Si esta acción depende de datos de una fuente no declarada como dependencia y, luego, establece hermetic en false. De lo contrario, configúralo como true.
materialized boolean
Solo es válida cuando el tipo de tabla es view.

Si se establece como verdadero, se creará una vista materializada.
protected boolean
Solo se permite para el tipo de tabla incremental .

Si se configura como verdadera, la ejecución de esta acción ignora la opción full-refresh. Esto es útil para las tablas que se crean a partir de datos transitorios, para garantizar que los datos históricos nunca se pierdan.
schema string
El esquema (conjunto de datos de BigQuery) en el que crea el resultado de esta acción.
tags string[]
Una lista de las etiquetas definidas por el usuario que se aplicaron a esta acción.
type TableType
El tipo de tabla.
uniqueKey string[]
Claves únicas para criterios de combinación de tablas incrementales.

Si se configuran, los registros con claves únicas coincidentes se actualicen en lugar de insertarse nuevas.

ITableContext

Los métodos de contexto están disponibles cuando se evalúa el código SQL contextual como dentro de los archivos SQLX o cuando se usa un Contextable con el núcleo de Dataform.

incremental () => boolean
Muestra true cuando el contexto actual indica que la tabla se creará de forma incremental.
name () => string
Muestra el nombre completamente calificado de esta tabla.
ref (ref: Resolvable | string[], rest: string[]) => string
Hace referencia a otra acción, la agrega como dependencia a esta acción. para mostrar un SQL válido para usar en una expresión from.

Esta función se puede llamar con un objeto Resolvable, por ejemplo:

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

Esta función también se puede llamar usando argumentos individuales para la Valores "database", "schema" y "name".

Cuando solo se proporcionan dos valores, se usa la base de datos predeterminada se interpretan como "schema" y "name".

Cuando se proporciona un solo valor, se usa el esquema de base de datos predeterminado, con la el valor proporcionado se interpreta como `"name"`.

${ref("database", "schema", "name")} ${ref("schema", "name")} ${ref("name")}
resolve (ref: Resolvable | string[], rest: string[]) => string
Es similar a ref, pero en lugar de agregar una dependencia. resuelve la referencia proporcionada para que pueda utilizarse en SQL, por ejemplo, en una expresión `from`.
self () => string
Equivale a resolve(name()).

Devuelve una cadena de SQL válida que pueda usarse para hacer referencia la tabla que produce esta acción.
when (cond: boolean, trueCase: string, falseCase: string) => string
Es la abreviación de una condición if . Equivale a cond ? trueCase : falseCase.

falseCase es opcional y se establece de forma predeterminada como una string vacía.

ITarget

Es una referencia a una tabla en BigQuery.

database string
name string
schema string

ITargetableConfig

Define la base de datos y el esquema de destino de una acción de flujo de trabajo de SQL.

database string

La base de datos en la que se debe crear el resultado de esta acción. Se debe configurar en BigQuery.
schema string

El esquema en el que se debe crear el resultado de esta acción.

operate()

operate (name: string, queries?: Contextable)

Define una operación de SQL.

Disponible solo en el directorio /definitions.

Ejemplo:

// definitions/file.js

operate("an-operation", ["SELECT 1", "SELECT 2"])

publish()

publish (name: string, queryOrConfig?: Contextable | ITableConfig)

Crea una tabla o vista.

Disponible solo en el directorio /definitions.

Ejemplo:

// definitions/file.js

publish("published-table", {
    type: "table",
    dependencies: ["a-declaration"],
  }).query(ctx => "SELECT 1 AS test");

Resolvable

Un elemento que se puede resolver puede ser el nombre de una tabla como string, o el objeto que describe la ruta de acceso completa a la relación.

string | ITarget

TableType

Tipos de acciones de tabla admitidos.

Las tablas de tipo view se crearán como vistas.

Las tablas de tipo table se crearán como tablas.

Las tablas de tipo incremental deben incluir una cláusula where. Para obtener más información, consulta Configura tablas incrementales.