docs(python): Update join_where docs to clarify behaviour (#18670)

pola-rs · Sep 11, 2024 · 9d01442 · 9d01442
1 parent 5c4e7e9
commit 9d01442
Show file tree

Hide file tree

Showing 2 changed files with 16 additions and 8 deletions.
diff --git a/py-polars/polars/dataframe/frame.py b/py-polars/polars/dataframe/frame.py
@@ -7103,21 +7103,25 @@ def join_where(
         suffix: str = "_right",
     ) -> DataFrame:
         """
-        Perform a join based on one or multiple equality predicates.
+        Perform a join based on one or multiple (in)equality predicates.
+
+        This performs an inner join, so only rows where all predicates are true
+        are included in the result, and a row from either DataFrame may be included
+        multiple times in the result.
+
+        .. note::
+            The row order of the input DataFrames is not preserved.
 
         .. warning::
             This functionality is experimental. It may be
             changed at any point without it being considered a breaking change.
 
-        A row from this table may be included in zero or multiple rows in the result,
-        and the relative order of rows may differ between the input and output tables.
-
         Parameters
         ----------
         other
             DataFrame to join with.
         *predicates
-            (In)Equality condition to join the two table on.
+            (In)Equality condition to join the two tables on.
             When a column name occurs in both tables, the proper suffix must
             be applied in the predicate.
         suffix

diff --git a/py-polars/polars/lazyframe/frame.py b/py-polars/polars/lazyframe/frame.py
@@ -4571,8 +4571,12 @@ def join_where(
         """
         Perform a join based on one or multiple (in)equality predicates.
 
-        A row from this table may be included in zero or multiple rows in the result,
-        and the relative order of rows may differ between the input and output tables.
+        This performs an inner join, so only rows where all predicates are true
+        are included in the result, and a row from either DataFrame may be included
+        multiple times in the result.
+
+        .. note::
+            The row order of the input DataFrames is not preserved.
 
         .. warning::
             This functionality is experimental. It may be
@@ -4583,7 +4587,7 @@ def join_where(
         other
             DataFrame to join with.
         *predicates
-            (In)Equality condition to join the two table on.
+            (In)Equality condition to join the two tables on.
             When a column name occurs in both tables, the proper suffix must
             be applied in the predicate.
         suffix