polars-df 0.14.0-x86_64-linux-musl → 0.16.0-x86_64-linux-musl

data/lib/polars/lazy_frame.rb

@@ -431,7 +431,9 @@ module Polars
       projection_pushdown: true,
       simplify_expression: true,
       no_optimization: false,
-      slice_pushdown: true
+      slice_pushdown: true,
+      storage_options: nil,
+      retries: 2
     )
       lf = _set_sink_optimizations(
         type_coercion: type_coercion,
@@ -460,6 +462,12 @@ module Polars
         }
       end
 
+      if storage_options&.any?
+        storage_options = storage_options.to_a
+      else
+        storage_options = nil
+      end
+
       lf.sink_parquet(
         path,
         compression,
@@ -467,7 +475,9 @@ module Polars
         statistics,
         row_group_size,
         data_pagesize_limit,
-        maintain_order
+        maintain_order,
+        storage_options,
+        retries
       )
     end
 
@@ -512,6 +522,10 @@ module Polars
       slice_pushdown: true,
       no_optimization: false
     )
+      # TODO support storage options in Rust
+      storage_options = nil
+      retries = 2
+
       lf = _set_sink_optimizations(
         type_coercion: type_coercion,
         predicate_pushdown: predicate_pushdown,
@@ -521,10 +535,18 @@ module Polars
         no_optimization: no_optimization
       )
 
+      if storage_options&.any?
+        storage_options = storage_options.to_a
+      else
+        storage_options = nil
+      end
+
       lf.sink_ipc(
         path,
         compression,
-        maintain_order
+        maintain_order,
+        storage_options,
+        retries
       )
     end
 
@@ -692,7 +714,9 @@ module Polars
       projection_pushdown: true,
       simplify_expression: true,
       slice_pushdown: true,
-      no_optimization: false
+      no_optimization: false,
+      storage_options: nil,
+      retries: 2
     )
       lf = _set_sink_optimizations(
         type_coercion: type_coercion,
@@ -703,7 +727,13 @@ module Polars
         no_optimization: no_optimization
       )
 
-      lf.sink_json(path, maintain_order)
+      if storage_options&.any?
+        storage_options = storage_options.to_a
+      else
+        storage_options = nil
+      end
+
+      lf.sink_json(path, maintain_order, storage_options, retries)
     end
 
     # @private
@@ -848,9 +878,70 @@ module Polars
       _from_rbldf(_ldf.cache)
     end
 
-    # TODO
-    # def cast
-    # end
+    # Cast LazyFrame column(s) to the specified dtype(s).
+    #
+    # @param dtypes [Hash]
+    #   Mapping of column names (or selector) to dtypes, or a single dtype
+    #   to which all columns will be cast.
+    # @param strict [Boolean]
+    #   Throw an error if a cast could not be done (for instance, due to an
+    #   overflow).
+    #
+    # @return [LazyFrame]
+    #
+    # @example Cast specific frame columns to the specified dtypes:
+    #   lf = Polars::LazyFrame.new(
+    #     {
+    #       "foo" => [1, 2, 3],
+    #       "bar" => [6.0, 7.0, 8.0],
+    #       "ham" => [Date.new(2020, 1, 2), Date.new(2021, 3, 4), Date.new(2022, 5, 6)]
+    #     }
+    #   )
+    #   lf.cast({"foo" => Polars::Float32, "bar" => Polars::UInt8}).collect
+    #   # =>
+    #   # shape: (3, 3)
+    #   # ┌─────┬─────┬────────────┐
+    #   # │ foo ┆ bar ┆ ham        │
+    #   # │ --- ┆ --- ┆ ---        │
+    #   # │ f32 ┆ u8  ┆ date       │
+    #   # ╞═════╪═════╪════════════╡
+    #   # │ 1.0 ┆ 6   ┆ 2020-01-02 │
+    #   # │ 2.0 ┆ 7   ┆ 2021-03-04 │
+    #   # │ 3.0 ┆ 8   ┆ 2022-05-06 │
+    #   # └─────┴─────┴────────────┘
+    #
+    # @example Cast all frame columns matching one dtype (or dtype group) to another dtype:
+    #   lf.cast({Polars::Date => Polars::Datetime}).collect
+    #   # =>
+    #   # shape: (3, 3)
+    #   # ┌─────┬─────┬─────────────────────┐
+    #   # │ foo ┆ bar ┆ ham                 │
+    #   # │ --- ┆ --- ┆ ---                 │
+    #   # │ i64 ┆ f64 ┆ datetime[μs]        │
+    #   # ╞═════╪═════╪═════════════════════╡
+    #   # │ 1   ┆ 6.0 ┆ 2020-01-02 00:00:00 │
+    #   # │ 2   ┆ 7.0 ┆ 2021-03-04 00:00:00 │
+    #   # │ 3   ┆ 8.0 ┆ 2022-05-06 00:00:00 │
+    #   # └─────┴─────┴─────────────────────┘
+    #
+    # @example Cast all frame columns to the specified dtype:
+    #   lf.cast(Polars::String).collect.to_h(as_series: false)
+    #   # => {"foo"=>["1", "2", "3"], "bar"=>["6.0", "7.0", "8.0"], "ham"=>["2020-01-02", "2021-03-04", "2022-05-06"]}
+    def cast(dtypes, strict: true)
+      if !dtypes.is_a?(Hash)
+        return _from_rbldf(_ldf.cast_all(dtypes, strict))
+      end
+
+      cast_map = {}
+      dtypes.each do |c, dtype|
+        dtype = Utils.parse_into_dtype(dtype)
+        cast_map.merge!(
+          c.is_a?(::String) ? {c => dtype} : Utils.expand_selector(self, c).to_h { |x| [x, dtype] }
+        )
+      end
+
+      _from_rbldf(_ldf.cast(cast_map, strict))
+    end
 
     # Create an empty copy of the current LazyFrame.
     #
