Docs

Daita agents / guide

Catalog

Inspect the authoritative current structure, relationships, revisions, and freshness of attached data sources.

#Authority

The catalog is authoritative for current source and resource identity, schemas, facets, relationships, sensitivity, and freshness. It is not a plugin and does not contain query results 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

python
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

python
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

python
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

python
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 source structure or local files change. Query and file backends recheck live revisions; stale resources fail safely rather than executing against structure that differs from the committed catalog.