Queries

relationalai.agent.cortex.queries

Abstract base class for managing pre-defined RAI queries.

Queries provide a registry of pre-built query functions that Cortex agents can discover and execute. This allows domain experts to define common analytical queries that agents can use without writing RAI code.

Implement this interface to create custom query providers, or use QueryCatalog for standard Python function-based queries.

Methods

.get_available_queries()

Queries.get_available_queries() -> dict

Return metadata about available queries.

Returns:

• dict - Dictionary with the following keys:

  • queries: dict Mapping from a query ID to a query metadata dictionary. Each query metadata dictionary contains:

    • id: str Unique query identifier.
    • description: str Human-readable description of the query.
    • args: dict Mapping from parameter name to parameter type.

  • query_instructions: str Instructions describing how to use the catalog.

.explain()

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

Return source code for a query by ID, or None if not found.

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

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

Execute a specific query by ID with provided arguments.

Parameters:

• query_id

  (str) - Unique identifier for the query to execute (e.g., "top_customers").

• args

  (dict) - Dictionary mapping parameter names to values (e.g., {"limit": 5, "days": 30}).

Returns:

• Fragment | pandas.DataFrame - Query results.

Raises:

• KeyError - If the query_id is not found in registered queries.

Inheritance Hierarchy

Subclassed By

 agent > cortex > queries
└──  QueryCatalog

Used By

 agent > cortex > tool
├──  DefaultTool
└──  ToolRegistry
    └──  add