Módulo de Notebooks

The Notebook feature provides an interactive Python environment embedded within each report. Use it to explore parameters, inspect query results, visualize data, and push outputs back into your final report—no local Python setup required.

Accessing the Notebook

  1. Open your report and click the Notebook tab.
  2. You’ll see a toolbar at the top and a series of code cells below.

Working with Cells

Notebooks consist of cells (code + output blocks):

  • Add a cell: Click the ➕ icon between cells to insert a new blank cell.
  • Delete a cell: Click the 🗑️ icon on a cell and confirm to remove it.
  • Reorder: Use the ↑/↓ arrows to move a cell up or down.

Running Code

  • Run cell: Click ▶️ on an individual cell to execute only that cell.
  • Run All: Click Run All in the toolbar to execute every cell in order and automatically save outputs.
  • Execution count: Each run increments the counter so you can track execution order.

AI-Powered Code Generation

PyQueryHub includes an intelligent AI assistant that can generate Python code for your notebook cells based on natural language descriptions:

AI Notebook Assistant Interface

Using the AI Assistant:

  1. Click the AI Assistant button in the notebook toolbar
  2. Describe what you want to analyze in plain English (e.g., "Create a chart showing sales by region", "Find correlations in the data")
  3. The AI will generate Python code that's automatically added to the last cell in your notebook
  4. The generated code is context-aware and uses your available datasets and parameters
  5. Run the cell to execute the AI-generated code immediately

AI Assistant Features:

  • Context awareness - Knows all available variables from your datasets and parameters
  • Dataset integration - Automatically references your query results and DataFrames
  • Parameter access - Can use values from your report's parameter configuration
  • Library optimization - Generates code using available Python packages (pandas, matplotlib, seaborn, etc.)
  • Visualization ready - Creates charts and plots that render inline in your notebook
  • Data analysis - Performs statistical analysis, correlations, and data exploration

Example prompts:

  • "Show a bar chart of sales by product category"
  • "Calculate correlation between revenue and units sold"
  • "Create a time series plot of monthly trends"
  • "Find the top 10 customers by total revenue"
  • "Generate summary statistics for all numeric columns"

Available Context: The AI assistant has access to:

  • datasets - All query results as pandas DataFrames
  • ParamsObject - Your report's parameter values
  • Available functions - print_df(), run_query(), and all Python/pandas methods
  • Installed packages - pandas, numpy, matplotlib, plotly, scikit-learn, and more

Preloaded Data

On load, the Notebook initializes a Pyodide environment and injects data from your report:

  • ParamsObject: Access and pretty‑print your report’s parameters:

    ParamsObject Example

    If You edit parameters in the Parameters tab, click on Run Queries to see changes reflected in both params and dataset content.

  • DataFrameContainer: Wraps your query results as pandas DataFrames, complete with row/column counts:

    DataFrameContainer Example

These helpers render as HTML tables and images directly in the notebook.

Inspecting Query Results

Your report’s queries run before the notebook loads and are passed in via the datasets variable. Example:

DataFrameContainer Example

Use print_df to display a DataFrame in the notebook. You can also use df.head() to show the first few rows of any DataFrame.

Adding Outputs to Your Report

Toggle Add to Report Builder on any cell to include that cell’s final output (HTML table or image) in your report when saving. This lets you mix narrative text with live data insights.

Add to Report Example

Enviar Alertas desde Notebooks

Puedes enviar notificaciones directamente desde una celda del notebook usando la función integrada send_alert(). Esto te permite activar alertas en cualquier canal configurado (Slack, Discord, Telegram, Email) basado en tu análisis de datos.

Uso

send_alert(channel, title, text, level)

Parámetros

Parámetro Tipo Requerido Descripción
channel string Sí El alias del canal al que enviar la alerta (ej., 'slack', 'discord', 'telegram', 'email')
title string No El título de la alerta
text string Sí El contenido del mensaje de la alerta
level string No Nivel de severidad: 'info', 'success', 'warning', o 'error' (por defecto: 'info')

Ejemplos

Alerta simple:

send_alert('slack', 'Reporte Diario', 'Todas las métricas están dentro del rango normal.', 'success')

Alerta basada en datos:

df = datasets["sales_query"]
total = df["revenue"].sum()

if total < 10000:
    send_alert('discord', 'Alerta de Ingresos', f'Los ingresos diarios son ${total:,.2f}, por debajo del umbral de ,000.', 'warning')
else:
    send_alert('slack', 'Actualizaci&oacute;n de Ingresos', f'Ingresos diarios: ${total:,.2f}', 'success')

Múltiples canales:

message = f'Se encontraron {len(anomalies)} anomal&iacute;as en el &uacute;ltimo lote de datos.'
send_alert('slack', 'Calidad de Datos', message, 'error')
send_alert('email', 'Calidad de Datos', message, 'error')

Nota: Los canales deben estar configurados antes de usarlos. Consulta Canales para instrucciones de configuración. Al combinarlo con la Programación de Consultas, puedes automatizar la ejecución del notebook y enviar alertas de forma recurrente.

Bajo el Capó

  • Funciones disponibles:
    • print_df: Mostrará el dataframe de pandas en una tabla html.
    • run_query(query, db_connection_name): Ejecutará una consulta y devolverá los resultados como un dataframe de pandas.
    • send_alert(channel, title, text, level): Enviar una notificación a un canal configurado.

  • Available Python Packages: Pyodide Comes by default with a set of packages, including:

    • pandas

    • numpy

    • matplotlib

    • scikit-learn

    • statsmodels

    • plotly

    • Check all available packages in the Pyodide documentation.

  • Some Packeges (like seasborn) are not available by default. You can install them using micropip in your notebook. For example, to install seaborn, run:
import micropip
await micropip.install(['seaborn'])

Example Code Snippet

Pandas Stats

Example Pandas Stats

Example Plot With Matplotlib and Seaborn

Example Plot

Best Practices

  • Focus: Keep each cell to a single purpose—data inspection, plotting, or parameter testing.
  • Re‑run Queries: After updating parameters in the Parameters tab, click Run Queries to refresh data.
  • Visualize: Use matplotlib to chart results; plots render inline thanks to a custom plt.show() hook.

Start experimenting with live Python in your reports today—your data, your code, your insights, all in one place!