Context Setup

The Context Engine combines schema metadata from database introspection with business documentation you upload. When other agents — Migration and Optimizer — analyze your database, they use this hybrid context for more informed recommendations.

For example, instead of just knowing that an orders table has a customer_id foreign key, the Context Engine can tell the Migration Agent that “the orders table powers the nightly revenue report and the customer dashboard.” This business understanding leads to better risk assessments and more relevant optimization suggestions.

Setting up context takes four steps: introspect your schema, upload business documents, verify uploads, and query context.

Setting Up Context

Introspect your database schema

AutoDB needs a snapshot of your current schema before it can provide context to other agents. Trigger an introspection using your connection ID:

curl -X POST https://api.autodb.app/api/v1/connections/550e8400-e29b-41d4-a716-446655440000/introspect \
  -H "X-API-Key: YOUR_API_KEY"

Introspection scans your database for tables, columns, data types, constraints, and foreign key relationships. The snapshot is stored and used by all agents when analyzing your database.

Response:

{
  "success": true,
  "data": {
    "connection_id": "550e8400-e29b-41d4-a716-446655440000",
    "table_count": 12,
    "tables": ["customers", "order_items", "orders", "products"],
    "snapshot_id": "660e8400-e29b-41d4-a716-446655440001",
    "introspected_at": "2024-01-15T10:00:00Z"
  }
}

Upload business documents

Upload documentation that provides business context about your database. Supported formats are PDF, Markdown, plain text, and SQL files (up to 10MB each, 50 files per batch). Re-uploading a file with the same name replaces old content.

curl -X POST https://api.autodb.app/api/v1/connections/550e8400-e29b-41d4-a716-446655440000/documents/upload \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "files=@data-dictionary.pdf" \
  -F "files=@schema-guide.md"

Response:

{
  "success": true,
  "data": {
    "files_processed": 2,
    "total_chunks": 47,
    "documents": [
      {
        "id": "770e8400-e29b-41d4-a716-446655440002",
        "filename": "data-dictionary.pdf",
        "chunk_count": 32,
        "size_bytes": 245760
      },
      {
        "id": "880e8400-e29b-41d4-a716-446655440003",
        "filename": "schema-guide.md",
        "chunk_count": 15,
        "size_bytes": 8192
      }
    ]
  }
}

List uploaded documents

Verify which documents are associated with a connection:
Terminal window
```
curl https://api.autodb.app/api/v1/connections/550e8400-e29b-41d4-a716-446655440000/documents \
  -H "X-API-Key: YOUR_API_KEY"
```
The response includes every document with its filename, chunk count, and upload timestamp.

Query context

Retrieve combined schema and document context for specific tables:

curl -X POST https://api.autodb.app/api/v1/connections/550e8400-e29b-41d4-a716-446655440000/context/query \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "table_names": ["orders", "order_items"],
    "query": "What business processes depend on the orders table?",
    "max_chunks": 5
  }'

The response includes schema metadata for the requested tables (columns, types, constraints, foreign keys) plus relevant document chunks ranked by relevance. The max_chunks parameter limits how many document chunks are returned (default 10, max 50).

How Context Improves Other Agents

The Context Engine does not operate in isolation — it feeds business understanding into the other agents automatically.

Migration Agent: When analyzing a migration, the Migration Agent queries context for affected tables and uses the results to generate a business_narrative in the risk report. This narrative explains which business processes are affected by the schema change and cites your uploaded documents. A migration that touches the orders table might note that it impacts the nightly revenue report pipeline.

Optimizer Agent: When optimizing a query, the Optimizer Agent uses context to understand which columns are frequently queried together and what business patterns drive the query. This leads to more relevant index recommendations and rewrite alternatives.

When context is available and used, agent responses include context_used: true so you know the analysis was informed by your schema snapshot and business documentation.

Tips

Next Steps

Architecture Overview How the Context Engine connects to the Migration and Optimizer agents