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 archivos de SQLX y 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 argumento Contextable con 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 y la agrega como dependencia a esta acción y muestra SQL válido para usarlo 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 usan el esquema y la base de datos 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 dependencia a esta acción.
self	() => string
	Equivale a resolve(name()). Muestra una string de SQL válida que se puede usar para hacer referencia a la tabla generada por esta acción.
schema	() => string
	Muestra el esquema de este conjunto de datos.

Contexto

Los argumentos contextuales pueden pasar un valor sin formato a 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. Es obligatorio para obtener propiedades 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"})

Configuración de IAction

Define las etiquetas de Dataform y las dependencias aplicadas a una acción del 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á. 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 assertion tipos de acción.

database	string
	Es 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. La acción aún puede depender de ella. 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 de manera explícita. Si esta acción depende de datos de una fuente que no se declaran como dependencia, configura hermetic como 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 etiquetas definidas por el usuario aplicadas a esta acción.

Opciones de IBigQuery

Opciones de almacén específicas de BigQuery.

additionalOptions
	Pares clave-valor para las opciones de tabla, vista y vista materializada. Algunas opciones, como partitionExpirationDays, tienen campos marcados como válidos y de tipo dedicado. Para esas opciones, usa los campos dedicados. Los valores de string deben encerrarse 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 las particiones por.
labels
	Pares clave-valor para etiquetas de BigQuery. Si el nombre de la etiqueta contiene caracteres especiales, p. ej., guiones, escribe su nombre (p. ej., labels: { "label-name": "value" }.).
partitionBy	string
	La clave mediante la cual 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 en función del tiempo de partición.
requirePartitionFilter	boolean
	Declara si la tabla particionada requiere un filtro de predicado de la cláusula WHERE que filtra la columna de partición.
updatePartitionFilter	string
	Filtro basado en SQL para el momento en que se aplican las actualizaciones incrementales.

IColumnsDescriptor

Describe las columnas de una tabla.

{ [name]: string | IRecordDescriptor }

Configuración de declaración

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

columns	IColumnsDescriptor
	Una descripción de las columnas dentro de la tabla.
database	string
	Ya existe la base de datos (ID del proyecto de Google Cloud) en la que se creará 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.

Configuración de dependencias

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 dependientes. Por lo general, no se establecerá, 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 todas sus dependencias se declaran de manera explícita. Si esta acción depende de datos de una fuente que no se declararon como dependencia, se debe establecer hermetic de manera explícita como false. De lo contrario, si esta acción solo depende de datos provenientes de dependencias declaradas de forma explícita, se debe configurar como true.

Configuración de IDocumentableConfig

Define las descripciones de un conjunto de datos y sus columnas.

columns	IColumnsDescriptor
	Una descripción de las columnas dentro del conjunto de datos.
description	string
	Una descripción del conjunto de datos.

Configuración de INamed

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

type	string
	Es el tipo de acción.
name	string
	Es el nombre de la acción.

Configuración de IOperation

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

columns	IColumnsDescriptor
	Una descripción de las columnas dentro 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. La acción aún puede depender de ella. 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 mediante la función ref. Si se establece como 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 de manera explícita. Si esta acción depende de datos de una fuente que no se declaran como dependencia, configura hermetic como 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 etiquetas definidas por el usuario aplicadas a esta acción.

Configuración del proyecto

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 se ponen a disposición para el código de 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 adjuntar a todos los nombres de la base de datos (ID del proyecto de Google Cloud).
schemaSuffix	string
	Opcional. El sufijo que se debe adjuntar 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 tablas.
warehouse	string
	Obligatorio. Debe establecerse en bigquery.

Puedes configurar 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 de IProjectConfig en una instrucción SELECT de SQL en un archivo de SQLX o JavaScript.

En la siguiente muestra de código, se muestra la variable de compilación personalizada myVariableName configurada 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 deseas obtener más información para anular los ajustes de configuración del proyecto de resultados de compilación individuales, consulta el recurso 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 que se aplican 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". Actualmente, BigQuery admite una etiqueta por columna.
columns	IColumnsDescriptor
	Una descripción de las columnas dentro del struct, del objeto o del registro.
description	string
	Es una descripción de la struct, del objeto o del 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[]
	Condiciones generales que deben ser 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.

Configuración de la tabla

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

Se extiende IActionConfig, IDependenciesConfig, IDocumentableConfig, INamedConfig y ITargetableConfig.

assertions	ITableAssertions
	Aserciones que se ejecutarán en la tabla. Si se configuran, las aserciones relevantes se crean automáticamente y se ejecutan como una dependencia de esta tabla.
bigquery	IBigQueryOptions
	Opciones de almacén específicas de BigQuery.
columns	IColumnsDescriptor
	Una descripción de las columnas dentro 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. La acción aún puede depender de ella. 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 de manera explícita. Si esta acción depende de datos de una fuente que no se declaran como dependencia, configura hermetic como 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 establece como verdadera, la ejecución de esta acción ignora la opción full-refresh. Esto es útil para tablas que se crean 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[]
	Una lista de etiquetas definidas por el usuario aplicadas 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, se actualizan los registros con claves únicas que coinciden, en lugar de insertar filas nuevas.

Contexto de tabla

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 argumento Contextable con núcleo de Dataform.

incremental	() => boolean
	Muestra verdadero 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, agregándola como una dependencia a esta acción y mostrando SQL válido para usarla 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 predeterminado de la base de datos, con el valor proporcionado como “name”. ${ref("database", "schema", "name")} ${ref("schema", "name")} ${ref("name")}
resolve	(ref: Resolvable | string[], rest: string[]) => string
	Similar a ref, pero en lugar de agregar una dependencia, resuelve la referencia proporcionada para que se pueda usar en SQL, por ejemplo, en una expresión "from".
self	() => string
	Equivale a resolve(name()). Muestra una string de SQL válida que se puede usar para hacer referencia a la tabla que produjo esta acción.
when	(cond: boolean, trueCase: string, falseCase: string) => string
	Compilación abreviada 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

Una referencia a una tabla en BigQuery.

database	string
name	string
schema	string

Configuración de ITargetable

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. Debe configurarse en BigQuery.
schema	string
	El esquema en el que se debe crear el resultado de esta acción.

opera()

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

publicación()

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

Resoluble

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

string | ITarget

Tipo de tabla

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.