Catalog

#Authority

The catalog is authoritative for current SQLite and PostgreSQL source and resource identity, schemas, facets, relationships, sensitivity, and freshness. It is not a plugin and does not contain query results, workspace-file inventory, or model-authored conclusions.

Each active source has one committed current snapshot. Attachment and refresh replace a snapshot atomically only after successful discovery.

#Summary and Preview

summary = await agent.catalog_summary()
preview = await agent.catalog_preview(limit=12)
 
print(summary.active_source_count)
for resource in preview:
    print(resource.id, resource.name, resource.kind)

catalog_preview() is deterministic and bounded. Use it for local inspection, onboarding, and source-selection interfaces.

#List Resources

resources = await agent.list_catalog_resources(source_id=source.id)

Catalog resources include stable IDs, source scope, kind, name, current revision, facets, and relationship references.

#Search

from daita.catalog import CatalogSearchRequest, ResourceKind
 
result = await agent.search_catalog(
    CatalogSearchRequest(
        agent_id=agent.id,
        query="orders customer revenue",
        source_ids=(source.id,),
        resource_kinds=(ResourceKind.TABLE,),
        limit=10,
    )
)
 
for hit in result.hits:
    print(hit.name, hit.resource_id, hit.score)

Search uses structural catalog text. It does not scan source rows.

#Inspect a Resource

details = await agent.inspect_catalog_resource(resource_id)

The returned frozen JSON object is suitable for debugging or a local UI. Model-facing catalog tools use the same current catalog owner:

• catalog_search
• catalog_schema
• catalog_inspect
• catalog_traverse

#Relationships

SQLite and PostgreSQL discovery records foreign-key relationships with field pairs and provenance. catalog_traverse can follow those relationships without querying business rows, allowing the model to plan a catalog-grounded join before calling a SQL tool.

#Refresh and Staleness

Use refresh_source() when an attached database's structure changes. Database query backends recheck live revisions; stale resources fail safely rather than executing against structure that differs from the committed catalog. Workspace files use separate physical revision bindings and are never refreshed into the catalog.