Crear tabla

En este documento, se muestra cómo definir tablas con el núcleo de Dataform en Dataform.

Acerca de las definiciones de tablas

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

En una sentencia 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 type: "table" SLQX, puedes crear tablas vacías si defines una consulta de 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 sentencia 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 el orden correcto de la canalización.

La función ref es una función integrada en el núcleo 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 de las tablas y el esquema:

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 instrucciones de texto estándar, como CREATE, REPLACE, INSERT o MERGE, a la sentencia SQL.

En la siguiente muestra de código, se muestra 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, proporcionas el nombre de la declaración de la tabla o fuente de datos de la que deseas depender. Por lo general, es el nombre 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 Configura parámetros adicionales de las tablas.

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

En la siguiente muestra de código, se muestra 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, declaraciones de fuentes de datos o operaciones SQL personalizadas a las que no se hace referencia en una función ref en la sentencia SELECT. Dataform ejecuta estas dependencias antes que las tablas dependientes.

En la siguiente muestra de código, se muestra 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 declaración de tabla o fuente de datos en una sentencia SELECT como la función ref, pero no agrega la referencia como dependencia. Esto significa que el objeto al que se hace referencia con 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 e inicializa un espacio de trabajo de desarrollo en tu repositorio.
  2. Opcional: Declara una fuente de datos.

Roles obligatorios

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

También puedes obtener los permisos necesarios mediante roles personalizados o cualquier otro rol predefinido.

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.

    Ve 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 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 el panel Files de tu espacio de trabajo de desarrollo, 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 tablas:

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

Define la estructura y las dependencias de la tabla

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

  1. En el panel Files de tu espacio de trabajo de desarrollo, 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 muestra una definición de tabla con una sentencia 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 tablas a las que no se hace referencia en la sentencia SELECT, pero que deben ejecutarse antes de la tabla actual, sigue estos pasos:

  1. En el panel Files de tu espacio de trabajo de desarrollo, 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 muestran dos tablas agregadas 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?