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 SQLX y JavaScript.

assert()

assert (name: string, query?: AContextable)

Agrega una aserción de Dataform al gráfico compilado.

Solo está disponible 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 el núcleo de Dataform.

database () => string
Devuelve 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 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 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.

Contextable

Los argumentos contextuales pueden pasar un valor simple 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

Es una variable global que contiene el objeto IProjectConfig. Es obligatorio para obtener propiedades IProjectConfig, por ejemplo:

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

declare()

declare (dataset: dataform.ITarget)

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

Solo está disponible en el directorio /definitions.

Ejemplo:

// definitions/file.js

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

IActionConfig

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

tags string[]

Es 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 verdadero, no se ejecutará esta acción. Sin embargo, se puede depender de la acción. Es útil para desactivar temporalmente las acciones interrumpidas.

IAssertionConfig

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

database string
Es la base de datos (Google Cloud ID del proyecto) en la que se creará la vista correspondiente para esta aserción.
description string
Una descripción de esta aserción.
disabled boolean
Si se configura en true, esta acción no se ejecuta. Aún se puede depender de la acción. Es útil para desactivar temporalmente 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 forma explícita.

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

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

IBigQueryOptions

Opciones de almacén específicas de BigQuery.

additionalOptions
Son pares clave-valor para las opciones de tabla, vista y vista materializada.

Algunas opciones, por ejemplo, partitionExpirationDays, tienen campos dedicados para verificar el tipo o la validez. Para esas opciones, usa los campos dedicados.

Los valores de 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[]
Son las claves por las que se agrupan las particiones.
labels
Pares clave-valor para las etiquetas de BigQuery.

Si el nombre de la etiqueta contiene caracteres especiales, por ejemplo, guiones, colócalo entre comillas, por ejemplo, labels: { "label-name": "value" }..
partitionBy string
Es la clave con la que se particiona la tabla. Por lo general, es el nombre de una marca de tiempo o la columna de fecha.
partitionExpirationDays number
Es la cantidad de días durante los cuales BigQuery almacena datos en cada partición. La configuración se aplica a todas las particiones de una tabla, pero se calcula de manera 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 cláusula WHERE que filtre la columna de partición.
updatePartitionFilter string
Es un filtro basado en SQL para cuando se aplican actualizaciones incrementales.

IColumnsDescriptor

Describe las columnas de una tabla.

{ [name]: string | IRecordDescriptor }

IDeclarationConfig

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

columns IColumnsDescriptor
Una descripción de las columnas de la tabla.
database string
Existe la base de datos (ID del proyectoGoogle Cloud ) en la que se creará la tabla de origen.
description string
Es una descripción de la tabla.
schema string
Es 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, esto no se establecería, ya que la mayoría de las dependencias se declaran como 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 forma explícita. Si esta acción depende de datos de una fuente que no se declaró como una dependencia, hermetic se debe establecer explícitamente en false. De lo contrario, si esta acción solo depende de los datos de las dependencias declaradas de forma explícita, se debe establecer en 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 de flujo de trabajo de SQL.

type string

Es el tipo de acción.
name string

Es el nombre de la acción.

IOperationConfig

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

columns IColumnsDescriptor
Una descripción de las columnas de la tabla.
database string
La base de datos (Google Cloud ID del proyecto) en la que se creará el resultado de esta acción.
description string
Es una descripción de la tabla.
disabled boolean
Si se configura en true, esta acción no se ejecuta. Aún se puede depender de la acción. Es útil para desactivar temporalmente las acciones interrumpidas.
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 establece en true, esta acción crea una tabla con su nombre configurado usando 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 forma explícita.

Si esta acción depende de datos de una fuente que no se declaró como una dependencia, establece hermetic en false. De lo contrario, configúralo como true.
schema string
Es el esquema (conjunto de datos de BigQuery) en el que se creará el resultado de esta acción.
tags string[]
Es una lista de etiquetas definidas por el usuario que se aplicaron 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 proyectoGoogle Cloud ).
defaultSchema string
Obligatorio. El esquema predeterminado (ID del conjunto de datos de BigQuery).
defaultLocation string
Obligatorio. Es 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. Es 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. Es el sufijo que se debe agregar a todos los nombres de la base de datos (Google Cloud ID de proyecto).
schemaSuffix string
Opcional. Es el sufijo que se debe agregar a todos los nombres de esquemas (ID de conjunto de datos de BigQuery).
tablePrefix string
Opcional. Es el prefijo que se debe anteponer a todos los nombres de las tablas.
warehouse string
Obligatorio. Debe establecerse en bigquery.

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

Puedes anular las propiedades defaultSchema y defaultDatabase para tablas individuales.

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

En la siguiente muestra de código, se muestra la variable de compilación personalizada myVariableName establecida en la configuración del flujo de trabajo con la 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!"
  )}

Para 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 de projects.locations.repositories.compilationResults#CodeCompilationConfig en la API de Dataform.

IRecordDescriptor

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

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

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 de la estructura, el objeto o el registro.
description string
Una descripción de la estructura, el objeto o el registro

ITableAssertions

Son opciones para crear aserciones como parte de una definición de tabla.

nonNull string | string[]
Son columnas que nunca pueden ser NULL.

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

Si se establece, la aserción correspondiente falla si alguna fila incumple alguna de estas condiciones.
uniqueKey string | string[]
Son las columnas que constituyen el índice de clave única de la tabla.

Si se establece, 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 establece, la aserción resultante falla si hay más de una fila en la tabla con los mismos valores para todas las columnas de las claves únicas.

ITableConfig

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

Extiende IActionConfig, IDependenciesConfig, IDocumentableConfig, INamedConfig y ITargetableConfig.

assertions ITableAssertions
Son 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 de la tabla.
database string
La base de datos (Google Cloud ID del proyecto) en la que se creará el resultado de esta acción.
description string
Es una descripción de la tabla.
disabled boolean
Si se configura en true, esta acción no se ejecuta. Aún se puede depender de la acción. Es útil para desactivar temporalmente las acciones interrumpidas.
hermetic boolean
Declara si esta acción es hermética. Una acción es hermética si todas sus dependencias se declaran de forma explícita.

Si esta acción depende de datos de una fuente que no se declaró como una 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 establece como verdadero, se creará una vista materializada.
protected boolean
Solo se permite para el tipo de tabla incremental .

Si se establece como verdadero, la ejecución de esta acción ignora la opción full-refresh. Esto es útil para las tablas que se compilan a partir de datos transitorios, para garantizar que nunca se pierdan los datos históricos.
schema string
Es el esquema (conjunto de datos de BigQuery) en el que se creará el resultado de esta acción.
tags string[]
Es una lista de etiquetas definidas por el usuario que se aplicaron 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 configura, se actualizan los registros con claves únicas coincidentes 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 los archivos SQLX, o cuando se usa un argumento Contextable con el 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, la agrega como dependencia a esta acción y muestra 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 base de datos predeterminado, 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 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 cadena de SQL válida que se puede usar para hacer referencia a la tabla que produce 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 se establece de forma predeterminada en una cadena vacía.

ITarget

Es una referencia a una tabla dentro de 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

Es la base de datos en la que se debe crear el resultado de esta acción. Debe establecerse en BigQuery.
schema string

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

operate()

operate (name: string, queries?: Contextable)

Define una operación SQL.

Solo está disponible 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.

Solo está disponible en el directorio /definitions.

Ejemplo:

// definitions/file.js

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

Soluble

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