From dac6e38132f924ebef1b38f0e323d36ba6d13eac Mon Sep 17 00:00:00 2001 From: Jim Galasyn Date: Thu, 19 Aug 2021 13:08:37 -0700 Subject: [PATCH] Revert GRACE keyword in Joins (#8020) (#8027) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Sergio Peña --- .../create-stream-as-select.md | 5 +-- .../ksqldb-reference/insert-into.md | 5 +-- .../ksqldb-reference/quick-reference.md | 19 ++++------- .../ksqldb-reference/select-push-query.md | 33 ++----------------- 4 files changed, 11 insertions(+), 51 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 index 4c07ed3a416..aaf30a2770a 100644 --- a/docs/developer-guide/ksqldb-reference/create-stream-as-select.md +++ b/docs/developer-guide/ksqldb-reference/create-stream-as-select.md @@ -13,10 +13,7 @@ CREATE [OR REPLACE] STREAM stream_name [WITH ( property_name = expression [, ...] )] AS SELECT select_expr [, ...] FROM from_stream - [[ LEFT | FULL | INNER ] - JOIN [join_table | join_stream] - [WITHIN [ | ( , )] [GRACE PERIOD ]] - ON join_criteria]* + [[ LEFT | FULL | INNER ] JOIN [join_table | join_stream] [ WITHIN [(before TIMEUNIT, after TIMEUNIT) | N TIMEUNIT] ] ON join_criteria]* [ WHERE condition ] [PARTITION BY column_name] EMIT CHANGES; diff --git a/docs/developer-guide/ksqldb-reference/insert-into.md b/docs/developer-guide/ksqldb-reference/insert-into.md index d60043dfe50..8d761f48e7b 100644 --- a/docs/developer-guide/ksqldb-reference/insert-into.md +++ b/docs/developer-guide/ksqldb-reference/insert-into.md @@ -16,10 +16,7 @@ Synopsis INSERT INTO stream_name SELECT select_expr [, ...] FROM from_stream - [ LEFT | FULL | INNER ] - JOIN [join_table | join_stream] - [WITHIN [ | ( , )] [GRACE PERIOD ]] - ON join_criteria + [ LEFT | FULL | INNER ] JOIN [join_table | join_stream] [ WITHIN [(before TIMEUNIT, after TIMEUNIT) | N TIMEUNIT] ] ON join_criteria [ WHERE condition ] [ PARTITION BY new_key_expr [, ...] ] EMIT CHANGES; diff --git a/docs/developer-guide/ksqldb-reference/quick-reference.md b/docs/developer-guide/ksqldb-reference/quick-reference.md index 74a9bf5c77e..ec259f491d1 100644 --- a/docs/developer-guide/ksqldb-reference/quick-reference.md +++ b/docs/developer-guide/ksqldb-reference/quick-reference.md @@ -168,10 +168,9 @@ CREATE STREAM stream_name [WITH ( property_name = expression [, ...] )] AS SELECT select_expr [, ...] FROM from_stream - [[ LEFT | FULL | INNER ] - JOIN [join_table | join_stream] - [WITHIN [ | ( , )] [GRACE PERIOD ]] - ON join_criteria]* + [[ LEFT | FULL | INNER ] JOIN [join_table | join_stream] + [ WITHIN [(before TIMEUNIT, after TIMEUNIT) | N TIMEUNIT] ] + ON join_criteria]* [ WHERE condition ] [PARTITION BY new_key_expr [, ...]] EMIT CHANGES; @@ -387,10 +386,9 @@ Stream the result of a SELECT query into an existing stream and its underlying INSERT INTO stream_name SELECT select_expr [, ...] FROM from_stream - [ LEFT | FULL | INNER ] - JOIN [join_table | join_stream] - [WITHIN [ | ( , )] [GRACE PERIOD ]] - ON join_criteria + [ LEFT | FULL | INNER ] JOIN [join_table | join_stream] + [ WITHIN [(before TIMEUNIT, after TIMEUNIT) | N TIMEUNIT] ] + ON join_criteria [ WHERE condition ] [ PARTITION BY new_key_expr [, ...] ] EMIT CHANGES; @@ -488,10 +486,7 @@ information, see [SELECT (Push Query)](../../ksqldb-reference/select-push-query) ```sql SELECT select_expr [, ...] FROM from_item - [[ LEFT | FULL | INNER ] - JOIN join_item - [WITHIN [ | ( , )] [GRACE PERIOD ]] - ON join_criteria]* + [[ LEFT | FULL | INNER ] JOIN join_item ON [ WITHIN [(before TIMEUNIT, after TIMEUNIT) | N TIMEUNIT] ] join_criteria]* [ WINDOW window_expression ] [ WHERE condition ] [ GROUP BY grouping_expression [, ...] ] diff --git a/docs/developer-guide/ksqldb-reference/select-push-query.md b/docs/developer-guide/ksqldb-reference/select-push-query.md index 98b7534fa75..72e664c36b5 100644 --- a/docs/developer-guide/ksqldb-reference/select-push-query.md +++ b/docs/developer-guide/ksqldb-reference/select-push-query.md @@ -11,10 +11,7 @@ keywords: ksqlDB, select, push query ```sql SELECT select_expr [, ...] FROM from_item - [[ LEFT | FULL | INNER ] - JOIN join_item - [WITHIN [ | ( , )] [GRACE PERIOD ]] - ON join_criteria]* + [[ LEFT | FULL | INNER ] JOIN join_item ON [ WITHIN [(before TIMEUNIT, after TIMEUNIT) | N TIMEUNIT] ] join_criteria]* [ WINDOW window_expression ] [ WHERE where_condition ] [ GROUP BY grouping_expression ] @@ -211,7 +208,7 @@ SELECT windowstart, windowend, item_id, SUM(quantity) EMIT CHANGES; ``` -#### WITHIN and GRACE PERIOD +#### WITHIN !!! note Stream-Stream joins must have a WITHIN clause specified. @@ -236,32 +233,6 @@ 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 out-of-order records for up -to the specified grace period. Events that arrive after the grace period has passed are dropped -as _late_ records and not joined. - -```sql - CREATE STREAM shipped_orders AS - SELECT - o.id as orderId - o.itemid as itemId, - s.id as shipmentId, - p.id as paymentId - FROM orders o - INNER JOIN payments p WITHIN 1 HOURS GRACE PERIOD 15 MINUTES ON p.id = o.id - INNER JOIN shipments s WITHIN 2 HOURS GRACE PERIOD 15 MINUTES ON s.id = o.id; -``` - -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. - -!!! important - 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. - #### Out-of-order events Accept events for up to two hours after the window ends. Events that arrive