Query Data from the Real-Time Context Engine in Confluent Cloud

After you connect an AI agent to the Real-Time Context Engine, the agent uses MCP tools to discover topics, inspect schemas, and query data.

For setup instructions, see Get Started.

An AI agent should follow this workflow when querying the Real-Time Context Engine:

Call the list_topics tool to discover available topics.
Call the get_metadata tool for each relevant topic to learn column names and types.
Call the query_data tool to run queries against the topic.

The agent should call get_metadata before query_data to prevent errors from incorrect column names or types.

MCP tools

The Real-Time Context Engine exposes three MCP tools that an AI agent calls to discover and query topic data.

list_topics

Returns the list of topics that have the Real-Time Context Engine enabled and are visible to the agent. The list_topics tool takes no arguments.

The response includes the available topics and their descriptions.

get_metadata

Returns the schema and column metadata for a topic that has the Real-Time Context Engine enabled. The agent should call get_metadata before query_data to learn column names and types.

The agent passes the name of the topic to inspect.

The response includes column names, data types, and primary key information for the topic.

query_data

Runs a read-only SQL query against a topic that has the Real-Time Context Engine enabled. The agent passes the name of the topic to query and an SQL fragment that specifies the SELECT, WHERE, ORDER BY, and LIMIT clauses. The agent can also set the maximum number of rows to return. For default and maximum values, see Query limits.

The response includes the matching rows. If the query fails, the response includes an error code and message.

Example queries

The following examples show queries you can ask an AI agent that is connected to the Real-Time Context Engine. The agent translates each request into a read-only SQL query and returns the results.

“Look up order ORD-4521.”
“Show me all orders that haven’t been cancelled.”
“Which orders are pending or processing?”
“Find orders that haven’t shipped yet.”
“Find orders between $100 and $500.”
“Show me completed orders over $100, sorted by highest total.”
“What are the top 10 highest-value completed orders?”

The agent generates SQL to fulfill these requests. For example, asking for “completed orders over $100, sorted by highest total” produces a query like the following:

SELECT ORDER_ID, STATUS, TOTAL
FROM orders_topic
WHERE STATUS = 'completed' AND TOTAL > 100
ORDER BY TOTAL DESC
LIMIT 10

Supported SQL capabilities

The agent can use the following SQL capabilities when querying the Real-Time Context Engine:

Key lookups: Look up rows by primary key value.
Filters: Narrow results using equality (=), inequality (!=, >, <, >=, <=), set membership (IN, NOT IN), null checks (IS NULL, IS NOT NULL), pattern matching (LIKE, NOT LIKE), and range (BETWEEN).
Compound predicates: Combine multiple conditions with AND and OR.
Column selection: Select specific columns to reduce response size, or select all columns.
Ordering: Sort results in ascending or descending order.
Row limits: Control the number of rows returned. For default and maximum values, see Query limits.

Query limits

The Real-Time Context Engine enforces the following limits on queries:

Limit	Value
Default rows returned (when LIMIT is not specified)	100
Maximum rows returned	200
Query timeout (seconds)	20

Rate limits also apply. If the agent exceeds the rate limit, the Real-Time Context Engine returns a RATE_LIMIT_EXCEEDED error.

Unsupported queries

The Real-Time Context Engine supports read-only queries only. The following operations are not supported:

Aggregates (COUNT, SUM, AVG, MIN, MAX)
GROUP BY
Joins
Subqueries
Set operations (UNION, EXCEPT, INTERSECT)
DDL statements (CREATE, ALTER, DROP)
DML statements (INSERT, UPDATE, DELETE)

Unsupported queries are rejected without execution.