Skip to main content

Asking the Calabi AI Agent

Professional+

The Calabi AI Agent is your conversational interface to the entire data platform. Ask it questions in plain English — it translates your intent into queries, searches, pipeline calls, and chart generation without requiring you to know SQL, Calabi Catalogue's search syntax, or the CalabiIQ API.

This page explains how to frame effective questions, what categories of questions the Agent handles best, and how to make the most of its multi-turn conversation capabilities.

How the AI Agent Works​

When you submit a question, the Agent follows this process:

  1. Intent classification — determines which tools and data sources are relevant.
  2. Tool dispatch — calls the appropriate Calabi platform tools (SQL engine, Catalogue API, pipeline API, etc.) in sequence or in parallel.
  3. Result synthesis — assembles the tool outputs into a coherent, human-readable response.
  4. Presentation — formats the answer as prose, a table, a code block, or an embedded chart depending on context.

The Agent has access to 117 tools across all Calabi modules. See AI Agent Tool Reference for the complete list.

Writing Good Questions​

The Agent is designed for natural language, but a few habits make responses significantly more accurate:

HabitWhy It HelpsExample
Name the data assetResolves ambiguity when multiple assets share similar names"revenue table in the sales schema" not just "revenue"
Specify a time rangeAvoids open-ended queries that scan all history"in the last 30 days" or "for Q1 2026"
State the desired output formatTells the Agent whether to return a table, chart, or prose summary"show me a bar chart" or "give me a CSV"
Use Calabi product namesHelps the Agent route to the right module"in Calabi Catalogue", "from Calabi Pipelines"
Be specific about aggregationAvoids guessing between count, sum, average"total count of rows" vs "average revenue per customer"

Question Categories​

SQL Queries​

The Agent can write and execute SQL against your connected data warehouses, then return results as formatted tables or downloadable files.

Example questions:

  1. "How many orders were placed in the last 7 days?"
  2. "What are the top 10 customers by total revenue in Q1 2026?"
  3. "Show me monthly active users for the past 12 months."
  4. "What is the average session duration by device type for last week?"
  5. "Find all tables in the staging schema that have more than 1 million rows."
  6. "Which products have a return rate above 5% this quarter?"
  7. "Compare gross margin by region for 2025 vs 2026."
  8. "List all users who logged in within the last 24 hours but have not completed onboarding."

Chart Generation​

Ask the Agent to generate a CalabiIQ visualization inline in the chat. Charts are interactive and can be saved directly to a CalabiIQ dashboard.

Example questions:

  1. "Show me a bar chart of revenue by product category for this month."
  2. "Plot daily pipeline failure counts for the last 30 days as a line chart."
  3. "Create a pie chart of user distribution by country."
  4. "Give me a stacked bar chart of orders by status (pending, shipped, delivered) per week."
  5. "Generate a scatter plot of customer lifetime value vs acquisition channel."

Pipeline Status​

The Agent queries Calabi Pipelines to report on DAG health, run history, and task-level outcomes.

Example questions:

  1. "What pipelines failed overnight?"
  2. "Show the run history for the customer_ltv DAG over the last week."
  3. "Which Calabi Pipelines DAGs are currently running?"
  4. "How long did the daily_dbt_run pipeline take yesterday compared to its 30-day average?"
  5. "List all DAGs that have failed more than 3 times in the past 7 days."

The Agent searches Calabi Catalogue for data assets, glossary terms, lineage information, and data quality results.

Example questions:

  1. "Find all tables related to customer churn."
  2. "Who owns the fact_orders table?"
  3. "Show me the lineage of the revenue_summary dashboard — what tables feed it?"
  4. "What glossary terms are defined for 'Monthly Active User'?"
  5. "Which tables have failing data quality tests right now?"
  6. "List all datasets tagged as PII in the prod environment."
  7. "What columns in the users table have a description?"

Multi-Category Questions​

The Agent handles complex questions that span multiple Calabi modules in a single response.

  1. "The orders pipeline failed last night — show me what it runs, what tables it writes to, and who owns them."
  2. "Which of our CalabiIQ dashboards are based on tables that had data quality failures this week?"

Multi-Turn Conversations​

The Agent maintains context throughout a conversation session. You do not need to repeat context in follow-up questions.

Example conversation:

You:   Show me the top 5 products by revenue this month.

Agent: [Returns table: Product | Revenue | Units Sold]
       1. Premium Widget — $1,204,300 — 8,204 units
       2. ...

You:   Now filter that to only the North America region.

Agent: [Returns filtered table without you restating "top 5 products by revenue this month"]

You:   Great — save that as a bar chart on the Executive dashboard.

Agent: Chart created and added to the "Executive" dashboard in CalabiIQ.
       [Link: View chart]

The Agent tracks:

  • The current data asset or table being discussed
  • Applied filters (time range, region, segment)
  • The last SQL query executed (so you can refine it)
  • Charts generated in the session (so you can save or modify them)

Context Awareness​

The Agent is aware of your:

  • Role and permissions — it will not return data you are not authorized to see, even if you ask for it directly.
  • Default workspace — queries run against your tenant's connected data sources.
  • Active filters — if you set a global date range in CalabiIQ, the Agent respects it.
  • Recent activity — the Agent can reference assets you recently viewed in Calabi Catalogue or CalabiIQ.

Limitations​

LimitationDetails
No write operations by defaultThe Agent reads data; it does not INSERT, UPDATE, or DELETE rows in source systems.
Complex joins require guidanceFor queries spanning many tables, naming the tables explicitly produces better SQL.
Chart typesThe Agent supports bar, line, pie, scatter, and big number charts. Funnel and gauge charts must be built in CalabiIQ directly.
Max result setInline table responses are capped at 500 rows. Larger results are offered as CSV downloads.
Real-time dataThe Agent queries your data warehouse; results reflect warehouse refresh latency, not real-time source data.