Consultas - Escribir y Ejecutar Consultas de Datos

La función de Consultas te permite escribir, ejecutar y gestionar consultas SQL contra tus bases de datos conectadas. Esta guía cubre la interfaz del editor de consultas, las opciones de ejecución, el manejo de parámetros y consideraciones especiales sobre tipos de bases de datos.

Acceder a las Consultas

  1. Navega a tu informe en la aplicación
  2. Haz clic en la pestaña Consulta en la navegación del informe
  3. Selecciona una consulta existente o crea una nueva

Nota: La interfaz de consulta incluye pestañas para Consulta, Tabla, Parámetros, Consulta Renderizada e Historial de Ejecución.

Interfaz del Editor de Consultas

El editor de consultas se adapta según el tipo de conexión de tu base de datos:

Generación de Consultas Potenciada por IA

PyQueryHub incluye un asistente de IA inteligente que puede generar consultas SQL a partir de descripciones en lenguaje natural:

Interfaz del Asistente de Consultas de IA

Uso del Asistente de IA:

  1. Haz clic en el botón Asistente de IA en la barra de herramientas del editor de consultas
  2. Describe lo que quieres en un inglés sencillo (p. ej., "Muéstrame todos los usuarios que se registraron en los últimos 7 días")
  3. La IA generará una consulta MySQL basada en el esquema de tu base de datos y la descripción
  4. Revisa y modifica la consulta generada según sea necesario
  5. Haz clic en Generar y Ejecutar para ejecutar la consulta inmediatamente

Características del Asistente de IA:

  • Procesamiento de lenguaje natural - Entiende solicitudes de datos complejas en un inglés sencillo
  • Conocimiento del esquema - Utiliza la estructura real de tu base de datos para generar consultas precisas
  • Optimización para MySQL - Genera consultas optimizadas específicamente para la sintaxis de MySQL
  • Comprensión del contexto - Interpreta las relaciones entre tablas y los patrones de consulta comunes
  • Ejecución instantánea - Las consultas generadas se pueden ejecutar inmediatamente o personalizarse aún más

Ejemplos de prompts:

  • "Mostrar ventas por región para el mes actual"
  • "Encontrar clientes que no han realizado una compra en 90 días"
  • "Obtener los 10 productos principales por ingresos este trimestre"
  • "Listar todos los usuarios con perfiles incompletos"

Conexiones de Bases de Datos SQL

Para bases de datos tradicionales (MySQL, PostgreSQL, BigQuery, etc.):

  • Editor de Código Monaco: Editor SQL con todas las funciones y resaltado de sintaxis
  • Diseño Redimensionable: Arrastra el divisor para ajustar la proporción editor/resultados
  • Panel de Esquema de Base de Datos: Activa/desactiva el panel derecho para explorar tablas y columnas
  • Autocompletado: Sugerencias de palabras clave SQL y del esquema de la base de datos
  • Métricas de Ejecución: Visualiza el tiempo de ejecución de la consulta y el tamaño de los datos

Interfaz de la Pestaña de Consulta

Ejecución de Consultas SQL:

  1. Escribe tu SQL in el editor Monaco
  2. Haz clic en el botón Ejecutar o presiona Ctrl/Cmd + Enter
  3. Los resultados aparecen abajo con columnas ordenables
  4. Se muestran las métricas de ejecución (tiempo, tamaño de los datos)

Conexiones de Google Sheets

Para conexiones con Google Sheets, la interfaz es diferente:

  • Selector de Hojas de Cálculo: Elige entre las hojas de cálculo de tu Google Drive
  • Selector de Hojas: Selecciona la hoja/pestaña específica dentro de la hoja de cálculo
  • Sin Editor SQL: Google Sheets no admite consultas SQL
  • Importación de Datos Crudos: Los datos completos de la hoja se importan para el procesamiento del gráfico

