# 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](get-started.md#rtce-get-started). An AI agent should follow this workflow when querying the Real-Time Context Engine: 1. Call the `listTopics` tool to discover available topics. 2. Call the `getMetadata` tool for each relevant topic to learn column names and types. 3. Call the `queryData` tool to run queries against the topic. The agent should call `getMetadata` before `queryData` 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. ### listTopics Returns the list of topics that have the Real-Time Context Engine enabled and are visible to the agent. The `listTopics` tool takes no arguments. The response includes the available topics and their descriptions. ### getMetadata Returns the schema and column metadata for a topic that has the Real-Time Context Engine enabled. The agent should call `getMetadata` before `queryData` 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. ### queryData 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](#rtce-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: ```sql 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](#rtce-query-limits). ## Query limits The Real-Time Context Engine enforces the following limits on queries: | Limit | Value | |-------------------------|---------| | Maximum rows returned | 200 | | Query timeout (seconds) | 20 | The `max_result_rows` parameter is required on every `queryData` call. Setting it to 0 or omitting it returns an error. The SQL `LIMIT` clause can further reduce the result set, but can’t exceed the `max_result_rows` cap. 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. ## Related content - [Get Started](get-started.md#rtce-get-started) - Set up and run your first query. - [Manage Topics](manage-topics.md#rtce-manage-topics) - Enable, disable, and configure topics. #### NOTE This website includes content developed at the [Apache Software Foundation](https://www.apache.org/) under the terms of the [Apache License v2](https://www.apache.org/licenses/LICENSE-2.0.html).