Merge

Namespace: Polars.FSharp

Module Functions

Merge.execute

Executes the merge plan lazily, returning a LazyFrame that can be further transformed or collected later. Validates the plan before building the AST.

Merge.execute : plan: MergePlan -> LazyFrame

Parameters

Name	Type	Description
plan	MergePlan	The fully constructed MergePlan.

Returns: A LazyFrame representing the merged result (not yet materialized).

---

Merge.executeEager

Executes the merge plan eagerly, materializing the result into a DataFrame. This is the terminal operation for a merge pipeline when a concrete result is needed.

Merge.executeEager : engine: Engine -> plan: MergePlan -> DataFrame

Parameters

Name	Type	Description
engine	Engine	The Polars execution engine to use (e.g., Engine.Auto).
plan	MergePlan	The fully constructed MergePlan.

Returns: A materialized DataFrame containing the merged data.

---

Merge.explain

Returns the optimized execution plan for the merge operation as a string, using Polars' EXPLAIN mechanism. This is useful for performance tuning.

Merge.explain : plan: MergePlan -> string

Parameters

Name	Type	Description
plan	MergePlan	The constructed MergePlan.

Returns: A string representing the query plan (e.g., optimized logical/physical plan).

---

Merge.includeNulls

Controls whether null values from the source should overwrite existing target values during a default column update (when no explicit setters are provided).

Merge.includeNulls : flag: bool -> plan: MergePlan -> MergePlan

Parameters

Name	Type	Description
flag	bool	If true, nulls from the source will overwrite target values.
plan	MergePlan	The current MergePlan being constructed.

Returns: A new MergePlan with the updated IncludeNulls setting.

---

Merge.initiate

Initializes a Merge plan from a target and source LazyFrame, using the provided join key columns. This is the module-level equivalent of calling myTarget.Merge(source, on).

Merge.initiate : source: LazyFrame -> on: seq<string> -> target: LazyFrame -> MergePlan

Parameters

Name	Type	Description
source	LazyFrame	The source LazyFrame containing the updates.
on	seq<string>	The resolved join key column names.
target	LazyFrame	The target LazyFrame to be updated.

Returns: A new MergePlan ready for further configuration via Merge.whenXxx functions.

---

Merge.inspectPlan

Inspects the current merge plan by passing its string representation to the given logger function, then returns the plan unchanged to continue the pipeline.

Merge.inspectPlan : logger: (string -> unit) -> plan: MergePlan -> MergePlan

Parameters

Name	Type	Description
logger	(string -> unit)	A function that receives the plan description string (e.g., printfn "%s").
plan	MergePlan	The MergePlan to inspect.

Returns: The original MergePlan for further chaining.

---

Merge.maintainOrder

Sets the row order preservation strategy for the join phase.

Merge.maintainOrder : order: JoinMaintainOrder -> plan: MergePlan -> MergePlan

Parameters

Name	Type	Description
order	JoinMaintainOrder	The desired maintain-order behavior from the JoinMaintainOrder enum.
plan	MergePlan	The current MergePlan being constructed.

Returns: A new MergePlan with the updated MaintainOrder setting.

---

Merge.printPlan

Convenience function that prints the merge plan to standard output using printfn. Equivalent to inspectPlan (printfn "%s") plan.

Merge.printPlan : plan: MergePlan -> MergePlan

Parameters

Name	Type	Description
plan	MergePlan	The MergePlan to inspect.

Returns: The original MergePlan for further chaining.

---

Merge.toPlanString

Generates a human-readable string describing the logical merge plan, including merge keys, match strategy, actions with conditions and setters, and the join strategy.

Merge.toPlanString : plan: MergePlan -> string

Parameters

Name	Type	Description
plan	MergePlan	The constructed MergePlan.

Returns: A formatted string representing the merge logic.

---

Merge.whenMatchedDelete

Adds a "WHEN MATCHED DELETE" action to the merge plan. If the condition is not provided, all matched rows are deleted.

Merge.whenMatchedDelete : condition: (MergeContext -> Expr) option -> plan: MergePlan -> MergePlan

Parameters

Name	Type	Description
condition	(MergeContext -> Expr) option	Optional condition expression builder using the MergeContext.
plan	MergePlan	The current MergePlan being constructed.