Uso de Google Sheets:

  1. Selecciona una hoja de cálculo del menú desplegable
  2. Elige la hoja/pestaña específica que quieres usar
  3. Los datos se importan automáticamente - no se necesita ejecución de consulta
  4. Todo el filtrado y procesamiento ocurre en la configuración del gráfico

Pestaña de Tabla

Visualiza los resultados de tu última consulta en una tabla a pantalla completa:

  • La paginación está fijada en 50 filas por página
  • Puedes ordenar por cualquier encabezado de columna
  • Vista a pantalla completa para un análisis detallado de los datos

Interfaz de la Pestaña de Tabla

Pestaña de Parámetros

Si tu consulta utiliza parámetros (definidos en YAML), la pestaña Parámetros te permite:

  1. Rellenar o ajustar los valores de los parámetros a través de un formulario
  2. Volver a ejecutar la consulta con nuevos valores para ver los resultados actualizados
  3. Probar diferentes combinaciones de parámetros

Interfaz de la Pestaña de Parámetros

Pestaña de Consulta Renderizada

Observa el SQL real enviado a la base de datos después del procesamiento de plantillas Liquid:

  • Editor de solo lectura que muestra la consulta final
  • Útil para depurar la sustitución de parámetros
  • Copia la sentencia final para uso externo

Interfaz de Consulta Renderizada

Panel de Opciones de Consulta y Esquema

Haz clic en el interruptor del panel en la parte superior derecha para abrir/cerrar el panel de Opciones de Consulta y Esquema, que incluye tres pestañas principales:

Pestaña de Esquema

La pestaña Esquema proporciona potentes funciones de exploración de bases de datos e inyección de código:

Panel de Esquema de Consulta

  • Conexión de Base de Datos: Cambia entre tus conexiones de base de datos configuradas a través del menú desplegable
  • Nombre de la Consulta: Edita y renombra tu consulta directamente en el panel
  • Navegador de Esquema: Vista de árbol expandible de la estructura de tu base de datos
  • Inyección de Tabla: Haz clic en el icono de flecha (▷) junto a cualquier tabla para inyectar el nombre de la tabla en tu consulta
  • Inyección de Campo: Haz clic en campos individuales para inyectar nombres de columna en tu SQL
  • Actualización de Esquema: Botón de actualización (🔄) para actualizar el esquema de la base de datos si la estructura cambia
  • Vista Previa de SQL: Haz clic en el icono de expandir junto a las tablas para inyectar el SQL completo de la tabla para una vista previa

Funciones de Inyección de Esquema

El panel de esquema facilita la escritura de consultas con estas capacidades de inyección:

Inyección de Nombre de Tabla:

  • Haz clic en el icono ▷ junto a cualquier tabla (p. ej., detailed_support_analytics, quarterly_sales, wine)
  • El nombre de la tabla se inserta automáticamente en la posición de tu cursor en el editor de consultas
  • Perfecto para cláusulas FROM y sentencias JOIN

Inyección de Nombre de Campo:

  • Expande cualquier tabla para ver sus columnas con tipos de datos
  • Haz clic en campos individuales (p. ej., report_month: date, product_name: string)
  • Los nombres de los campos se inyectan directamente en tu consulta
  • Ahorra tiempo de escritura y previene errores en los nombres de las columnas

Actualización de Esquema:

  • El esquema de la base de datos se almacena en caché para un mejor rendimiento
  • Haz clic en el icono de actualización (🔄) cuando la estructura de tu base de datos cambie
  • Actualiza las listas de tablas, nombres de columnas y tipos de datos
  • Esencial cuando se añaden nuevas tablas o columnas

Vista Previa y Estructura de SQL:

  • Usa la funcionalidad de vista previa para ver las estructuras completas de las tablas
  • Inyecta definiciones SQL completas de tablas como referencia
  • Útil para entender los tipos de datos y las restricciones

Pestaña de Vista Previa

