Overview

SQL Notebooks provide an interactive, cell-based interface for running SQL queries against your data warehouse. Notebooks support SQL, markdown, and parameter cells with built-in visualizations, making them ideal for ad-hoc data validation, exploration, and sharing results with your team.

Key capabilities:

• Run SQL queries against your warehouse via MC Bridge
• Visualize results as tables, bar charts, or time series
• Define reusable parameters for dynamic queries
• Import and export notebooks as YAML
• Share notebooks via URL

Prerequisites

• MC Bridge running and connected to your warehouse (see MC Bridge setup)
• Logged into Monte Carlo

Getting Started

1. Navigate to Notebooks in the left sidebar (or go to /notebooks)
2. Click New Notebook to create a blank notebook
3. Select a connector from the dropdown to connect to your warehouse
4. Add cells and start writing queries

Cell Types

SQL Cells

SQL cells let you write and execute queries against your connected warehouse. Each cell runs independently and displays results inline.

• Write any SQL supported by your warehouse
• Click Run (or use the keyboard shortcut) to execute
• Choose a display type for results: table, bar chart, or timeseries
• Reference parameters using {{param_name}} syntax

Markdown Cells

Markdown cells support standard markdown for documenting your analysis. Click a markdown cell to edit, and click away to render.

Parameter Cells

Parameter cells define variables that can be referenced in SQL cells via {{param_name}} interpolation. Three input types are supported:

Example: Define a target_schema parameter with type schema_selector, then use SELECT * FROM {{target_schema}}.my_table in a SQL cell.

Running Queries

• Run a single cell: Click the Run button on any SQL cell
• Run All: Execute all SQL cells in order from top to bottom
• Cancel: Stop a running query mid-execution

Parameter interpolation happens at runtime — {{param_name}} placeholders are replaced with current parameter values before the query is sent to the warehouse.

Visualizations

Each SQL cell can display results in one of three formats:

• Table (default): Standard tabular view of query results
• Bar chart: Requires a dimension column (categorical) and a value column (numeric). Auto-detected from result columns
• Timeseries: Requires a timestamp column and one or more value columns. Renders as a line chart over time

Switch between display types using the dropdown on each cell.

Import and Export

Notebooks use a YAML format for portability:

• Export: Download the current notebook as a .yaml file
• Import: Load a notebook from a YAML file or via URL

Import via URL

Notebooks can be imported programmatically using a URL with base64-encoded YAML:

https://getmontecarlo.com/notebooks/import#<base64-encoded-yaml>

This is used by tools like the Validation Notebook Generator to automatically open generated notebooks.

YAML Format

version: 1
metadata:
  id: my-notebook-abc123
  name: My Notebook
  created_at: "2026-03-02T00:00:00.000Z"
  updated_at: "2026-03-02T00:00:00.000Z"
default_context:
  database: ANALYTICS
  schema: PROD
cells:
  - id: param-1
    type: parameter
    content:
      name: target_schema
      config:
        type: schema_selector
  - id: cell-1
    type: sql
    content: SELECT * FROM {{target_schema}}.my_table LIMIT 10
    display_type: table
  - id: cell-2
    type: markdown
    content: |
      ## Notes
      This query samples from the target schema.
    display_type: table

Notebook List

The /notebooks page shows all your saved notebooks. From here you can:

• Create a new notebook
• Open an existing notebook by clicking on it
• Delete a notebook you no longer need
• Rename a notebook by editing its title