Returns: A new MergePlan with the DELETE action appended.

---

Merge.whenMatchedUpdate

Adds a "WHEN MATCHED UPDATE" action to the merge plan. If the condition is not provided, all matched rows are updated. If setters are not provided, all source columns with matching names will overwrite target columns (respecting includeNulls). If explicit setters or a SetterSpec are given, only those columns are updated.

Merge.whenMatchedUpdate : condition: (MergeContext -> Expr) option -> setters: SetterSpec option -> plan: MergePlan -> MergePlan

Parameters

Name	Type	Description
condition	(MergeContext -> Expr) option	Optional condition expression builder using the MergeContext (source/target column accessors).
setters	SetterSpec option	Optional SetterSpec defining which columns to update and how.
plan	MergePlan	The current MergePlan being constructed.

Returns: A new MergePlan with the UPDATE action appended.

---

Merge.whenMatchedUpdateAll

Convenience shorthand for whenMatchedUpdate None None – updates all matched rows using all source columns (with includeNulls controlling null overwrites).

Merge.whenMatchedUpdateAll : plan: MergePlan -> MergePlan

Parameters

Name	Type	Description
plan	MergePlan	The current MergePlan being constructed.

Returns: A new MergePlan with an unconditional, full-row UPDATE action appended.

---

Merge.whenMatchedUpdateSet

Convenience shorthand for whenMatchedUpdate None (Some setters) – updates all matched rows but only the columns specified by the setters.

Merge.whenMatchedUpdateSet : setters: SetterSpec -> plan: MergePlan -> MergePlan

Parameters

Name	Type	Description
setters	SetterSpec	The SetterSpec (built via Set.build) defining which columns to update.
plan	MergePlan	The current MergePlan being constructed.

Returns: A new MergePlan with an unconditional, setter-defined UPDATE action appended.

---

Merge.whenNotMatchedBySourceDelete

Adds a "WHEN NOT MATCHED BY SOURCE DELETE" action to the merge plan. This deletes rows from the target that have no matching row in the source, optionally filtered by a condition.

Merge.whenNotMatchedBySourceDelete : condition: (MergeContext -> Expr) option -> plan: MergePlan -> MergePlan

Parameters

Name	Type	Description
condition	(MergeContext -> Expr) option	Optional condition expression builder using the MergeContext.
plan	MergePlan	The current MergePlan being constructed.

Returns: A new MergePlan with the DELETE (by source) action appended.

---

Merge.whenNotMatchedInsert

Adds a "WHEN NOT MATCHED INSERT" action to the merge plan. If the condition is not provided, all unmatched source rows are inserted. If setters are not provided, all source columns are inserted as-is. If setters are given, only those columns are populated (with the rest set to null/default).

Merge.whenNotMatchedInsert : condition: (MergeContext -> Expr) option -> setters: SetterSpec option -> plan: MergePlan -> MergePlan

Parameters

Name	Type	Description
condition	(MergeContext -> Expr) option	Optional condition expression builder using the MergeContext.
setters	SetterSpec option	Optional SetterSpec defining which columns to populate in the new row.
plan	MergePlan	The current MergePlan being constructed.

Returns: A new MergePlan with the INSERT action appended.

---

Merge.whenNotMatchedInsertAll

Convenience shorthand for whenNotMatchedInsert None None – inserts all unmatched source rows with all source columns.

Merge.whenNotMatchedInsertAll : plan: MergePlan -> MergePlan

Parameters

Name	Type	Description
plan	MergePlan	The current MergePlan being constructed.

Returns: A new MergePlan with an unconditional, full-row INSERT action appended.

---

Merge.whenNotMatchedInsertSet

Convenience shorthand for whenNotMatchedInsert None (Some setters) – inserts unmatched source rows but only the columns specified by the setters.

Merge.whenNotMatchedInsertSet : setters: SetterSpec -> plan: MergePlan -> MergePlan

Parameters

Name	Type	Description
setters	SetterSpec	The SetterSpec (built via Set.build) defining which columns to populate.
plan	MergePlan	The current MergePlan being constructed.

Returns: A new MergePlan with an unconditional, setter-defined INSERT action appended.

---