QueryCatalog

relationalai.agent.cortex.queries

QueryCatalog(*query_funcs: Callable, model: Optional[rai.Model] = None)

Query provider that registers Python functions as executable queries.

Extracts metadata from Python callables (functions, methods) including their docstrings, type annotations, and source code. This metadata is exposed to Cortex agents for query discovery, while the functions remain executable for query execution.

Query functions should follow these conventions:

1. Return type: Must return either rai.Fragment or pandas.DataFrame
2. Parameters: Can have any parameters with type annotations (recommended)
3. Docstring: Should include a clear description of what the query does
4. Function name: Will be used as the query ID (e.g., "top_customers") (the name "dynamic" is reserved for DynamicQueries)

Parameters

• *query_funcs

  (Callable, default: ()) - Variable number of Python callables to register as queries. The function name becomes the query id. The id "dynamic" is reserved for DynamicQueries.

• model

  (relationalai.semantics.Model, default: None) - When provided, the catalog also exposes a dynamic-query path backed by a DynamicQueries over the same model — the agent can author ad-hoc queries at runtime when no catalog query fits. Equivalent to wrapping the catalog in CompositeQueries(QueryCatalog(...), DynamicQueries(model)). Omitting model keeps catalog-only behavior.

Examples

Catalog-only:

from functools import partial


def top_customers(model, limit=10):
    return model.query(...)


queries = QueryCatalog(partial(top_customers, jaffle_model))

Catalog + dynamic queries (agent can also author ad-hoc specs):

queries = QueryCatalog(partial(top_customers, jaffle_model), model=jaffle_model)

Methods

.get_available_queries()

QueryCatalog.get_available_queries() -> dict

Return metadata for all registered queries.

Returns:

• dict - Dict with "queries", "query_instructions", and "query_mode" ("catalog" for a pure catalog, "dynamic" when the catalog was built with model=). The latter case also includes "schema" and "spec_format" from the embedded DynamicQueries.

.explain()

QueryCatalog.explain(query_id: str) -> Optional[str]

Return source code for a registered query by ID.

Parameters:

• query_id

  (str) - Unique identifier for the query to explain.

Returns:

• str or None - Source code string, or None if the query ID is not found.

.execute()

QueryCatalog.execute(query_id: str, args: dict) -> Union[rai.Fragment, pandas.DataFrame]

Execute a registered query by ID.

Parameters:

• query_id

  (str) - ID of the query to execute.

• args

  (dict) - Arguments to pass to the query function.

Returns:

• relationalai.semantics.Fragment or pandas.DataFrame - Query results.

Raises:

• KeyError - If query_id is not registered.

Inheritance Hierarchy