Data Analysis Workshop

The Agent gets a menu of approved queries, not the keys to the SQL pantry.

1. Motivation

Free-form SQL generation makes execution difficult to review. The Database extension lets applications persist approved snippets and searchable predicates as typed rows, then expose a narrow MCP surface. Complete Data Connection first so ws, database_id, and warehouse.db exist in the same Python process.

2. Register a Read-Only Snippet

ws.upsert(
    "db-snippet",
    {
        "object_id": "snippet-customer-count",
        "database_id": database_id,
        "title": "Count customers",
        "sql": "SELECT COUNT(*) AS n FROM customers",
        "readonly": True,
        "card_text": "Count all customers in the warehouse.",
    },
)

Snippet rows keep SQL, default bind parameters, a read-only policy, and searchable card text. The linked db-database row identifies the external source.

3. Run through the Attached API

result = ws.database.run_snippet("snippet-customer-count")
print(result["rows"])

suggestions = ws.database.suggest_sql("How many customers are there?")
print([row["object_id"] for row in suggestions["snippets"]])

suggest_sql searches approved snippets and predicates. It does not ask an LLM to invent SQL inside the engine. Write snippets remain refused unless heavenbase.database.allow_write is explicitly enabled. The default is false.

4. Add a Searchable Predicate

ws.upsert(
    "db-predicate",
    {
        "object_id": "predicate-customer-id",
        "column_id": columns[0]["object_id"],
        "expression": "customer_id = :customer_id",
        "desc": "Select one customer by primary key.",
    },
)

Predicates are searchable evidence for planning. They are not executed by suggest_sql.

5. Expose the Database Profile

toolkit = ws.to_mcp(profile="database")

suggested = toolkit.run(
    "suggest_sql",
    question="How many customers are there?",
)
counted = toolkit.run(
    "run_snippet",
    snippet_id="snippet-customer-count",
)

The database profile scopes ordinary read/query tools plus suggest_sql and run_snippet. Use the MCP Toolkit reference when you are ready to register and serve the Toolkit to an external Agent.

6. Keep the Boundary Honest

Schema ingestion does not copy source rows.
Search proposes approved snippets; it does not execute them.
Snippet execution reconnects to the external database.
Read-only is the default, and write access is a deliberate configuration change.
HeavenBase does not claim distributed transactions with the source database.

Summary

Persist approved SQL as db-snippet rows.
Use ws.database for direct application calls.
Use the database MCP profile for a small Agent-facing surface.
Keep connection credentials in the execution environment.

Further Exploration

Related resources:

Data Connection — Ingest and browse schema rows
MCP Toolkit Reference — Register and serve Toolkits
Agent Extension — Agent sessions, skills, and recipes

Introduction

Quickstart

Core Concepts

Developer

Utilities Toolbox

LLM

Agent Runtime

Community

Data Analysis Workshop

1. Motivation

2. Register a Read-Only Snippet

3. Run through the Attached API

4. Add a Searchable Predicate

5. Expose the Database Profile

6. Keep the Boundary Honest

Summary

Further Exploration

​1. Motivation

​2. Register a Read-Only Snippet

​3. Run through the Attached API

​4. Add a Searchable Predicate

​5. Expose the Database Profile

​6. Keep the Boundary Honest

​Summary

​Further Exploration

1. Motivation

2. Register a Read-Only Snippet

3. Run through the Attached API

4. Add a Searchable Predicate

5. Expose the Database Profile

6. Keep the Boundary Honest

Summary

Further Exploration