Docs and better error for exactly once join (#9374)

Co-authored-by: Sergey <[email protected]>
GitOrigin-RevId: 4278479143415f75ceddb0e20dcde6eeae6fd0b0

Author: 2 people

python/pathway/internals/joins.py

@@ -157,9 +157,11 @@ def join(
             left_exactly_once: if you can guarantee that each row on the left side of the join will be
               joined at most once, then you can set this parameter to ``True``. Then each row after
               getting a match is removed from the join state. As a result, less memory is needed.
+              Works only for append-only tables.
             right_exactly_once: if you can guarantee that each row on the right side of the join will be
               joined at most once, then you can set this parameter to ``True``. Then each row after
               getting a match is removed from the join state. As a result, less memory is needed.
+              Works only for append-only tables.
 
         Returns:
             JoinResult: an object on which `.select()` may be called to extract relevant
@@ -224,9 +226,11 @@ def join_inner(
             left_exactly_once: if you can guarantee that each row on the left side of the join will be
               joined at most once, then you can set this parameter to ``True``. Then each row after
               getting a match is removed from the join state. As a result, less memory is needed.
+              Works only for append-only tables.
             right_exactly_once: if you can guarantee that each row on the right side of the join will be
               joined at most once, then you can set this parameter to ``True``. Then each row after
               getting a match is removed from the join state. As a result, less memory is needed.
+              Works only for append-only tables.
 
         Returns:
             JoinResult: an object on which `.select()` may be called to extract relevant
@@ -291,9 +295,11 @@ def join_left(
             left_exactly_once: if you can guarantee that each row on the left side of the join will be
               joined at most once, then you can set this parameter to ``True``. Then each row after
               getting a match is removed from the join state. As a result, less memory is needed.
+              Works only for append-only tables.
             right_exactly_once: if you can guarantee that each row on the right side of the join will be
               joined at most once, then you can set this parameter to ``True``. Then each row after
               getting a match is removed from the join state. As a result, less memory is needed.
+              Works only for append-only tables.
 
         Remarks:
         args cannot contain id column from either of tables, \
@@ -378,9 +384,11 @@ def join_right(
             left_exactly_once: if you can guarantee that each row on the left side of the join will be
               joined at most once, then you can set this parameter to ``True``. Then each row after
               getting a match is removed from the join state. As a result, less memory is needed.
+              Works only for append-only tables.
             right_exactly_once: if you can guarantee that each row on the right side of the join will be
               joined at most once, then you can set this parameter to ``True``. Then each row after
               getting a match is removed from the join state. As a result, less memory is needed.
+              Works only for append-only tables.
 
         Remarks: args cannot contain id column from either of tables, \
         as the result table has id column with auto-generated ids; \
@@ -466,9 +474,11 @@ def join_outer(
             left_exactly_once: if you can guarantee that each row on the left side of the join will be
               joined at most once, then you can set this parameter to ``True``. Then each row after
               getting a match is removed from the join state. As a result, less memory is needed.
+              Works only for append-only tables.
             right_exactly_once: if you can guarantee that each row on the right side of the join will be
               joined at most once, then you can set this parameter to ``True``. Then each row after
               getting a match is removed from the join state. As a result, less memory is needed.
+              Works only for append-only tables.
 
         Remarks: args cannot contain id column from either of tables, \
             as the result table has id column with auto-generated ids; \
@@ -1184,9 +1194,11 @@ def join(
         left_exactly_once: if you can guarantee that each row on the left side of the join will be
             joined at most once, then you can set this parameter to ``True``. Then each row after
             getting a match is removed from the join state. As a result, less memory is needed.
+            Works only for append-only tables.
         right_exactly_once: if you can guarantee that each row on the right side of the join will be
             joined at most once, then you can set this parameter to ``True``. Then each row after
             getting a match is removed from the join state. As a result, less memory is needed.
+            Works only for append-only tables.
 
     Returns:
         JoinResult: an object on which `.select()` may be called to extract relevant
@@ -1249,9 +1261,11 @@ def join_inner(
         left_exactly_once: if you can guarantee that each row on the left side of the join will be
             joined at most once, then you can set this parameter to ``True``. Then each row after
             getting a match is removed from the join state. As a result, less memory is needed.
+            Works only for append-only tables.
         right_exactly_once: if you can guarantee that each row on the right side of the join will be
             joined at most once, then you can set this parameter to ``True``. Then each row after
             getting a match is removed from the join state. As a result, less memory is needed.
+            Works only for append-only tables.
 
     Returns:
         JoinResult: an object on which `.select()` may be called to extract relevant
@@ -1313,9 +1327,11 @@ def join_left(
         left_exactly_once: if you can guarantee that each row on the left side of the join will be
             joined at most once, then you can set this parameter to ``True``. Then each row after
             getting a match is removed from the join state. As a result, less memory is needed.
+            Works only for append-only tables.
         right_exactly_once: if you can guarantee that each row on the right side of the join will be
             joined at most once, then you can set this parameter to ``True``. Then each row after
             getting a match is removed from the join state. As a result, less memory is needed.
+            Works only for append-only tables.
 
     Remarks:
     args cannot contain id column from either of tables, \
@@ -1397,9 +1413,11 @@ def join_right(
         left_exactly_once: if you can guarantee that each row on the left side of the join will be
             joined at most once, then you can set this parameter to ``True``. Then each row after
             getting a match is removed from the join state. As a result, less memory is needed.
+            Works only for append-only tables.
         right_exactly_once: if you can guarantee that each row on the right side of the join will be
             joined at most once, then you can set this parameter to ``True``. Then each row after
             getting a match is removed from the join state. As a result, less memory is needed.
+            Works only for append-only tables.
 
     Remarks: args cannot contain id column from either of tables, \
     as the result table has id column with auto-generated ids; \
@@ -1483,9 +1501,11 @@ def join_outer(
         left_exactly_once: if you can guarantee that each row on the left side of the join will be
             joined at most once, then you can set this parameter to ``True``. Then each row after
             getting a match is removed from the join state. As a result, less memory is needed.
+            Works only for append-only tables.
         right_exactly_once: if you can guarantee that each row on the right side of the join will be
             joined at most once, then you can set this parameter to ``True``. Then each row after
             getting a match is removed from the join state. As a result, less memory is needed.
+            Works only for append-only tables.
 
     Remarks: args cannot contain id column from either of tables, \
         as the result table has id column with auto-generated ids; \

src/engine/dataflow.rs

@@ -2820,9 +2820,18 @@ impl<S: MaybeTotalScope> DataflowGraphInner<S> {
                 let without_retractions = join_left_right_without_persisted
                     .filter_out_forgetting()
                     .consolidate();
-                without_retractions
-                    .inner
-                    .inspect(|(_data, _time, diff)| assert!(*diff > 0));
+                let error_logger = self.create_error_logger()?;
+                let trace = table_properties.trace();
+                without_retractions.inner.inspect(
+                    move |((join_key, _left, _right), _time, diff)| {
+                        if *diff < 0 {
+                            error_logger.log_error_with_trace(
+                                DataError::ExpectedAppendOnly(*join_key).into(),
+                                &trace,
+                            );
+                        }
+                    },
+                );
 
                 if let Some(left_retractions) = left_retractions {
                     let left_side = without_retractions.map_named(