@@ -1520,8 +1611,197 @@ module Polars
     # @param force_parallel [Boolean]
     #   Force the physical plan to evaluate the computation of both DataFrames up to
     #   the join in parallel.
+    # @param coalesce [Boolean]
+    #   Coalescing behavior (merging of join columns).
+    #     - true: -> Always coalesce join columns.
+    #     - false: -> Never coalesce join columns.
+    #   Note that joining on any other expressions than `col` will turn off coalescing.
     #
     # @return [LazyFrame]
+    #
+    # @example
+    #   gdp = Polars::LazyFrame.new(
+    #     {
+    #       "date" => Polars.date_range(
+    #         Date.new(2016, 1, 1),
+    #         Date.new(2020, 1, 1),
+    #         "1y",
+    #         eager: true
+    #       ),
+    #       "gdp" => [4164, 4411, 4566, 4696, 4827]
+    #     }
+    #   )
+    #   gdp.collect
+    #   # =>
+    #   # shape: (5, 2)
+    #   # ┌────────────┬──────┐
+    #   # │ date       ┆ gdp  │
+    #   # │ ---        ┆ ---  │
+    #   # │ date       ┆ i64  │
+    #   # ╞════════════╪══════╡
+    #   # │ 2016-01-01 ┆ 4164 │
+    #   # │ 2017-01-01 ┆ 4411 │
+    #   # │ 2018-01-01 ┆ 4566 │
+    #   # │ 2019-01-01 ┆ 4696 │
+    #   # │ 2020-01-01 ┆ 4827 │
+    #   # └────────────┴──────┘
+    #
+    # @example
+    #   population = Polars::LazyFrame.new(
+    #     {
+    #       "date" => [Date.new(2016, 3, 1), Date.new(2018, 8, 1), Date.new(2019, 1, 1)],
+    #       "population" => [82.19, 82.66, 83.12]
+    #     }
+    #   ).sort("date")
+    #   population.collect
+    #   # =>
+    #   # shape: (3, 2)
+    #   # ┌────────────┬────────────┐
+    #   # │ date       ┆ population │
+    #   # │ ---        ┆ ---        │
+    #   # │ date       ┆ f64        │
+    #   # ╞════════════╪════════════╡
+    #   # │ 2016-03-01 ┆ 82.19      │
+    #   # │ 2018-08-01 ┆ 82.66      │
+    #   # │ 2019-01-01 ┆ 83.12      │
+    #   # └────────────┴────────────┘
+    #
+    # @example Note how the dates don't quite match. If we join them using `join_asof` and `strategy: "backward"`, then each date from `population` which doesn't have an exact match is matched with the closest earlier date from `gdp`:
+    #   population.join_asof(gdp, on: "date", strategy: "backward").collect
+    #   # =>
+    #   # shape: (3, 3)
+    #   # ┌────────────┬────────────┬──────┐
+    #   # │ date       ┆ population ┆ gdp  │
+    #   # │ ---        ┆ ---        ┆ ---  │
+    #   # │ date       ┆ f64        ┆ i64  │
+    #   # ╞════════════╪════════════╪══════╡
+    #   # │ 2016-03-01 ┆ 82.19      ┆ 4164 │
+    #   # │ 2018-08-01 ┆ 82.66      ┆ 4566 │
+    #   # │ 2019-01-01 ┆ 83.12      ┆ 4696 │
+    #   # └────────────┴────────────┴──────┘
+    #
+    # @example
+    #   population.join_asof(
+    #     gdp, on: "date", strategy: "backward", coalesce: false
+    #   ).collect
+    #   # =>
+    #   # shape: (3, 4)
+    #   # ┌────────────┬────────────┬────────────┬──────┐
+    #   # │ date       ┆ population ┆ date_right ┆ gdp  │
+    #   # │ ---        ┆ ---        ┆ ---        ┆ ---  │
+    #   # │ date       ┆ f64        ┆ date       ┆ i64  │
+    #   # ╞════════════╪════════════╪════════════╪══════╡
+    #   # │ 2016-03-01 ┆ 82.19      ┆ 2016-01-01 ┆ 4164 │
+    #   # │ 2018-08-01 ┆ 82.66      ┆ 2018-01-01 ┆ 4566 │
+    #   # │ 2019-01-01 ┆ 83.12      ┆ 2019-01-01 ┆ 4696 │
+    #   # └────────────┴────────────┴────────────┴──────┘
+    #
+    # @example If we instead use `strategy: "forward"`, then each date from `population` which doesn't have an exact match is matched with the closest later date from `gdp`:
+    #   population.join_asof(gdp, on: "date", strategy: "forward").collect
+    #   # =>
+    #   # shape: (3, 3)
+    #   # ┌────────────┬────────────┬──────┐
+    #   # │ date       ┆ population ┆ gdp  │
+    #   # │ ---        ┆ ---        ┆ ---  │
+    #   # │ date       ┆ f64        ┆ i64  │
+    #   # ╞════════════╪════════════╪══════╡
+    #   # │ 2016-03-01 ┆ 82.19      ┆ 4411 │
+    #   # │ 2018-08-01 ┆ 82.66      ┆ 4696 │
+    #   # │ 2019-01-01 ┆ 83.12      ┆ 4696 │
+    #   # └────────────┴────────────┴──────┘
+    #
+    # @example
+    #   population.join_asof(gdp, on: "date", strategy: "nearest").collect
+    #   # =>
+    #   # shape: (3, 3)
+    #   # ┌────────────┬────────────┬──────┐
+    #   # │ date       ┆ population ┆ gdp  │
+    #   # │ ---        ┆ ---        ┆ ---  │
+    #   # │ date       ┆ f64        ┆ i64  │
+    #   # ╞════════════╪════════════╪══════╡
+    #   # │ 2016-03-01 ┆ 82.19      ┆ 4164 │
+    #   # │ 2018-08-01 ┆ 82.66      ┆ 4696 │
+    #   # │ 2019-01-01 ┆ 83.12      ┆ 4696 │
+    #   # └────────────┴────────────┴──────┘
+    #
+    # @example
+    #   gdp_dates = Polars.date_range(
+    #     Date.new(2016, 1, 1), Date.new(2020, 1, 1), "1y", eager: true
+    #   )
+    #   gdp2 = Polars::LazyFrame.new(
+    #     {
+    #       "country" => ["Germany"] * 5 + ["Netherlands"] * 5,
+    #       "date" => Polars.concat([gdp_dates, gdp_dates]),
+    #       "gdp" => [4164, 4411, 4566, 4696, 4827, 784, 833, 914, 910, 909]
+    #     }
+    #   ).sort("country", "date")
+    #   gdp2.collect
+    #   # =>
+    #   # shape: (10, 3)
+    #   # ┌─────────────┬────────────┬──────┐
+    #   # │ country     ┆ date       ┆ gdp  │
+    #   # │ ---         ┆ ---        ┆ ---  │
+    #   # │ str         ┆ date       ┆ i64  │
+    #   # ╞═════════════╪════════════╪══════╡
+    #   # │ Germany     ┆ 2016-01-01 ┆ 4164 │
+    #   # │ Germany     ┆ 2017-01-01 ┆ 4411 │
+    #   # │ Germany     ┆ 2018-01-01 ┆ 4566 │
+    #   # │ Germany     ┆ 2019-01-01 ┆ 4696 │
+    #   # │ Germany     ┆ 2020-01-01 ┆ 4827 │
+    #   # │ Netherlands ┆ 2016-01-01 ┆ 784  │
+    #   # │ Netherlands ┆ 2017-01-01 ┆ 833  │
+    #   # │ Netherlands ┆ 2018-01-01 ┆ 914  │
+    #   # │ Netherlands ┆ 2019-01-01 ┆ 910  │
+    #   # │ Netherlands ┆ 2020-01-01 ┆ 909  │
+    #   # └─────────────┴────────────┴──────┘
+    #
+    # @example
+    #   pop2 = Polars::LazyFrame.new(
+    #     {
+    #       "country" => ["Germany"] * 3 + ["Netherlands"] * 3,
+    #       "date" => [
+    #         Date.new(2016, 3, 1),
+    #         Date.new(2018, 8, 1),
+    #         Date.new(2019, 1, 1),
+    #         Date.new(2016, 3, 1),
+    #         Date.new(2018, 8, 1),
+    #         Date.new(2019, 1, 1)
+    #       ],
+    #       "population" => [82.19, 82.66, 83.12, 17.11, 17.32, 17.40]
+    #     }
+    #   ).sort("country", "date")
+    #   pop2.collect
+    #   # =>
+    #   # shape: (6, 3)
+    #   # ┌─────────────┬────────────┬────────────┐
+    #   # │ country     ┆ date       ┆ population │
+    #   # │ ---         ┆ ---        ┆ ---        │
+    #   # │ str         ┆ date       ┆ f64        │
+    #   # ╞═════════════╪════════════╪════════════╡
+    #   # │ Germany     ┆ 2016-03-01 ┆ 82.19      │
+    #   # │ Germany     ┆ 2018-08-01 ┆ 82.66      │
+    #   # │ Germany     ┆ 2019-01-01 ┆ 83.12      │
+    #   # │ Netherlands ┆ 2016-03-01 ┆ 17.11      │
+    #   # │ Netherlands ┆ 2018-08-01 ┆ 17.32      │
+    #   # │ Netherlands ┆ 2019-01-01 ┆ 17.4       │
+    #   # └─────────────┴────────────┴────────────┘
+    #
+    # @example
+    #   pop2.join_asof(gdp2, by: "country", on: "date", strategy: "nearest").collect
+    #   # =>
+    #   # shape: (6, 4)
+    #   # ┌─────────────┬────────────┬────────────┬──────┐
+    #   # │ country     ┆ date       ┆ population ┆ gdp  │
+    #   # │ ---         ┆ ---        ┆ ---        ┆ ---  │
+    #   # │ str         ┆ date       ┆ f64        ┆ i64  │
+    #   # ╞═════════════╪════════════╪════════════╪══════╡
+    #   # │ Germany     ┆ 2016-03-01 ┆ 82.19      ┆ 4164 │
+    #   # │ Germany     ┆ 2018-08-01 ┆ 82.66      ┆ 4696 │
+    #   # │ Germany     ┆ 2019-01-01 ┆ 83.12      ┆ 4696 │
+    #   # │ Netherlands ┆ 2016-03-01 ┆ 17.11      ┆ 784  │
+    #   # │ Netherlands ┆ 2018-08-01 ┆ 17.32      ┆ 910  │
+    #   # │ Netherlands ┆ 2019-01-01 ┆ 17.4       ┆ 910  │
+    #   # └─────────────┴────────────┴────────────┴──────┘
     def join_asof(
       other,
       left_on: nil,
@@ -1534,7 +1814,8 @@ module Polars
       suffix: "_right",
       tolerance: nil,
       allow_parallel: true,
-      force_parallel: false
+      force_parallel: false,
+      coalesce: true
     )
       if !other.is_a?(LazyFrame)
         raise ArgumentError, "Expected a `LazyFrame` as join table, got #{other.class.name}"
