aliehsaeedii commented on code in PR #21367:
URL: https://github.com/apache/kafka/pull/21367#discussion_r2746585595
##########
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()) {
+ // Handle query failures
+ result.getFailures().forEach((host, failure) ->
+ System.out.println("Query failed on " + host + ": " + failure)
+ );
+ } else {
+ // Get the successful query result
+ Long value = result.getResult();
+ System.out.println("Query result: " + value);
+ }
+
+## Comparison : Interactive Queries (IQv1) and (IQv2)
+
+| **Aspects** | **Interactive Queries v1 (Legacy API)** | **Interactive
Queries v2 (New API)** |
+|-------------|-----------------------------------------|--------------------------------------|
+| API Style | Store-based API |
Query-based API |
+| How queries are defined | Direct access to state store
objects | Explicit query objects (e.g.,
KeyQuery) |
+| Interaction with state stores | Application interacts
directly with store internals |
Kafka Streams executes queries on behalf of the application
|
+| Result handling | Results returned directly or via
iterators | Results wrapped in
StateQueryResult |
+| Error handling | Exception-based
| Structured failures returned with results
|
+| Coupling to store implementation | Tightly coupled
to store types | Decoupled from store
internals |
+| Extensibility | Harder to evolve without breaking changes
| Designed to be extensible and future-proof
|
+| Partial failure visibility | Limited
| Explicit visibility into per-host failures
|
+| Feature completeness | Feature complete and stable
| Not yet feature complete
|
+
+## Limitations of Interactive Queries v2
+
+Interactive Queries v2 is not yet feature complete.
+
+**Some advanced query patterns available in the original Interactive Queries
API may not yet be supported.
+The API is expected to evolve, and user feedback will guide future
improvements.**
+
+
* [Documentation](/documentation)
* [Kafka Streams](/documentation/streams)
* [Developer Guide](/documentation/streams/developer-guide/)
Review Comment:
h
##########
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()) {
+ // Handle query failures
+ result.getFailures().forEach((host, failure) ->
+ System.out.println("Query failed on " + host + ": " + failure)
+ );
+ } else {
+ // Get the successful query result
+ Long value = result.getResult();
+ System.out.println("Query result: " + value);
+ }
+
+## Comparison : Interactive Queries (IQv1) and (IQv2)
+
+| **Aspects** | **Interactive Queries v1 (Legacy API)** | **Interactive
Queries v2 (New API)** |
+|-------------|-----------------------------------------|--------------------------------------|
+| API Style | Store-based API |
Query-based API |
+| How queries are defined | Direct access to state store
objects | Explicit query objects (e.g.,
KeyQuery) |
+| Interaction with state stores | Application interacts
directly with store internals |
Kafka Streams executes queries on behalf of the application
|
+| Result handling | Results returned directly or via
iterators | Results wrapped in
StateQueryResult |
+| Error handling | Exception-based
| Structured failures returned with results
|
+| Coupling to store implementation | Tightly coupled
to store types | Decoupled from store
internals |
+| Extensibility | Harder to evolve without breaking changes
| Designed to be extensible and future-proof
|
+| Partial failure visibility | Limited
| Explicit visibility into per-host failures
|
+| Feature completeness | Feature complete and stable
| Not yet feature complete
|
+
+## Limitations of Interactive Queries v2
+
+Interactive Queries v2 is not yet feature complete.
+
+**Some advanced query patterns available in the original Interactive Queries
API may not yet be supported.
+The API is expected to evolve, and user feedback will guide future
improvements.**
+
+
* [Documentation](/documentation)
* [Kafka Streams](/documentation/streams)
* [Developer Guide](/documentation/streams/developer-guide/)
Review Comment:
h
--
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]
