ModelMonkey Logo
Integrations5 min read

Consultas SQL con DuckDB

Consulta tus datos de hojas de cálculo y bases de datos externas usando SQL

Descripción general

ModelMonkey incluye un motor SQL integrado impulsado por DuckDB, que te permite ejecutar consultas SQL directamente sobre tus datos de hojas de cálculo. También puedes consultar bases de datos externas (PostgreSQL, BigQuery) e incluso combinar datos de múltiples fuentes mediante joins.

Esto es útil cuando necesitas un control preciso sobre las transformaciones de datos, deseas realizar agregaciones complejas o necesitas combinar datos de distintas fuentes de maneras que el lenguaje natural podría no expresar con claridad.

Tip

No necesitas escribir SQL por tu cuenta. Simplemente describe lo que quieres en lenguaje natural y ModelMonkey generará y ejecutará la consulta SQL apropiada por ti.

Cuándo se usan las consultas SQL

ModelMonkey utiliza consultas SQL automáticamente cuando tu solicitud involucra:

Agregaciones complejas
Agrupación de datos, cálculo de sumas, promedios, conteos u otras operaciones estadísticas sobre muchas filas.

Filtrado y ordenamiento
Búsqueda de registros específicos basándose en múltiples condiciones, u ordenamiento de grandes conjuntos de datos por distintos criterios.

Combinación de datos (Joins)
Combinar datos de tu hoja de cálculo con bases de datos externas, o fusionar múltiples hojas.

Transformaciones de datos
Reformatear, calcular nuevas columnas o reestructurar datos de maneras que requieren procesamiento fila por fila.

También puedes pedirle explícitamente a ModelMonkey que "use SQL" o "ejecute una consulta SQL" si prefieres la precisión de SQL para una operación en particular.

Consultar datos de hojas de cálculo

Tus datos de hoja de cálculo son accesibles a través de la función sheet_range(). Esta función recibe una referencia en notación A1 y devuelve los datos como una tabla consultable.

Requisitos importantes

  • La primera fila de tu rango debe contener encabezados de columna
  • Los nombres de columna se derivan de la fila de encabezado
  • Los encabezados vacíos generan columnas con nombres como "column_1", "column_2", etc.

Formatos de rango compatibles

  • Hoja completa: sheet_range('Sheet1!A:Z')
  • Rango específico: sheet_range('Sales!A1:D100')
  • Los rangos con nombres que contienen caracteres especiales se escapan automáticamente
text
-- Query all data from a sheet
SELECT * FROM sheet_range('Sheet1!A1:D100')

-- Filter and aggregate
SELECT category, SUM(amount) as total
FROM sheet_range('Sales!A1:E500')
WHERE date >= '2024-01-01'
GROUP BY category

-- Sort by multiple columns
SELECT * FROM sheet_range('Customers!A:F')
ORDER BY region ASC, revenue DESC

Ejemplos de consultas a hojas de cálculo

Consultar bases de datos externas

Si tienes conexiones de datos externos configuradas, puedes consultarlas usando su nombre de conexión:

PostgreSQL
Referencia las tablas como connection_name.schema.table. El esquema predeterminado suele ser "public".

BigQuery
Referencia las tablas como connection_name.dataset.table.

Las consultas a bases de datos externas funcionan exactamente como el SQL estándar. Puedes utilizar todas las funciones compatibles con DuckDB, incluyendo joins, subconsultas, funciones de ventana y CTEs.

Tip

Configura primero tus conexiones externas en el panel External Data Connections antes de consultarlas.

text
-- Query a PostgreSQL table
SELECT * FROM my_postgres.public.customers
WHERE country = 'USA'

-- Query a BigQuery table
SELECT event_date, COUNT(*) as events
FROM my_bigquery.analytics.page_views
GROUP BY event_date

-- Join PostgreSQL with BigQuery
SELECT p.name, b.total_events
FROM my_postgres.public.products p
JOIN my_bigquery.analytics.product_stats b
  ON p.id = b.product_id

Ejemplos de consultas a bases de datos externas

Combinar datos de hojas de cálculo y bases de datos