La pestaña Vista Previa proporciona una exploración de datos interactiva con vistas previas automáticas de las tablas:

Panel de Vista Previa de Consulta

Selección y Vista Previa de Tabla:

  • Haz clic en cualquier tabla en el navegador de esquemas para cargar automáticamente una vista previa de 100 registros
  • Los datos de la tabla aparecen instantáneamente en la pestaña de Vista Previa sin ejecutar una consulta
  • Perfecto para explorar la estructura y el contenido de los datos antes de escribir SQL
  • No es necesario escribir SELECT * FROM table LIMIT 100 - es automático

Inyección de Nombre de Campo desde la Vista Previa:

  • Haz clic en cualquier encabezado de columna en la vista previa para inyectar el nombre del campo en tu consulta
  • Los nombres de los campos se insertan en la posición de tu cursor en el editor SQL
  • Combina con la inyección de tablas para una construcción rápida de consultas
  • Elimina errores de escritura y acelera el desarrollo de consultas

Flujo de Trabajo de Exploración de Datos:

  1. Explora las tablas en la pestaña de Esquema
  2. Haz clic en el nombre de una tabla para ver los datos de vista previa en la pestaña de Vista Previa
  3. Haz clic en los encabezados de las columnas para inyectar nombres de campo en tu consulta
  4. Usa el icono de actualización si la estructura de la tabla cambia
  5. Construye consultas de manera eficiente con una referencia visual de los datos

Esta característica hace que la exploración de datos sea intuitiva: puedes ver muestras de datos reales mientras construyes tus consultas, lo que facilita la comprensión de los tipos de datos, formatos y patrones de contenido.

Pestaña de Configuración

La pestaña Configuración proporciona opciones de configuración completas para el editor de consultas:

Panel de Configuración de Consulta

Configuración de Consulta:

  • Nombre: Edita el nombre de la consulta directamente en el panel
  • Conexión: Cambia entre diferentes conexiones de bases de datos a través del menú desplegable

Opciones de Inserción de Campos:

  • Incluir nombre de la tabla en la inserción de campos: Cuando está habilitado, al hacer clic en los campos se inyecta el formato tabla.columna en lugar de solo columna
  • Añadir comillas a los nombres de las tablas durante las inserciones: Envuelve automáticamente los nombres de las tablas en comillas invertidas al inyectar (p. ej., `nombre_tabla`)
  • Incluir conjunto de datos para las tablas: Para bases de datos como BigQuery, incluye el prefijo del conjunto de datos (p. ej., conjunto_de_datos.tabla.columna)

Autocompletado y Sugerencias:

  • Habilitar autocompletado: Activa/desactiva la funcionalidad de autocompletado del editor Monaco
  • Sugerir tablas: Incluye nombres de tablas en las sugerencias de autocompletado
  • Sugerir columnas: Incluye nombres de columnas en las sugerencias de autocompletado
  • Sugerir palabras clave SQL: Incluye palabras clave SQL (SELECT, FROM, WHERE, etc.) en las sugerencias
  • Añadir comillas en las sugerencias de autocompletado: Añade automáticamente comillas alrededor de los nombres de tablas/columnas en las sugerencias

Estilo de Código:

  • Mayúsculas/minúsculas de las palabras clave: Elige entre MAYÚSCULAS o minúsculas para las palabras clave SQL
    • MAYÚSCULAS: SELECT, FROM, WHERE (estilo SQL tradicional)
    • minúsculas: select, from, where (preferencia moderna)

Tema del Editor:

  • Modo Claro: Tema de editor brillante con texto oscuro sobre fondo claro
  • Modo Oscuro: Tema de editor oscuro con texto claro sobre fondo oscuro (predeterminado)

Estas configuraciones se guardan como cookies del navegador y persisten entre sesiones. Cada configuración afecta inmediatamente el comportamiento del editor de consultas, permitiéndote personalizar la experiencia de desarrollo para que coincida con tus preferencias y estándares de codificación.

