docs: fix accidental commas and add extre note to GRACE PERIOD syntax (…

…#7706)
confluentinc · Jun 23, 2021 · 1823c0d · 1823c0d
1 parent 18cc030
commit 1823c0d
Show file tree

Hide file tree

Showing 4 changed files with 20 additions and 11 deletions.
diff --git a/docs/developer-guide/ksqldb-reference/create-stream-as-select.md b/docs/developer-guide/ksqldb-reference/create-stream-as-select.md
@@ -15,7 +15,7 @@ CREATE [OR REPLACE] STREAM stream_name
   FROM from_stream
   [[ LEFT | FULL | INNER ]
       JOIN [join_table | join_stream]
-          [WITHIN [<size> <timeunit> | (<before_size> <timeunit>, <after_size> <timeunit>)] [, GRACE PERIOD <grace_size> <timeunit>]]
+          [WITHIN [<size> <timeunit> | (<before_size> <timeunit>, <after_size> <timeunit>)] [GRACE PERIOD <grace_size> <timeunit>]]
       ON join_criteria]*
   [ WHERE condition ]
   [PARTITION BY column_name]

diff --git a/docs/developer-guide/ksqldb-reference/insert-into.md b/docs/developer-guide/ksqldb-reference/insert-into.md
@@ -18,7 +18,7 @@ INSERT INTO stream_name
   FROM from_stream
   [ LEFT | FULL | INNER ]
       JOIN [join_table | join_stream]
-        [WITHIN [<size> <timeunit> | (<before_size> <timeunit>, <after_size> <timeunit>)] [, GRACE PERIOD <grace_size> <timeunit>]]
+        [WITHIN [<size> <timeunit> | (<before_size> <timeunit>, <after_size> <timeunit>)] [GRACE PERIOD <grace_size> <timeunit>]]
       ON join_criteria
   [ WHERE condition ]
   [ PARTITION BY new_key_expr [, ...] ]

diff --git a/docs/developer-guide/ksqldb-reference/quick-reference.md b/docs/developer-guide/ksqldb-reference/quick-reference.md
@@ -170,7 +170,7 @@ CREATE STREAM stream_name
   FROM from_stream
   [[ LEFT | FULL | INNER ]
     JOIN [join_table | join_stream]
-      [WITHIN [<size> <timeunit> | (<before_size> <timeunit>, <after_size> <timeunit>)] [, GRACE PERIOD <grace_size> <timeunit>]]
+      [WITHIN [<size> <timeunit> | (<before_size> <timeunit>, <after_size> <timeunit>)] [GRACE PERIOD <grace_size> <timeunit>]]
     ON join_criteria]*
   [ WHERE condition ]
   [PARTITION BY new_key_expr [, ...]]
@@ -372,7 +372,7 @@ INSERT INTO stream_name
   FROM from_stream
   [ LEFT | FULL | INNER ]
       JOIN [join_table | join_stream]
-        [WITHIN [<size> <timeunit> | (<before_size> <timeunit>, <after_size> <timeunit>)] [, GRACE PERIOD <grace_size> <timeunit>]]
+        [WITHIN [<size> <timeunit> | (<before_size> <timeunit>, <after_size> <timeunit>)] [GRACE PERIOD <grace_size> <timeunit>]]
       ON join_criteria
   [ WHERE condition ]
   [ PARTITION BY new_key_expr [, ...] ]
@@ -490,7 +490,7 @@ SELECT select_expr [, ...]
   FROM from_item
   [[ LEFT | FULL | INNER ]
       JOIN join_item
-        [WITHIN [<size> <timeunit> | (<before_size> <timeunit>, <after_size> <timeunit>)] [, GRACE PERIOD <grace_size> <timeunit>]]
+        [WITHIN [<size> <timeunit> | (<before_size> <timeunit>, <after_size> <timeunit>)] [GRACE PERIOD <grace_size> <timeunit>]]
       ON join_criteria]*
   [ WINDOW window_expression ]
   [ WHERE condition ]

diff --git a/docs/developer-guide/ksqldb-reference/select-push-query.md b/docs/developer-guide/ksqldb-reference/select-push-query.md
@@ -17,7 +17,7 @@ SELECT select_expr [, ...]
   FROM from_item
   [[ LEFT | FULL | INNER ]
     JOIN join_item
-        [WITHIN [<size> <timeunit> | (<before_size> <timeunit>, <after_size> <timeunit>)] [, GRACE PERIOD <grace_size> <timeunit>]]
+        [WITHIN [<size> <timeunit> | (<before_size> <timeunit>, <after_size> <timeunit>)] [GRACE PERIOD <grace_size> <timeunit>]]
     ON join_criteria]*
   [ WINDOW window_expression ]
   [ WHERE where_condition ]
@@ -218,14 +218,23 @@ the order was placed, and shipped within 2 hours of the payment being received.
         INNER JOIN shipments s WITHIN 2 HOURS ON s.id = o.id;
 ```
 
-The GRACE PERIOD, part of the WITHIN clause, allows the join to process late records for up
+The GRACE PERIOD, part of the WITHIN clause, allows the join to process out-of-order records for up
 to the specified grace period. Events that arrive after the grace period has passed are dropped
-and not joined with older records.
+as _late_ records and not joined.
 
-The default grace period, if not used in the join, is 24 hours. This could cause a huge amount
-of disk usage on high-throughput streams. Setting a specific GRACE PERIOD is recommended to
+If you don't specify a grace period explicitly, the default grace period is 24 hours. This could
+cause a huge amount of disk usage on high-throughput streams. Setting a specific GRACE PERIOD is
+recommended to reduce high disk usage.
+
+!!! note
+    If you specify a GRACE PERIOD for left/outer joins, the grace period defines when the left/outer
+
+    join result is emitted. If you don't specify a GRACE PERIOD for left/outer joins,
+
+    left/outer join results are emitted eagerly, which may cause "spurious" result records, so
+
+    we recommended that you specify a GRACE PERIOD.
 
-reduce high disk usage.
 
 ```sql
    CREATE STREAM shipped_orders AS