Una de las funciones más potentes es la capacidad de combinar datos de distintas fuentes. Puedes unir datos de hojas de cálculo con bases de datos externas en una sola consulta.

Casos de uso comunes

  • Enriquecer registros de hojas de cálculo con datos de clientes de tu base de datos
  • Comparar datos de seguimiento local contra tu almacén de datos
  • Validar entradas de hojas de cálculo contra tablas de referencia externas
  • Combinar datos de ventas de hojas con el catálogo de productos de la base de datos
text
-- Join spreadsheet orders with database customers
SELECT
  s.order_id,
  s.order_date,
  s.amount,
  c.customer_name,
  c.email,
  c.tier
FROM sheet_range('Orders!A1:D500') s
JOIN my_postgres.public.customers c
  ON s.customer_id = c.id
WHERE s.amount > 1000

-- Cross-database aggregation
SELECT
  c.country,
  COUNT(*) as order_count,
  SUM(s.amount) as total_sales
FROM sheet_range('Sales!A1:C1000') s
JOIN my_postgres.public.customers c
  ON s.customer_id = c.id
GROUP BY c.country
ORDER BY total_sales DESC

Ejemplos de joins entre múltiples fuentes

Opciones de salida de consultas

Los resultados de las consultas pueden entregarse de dos maneras:

Resultados en línea (predeterminado)
Los resultados se devuelven directamente a ModelMonkey para su análisis y razonamiento. Esto es útil para consultas exploratorias donde quieres entender los datos antes de decidir qué hacer con ellos.

  • Devuelve hasta 20 filas de forma predeterminada (configurable hasta 100)
  • Incluye tipos de columna y metadatos
  • Ideal para la exploración rápida de datos

Salida a hoja
Los resultados se escriben directamente en una nueva hoja de tu hoja de cálculo. Esto es útil cuando deseas conservar los resultados de la consulta para trabajos posteriores.

  • Crea una nueva hoja con el nombre que especifiques
  • Incluye todas las filas (sin límite de filas)
  • Fila de encabezado agregada automáticamente
  • Ideal para crear informes o preparar datos

Tip

Pídele a ModelMonkey que "guarde los resultados en una nueva hoja" o que "escriba la salida en una hoja llamada Resultados" para usar el modo de salida a hoja.

Manejo de tipos de datos

ModelMonkey infiere automáticamente los tipos de columna a partir de los datos de tu hoja de cálculo:

Tipos compatibles

  • Números: Los enteros y decimales se detectan y tratan como tipos numéricos
  • Booleanos: Los valores TRUE/FALSE se reconocen como booleanos
  • Texto: Todo lo demás se trata como texto (VARCHAR)
  • Fechas: Los valores de fecha en las celdas normalmente se manejan como texto; usa funciones de fecha de SQL para procesarlos

Proceso de inferencia de tipos
ModelMonkey muestrea las primeras filas de datos para determinar el tipo apropiado para cada columna. Si una columna contiene tipos mixtos, se establece texto de forma predeterminada para evitar pérdida de datos.

text
-- Parse date strings in queries
SELECT
  order_id,
  strptime(order_date, '%Y-%m-%d') as parsed_date,
  amount
FROM sheet_range('Orders!A1:C100')
WHERE strptime(order_date, '%Y-%m-%d') >= DATE '2024-01-01'

-- Cast numeric strings
SELECT
  product_name,
  CAST(price AS DOUBLE) as numeric_price
FROM sheet_range('Products!A1:B50')

Trabajar con tipos de datos

Consideraciones de rendimiento

Ejecución de consultas

  • Las consultas tienen un tiempo de espera de 30 segundos
  • El conjunto de resultados máximo es de 16.384 filas por seguridad
  • Los rangos grandes de hojas de cálculo se cargan en memoria para la consulta

Buenas prácticas

  • Especifica rangos precisos en lugar de columnas enteras (p. ej., A1:D500 en vez de A:D)
  • Usa cláusulas WHERE para filtrar con anticipación y reducir los datos procesados
  • Para conjuntos de datos muy grandes, considera usar la salida a hoja para evitar problemas de memoria
  • Indexa las tablas de bases de datos externas grandes para acelerar los joins

