Referencia principal de Dataform

En este documento, se describen los métodos, las propiedades y las opciones de configuración del núcleo de Dataform. Puedes usar Dataform Core en los archivos SQLX y JavaScript.

assert()

assert (name: string, query?: AContextable)

Agrega una aserción de Dataform al gráfico 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 archivos SQLX o cuando se usa un 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 y muestra un SQL válido para usar en una expresión `from`. Se puede llamar a esta función con un objeto `Resolvable`, por ejemplo: `${ref({ name: "name", schema: "schema", database: "database" })}` También se puede llamar a esta función con argumentos individuales para los valores `"database"`, `"schema"` y `"name"`. Cuando solo se proporcionan dos valores, se usa la base de datos predeterminada y los valores se interpretan como `"schema"` y `"name"`. Cuando se proporciona un solo valor, se usan la base de datos y el esquema predeterminados, y 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 no agrega la acción a la que se hace referencia como una dependencia a esta acción.
`self`	`() => string`
	Equivale a `resolve(name())`. Muestra una cadena de SQL válida que se puede usar para hacer referencia a la tabla que genera 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 este tipo de operación.

T | (ctx: Context) => T

Dataform

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

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

declarar()

declare (dataset: dataform.ITarget)

Declara el conjunto de datos como una 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 aplicadas 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 se establece como verdadera, no se ejecutará esta acción. Sin embargo, aún se puede depender de la acción. Es útil para desactivar temporalmente las acciones dañadas.

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 crea la vista correspondiente para esta aserción.
`description`	`string`
	Es una descripción de esta aserción.
`disabled`	`boolean`
	Si se configura como `true`, no se ejecuta esta acción. Aún se puede depender de la acción. Es útil para desactivar temporalmente las acciones dañadas.
`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 que no está declarada como dependencia, establece `hermetic` en `false`. De lo contrario, configúralo como `true`.
`schema`	`string`
	El esquema (conjunto de datos de BigQuery) en el que se crea la vista correspondiente para esta aserción.
`tags`	`string[]`
	Lista de etiquetas definidas por el usuario aplicadas a esta acción.

IBigQueryOptions

Opciones de almacén específicas de BigQuery.

`additionalOptions`
	Pares clave-valor para las opciones de tabla, vista y vista materializada Algunas opciones, por ejemplo, `partitionExpirationDays`, tienen campos de verificación de tipo/validez dedicados. Para esas opciones, usa los campos dedicados. Los valores de string deben encapsularse 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 agrupar las particiones del clúster.
`labels`
	Pares clave-valor para las etiquetas de BigQuery. Si el nombre de la etiqueta contiene caracteres especiales, p. ej., guiones, debes ponerlo entre comillas, p. ej., `labels: { "label-name": "value" }.`.
`partitionBy`	`string`
	La clave por la que se particiona la tabla. Por lo general, es el nombre de una marca de tiempo o la columna de fecha.
`partitionExpirationDays`	`number`
	La cantidad de días en los que BigQuery almacena datos en cada partición. La configuración se aplica a todas las particiones de una tabla, pero se calcula de forma independiente para cada partición según el tiempo de partición.
`requirePartitionFilter`	`boolean`
	Declara si la tabla particionada requiere un filtro de predicado de la cláusula `WHERE` que filtre la columna de partición.
`updatePartitionFilter`	`string`
	Filtro basado en SQL para cuando se aplican las actualizaciones incrementales.

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`
	Existe la base de datos (ID del proyecto de Google Cloud) en la que se crea 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. Las acciones de dependencia se ejecutarán antes que las acciones dependientes. Por lo general, no se establece porque 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 se declaran explícitamente todas sus dependencias. Si esta acción depende de datos de una fuente que no se declaró como dependencia, `hermetic` debe establecerse explícitamente como `false`. De lo contrario, si esta acción solo depende de datos de dependencias declaradas de forma explícita, se debe configurar como `true`.

IDocumentableConfig

Define las 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 el nombre de una acción del flujo de trabajo de SQL.

`type`	`string`
	Es el tipo de acción.
`name`	`string`
	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 crea el resultado de esta acción.
`description`	`string`
	Es una descripción de la tabla.
`disabled`	`boolean`
	Si se configura como `true`, no se ejecuta esta acción. Aún se puede depender de la acción. Es útil para desactivar temporalmente las acciones dañadas.
`hasOutput`	`boolean`
	Declara que esta acción `operations` crea una tabla a la que se puede hacer referencia con la función `ref`. Si se configura en `true`, esta acción crea una tabla con su nombre configurado mediante 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 que no está declarada como dependencia, establece `hermetic` en `false`. De lo contrario, configúralo como `true`.
`schema`	`string`
	El esquema (conjunto de datos de BigQuery) en el que se crea el resultado de esta acción.
`tags`	`string[]`
	Lista de etiquetas definidas por el usuario aplicadas a esta acción.

IProjectConfig

