Database Magic

The %db and %%db magic commands give you direct access to your databases from notebook cells — connect to datasources, inspect schemas, and ask natural language questions that return pandas DataFrames.

Quick Reference

Cell Magic

%%db ask <datasource_id>
Your question in natural language

%%db ask <datasource_id> --model anthropic:claude-3-5-sonnet-20241022
Your question with a specific model

Line Magic

%db list                          # List available datasources
%db connect <datasource_id>       # Create SQLAlchemy engine
%db connect <datasource_id> --var engine   # Use custom variable name
%db schema <datasource_id>        # Show tables and columns
%db help                          # Show help

Natural Language SQL (%%db ask)

Ask questions in plain English — the AI generates SQL, executes it, and returns a DataFrame.

%%db ask sales_db
What were the top 10 customers by revenue last quarter?

Results are automatically stored in:

• _df — pandas DataFrame of results
• _sql — the generated SQL query

# Use the results
print(_sql)     # See the generated query
_df.head()      # Explore the data
_df.plot()      # Visualize

Specify a Model

%%db ask sales_db --model anthropic:claude-3-5-sonnet-20241022
Show me monthly revenue trends for this year

The default model comes from the AI model selected in the sidebar.

Connecting to Datasources

List Available Datasources

%db list

Lists all datasources from your credential vault with their IDs and types.

Connect

%db connect sales_db

Creates a SQLAlchemy engine stored in a variable named after the datasource ID. Use --var to customize:

%db connect sales_db --var engine

Then use it directly with pandas or SQLAlchemy:

import pandas as pd
df = pd.read_sql("SELECT * FROM orders LIMIT 100", engine)

Inspect Schema

%db schema sales_db

Displays all tables and columns in the datasource — useful before asking questions so you understand the data structure.

Supported Databases

Datasources are configured in your workspace credential vault — contact your admin or use the Hub to add connections.

Tips

• Run %db schema <id> before asking questions to get better SQL generation
• Results in _df persist across cells — chain analysis steps
• Use --model to try a different AI if results aren’t accurate
• Tab completion works for datasource IDs and flags