aliehsaeedii commented on code in PR #21367: URL: https://github.com/apache/kafka/pull/21367#discussion_r2746431220
########## docs/streams/developer-guide/interactive-queries.md: ########## @@ -486,9 +486,106 @@ At this point the full state of the application is interactively queryable: * Collectively, this allows us to query the full state of the entire application. +## Interactive Queries APIs +Kafka Streams currently provides two APIs for querying state: + +- **Interactive Queries v2 (IQv2)** – the newer, query-based API +- **Interactive Queries v1 (IQv1)** – the original, store-access-based API + +This documentation introduces **Interactive Queries v2** as the **new API**, while retaining IQv1 for backward compatibility. + + +**Interactive Queries v2 (IQv2)** introduces a **query-based API** for accessing Kafka Streams application state. +Instead of directly interacting with state store objects, applications **define structured queries** that are executed by Kafka Streams. + +IQv2 improves API safety, extensibility, and error handling by: + +- Decoupling query definition from store internals +- Returning structured query results instead of throwing exceptions +- Enabling clearer handling of partial failures in distributed environments + +Queries are executed against local state stores on an application instance, with Kafka Streams managing: + +- Query execution +- Validation +- Result and failure reporting + +IQv2 is designed to evolve independently of specific state store implementations and serves as the **successor to the legacy Interactive Queries v1 API.** + +## How Interactive Queries v2 Works + +Interactive Queries v2 works by allowing applications to **define explicit query objects** that describe what data to fetch from a state store. +These queries are submitted to Kafka Streams, which is responsible for **executing the query,** handling validation, and returning a **structured result.** + +Instead of exposing state store internals, Kafka Streams processes the query and returns a **StateQueryResult**, which may contain either the requested data or detailed failure information. +This approach makes querying state safer, more extensible, and better suited for distributed environments. To see an end-to-end application with interactive queries, review the demo applications. +## Building and Executing a Query (IQv2) + +In Interactive Queries v2, applications first **build a query object** that describes the data to retrieve from a specific state store (for example, a key lookup or range query). +This query is wrapped in a **StateQueryRequest**, which also specifies the target state store. + +Once the request is created, it is executed using the **KafkaStreams#query()** method. +Kafka Streams validates the request, executes the query against the appropriate local state store, and returns a **StateQueryResult** containing either the query result or failure details. + +This separation of **query construction** and **query execution** allows Kafka Streams to manage execution logic while keeping application code clean and extensible. + +1. **Build the Query** + + ``` + // Build a query to fetch the value for a specific key + StateQueryRequest<KeyQuery<String, Long>> request = Review Comment: Did you run this test? It needs to be `StateQueryRequest<Long>` -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