Caché
Los resultados de las consultas no se almacenan en caché entre solicitudes. Cada consulta vuelve a leer los datos actuales de la hoja de cálculo, asegurando que siempre obtengas los valores más recientes.

Warning

Los rangos muy grandes (decenas de miles de filas) pueden ralentizar la ejecución de las consultas. Considera filtrar los datos o usar bases de datos externas para análisis a gran escala.

Funciones SQL compatibles

ModelMonkey admite una amplia gama de funciones SQL a través de DuckDB:

Operaciones estándar

  • SELECT, FROM, WHERE, ORDER BY, LIMIT
  • GROUP BY con funciones de agregación (SUM, COUNT, AVG, MIN, MAX, etc.)
  • Cláusulas DISTINCT y HAVING
  • UNION, INTERSECT, EXCEPT

Joins

  • INNER JOIN, LEFT JOIN, RIGHT JOIN, FULL OUTER JOIN
  • Cross joins y self joins
  • Joins de múltiples tablas

Funciones avanzadas

  • Subconsultas y CTEs (cláusulas WITH)
  • Funciones de ventana (ROW_NUMBER, RANK, LAG, LEAD, etc.)
  • Expresiones CASE
  • Funciones de cadena, funciones de fecha, funciones matemáticas

No compatible

  • INSERT, UPDATE, DELETE (las consultas son de solo lectura)
  • CREATE TABLE, ALTER TABLE (sin modificaciones de esquema)
  • Procedimientos almacenados o funciones definidas por el usuario

Ejemplos de consultas

A continuación se presentan algunos ejemplos prácticos de consultas SQL que podrías utilizar:

text
-- Monthly sales summary
SELECT
  strftime(strptime(date, '%Y-%m-%d'), '%Y-%m') as month,
  COUNT(*) as num_orders,
  SUM(amount) as total_revenue,
  AVG(amount) as avg_order_value
FROM sheet_range('Orders!A1:D1000')
GROUP BY month
ORDER BY month DESC

-- Find duplicate entries
SELECT email, COUNT(*) as count
FROM sheet_range('Contacts!A1:E500')
GROUP BY email
HAVING COUNT(*) > 1

-- Top customers by spending
SELECT
  customer_id,
  SUM(amount) as total_spent,
  COUNT(*) as num_orders
FROM sheet_range('Orders!A1:D1000')
GROUP BY customer_id
ORDER BY total_spent DESC
LIMIT 10

-- Running total with window function
SELECT
  date,
  amount,
  SUM(amount) OVER (ORDER BY date) as running_total
FROM sheet_range('Transactions!A1:C100')

Ejemplos prácticos de consultas SQL

Resolución de problemas

Errores de "Columna no encontrada"

  • Verifica que tu fila de encabezado contenga los nombres de columna esperados
  • Los nombres de columna distinguen entre mayúsculas y minúsculas
  • Los espacios en los nombres de columna funcionan, pero pueden requerir comillas en consultas complejas

Errores de "Rango no válido"

  • Verifica que el nombre de la hoja esté escrito correctamente
  • Asegúrate de que el rango exista y contenga datos
  • Revisa si hay caracteres especiales en los nombres de hoja que requieran escape

Errores de "Tiempo de espera de consulta agotado"

  • Simplifica tu consulta o reduce el rango de datos
  • Agrega cláusulas WHERE para filtrar los datos con anticipación
  • Considera usar la salida a hoja para conjuntos de resultados grandes

Errores de "Conexión no encontrada"

  • Verifica que el nombre de la conexión externa sea correcto
  • Comprueba que la conexión esté activa en el panel External Data Connections
  • Asegúrate de tener permiso para acceder a la base de datos externa

Resultados vacíos o inesperados

  • Verifica que los tipos de datos coincidan con tus condiciones WHERE
  • Comprueba que los formatos de fecha coincidan con los de tu hoja de cálculo
  • Busca espacios iniciales o finales en los datos de texto
ModelMonkey Docs