Asistente de Consultas de IA

PyQueryHub incluye un ayudante de consultas potenciado por IA:

  • Prompts en Lenguaje Natural: Describe qué datos necesitas en un inglés sencillo
  • Generación de Consultas: La IA genera SQL basado en el esquema de tu base de datos y el prompt
  • Refinamiento de Consultas: Mejora las consultas existentes con la asistencia de la IA
  • Seguimiento del Uso de Tokens: El uso de la IA se rastrea por espacio de trabajo con límites de cuota

Programación de Consultas y Alertas

Las consultas se pueden programar para que se ejecuten automáticamente:

  • Configuración de Programación: Establece tiempos de ejecución recurrentes
  • Integración de Alertas: Dispara notificaciones cuando los resultados de la consulta cumplen condiciones específicas
  • Seguimiento del Historial: Todas las ejecuciones programadas se registran con detalles de ejecución

Interfaz del Cajón de Opciones

Ejecución de Consultas y Resultados

Métodos de Ejecución

  • Botón Ejecutar: Haz clic en el botón Ejecutar en la interfaz
  • Atajo de Teclado: Presiona Ctrl/Cmd + Enter para ejecutar
  • Texto Seleccionado: Ejecuta solo la porción seleccionada de tu consulta
  • Ejecución en Segundo Plano: Las consultas grandes se ejecutan de forma asíncrona con seguimiento del progreso

Visualización de Resultados

  • Resultados en Línea: Los resultados aparecen debajo del editor en la pestaña Consulta
  • Tabla a Pantalla Completa: Cambia a la pestaña Tabla para una vista expandida
  • Columnas Ordenables: Haz clic en los encabezados de las columnas para ordenar los resultados
  • Paginación: Los resultados se paginan para grandes conjuntos de datos
  • Opciones de Exportación: Descarga los resultados en varios formatos

Métricas de Ejecución

Cada ejecución de consulta proporciona métricas detalladas:

  • Tiempo de Ejecución: Tiempo de ejecución de la consulta en milisegundos
  • Tamaño de los Datos: Tamaño de los datos devueltos en bytes
  • Conteo de Filas: Número de filas devueltas
  • Historial de Ejecución: Ejecuciones anteriores con marcas de tiempo y datos de rendimiento

Manejo de Errores

  • Errores de Sintaxis: Los problemas de sintaxis SQL se resaltan en el editor
  • Errores de Base de Datos: Los errores de conexión y ejecución se muestran claramente
  • Manejo de Tiempos de Espera: Las consultas de larga duración tienen una gestión de tiempo de espera adecuada
  • Lógica de Reintentos: Las consultas fallidas se pueden volver a ejecutar fácilmente

Parámetros de Consulta y Plantillas

Las consultas admiten parámetros dinámicos a través de plantillas Liquid:

Sistema de Parámetros

  • Definición en YAML: Los parámetros se definen en formato YAML
  • Soporte de Tipos: Texto, números, fechas, menús desplegables y más
  • Valores Predeterminados: Establece valores predeterminados para los parámetros
  • Validación: La validación de parámetros asegura la integridad de los datos

Plantillas Liquid

PyQueryHub utiliza plantillas Liquid para la inyección de parámetros:

  • Sustitución de Parámetros: Sintaxis {{ nombre_parametro }}
  • Lógica Condicional: Sentencias @{% if %} para consultas dinámicas
  • Filtros: Aplica formato y transformaciones
  • Sentencias Assign: Crea variables derivadas

Interfaz de Parámetros

  • Formularios Autogenerados: Los parámetros crean controles de formulario interactivos
  • Actualizaciones en Tiempo Real: Cambia los valores de los parámetros y vuelve a ejecutar las consultas
  • Historial de Parámetros: Los valores de los parámetros anteriores se guardan con las ejecuciones de las consultas