@@ -1589,7 +1870,8 @@ module Polars
           suffix,
           strategy,
           tolerance_num,
-          tolerance_str
+          tolerance_str,
+          coalesce
         )
       )
     end
@@ -1609,6 +1891,12 @@ module Polars
     #   Join strategy.
     # @param suffix [String]
     #   Suffix to append to columns with a duplicate name.
+    # @param validate ['m:m', 'm:1', '1:m', '1:1']
+    #   Checks if join is of specified type.
+    #     * *many_to_many* - “m:m”: default, does not result in checks
+    #     * *one_to_one* - “1:1”: check if join keys are unique in both left and right datasets
+    #     * *one_to_many* - “1:m”: check if join keys are unique in left dataset
+    #     * *many_to_one* - “m:1”: check if join keys are unique in right dataset
     # @param join_nulls [Boolean]
     #   Join on null values. By default null values will never produce matches.
     # @param allow_parallel [Boolean]
@@ -1617,6 +1905,12 @@ module Polars
     # @param force_parallel [Boolean]
     #   Force the physical plan to evaluate the computation of both DataFrames up to
     #   the join in parallel.
+    # @param coalesce [Boolean]
+    #   Coalescing behavior (merging of join columns).
+    #     - nil: -> join specific.
+    #     - true: -> Always coalesce join columns.
+    #     - false: -> Never coalesce join columns.
+    #   Note that joining on any other expressions than `col` will turn off coalescing.
     #
     # @return [LazyFrame]
     #