Contiene la 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 que se 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. Son variables definidas por el usuario que están disponibles para el código del proyecto 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 todos los nombres de bases de datos (ID del proyecto de Google Cloud).
`schemaSuffix`	`string`
	Opcional. El sufijo que se debe agregar a todos los nombres de esquema (ID del conjunto de datos de BigQuery).
`tablePrefix`	`string`
	Opcional. El prefijo que se debe anteponer a todos los nombres de las tablas.
`warehouse`	`string`
	Obligatorio. Se debe configurar en `bigquery`.

Puedes establecer las propiedades IProjectConfig en dataform.json a nivel del repositorio.

Puedes anular las propiedades defaultSchema y defaultDatabase para 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 ve la variable de compilación personalizada myVariableName establecida en dataform.json con la propiedad projectConfig.vars, a la que se accede en una instrucción 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!"
  )}

Si quieres obtener más información sobre cómo anular la configuración del proyecto para resultados de compilación individuales, consulta el recurso de REST projects.locations.repositories.compilationResults#CodeCompilationConfig en la API de Dataform.

IRecordDescriptor

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

`bigqueryPolicyTags`	`string \| string[]`
	Son los identificadores completos de las etiquetas de política de BigQuery aplicados a esta columna. El 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"`. Actualmente, BigQuery admite una etiqueta por columna.
`columns`	`IColumnsDescriptor`
	Una descripción de las columnas dentro de la struct, el objeto o el registro.
`description`	`string`
	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 valores `NULL` para estas columnas.
`rowConditions`	`string[]`
	Son condiciones generales que deben mantenerse como verdaderas para todas las filas de la tabla. Si se configura, la aserción correspondiente falla si alguna fila infringe alguna 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 para todas estas columnas.
`uniqueKeys`	`[]`
	Combinaciones de columnas, cada una de las cuales constituye un í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 para todas las columnas en las claves únicas.

ITableConfig

Opciones de configuración para las acciones table, incluidos los tipos de tabla table, view y incremental.

Extiende IActionConfig, IDependenciesConfig, IDocumentableConfig, INamedConfig y ITargetableConfig.

`assertions`	`ITableAssertions`
	Son las aserciones que se ejecutarán en la tabla. Si se configuran, las aserciones relevantes se crean y ejecutan automáticamente como una 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 la que se crea el resultado de esta acción.
`description`	`string`
	Es una descripción de la tabla.
`disabled`	`boolean`
	Si se configura como `true`, no se ejecuta esta acción. Aún se puede depender de la acción. Es útil para desactivar temporalmente las acciones dañadas.
`hermetic`	`boolean`
	Declara si esta acción es hermética. Una acción es hermética si se declaran explícitamente todas sus dependencias. Si esta acción depende de datos de una fuente que no está declarada como dependencia, establece `hermetic` en `false`. De lo contrario, configúralo como `true`.
`materialized`	`boolean`
	Solo es válido cuando el tipo de tabla es `view`. Si se configura como verdadera, 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 se ignora la opción `full-refresh`. Esto es útil para tablas que se compilan a partir de datos transitorios a fin de garantizar que los datos históricos nunca se pierdan.
`schema`	`string`
	El esquema (conjunto de datos de BigQuery) en el que se creará el resultado de esta acción.
`tags`	`string[]`
	Lista de etiquetas definidas por el usuario aplicadas a esta acción.
`type`	`TableType`
	El tipo de tabla.
`uniqueKey`	`string[]`
	Claves únicas para los criterios de combinación de tablas incrementales. Si se configuran, los registros con claves únicas coincidentes se actualizan en lugar de insertar filas nuevas.

ITableContext

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

`incremental`	`() => boolean`
	Muestra true cuando el contexto actual indica que la tabla se compilará 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, y muestra un SQL válido para usar en una expresión from. Se puede llamar a esta función con un objeto `Resolvable`, por ejemplo: `${ref({ name: "name", schema: "schema", database: "database" })}` También se puede llamar a esta función con argumentos individuales para los valores `"database"`, `"schema"` y `"name"`. Cuando solo se proporcionan dos valores, se usa la base de datos predeterminada y los valores se interpretan como `"schema"` y `"name"`. Cuando solo se proporciona un valor, se usa el esquema de la base de datos predeterminado, con 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 en lugar de agregar una dependencia, resuelve la referencia proporcionada para que pueda usarse en SQL, por ejemplo, en una expresión `from`.
`self`	`() => string`
	Equivale a `resolve(name())`. Muestra una cadena de SQL válida que se puede usar para hacer referencia a la tabla que generó esta acción.
`when`	`(cond: boolean, trueCase: string, falseCase: string) => string`
	Es la abreviatura de una condición `if` . Equivale a `cond ? trueCase : falseCase`. `falseCase` es opcional y, de forma predeterminada, es 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 de destino y el esquema 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.

operar()

operate (name: string, queries?: Contextable)

Define una operación 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");

Resolvible

Un resolvable puede ser el nombre de una tabla como string o el objeto que describe la ruta completa a la relación.

string | ITarget

TableType

Tipos de acciones de tabla compatibles.

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.