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:
- tablas de todos los tipos de tablas compatibles
- declaraciones de fuentes de datos
- Operaciones de SQL personalizadas con la propiedad
hasOutput
establecida entrue
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
- Crea e inicializa un espacio de trabajo de desarrollo en tu repositorio.
- 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:
En la consola de Cloud, ve a la página Dataform.
Para abrir un repositorio, haz clic en su nombre.
Para abrir un lugar de trabajo de desarrollo, haz clic en su nombre.
En el panel Archivos, junto a
definitions/
, haz clic en el menú Más.Haz clic en Crear archivo.
En el campo Agregar una ruta de archivo, ingresa el nombre del archivo seguido de
.sqlx
después dedefinitions/
. Por ejemplo,definitions/my-table.sqlx
.Los nombres de archivo solo pueden incluir números, letras, guiones y guiones bajos.
Haz clic en Crear archivo.
Define el tipo de tabla
Para crear una nueva definición de tipo de tabla, sigue estos pasos:
- En el panel Files de tu espacio de trabajo de desarrollo, expande el directorio
definitions/
. - Selecciona el archivo SQLX de definición de tablas que deseas editar.
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
Opcional: Para definir una vista materializada, ingresa la propiedad
materialized
entype: "view"
con el siguiente formato:config { type: "view", materialized: true }
Para obtener más información, consulta la referencia principal de Dataform de
ITableConfig
.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:
- En el panel Files de tu espacio de trabajo de desarrollo, expande el directorio
definitions/
. - Selecciona el archivo SQLX de definición de tablas que deseas editar.
- Debajo del bloque
config
, escribe una sentenciaSELECT
. - 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:
- En el panel Files de tu espacio de trabajo de desarrollo, expande el directorio
definitions/
. - Selecciona el archivo SQLX de definición de tablas que deseas editar.
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.
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?
- Para obtener información sobre cómo configurar tablas incrementales, consulta Configura tablas incrementales.
- Para aprender a configurar particiones y clústeres de tablas, consulta Crea particiones y clústeres de tablas.
- Para obtener información sobre cómo agregar documentación a las tablas, consulta Cómo agregar documentación a las tablas.
- Para aprender a probar datos de tablas con aserciones, consulta Cómo probar tablas con aserciones.
- Para aprender a definir tablas con JavaScript, consulta Crea flujos de trabajo de Dataform con JavaScript.
- Para obtener información sobre cómo configurar parámetros adicionales de la tabla, consulta Configura parámetros adicionales de la tabla.