@@ -1706,9 +2000,11 @@ module Polars
       on: nil,
       how: "inner",
       suffix: "_right",
+      validate: "m:m",
       join_nulls: false,
       allow_parallel: true,
-      force_parallel: false
+      force_parallel: false,
+      coalesce: nil
     )
       if !other.is_a?(LazyFrame)
         raise ArgumentError, "Expected a `LazyFrame` as join table, got #{other.class.name}"
@@ -1719,7 +2015,7 @@ module Polars
       elsif how == "cross"
         return _from_rbldf(
           _ldf.join(
-            other._ldf, [], [], allow_parallel, join_nulls, force_parallel, how, suffix
+            other._ldf, [], [], allow_parallel, join_nulls, force_parallel, how, suffix, validate, coalesce
           )
         )
       end
@@ -1745,6 +2041,8 @@ module Polars
           join_nulls,
           how,
           suffix,
+          validate,
+          coalesce
         )
       )
     end
@@ -1879,6 +2177,55 @@ module Polars
     #   - List of column names.
     #
     # @return [LazyFrame]
+    #
+    # @example Drop a single column by passing the name of that column.
+    #   lf = Polars::LazyFrame.new(
+    #     {
+    #       "foo" => [1, 2, 3],
+    #       "bar" => [6.0, 7.0, 8.0],
+    #       "ham" => ["a", "b", "c"]
+    #     }
+    #   )
+    #   lf.drop("ham").collect
+    #   # =>
+    #   # shape: (3, 2)
+    #   # ┌─────┬─────┐
+    #   # │ foo ┆ bar │
+    #   # │ --- ┆ --- │
+    #   # │ i64 ┆ f64 │
+    #   # ╞═════╪═════╡
+    #   # │ 1   ┆ 6.0 │
+    #   # │ 2   ┆ 7.0 │
+    #   # │ 3   ┆ 8.0 │
+    #   # └─────┴─────┘
+    #
+    # @example Drop multiple columns by passing a selector.
+    #   lf.drop(Polars.cs.numeric).collect
+    #   # =>
+    #   # shape: (3, 1)
+    #   # ┌─────┐
+    #   # │ ham │
+    #   # │ --- │
+    #   # │ str │
+    #   # ╞═════╡
+    #   # │ a   │
+    #   # │ b   │
+    #   # │ c   │
+    #   # └─────┘
+    #
+    # @example Use positional arguments to drop multiple columns.
+    #   lf.drop("foo", "ham").collect
+    #   # =>
+    #   # shape: (3, 1)
+    #   # ┌─────┐
+    #   # │ bar │
+    #   # │ --- │
+    #   # │ f64 │
+    #   # ╞═════╡
+    #   # │ 6.0 │
+    #   # │ 7.0 │
+    #   # │ 8.0 │
+    #   # └─────┘
     def drop(*columns)
       drop_cols = Utils._expand_selectors(self, *columns)
       _from_rbldf(_ldf.drop(drop_cols))
