Daita Logo

from_db Schema Navigation

Metadata-only schema tools that help Agent.from_db() agents work with large or ambiguous database schemas.

#Overview

Large schemas should not be fully inlined into every model prompt. Agent.from_db() can expose metadata-only schema tools so the agent can inspect the discovered schema at run time.

These tools never execute SQL and never return row data.

#Tools

ToolPurpose
db_list_tablesList discovered table summaries with pagination
db_search_schemaSearch table and column metadata
db_inspect_tableInspect one table's columns and relationships
db_describe_relationshipsList foreign-key relationships
db_find_join_pathFind SQL-ready join paths between tables

#Listing Tables

text
Tool: db_list_tables
Args: {"pattern": "order*", "limit": 30, "offset": 0}

Use this when table names are unknown or when a schema has many similarly named tables.

#Searching Metadata

text
Tool: db_search_schema
Args: {"query": "customer segment revenue", "limit": 12}

Search returns matching table summaries, matched columns, relationship hints, and match reasons.

#Inspecting a Table

text
Tool: db_inspect_table
Args: {
  "table_name": "orders",
  "column_pattern": "*total*",
  "include_columns": true,
  "limit": 40
}

db_inspect_table is the right next step after db_search_schema finds a likely table.

#Describing Relationships

text
Tool: db_describe_relationships
Args: {"table_name": "orders", "limit": 24}

Use this to understand foreign keys around a table before writing joins.

#Finding Join Paths

text
Tool: db_find_join_path
Args: {
  "from_tables": ["orders"],
  "to_tables": ["customers"],
  "max_hops": 4,
  "max_paths": 5
}

The result includes join path candidates and predicates that can be used by query planning and SQL generation.

#When Navigation Is Enabled

Schema navigation is used when the schema is large, tables are wide, table names are ambiguous, or the selected prompt budget does not inline the full schema.

You can encourage retrieval-style behavior with:

python
agent = await Agent.from_db(
    "postgresql://user:pass@host/db",
    budget="retrieval",
)

Use agent.describe() to see prompt strategy metadata:

python
metadata = agent.describe()
print(metadata["db"]["prompt"])