Builder to specify how to merge data from source DataFrame into the target Delta table. You can specify any number of whenMatched and whenNotMatched clauses. Here are the constraints on these clauses.

• whenMatched clauses:
  • The condition in a whenMatched clause is optional. However, if there are multiple whenMatched clauses, then only the last one may omit the condition.
  • When there are more than one whenMatched clauses and there are conditions (or the lack of) such that a row satisfies multiple clauses, then the action for the first clause satisfied is executed. In other words, the order of the whenMatched clauses matters.
  • If none of the whenMatched clauses match a source-target row pair that satisfy the merge condition, then the target rows will not be updated or deleted.
  • If you want to update all the columns of the target Delta table with the corresponding column of the source DataFrame, then you can use the whenMatched(...).updateAll(). This is equivalent to

            whenMatched(...).updateExpr(Map(
              ("col1", "source.col1"),
              ("col2", "source.col2"),
              ...))
    

• whenNotMatched clauses:
  • The condition in a whenNotMatched clause is optional. However, if there are multiple whenNotMatched clauses, then only the last one may omit the condition.
  • When there are more than one whenNotMatched clauses and there are conditions (or the lack of) such that a row satisfies multiple clauses, then the action for the first clause satisfied is executed. In other words, the order of the whenNotMatched clauses matters.
  • If no whenNotMatched clause is present or if it is present but the non-matching source row does not satisfy the condition, then the source row is not inserted.
  • If you want to insert all the columns of the target Delta table with the corresponding column of the source DataFrame, then you can use whenNotMatched(...).insertAll(). This is equivalent to

            whenNotMatched(...).insertExpr(Map(
              ("col1", "source.col1"),
              ("col2", "source.col2"),
              ...))
    

• whenNotMatchedBySource clauses:
  • The condition in a whenNotMatchedBySource clause is optional. However, if there are multiple whenNotMatchedBySource clauses, then only the last one may omit the condition.
  • When there are more than one whenNotMatchedBySource clauses and there are conditions (or the lack of) such that a row satisfies multiple clauses, then the action for the first clause satisfied is executed. In other words, the order of the whenNotMatchedBySource clauses matters.
  • If no whenNotMatchedBySource clause is present or if it is present but the non-matching target row does not satisfy any of the whenNotMatchedBySource clause condition, then the target row will not be updated or deleted.

Scala example to update a key-value Delta table with new key-values from a source DataFrame:

deltaTable
 .as("target")
 .merge(
   source.as("source"),
   "target.key = source.key")
 .withSchemaEvolution()
 .whenMatched()
 .updateExpr(Map(
   "value" -> "source.value"))
 .whenNotMatched()
 .insertExpr(Map(
   "key" -> "source.key",
   "value" -> "source.value"))
 .whenNotMatchedBySource()
 .updateExpr(Map(
   "value" -> "target.value + 1"))
 .execute()

Java example to update a key-value Delta table with new key-values from a source DataFrame:

deltaTable
 .as("target")
 .merge(
   source.as("source"),
   "target.key = source.key")
 .withSchemaEvolution()
 .whenMatched()
 .updateExpr(
    new HashMap<String, String>() {{
      put("value", "source.value");
    }})
 .whenNotMatched()
 .insertExpr(
    new HashMap<String, String>() {{
     put("key", "source.key");
     put("value", "source.value");
   }})
 .whenNotMatchedBySource()
 .updateExpr(
    new HashMap<String, String>() {{
     put("value", "target.value + 1");
   }})
 .execute();