@@ -1888,17 +2235,80 @@ module Polars
     #
     # @param mapping [Hash]
     #   Key value pairs that map from old name to new name.
+    # @param strict [Boolean]
+    #   Validate that all column names exist in the current schema,
+    #   and throw an exception if any do not. (Note that this parameter
+    #   is a no-op when passing a function to `mapping`).
     #
     # @return [LazyFrame]
-    def rename(mapping)
-      existing = mapping.keys
-      _new = mapping.values
-      _from_rbldf(_ldf.rename(existing, _new))
+    #
+    # @example
+    #   lf = Polars::LazyFrame.new(
+    #     {
+    #       "foo" => [1, 2, 3],
+    #       "bar" => [6, 7, 8],
+    #       "ham" => ["a", "b", "c"]
+    #     }
+    #   )
+    #   lf.rename({"foo" => "apple"}).collect
+    #   # =>
+    #   # shape: (3, 3)
+    #   # ┌───────┬─────┬─────┐
+    #   # │ apple ┆ bar ┆ ham │
+    #   # │ ---   ┆ --- ┆ --- │
+    #   # │ i64   ┆ i64 ┆ str │
+    #   # ╞═══════╪═════╪═════╡
+    #   # │ 1     ┆ 6   ┆ a   │
+    #   # │ 2     ┆ 7   ┆ b   │
+    #   # │ 3     ┆ 8   ┆ c   │
+    #   # └───────┴─────┴─────┘
+    #
+    # @example
+    #   lf.rename(->(column_name) { "c" + column_name[1..] }).collect
+    #   # =>
+    #   # shape: (3, 3)
+    #   # ┌─────┬─────┬─────┐
+    #   # │ coo ┆ car ┆ cam │
+    #   # │ --- ┆ --- ┆ --- │
+    #   # │ i64 ┆ i64 ┆ str │
+    #   # ╞═════╪═════╪═════╡
+    #   # │ 1   ┆ 6   ┆ a   │
+    #   # │ 2   ┆ 7   ┆ b   │
+    #   # │ 3   ┆ 8   ┆ c   │
+    #   # └─────┴─────┴─────┘
+    def rename(mapping, strict: true)
+      if mapping.respond_to?(:call)
+        select(F.all.name.map(&mapping))
+      else
+        existing = mapping.keys
+        _new = mapping.values
+        _from_rbldf(_ldf.rename(existing, _new, strict))
+      end
     end
 
     # Reverse the DataFrame.
     #
     # @return [LazyFrame]
