aliehsaeedii commented on code in PR #21367:
URL: https://github.com/apache/kafka/pull/21367#discussion_r2746478072
##########
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 =
+ StateQueryRequest.inStore("counts-store")
+ .withQuery(KeyQuery.withKey("user-1"));
+
+Here:
+
+- `"counts-store"` is the name of the state store.
+- `"user-1"` is the key you want to query.
+- `KeyQuery` defines what kind of query you are performing.
+
+2. **Execute the Query**
+ ```
+ StateQueryResult<Long> result = kafkaStreams.query(request);
+Kafka Streams executes the query against the local state store and returns a
result object.
+
+3. **Read the Result**
+ ```
+ if (result.hasFailures()) {
Review Comment:
`StateQueryResult` (`result`) does not provide these methods. First obtain a
`QueryResult` object by calling one of the getPartitions... methods, and then
invoke the methods on that object. Please verify this with a real example
before posting the code. Thanks.
--
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]
