docs(python): Fix LazyFrame fetch method references (#18033)

Co-authored-by: Edwin Vehmaanperä <edwinvehmaanpera@gmail.com> Co-authored-by: Rodrigo Girão Serrão <5621605+rodrigogiraoserrao@users.noreply.github.com>
pola-rs · Sep 25, 2024 · 39d63aa · 39d63aa
1 parent f246a4c
commit 39d63aa
Show file tree

Hide file tree

Showing 3 changed files with 13 additions and 34 deletions.
diff --git a/docs/source/src/python/user-guide/lazy/execution.py b/docs/source/src/python/user-guide/lazy/execution.py
@@ -31,9 +31,10 @@
 # --8<-- [start:partial]
 q9 = (
     pl.scan_csv(f"docs/assets/data/reddit.csv")
+    .head(10)
     .with_columns(pl.col("name").str.to_uppercase())
     .filter(pl.col("comment_karma") > 0)
-    .fetch(n_rows=int(100))
+    .collect()
 )
 # --8<-- [end:partial]
 """
diff --git a/docs/source/user-guide/lazy/execution.md b/docs/source/user-guide/lazy/execution.md
@@ -53,27 +53,18 @@ We look at [streaming in more detail here](streaming.md).
 
 While you're writing, optimizing or checking your query on a large dataset, querying all available data may lead to a slow development process.
 
-You can instead execute the query with the `.fetch` method. The `.fetch` method takes a parameter `n_rows` and tries to 'fetch' that number of rows at the data source. The number of rows cannot be guaranteed, however, as the lazy API does not count how many rows there are at each stage of the query.
+Instead, you can scan a subset of your partitions or use `.head`/`.collect` at the beginning and end of your query, respectively.
+Keep in mind that the results of aggregations and filters on subsets of your data may not be representative of the result you would get on the full data.
 
-Here we "fetch" 100 rows from the source file and apply the predicates.
-
-{{code_block('user-guide/lazy/execution','partial',['scan_csv','collect','fetch'])}}
+{{code_block('user-guide/lazy/execution','partial',['scan_csv','collect','head'])}}
 
 ```text
-shape: (27, 6)
-┌───────┬───────────────────────────┬─────────────┬────────────┬───────────────┬────────────┐
-│ id    ┆ name                      ┆ created_utc ┆ updated_on ┆ comment_karma ┆ link_karma │
-│ ---   ┆ ---                       ┆ ---         ┆ ---        ┆ ---           ┆ ---        │
-│ i64   ┆ str                       ┆ i64         ┆ i64        ┆ i64           ┆ i64        │
-╞═══════╪═══════════════════════════╪═════════════╪════════════╪═══════════════╪════════════╡
-│ 6     ┆ TAOJIANLONG_JASONBROKEN   ┆ 1397113510  ┆ 1536527864 ┆ 4             ┆ 0          │
-│ 17    ┆ SSAIG_JASONBROKEN         ┆ 1397113544  ┆ 1536527864 ┆ 1             ┆ 0          │
-│ 19    ┆ FDBVFDSSDGFDS_JASONBROKEN ┆ 1397113552  ┆ 1536527864 ┆ 3             ┆ 0          │
-│ 37    ┆ IHATEWHOWEARE_JASONBROKEN ┆ 1397113636  ┆ 1536527864 ┆ 61            ┆ 0          │
-│ …     ┆ …                         ┆ …           ┆ …          ┆ …             ┆ …          │
-│ 77763 ┆ LUNCHY                    ┆ 1137599510  ┆ 1536528275 ┆ 65            ┆ 0          │
-│ 77765 ┆ COMPOSTELLAS              ┆ 1137474000  ┆ 1536528276 ┆ 6             ┆ 0          │
-│ 77766 ┆ GENERICBOB                ┆ 1137474000  ┆ 1536528276 ┆ 291           ┆ 14         │
-│ 77768 ┆ TINHEADNED                ┆ 1139665457  ┆ 1536497404 ┆ 4434          ┆ 103        │
-└───────┴───────────────────────────┴─────────────┴────────────┴───────────────┴────────────┘
+shape: (1, 6)
+┌─────┬─────────────────────────┬─────────────┬────────────┬───────────────┬────────────┐
+│ id  ┆ name                    ┆ created_utc ┆ updated_on ┆ comment_karma ┆ link_karma │
+│ --- ┆ ---                     ┆ ---         ┆ ---        ┆ ---           ┆ ---        │
+│ i64 ┆ str                     ┆ i64         ┆ i64        ┆ i64           ┆ i64        │
+╞═════╪═════════════════════════╪═════════════╪════════════╪═══════════════╪════════════╡
+│ 6   ┆ TAOJIANLONG_JASONBROKEN ┆ 1397113510  ┆ 1536527864 ┆ 4             ┆ 0          │
+└─────┴─────────────────────────┴─────────────┴────────────┴───────────────┴────────────┘
 ```
diff --git a/py-polars/polars/lazyframe/frame.py b/py-polars/polars/lazyframe/frame.py
@@ -1912,7 +1912,6 @@ def collect(
 
         See Also
         --------
-        fetch: Run the query on the first `n` rows only for debugging purposes.
         explain : Print the query plan that is evaluated with collect.
         profile : Collect the LazyFrame and time each node in the computation graph.
         polars.collect_all : Collect multiple LazyFrames at the same time.
@@ -5240,12 +5239,6 @@ def limit(self, n: int = 5) -> LazyFrame:
         n
             Number of rows to return.
 
-        Notes
-        -----
-        Consider using the :func:`fetch` operation if you only want to test your
-        query. The :func:`fetch` operation will load the first `n` rows at the scan
-        level, whereas the :func:`head`/:func:`limit` are applied at the end.
-
         Examples
         --------
         >>> lf = pl.LazyFrame(
@@ -5289,12 +5282,6 @@ def head(self, n: int = 5) -> LazyFrame:
         n
             Number of rows to return.
 
-        Notes
-        -----
-        Consider using the :func:`fetch` operation if you only want to test your
-        query. The :func:`fetch` operation will load the first `n` rows at the scan
-        level, whereas the :func:`head`/:func:`limit` are applied at the end.
-
         Examples
         --------
         >>> lf = pl.LazyFrame(