mjsax commented on a change in pull request #11114:
URL: https://github.com/apache/kafka/pull/11114#discussion_r675707618
##########
File path: docs/streams/upgrade-guide.html
##########
@@ -135,25 +135,30 @@ <h3><a id="streams_api_changes_300"
href="#streams_api_changes_300">Streams API
We removed the default implementation of
<code>RocksDBConfigSetter#close()</code>.
</p>
<p>
- We dropped the default 24 hours grace period for windowed operations
such as Window or Session aggregates, or stream-stream joins.
- This period determines how long after a window ends any out-of-order
records will still be processed.
- Records coming in after the grace period has elapsed will be dropped
from those windows.
- With a long grace period, though Kafka Streams can handle out-of-order
data up to that amount of time, it will also incur a high and confusing latency
for users,
- e.g. suppression operators with the default won't emit results up for
24 hours, while in practice out-of-order data usually has a much smaller
time-skewness.
- Instead of abstracting this config from users with a long default
value, we introduced new constructs such as
<code>TimeWindows#ofSizeAndGrace</code> to let callers always set it upon
constructing the windows;
- the other setters such as <code>TimeWindows#grace</code> are
deprecated and will be removed in the future.
+ We dropped the default 24 hours grace period for windowed operations
such as Window or Session aggregates, or
+ stream-stream joins. This period determines how long after a window
ends any out-of-order records will still
+ be processed. Records coming in after the grace period has elapsed are
considered late and will be dropped.
+ But in operators such as suppression, a large grace period has the
drawback of incurring an equally large
+ output latency. The current API made it all too easy to miss the grace
period config completely, leading you
+ to wonder why your application seems to produce no output -- it
actually is, but not for 24 hours.
+ <p>
+ To prevent accidentally or unknowingly falling back to the default
24hr grace period, we deprecated all of the
+ existing static constructors for the <code>indows</code> classes (such
as <code>TimeWindows#of</code>). These
+ are replaced by new static constructors of two flavors:
<code>#ofSizeAndGrace</code> and <code>#ofSizeWithNoGrace</code>
+ (these are for the <code>TimeWindows</code> class; analogous APIs
exist for the <code>JoinWindows</code>,
Review comment:
For JoinWindows and left/outer join, we also enable the spurious result
fix (as pointed out in the next paragraph -- might be good to call out here,
too, by referring to the next paragraph).
--
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: jira-unsubscr...@kafka.apache.org
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org
