SQL cells.

Pick a connection from the cell header, write a query, get a DataFrame. Mix it freely with Python cells below.

Picking a connection

Every SQL cell has a connection picker in its header. Pick one of your saved integrations — PostgreSQL, Snowflake, BigQuery, anything from the connectors list — and the cell runs against it.

New to integrations? Add one from Integrations → + Add connection in the activity bar. Connections are scoped to your machine and your user; teammates supply their own.

A SQL cell header showing the connection picker, the result variable name input, and the run button./docs-images/notebooks/sql-header.png
Connection on the left, output variable name on the right.

The output DataFrame

Every SQL cell exposes its result as a DataFrame variable. The name lives in the cell header — defaults to df, then df_2, df_3 — and you can rename it inline. Use that name in any Python cell below.

-- SQL cell, output named "orders"
SELECT id, customer_id, amount, created_at
FROM orders
WHERE created_at >= now() - interval '30 days';
# Python cell — orders is already a DataFrame
orders.groupby("customer_id")["amount"].sum().sort_values(ascending=False).head(10)

Variables & parameters

Use {{ var }} inside a SQL cell to interpolate Python variables. Orchid parameterizes the query — values are bound, not string-spliced, so SQL injection isn't a concern even with untrusted input.

# Define inputs in a Python cell above
region = "EMEA"
since = "2026-01-01"
SELECT region, sum(amount) AS revenue
FROM orders
WHERE region = {{ region }}
  AND created_at >= {{ since }}
GROUP BY region;
Tip

Loops, conditionals, and lists work too: {{ ids | sqlsafe }} for a pre-trusted list literal, {% if region %}...{% endif %} for optional clauses. Useful when you want one SQL cell to power a parameterized dashboard tile.

The result viewer

Results render in a virtualized table — scrolls smoothly through large result sets without paging. Click a column header to sort. Drag column edges to resize. The toolbar above the table lets you:

  • Filter — quick filters per column, no SQL re-run.
  • Search — substring across all visible columns.
  • Copy as CSV / JSON — visible rows, with current sort and filter applied.
  • Open in full pane — pops the table into the bottom panel for more room.
A virtualized SQL result table with sortable columns and a row count of two million./docs-images/notebooks/sql-result.png
Virtualized table — scrolls smoothly past hundreds of thousands of rows.

Common gotchas

  • No connection selected — the run button is disabled until you pick one. Cells from teammates show their original connection name; pick your local one if names differ.
  • Result is too wide — Orchid truncates very long string values in the inline preview. Full values are preserved in the DataFrame; export to CSV to see them.
  • Write statement attempted on a read-only connection — the run fails with an explicit message. Lift the lock from connection settings if you mean it. See Approvals.

See the connector docs for setup specifics — PostgreSQL, Snowflake, BigQuery. Back to Notebooks.