+    #
+    # @example
+    #   lf = Polars::LazyFrame.new(
+    #     {
+    #       "key" => ["a", "b", "c"],
+    #       "val" => [1, 2, 3]
+    #     }
+    #   )
+    #   lf.reverse.collect
+    #   # =>
+    #   # shape: (3, 2)
+    #   # ┌─────┬─────┐
+    #   # │ key ┆ val │
+    #   # │ --- ┆ --- │
+    #   # │ str ┆ i64 │
+    #   # ╞═════╪═════╡
+    #   # │ c   ┆ 3   │
+    #   # │ b   ┆ 2   │
+    #   # │ a   ┆ 1   │
+    #   # └─────┴─────┘
     def reverse
       _from_rbldf(_ldf.reverse)
     end
@@ -2048,8 +2458,43 @@ module Polars
     #   Consider using the {#fetch} operation if you only want to test your
     #   query. The {#fetch} operation will load the first `n` rows at the scan
     #   level, whereas the {#head}/{#limit} are applied at the end.
+    #
+    # @example
+    #   lf = Polars::LazyFrame.new(
+    #     {
+    #       "a" => [1, 2, 3, 4, 5, 6],
+    #       "b" => [7, 8, 9, 10, 11, 12]
+    #     }
+    #   )
+    #   lf.limit.collect
+    #   # =>
+    #   # shape: (5, 2)
+    #   # ┌─────┬─────┐
+    #   # │ a   ┆ b   │
+    #   # │ --- ┆ --- │
+    #   # │ i64 ┆ i64 │
+    #   # ╞═════╪═════╡
+    #   # │ 1   ┆ 7   │
+    #   # │ 2   ┆ 8   │
+    #   # │ 3   ┆ 9   │
+    #   # │ 4   ┆ 10  │
+    #   # │ 5   ┆ 11  │
+    #   # └─────┴─────┘
+    #
+    # @example
+    #   lf.limit(2).collect
+    #   # =>
+    #   # shape: (2, 2)
+    #   # ┌─────┬─────┐
+    #   # │ a   ┆ b   │
+    #   # │ --- ┆ --- │
+    #   # │ i64 ┆ i64 │
+    #   # ╞═════╪═════╡
+    #   # │ 1   ┆ 7   │
+    #   # │ 2   ┆ 8   │
+    #   # └─────┴─────┘
     def limit(n = 5)
-      head(5)
+      head(n)
     end
 
     # Get the first `n` rows.
@@ -2063,6 +2508,41 @@ module Polars
     #   Consider using the {#fetch} operation if you only want to test your
     #   query. The {#fetch} operation will load the first `n` rows at the scan
     #   level, whereas the {#head}/{#limit} are applied at the end.
+    #
+    # @example
+    #   lf = Polars::LazyFrame.new(
+    #     {
+    #       "a" => [1, 2, 3, 4, 5, 6],
+    #       "b" => [7, 8, 9, 10, 11, 12]
+    #     }
+    #   )
+    #   lf.head.collect
+    #   # =>
+    #   # shape: (5, 2)
+    #   # ┌─────┬─────┐
+    #   # │ a   ┆ b   │
+    #   # │ --- ┆ --- │
+    #   # │ i64 ┆ i64 │
+    #   # ╞═════╪═════╡
+    #   # │ 1   ┆ 7   │
+    #   # │ 2   ┆ 8   │
+    #   # │ 3   ┆ 9   │
+    #   # │ 4   ┆ 10  │
+    #   # │ 5   ┆ 11  │
+    #   # └─────┴─────┘
+    #
+    # @example
+    #   lf.head(2).collect
+    #   # =>
+    #   # shape: (2, 2)
+    #   # ┌─────┬─────┐
+    #   # │ a   ┆ b   │
+    #   # │ --- ┆ --- │
+    #   # │ i64 ┆ i64 │
+    #   # ╞═════╪═════╡
+    #   # │ 1   ┆ 7   │
+    #   # │ 2   ┆ 8   │
+    #   # └─────┴─────┘
     def head(n = 5)
       slice(0, n)
     end
