ask-sql

Convert natural language questions to SQL and execute them against your database.

Syntax

%%calliope ask-sql <datasource> [options]
Your question in plain English

Options

Basic Usage

%%calliope ask-sql sales_db
What were the total sales by region last quarter?

Output includes:

• The generated SQL query
• Query results as a table
• A relevant chart
• Suggested follow-up questions

With Model Selection

Use a specific model:

%%calliope ask-sql sales_db --model claude
Show me the top 10 customers by lifetime value

Or with provider:model format:

%%calliope ask-sql sales_db --model openai:gpt-4o
What's the month-over-month growth rate?

With AI Analysis

Pass results to AI for interpretation:

%%calliope ask-sql analytics_db --to-ai
What's causing the decline in user engagement?

The AI will:

1. Generate and run the SQL
2. Analyze the results
3. Provide insights and recommendations

Examples

Sales Analysis

%%calliope ask-sql sales_db
Show monthly revenue for 2024 compared to 2023

Customer Insights

%%calliope ask-sql customers_db
Which customer segments have the highest churn rate?

Trend Analysis

%%calliope ask-sql metrics_db
What's the 7-day moving average of daily active users?

Comparative Queries

%%calliope ask-sql ecommerce_db
Compare conversion rates between mobile and desktop users by month

Aggregations

%%calliope ask-sql inventory_db
What's the average time products spend in inventory by category?

How It Works

1. Understanding: The AI interprets your question
2. Schema matching: It references the database schema (learned via RAG)
3. SQL generation: It creates an appropriate SQL query
4. Execution: The query runs against your database
5. Visualization: Results are displayed with charts
6. Follow-ups: Related questions are suggested

Tips for Better Results

Be Specific

# Good
%%calliope ask-sql sales
Show total revenue by product category for Q4 2024,
sorted by revenue descending

%%calliope ask-sql sales
Show me some sales data

Use Business Terms

If you’ve trained RAG with documentation:

%%calliope ask-sql finance_db
What's our ARR growth rate this quarter?

The system understands “ARR” if you’ve documented it.

Mention Time Frames

%%calliope ask-sql analytics
Daily active users for the last 30 days

Request Specific Formats

%%calliope ask-sql reports
Show a breakdown of support tickets by priority and status
as a pivot table

Accessing Results

After running ask-sql:

# The generated SQL
print(_calliope_last_sql)

data = _calliope_last_data

import pandas as pd
df = pd.DataFrame(data)
df.to_csv('results.csv')

Follow-up Questions

Each response includes suggested follow-up questions. Click them to run related queries without typing.

Troubleshooting

Wrong table or columns

• Run %calliope get-datasource <id> to see available tables
• Train RAG with documentation about your schema
• Use exact column names in your question

Slow responses

• Complex queries take longer
• Large result sets need more processing
• Add LIMIT in your question: “Show the first 100…”

Unexpected results

• Check the generated SQL in the output
• Rephrase your question
• Be more specific about what you want