QueryCatalog

relationalai.agent.cortex.queries

QueryCatalog(*query_funcs: Callable)

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")

Parameters

• *query_funcs

  (Callable, default: ()) - Variable number of Python callables to register as queries.

Examples

>>> from functools import partial
>>> def top_customers(model, limit=10):
...     return model.query(...)
>>> queries = QueryCatalog(partial(top_customers, jaffle_model))

Methods

.get_available_queries()

QueryCatalog.get_available_queries() -> dict

Return metadata for all registered queries.

Returns:

• dict - Dict with "queries" and "query_instructions" keys.

.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