@@ -2073,6 +2553,41 @@ module Polars
     #     Number of rows.
     #
     # @return [LazyFrame]
+    #
+    # @example
+    #   lf = Polars::LazyFrame.new(
+    #     {
+    #       "a" => [1, 2, 3, 4, 5, 6],
+    #       "b" => [7, 8, 9, 10, 11, 12]
+    #     }
+    #   )
+    #   lf.tail.collect
+    #   # =>
+    #   # shape: (5, 2)
+    #   # ┌─────┬─────┐
+    #   # │ a   ┆ b   │
+    #   # │ --- ┆ --- │
+    #   # │ i64 ┆ i64 │
+    #   # ╞═════╪═════╡
+    #   # │ 2   ┆ 8   │
+    #   # │ 3   ┆ 9   │
+    #   # │ 4   ┆ 10  │
+    #   # │ 5   ┆ 11  │
+    #   # │ 6   ┆ 12  │
+    #   # └─────┴─────┘
+    #
+    # @example
+    #   lf.tail(2).collect
+    #   # =>
+    #   # shape: (2, 2)
+    #   # ┌─────┬─────┐
+    #   # │ a   ┆ b   │
+    #   # │ --- ┆ --- │
+    #   # │ i64 ┆ i64 │
+    #   # ╞═════╪═════╡
+    #   # │ 5   ┆ 11  │
+    #   # │ 6   ┆ 12  │
+    #   # └─────┴─────┘
     def tail(n = 5)
       _from_rbldf(_ldf.tail(n))
     end
@@ -2080,6 +2595,24 @@ module Polars
     # Get the last row of the DataFrame.
     #
     # @return [LazyFrame]
+    #
+    # @example
+    #   lf = Polars::LazyFrame.new(
+    #     {
+    #       "a" => [1, 5, 3],
+    #       "b" => [2, 4, 6]
+    #     }
+    #   )
+    #   lf.last.collect
+    #   # =>
+    #   # shape: (1, 2)
+    #   # ┌─────┬─────┐
+    #   # │ a   ┆ b   │
+    #   # │ --- ┆ --- │
+    #   # │ i64 ┆ i64 │
+    #   # ╞═════╪═════╡
+    #   # │ 3   ┆ 6   │
+    #   # └─────┴─────┘
     def last
       tail(1)
     end
@@ -2087,6 +2620,24 @@ module Polars
     # Get the first row of the DataFrame.
     #
     # @return [LazyFrame]
+    #
+    # @example
+    #   lf = Polars::LazyFrame.new(
+    #     {
+    #       "a" => [1, 5, 3],
+    #       "b" => [2, 4, 6]
+    #     }
+    #   )
+    #   lf.first.collect
+    #   # =>
+    #   # shape: (1, 2)
+    #   # ┌─────┬─────┐
+    #   # │ a   ┆ b   │
+    #   # │ --- ┆ --- │
+    #   # │ i64 ┆ i64 │
+    #   # ╞═════╪═════╡
+    #   # │ 1   ┆ 2   │
+    #   # └─────┴─────┘
     def first
       slice(0, 1)
     end
@@ -2152,6 +2703,72 @@ module Polars
     # Fill null values using the specified value or strategy.
     #
     # @return [LazyFrame]
+    #
+    # @example
+    #   lf = Polars::LazyFrame.new(
+    #     {
+    #       "a" => [1, 2, nil, 4],
+    #       "b" => [0.5, 4, nil, 13]
+    #     }
+    #   )
+    #   lf.fill_null(99).collect
+    #   # =>
+    #   # shape: (4, 2)
+    #   # ┌─────┬──────┐
+    #   # │ a   ┆ b    │
+    #   # │ --- ┆ ---  │
+    #   # │ i64 ┆ f64  │
+    #   # ╞═════╪══════╡
+    #   # │ 1   ┆ 0.5  │
+    #   # │ 2   ┆ 4.0  │
+    #   # │ 99  ┆ 99.0 │
+    #   # │ 4   ┆ 13.0 │
+    #   # └─────┴──────┘
+    #
+    # @example
+    #   lf.fill_null(strategy: "forward").collect
+    #   # =>
+    #   # shape: (4, 2)
+    #   # ┌─────┬──────┐
+    #   # │ a   ┆ b    │
+    #   # │ --- ┆ ---  │
+    #   # │ i64 ┆ f64  │
+    #   # ╞═════╪══════╡
+    #   # │ 1   ┆ 0.5  │
+    #   # │ 2   ┆ 4.0  │
+    #   # │ 2   ┆ 4.0  │
+    #   # │ 4   ┆ 13.0 │
+    #   # └─────┴──────┘
+    #
+    # @example
+    #   lf.fill_null(strategy: "max").collect
+    #   # =>
+    #   # shape: (4, 2)
+    #   # ┌─────┬──────┐
+    #   # │ a   ┆ b    │
+    #   # │ --- ┆ ---  │
+    #   # │ i64 ┆ f64  │
+    #   # ╞═════╪══════╡
+    #   # │ 1   ┆ 0.5  │
+    #   # │ 2   ┆ 4.0  │
+    #   # │ 4   ┆ 13.0 │
+    #   # │ 4   ┆ 13.0 │
+    #   # └─────┴──────┘
+    #
+    # @example
+    #   lf.fill_null(strategy: "zero").collect
+    #   # =>
+    #   # shape: (4, 2)
+    #   # ┌─────┬──────┐
+    #   # │ a   ┆ b    │
+    #   # │ --- ┆ ---  │
+    #   # │ i64 ┆ f64  │
+    #   # ╞═════╪══════╡
+    #   # │ 1   ┆ 0.5  │
+    #   # │ 2   ┆ 4.0  │
+    #   # │ 0   ┆ 0.0  │
+    #   # │ 4   ┆ 13.0 │
+    #   # └─────┴──────┘
     def fill_null(value = nil, strategy: nil, limit: nil, matches_supertype: nil)
       select(Polars.all.fill_null(value, strategy: strategy, limit: limit))
     end