Para documentación detallada de los parámetros, consulta la guía de Parámetros.

Historial de Consultas y Versionado

Historial de Ejecución

  • Pista de Auditoría Completa: Cada ejecución de consulta se registra
  • Almacenamiento de Resultados: Los resultados de las consultas se almacenan para una recuperación rápida
  • Seguimiento de Parámetros: Se guardan los valores de los parámetros utilizados para cada ejecución
  • Métricas de Rendimiento: Tiempo de ejecución y tamaño de los datos para cada ejecución

Versionado de Consultas

  • Almacenamiento de Consultas Originales: Se guardan tanto las consultas originales como las renderizadas
  • Instantáneas de Parámetros: Se conservan los parámetros utilizados para cada ejecución
  • Comparación de Resultados: Compara los resultados entre diferentes ejecuciones
  • Recuperación de Historial: Accede a versiones y resultados de consultas anteriores

Características Específicas de la Base de Datos

Bases de Datos SQL Tradicionales

  • Soporte SQL Completo: Soporte completo de sintaxis SQL según el tipo de base de datos
  • Introspección de Esquema: Descubrimiento automático de tablas, columnas y tipos
  • Cambio de Conexión: Cambia las conexiones de la base de datos por consulta
  • Optimización del Rendimiento: Métricas de ejecución de consultas y sugerencias de optimización

Google Sheets

  • Sin Interfaz SQL: Interfaz de selección de hojas de cálculo y hojas
  • Datos en Tiempo Real: Conexión directa a los datos en vivo de Google Sheets
  • Detección de Esquema: Detección automática de nombres de columna desde la primera fila
  • Autenticación: Conexión segura basada en OAuth a Google Drive

Almacenes de Datos en la Nube

  • BigQuery: Soporte para consultas analíticas complejas
  • Redshift: Optimizado para operaciones de almacén de datos a gran escala
  • Azure SQL: Características de seguridad y rendimiento de nivel empresarial

Mejores Prácticas

Rendimiento de Consultas

  • Usa cláusulas LIMIT: Evita devolver accidentalmente conjuntos de datos enormes
  • Optimiza las condiciones WHERE: Usa los índices de manera efectiva
  • Validación de parámetros: Valida los parámetros para prevenir la inyección de SQL
  • Gestión de conexiones: Elige las conexiones de base de datos adecuadas

Organización del Código

  • Nombres descriptivos: Usa nombres de consulta claros y significativos
  • Comentarios: Documenta las consultas complejas con comentarios SQL
  • Documentación de parámetros: Explica los propósitos de los parámetros en YAML
  • Control de versiones: Usa el historial de consultas para rastrear los cambios

Consideraciones de Seguridad

  • Vinculación de parámetros: Usa siempre parámetros en lugar de concatenación de cadenas
  • Aislamiento de conexiones: Usa usuarios de base de datos apropiados con permisos limitados
  • Acceso a datos: Asegúrate de que las consultas solo accedan a datos autorizados
  • Registro de auditoría: Monitorea la ejecución de consultas y el acceso a los datos

Solución de Problemas

Problemas Comunes

  • Errores de Conexión: Verifica la configuración y las credenciales de la conexión de la base de datos
  • Problemas de Tiempo de Espera: Optimiza las consultas o aumenta los límites de tiempo de espera
  • Errores de Permisos: Comprueba los permisos del usuario de la base de datos
  • Errores de Parámetros: Valida los tipos y valores de los parámetros

Obtener Ayuda

  • Mensajes de Error: Lee los mensajes de error cuidadosamente para obtener una guía específica
  • Historial de Consultas: Comprueba las ejecuciones exitosas anteriores como referencia
  • Registros de la Base de Datos: Revisa los registros de la base de datos para obtener información detallada del error
  • Soporte: Contacta al soporte con mensajes de error específicos y detalles de la consulta

Para más información sobre características relacionadas: