Crear una tabla

En este documento, se muestra cómo definir tablas con Dataform core en Dataform.

Acerca de las definiciones de tablas

Para definir una tabla, debes definir el tipo de tabla y escribir una instrucción SELECT en un archivo SQLX type: "table". Luego, Dataform compila tu código principal de Dataform en SQL, ejecuta el código de SQL y crea las tablas definidas en BigQuery.

En una instrucción SELECT principal de Dataform, defines la estructura de la tabla y haces referencia a otros objetos de tu flujo de trabajo de SQL.

Además de definir tablas en un archivo SLQX de type: "table", puedes crear tablas vacías si defines una consulta en SQL personalizada en un archivo SQLX type: "operations". Para obtener más información, consulta Crea una tabla vacía.

Cómo hacer referencia a dependencias con ref

Para hacer referencia a un objeto de flujo de trabajo de SQL en una instrucción SELECT y agregarlo automáticamente como una dependencia, usa la función ref. Dataform ejecuta las dependencias antes que las tablas que dependen de ellas para garantizar un orden correcto de la canalización.

La función ref es una función integrada principal de Dataform que es fundamental para la administración de dependencias en Dataform. La función ref te permite hacer referencia a los siguientes objetos definidos en tu flujo de trabajo de SQL de Dataform y depender automáticamente de ellos, en lugar de codificar de forma fija los nombres del esquema y la tabla:

Dataform usa la función ref para compilar un árbol de dependencias de todas las tablas que se crearán o actualizarán.

Después de la compilación, Dataform agrega sentencias estándar, como CREATE, REPLACE, INSERT o MERGE a la instrucción de SQL.

En la siguiente muestra de código, se incluye una definición de tabla con el uso de la función ref:

config { type: "table" }

SELECT
  order_date AS date,
  order_id AS order_id,
  order_status AS order_status,
  SUM(item_count) AS item_count,
  SUM(amount) AS revenue

FROM ${ref("store_clean")}

GROUP BY 1, 2

En la función ref, debes proporcionar el nombre de la tabla o la declaración de fuente de datos de la que deseas depender. Por lo general, este es el nombre de archivo del archivo SQLX en el que se define esa declaración de tabla o fuente de datos.

Si se anula el nombre de una tabla, usa el nombre anulado en la función ref. Por ejemplo, haz referencia a una tabla con config { name: "overridden_name" } como ref("overridden_name"). Para obtener más información sobre cómo anular los nombres de las tablas, consulta Establece parámetros de configuración adicionales para las tablas.

Cuando tienes varias tablas con el mismo nombre en diferentes esquemas, puedes hacer referencia a una tabla específica si proporcionas dos argumentos a la función ref: nombre del esquema y nombre de la tabla.

En la siguiente muestra de código, se ve la función ref con dos argumentos para especificar una tabla dentro de un esquema específico:

config { type: "table" }
SELECT * FROM ${ref("schema", "store_clean")}

También puedes agregar dependencias de tablas de forma manual al bloque config para tablas, aserciones, operaciones de SQL personalizadas o declaraciones de fuente de datos a las que no se hace referencia en una función ref en la declaración SELECT. Dataform ejecuta estas dependencias antes que las tablas dependientes.

En la siguiente muestra de código, se incluye una dependencia de tabla en el bloque config:

config { dependencies: [ "unreferenced_table" ] }
SELECT * FROM ...

Para obtener más información sobre la administración de dependencias en tu flujo de trabajo de SQL, consulta Cómo declarar dependencias.

Cómo hacer referencia a otras tablas con resolve

La función resolve te permite hacer referencia a una tabla o una declaración de fuente de datos en una declaración SELECT, como la función ref, pero no agrega la referencia como una dependencia. Esto significa que el objeto al que se hace referencia mediante resolve no afecta la ejecución de la tabla que usa resolve.

Para obtener más información sobre las funciones principales integradas de Dataform, consulta la referencia principal de Dataform.

Antes de comenzar

  1. Crea y, luego, inicializa un lugar de trabajo de desarrollo en tu repositorio.
  2. Opcional: Declara una fuente de datos.

Funciones obligatorias

Si quieres obtener los permisos que necesitas para definir una tabla, pídele a tu administrador que te otorgue el rol de IAM de Editor de Dataform (roles/dataform.editor) en los lugares de trabajo. Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso.

Es posible que también puedas obtener los permisos necesarios mediante funciones personalizadas, o bien otras funciones predefinidas.

Crea un archivo SQLX para la definición de tablas

Almacena los archivos SQLX de definición de tablas en el directorio definitions/. Para crear un archivo SQLX nuevo en el directorio definitions/, sigue estos pasos:

  1. En la consola de Cloud, ve a la página Dataform.

    Ir a la página Dataform

  2. Para abrir un repositorio, haz clic en su nombre.

  3. Para abrir un lugar de trabajo de desarrollo, haz clic en su nombre.

  4. En el panel Archivos, junto a definitions/, haz clic en el menú Más.

  5. Haz clic en Crear archivo.

  6. En el campo Agregar una ruta de acceso al archivo, ingresa el nombre del archivo, seguido de .sqlx después de definitions/. Por ejemplo, definitions/my-table.sqlx.

    Los nombres de archivo solo pueden incluir números, letras, guiones y guiones bajos.

  7. Haz clic en Crear archivo.

Define el tipo de tabla

Para crear una nueva definición de tipo de tabla, sigue estos pasos:

  1. En tu lugar de trabajo de desarrollo, en el panel Archivos, expande el directorio definitions/.
  2. Selecciona el archivo SQLX de definición de tablas que deseas editar.

  3. En el archivo, ingresa el siguiente fragmento de código:

    config { type: "TABLE_TYPE" }

    Reemplaza TABLE_TYPE por uno de los siguientes tipos de tabla:

    • table
    • incremental
    • view

  4. Opcional: Para definir una vista materializada, ingresa la propiedad materialized en type: "view" con el siguiente formato:

    config {
  type: "view",
  materialized: true
}

    Para obtener más información, consulta la Referencia principal de Dataform de ITableConfig.

  5. Opcional: Haz clic en Formato.

Cómo definir la estructura y las dependencias de la tabla

Para escribir una declaración SELECT de definición de tablas y definir la estructura y las dependencias de la tabla, sigue estos pasos:

  1. En el lugar de trabajo de desarrollo, en el panel Archivos, expande el directorio definitions/.
  2. Selecciona el archivo SQLX de definición de tablas que deseas editar.
  3. Debajo del bloque config, escribe una sentencia SELECT.
  4. Opcional: Haz clic en Formato.

En la siguiente muestra de código, se incluye una definición de tabla con una declaración SELECT y la función ref:

config { type: "table" }
SELECT
  customers.id AS id,
  customers.first_name AS first_name,
  customers.last_name AS last_name,
  customers.email AS email,
  customers.country AS country,
  COUNT(orders.id) AS order_count,
  SUM(orders.amount) AS total_spent
FROM
  dataform-samples.dataform_sample.crm_customers AS customers
  LEFT JOIN ${ref('order_stats')} orders
    ON customers.id = orders.customer_id

WHERE
  customers.id IS NOT NULL
  AND customers.first_name <> 'Internal account'
  AND country IN ('UK', 'US', 'FR', 'ES', 'NG', 'JP')

GROUP BY 1, 2, 3, 4, 5

Cómo agregar dependencias de tablas manuales

Para agregar dependencias de tabla a las que no se hace referencia en la declaración SELECT, pero que deben ejecutarse antes que la tabla actual, sigue estos pasos:

  1. En el lugar de trabajo de desarrollo, en el panel Archivos, expande el directorio definitions/.
  2. Selecciona el archivo SQLX de definición de tablas que deseas editar.

  3. En el bloque config de la tabla, ingresa el siguiente fragmento de código:

    dependencies: [ "DEPENDENCY_TABLE", ]

    Reemplaza DEPENDENCY_TABLE por el nombre de archivo de la tabla que deseas agregar como dependencia. Puedes ingresar varios nombres de archivo.

  4. Opcional: Haz clic en Formato.

En la siguiente muestra de código, se ven dos tablas que se agregaron como dependencias de tablas manuales al bloque config de un archivo de definición de tablas:

config { dependencies: [ "some_table", "some_other_table" ] }

¿Qué sigue?