@@ -2431,6 +3048,53 @@ module Polars
     #   Which of the duplicate rows to keep.
     #
     # @return [LazyFrame]
+    #
+    # @example
+    #   lf = Polars::LazyFrame.new(
+    #     {
+    #       "foo" => [1, 2, 3, 1],
+    #       "bar" => ["a", "a", "a", "a"],
+    #       "ham" => ["b", "b", "b", "b"]
+    #     }
+    #   )
+    #   lf.unique(maintain_order: true).collect
+    #   # =>
+    #   # shape: (3, 3)
+    #   # ┌─────┬─────┬─────┐
+    #   # │ foo ┆ bar ┆ ham │
+    #   # │ --- ┆ --- ┆ --- │
+    #   # │ i64 ┆ str ┆ str │
+    #   # ╞═════╪═════╪═════╡
+    #   # │ 1   ┆ a   ┆ b   │
+    #   # │ 2   ┆ a   ┆ b   │
+    #   # │ 3   ┆ a   ┆ b   │
+    #   # └─────┴─────┴─────┘
+    #
+    # @example
+    #   lf.unique(subset: ["bar", "ham"], maintain_order: true).collect
+    #   # =>
+    #   # shape: (1, 3)
+    #   # ┌─────┬─────┬─────┐
+    #   # │ foo ┆ bar ┆ ham │
+    #   # │ --- ┆ --- ┆ --- │
+    #   # │ i64 ┆ str ┆ str │
+    #   # ╞═════╪═════╪═════╡
+    #   # │ 1   ┆ a   ┆ b   │
+    #   # └─────┴─────┴─────┘
+    #
+    # @example
+    #   lf.unique(keep: "last", maintain_order: true).collect
+    #   # =>
+    #   # shape: (3, 3)
+    #   # ┌─────┬─────┬─────┐
+    #   # │ foo ┆ bar ┆ ham │
+    #   # │ --- ┆ --- ┆ --- │
+    #   # │ i64 ┆ str ┆ str │
+    #   # ╞═════╪═════╪═════╡
+    #   # │ 2   ┆ a   ┆ b   │
+    #   # │ 3   ┆ a   ┆ b   │
+    #   # │ 1   ┆ a   ┆ b   │
+    #   # └─────┴─────┴─────┘
     def unique(maintain_order: true, subset: nil, keep: "first")
       if !subset.nil? && !subset.is_a?(::Array)
         subset = [subset]
@@ -2504,7 +3168,7 @@ module Polars
     #       "c" => [2, 4, 6]
     #     }
     #   )
-    #   lf.unpivot(Polars::Selectors.numeric, index: "a").collect
+    #   lf.unpivot(Polars.cs.numeric, index: "a").collect
     #   # =>
     #   # shape: (6, 3)
     #   # ┌─────┬──────────┬───────┐
@@ -2530,8 +3194,8 @@ module Polars
         warn "The `streamable` parameter for `LazyFrame.unpivot` is deprecated"
       end
 
-      on = on.nil? ? [] : Utils._expand_selectors(self, on)
-      index = index.nil? ? [] : Utils._expand_selectors(self, index)
+      on = on.nil? ? [] : Utils.parse_into_list_of_expressions(on)
+      index = index.nil? ? [] : Utils.parse_into_list_of_expressions(index)
 
       _from_rbldf(
         _ldf.unpivot(on, index, value_name, variable_name)