This page is meant as a template for writing a KIP. To create a KIP choose Tools->Copy on this page and modify with your content and replace the heading with the next KIP number and a description of your issue. Replace anything in italics with your own description.
Current state: Accpted
Please keep the discussion on the mailing list rather than commenting on the wiki (wiki discussions get unwieldy fast).
In the current IQv2 code, there are noticeable differences when interfacing with
ts-kv-store . Notably, the return type
V acts as a simple value for
kv-store but evolves into
ts-kv-store , which presents type safety issues in the API.
Before the introduction of
TimestampedKeyQuery , when using
KeyQuery , we obtained the result using the following code:
This meant that the returned result could be of two potential data types: plain
ValueAndTimestamp<V> . This was a source of inconsistency. For instance, querying a
KeyQuery would return a
V type, but querying a
ts-kv-store would yield a
ValueAndTimestamp<V> . This behavior is unintuitive and potentially confusing for developers.
To ensure consistency, we suggest that KeyQuery always return the plain V type, enhancing the predictability of the mentioned code. Likewise, RangeQuery should uniformly return the plain V KeyValueIterator.
For those requiring timestamped values from a
ts-kv-store , we recommend introducing a new query type:
TimestampedKeyQuery . This new query will specifically target
ts-kv-stores and will return
ValueAndTimestamp<V> . Furthermore, to complement this,
TimestampedRangeQuery should be introduced to query ranges in
ts-kv-stores , ensuring that the returned value always includes timestamps.
TimestampedRangeQuery ? The primary motivation behind this is to ensure type safety and foster a clear distinction in our API. They bridge the difference between simple key-value stores and those integrated with timestamps, offering a more robust and intuitive querying mechanism.
Within the current IQv2 codebase, there have been distinct interactions between plain-kv-store and ts-kv-store. These differences, especially in return types, have raised concerns over type safety within the API.
To address these challenges and streamline the querying experience, we have decided to refine our approach and introduce two specialized query types:
TimestampedKeyQuery : This query type will consistently return
ValueAndTimestamp<V> , ensuring that there's a clear and predictable return type associated with timestamped key-value stores.
TimestampedRangeQuery : Tailored for ranges with timestamps, this query will return a
According to KIP-968, this KIP introduces the public enum ResultOrder to determine whether keys are sorted in ascending or descending or unordered order. Order is based on the serialized byte of the keys, not the 'logical' key order. employs the
withDescendingKeys() and withAscendingKeys() methods to specify that the keys should be ordered in descending or ascending or unordered sequence, and the resultOrder() method to retrieve the value of enum value in ResultOrder. I've incorporated these variables and methods into the
TimestampedRangeQuery class and modified some method inputs. As a result, we can now use
withDescendingKeys() to obtain results in reverse order and use withAscendingKeys to obtain the result in ascending order.
According to KIP-968, we introduce a public enum ResultOrder.
It helps with specifying the order of the returned results by the query.
Compatibility, Deprecation, and Migration Plan
- Changing the semantics of existing
RangeQueryis a breaking change. However, both classes are marked as
@Evolving`and thus a breaking change in a minor release is allowed without a deprecation period. Given that IQv2 is not yet widely adopted, we believe it’s cleaner to make this breaking change right away.
- Adding new query types does not imply any compatibility concerns.
To ensure the robustness and accuracy of our new query types,
TimestampedRangeQuery , it's essential to have thorough test coverage. With that in mind, we propose the creation of two specific test methods:
shouldHandleTimestampedKeyQuery : This test method will validate the functionality of
TimestampedKeyQuery , ensuring it consistently returns
ValueAndTimestamp<V> as expected.
shouldHandleTimestampedRangeQuery : This method is tailored to verify the
TimestampedRangeQuery , ensuring that it correctly returns a
KeyValueIterator<K, ValueAndTimestamp<V>> .
We will focus on conducting a detailed test for
The alternative would be to deprecate the existing
RangeQuery and add new query types that always return plain value. However, it seems to introduce unnecessary “deprecation noise”, and it would be hard to find good names for these newly added query types. Making a semantics change on the existing queries allows us to keep the existing names.