ableegoldman commented on a change in pull request #9264: URL: https://github.com/apache/kafka/pull/9264#discussion_r485314713
########## File path: docs/streams/developer-guide/dsl-api.html ########## @@ -3286,13 +3306,33 @@ <h5><a class="toc-backref" href="#id34">KTable-KTable Foreign-Key <div class="section" id="sliding-time-windows"> <span id="windowing-sliding"></span><h5><a class="toc-backref" href="#id22">Sliding time windows</a><a class="headerlink" href="#sliding-time-windows" title="Permalink to this headline"></a></h5> <p>Sliding windows are actually quite different from hopping and tumbling windows. In Kafka Streams, sliding windows - are used only for <a class="reference internal" href="#streams-developer-guide-dsl-joins"><span class="std std-ref">join operations</span></a>, and can be specified through the - <code class="docutils literal"><span class="pre">JoinWindows</span></code> class.</p> - <p>A sliding window models a fixed-size window that slides continuously over the time axis; here, two data records are + are used for <a class="reference internal" href="#streams-developer-guide-dsl-joins"><span class="std std-ref">join operations</span></a>, specified by using the + <code class="docutils literal"><span class="pre">JoinWindows</span></code> class, and windowed aggregations, specified by using the code class="docutils literal"><span class="pre">SlidingWindows</span></code> class.</p> Review comment: ```suggestion <code class="docutils literal"><span class="pre">JoinWindows</span></code> class, and windowed aggregations, specified by using the <code class="docutils literal"><span class="pre">SlidingWindows</span></code> class.</p> ``` ########## File path: docs/streams/developer-guide/dsl-api.html ########## @@ -3286,13 +3306,33 @@ <h5><a class="toc-backref" href="#id34">KTable-KTable Foreign-Key <div class="section" id="sliding-time-windows"> <span id="windowing-sliding"></span><h5><a class="toc-backref" href="#id22">Sliding time windows</a><a class="headerlink" href="#sliding-time-windows" title="Permalink to this headline"></a></h5> <p>Sliding windows are actually quite different from hopping and tumbling windows. In Kafka Streams, sliding windows - are used only for <a class="reference internal" href="#streams-developer-guide-dsl-joins"><span class="std std-ref">join operations</span></a>, and can be specified through the - <code class="docutils literal"><span class="pre">JoinWindows</span></code> class.</p> - <p>A sliding window models a fixed-size window that slides continuously over the time axis; here, two data records are + are used for <a class="reference internal" href="#streams-developer-guide-dsl-joins"><span class="std std-ref">join operations</span></a>, specified by using the + <code class="docutils literal"><span class="pre">JoinWindows</span></code> class, and windowed aggregations, specified by using the code class="docutils literal"><span class="pre">SlidingWindows</span></code> class.</p> + <p>A sliding window models a fixed-size window that slides continuously over the time axis. In this model, two data records are said to be included in the same window if (in the case of symmetric windows) the difference of their timestamps is - within the window size. Thus, sliding windows are not aligned to the epoch, but to the data record timestamps. In - contrast to hopping and tumbling windows, the lower and upper window time interval bounds of sliding windows are - <em>both inclusive</em>.</p> + within the window size. As a sliding window moves along the time axis, records may fall into multiple snapshots of + the sliding window, but each unique combination of records appears only in one sliding window snapshot.</p> + <p>The following code defines a sliding window with a time difference of 10 minutes and a grace period of 30 minutes:</p> + <div class="highlight-java"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">org.apache.kafka.streams.kstream.SlidingWindows</span><span class="o">;</span> + +<span class="c1">// A sliding time window with a time difference of 10 minutes and grace period of 30 minutes</span> +<span class="kt">Duration</span> <span class="n">timeDifferenceMs</span> <span class="o">=</span> <span class="n">Duration</span><span class="o">.</span><span class="na">ofMinutes</span><span class="o">(</span><span class="mi">10</span><span class="o">);</span> +<span class="kt">Duration</span> <span class="n">gracePeriodMs</span> <span class="o">=</span> <span class="n">Duration</span><span class="o">.</span><span class="na">ofMinutes</span><span class="o">(</span><span class="mi">30</span><span class="o">);</span> +<span class="n">SlidingWindows</span><span class="o">.</span><span class="na">withTimeDifferenceAndGrace</span><span class="o">(</span><span class="n">timeDifferenceMs</span><span class="o">,</span><span class="n">gracePeriodMs</span><span class="o">);</span> +</pre></div> + <div class="admonition note"> + <p><b>Note</b></p> + <p>Sliding windows <em>require</em> that you set a grace period, as shown above. For time windows and session windows, + setting the grace period is optional and defaults to 24 hours.</p> + </div> + <div class="figure align-center" id="id35"> + <img class="centered" src="/{{version}}/images/streams-sliding-windows.png"> + <p class="caption"><span class="caption-text">This diagram shows windowing a stream of data records with sliding windows. The overlap of + the sliding window snapshots varies depending on the record times. In this diagram, the time numbers represent miliseconds. For example, + t=5 means “at the five milisecond mark”.</span></p> Review comment: I rendered the site locally and there's something weird going on here. Seems like you can't use literal `"`. Look at what the other captions do, seems like it might be `“` ---------------------------------------------------------------- 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. For queries about this service, please contact Infrastructure at: us...@infra.apache.org