diff --git a/scripts/generate-site-examples.js b/scripts/generate-site-examples.js
index 54030150f..a667470ab 100644
--- a/scripts/generate-site-examples.js
+++ b/scripts/generate-site-examples.js
@@ -71,6 +71,24 @@ const moreExamplesByCategory = {
'returning method':
'https://kysely-org.github.io/kysely-apidoc/classes/DeleteQueryBuilder.html#returning',
},
+ merge: {
+ 'mergeInto method':
+ 'https://kysely-org.github.io/kysely-apidoc/classes/Kysely.html#mergeInto',
+ 'using method':
+ 'https://kysely-org.github.io/kysely-apidoc/classes/MergeQueryBuilder.html#using',
+ 'whenMatched method':
+ 'https://kysely-org.github.io/kysely-apidoc/classes/WheneableMergeQueryBuilder.html#whenMatched',
+ 'thenUpdateSet method':
+ 'https://kysely-org.github.io/kysely-apidoc/classes/MatchedThenableMergeQueryBuilder.html#thenUpdateSet',
+ 'thenDelete method':
+ 'https://kysely-org.github.io/kysely-apidoc/classes/MatchedThenableMergeQueryBuilder.html#thenDelete',
+ 'thenDoNothing method':
+ 'https://kysely-org.github.io/kysely-apidoc/classes/MatchedThenableMergeQueryBuilder.html#thenDoNothing',
+ 'whenNotMatched method':
+ 'https://kysely-org.github.io/kysely-apidoc/classes/WheneableMergeQueryBuilder.html#whenNotMatched',
+ 'thenInsertValues method':
+ 'https://kysely-org.github.io/kysely-apidoc/classes/NotMatchedThenableMergeQueryBuilder.html#thenInsertValues',
+ },
transactions: {
'transaction method':
'https://kysely-org.github.io/kysely-apidoc/classes/Kysely.html#transaction',
diff --git a/site/docs/examples/cte/_category_.json b/site/docs/examples/cte/_category_.json
index da9e25b76..a4fc30836 100644
--- a/site/docs/examples/cte/_category_.json
+++ b/site/docs/examples/cte/_category_.json
@@ -1,6 +1,6 @@
{
"label": "CTE",
- "position": 7,
+ "position": 9,
"link": {
"type": "generated-index",
"description": "Short and simple examples of how to use Common Table Expressions (CTE) in queries."
diff --git a/site/docs/examples/merge/0010-update-target-column-based-on-existence-of-source-row.js b/site/docs/examples/merge/0010-update-target-column-based-on-existence-of-source-row.js
new file mode 100644
index 000000000..a3b589f7d
--- /dev/null
+++ b/site/docs/examples/merge/0010-update-target-column-based-on-existence-of-source-row.js
@@ -0,0 +1,10 @@
+export const updateTargetColumnBasedOnExistenceOfSourceRow = `const result = await db
+ .mergeInto('person as target')
+ .using('pet as source', 'source.owner_id', 'target.id')
+ .whenMatchedAnd('target.has_pets', '!=', 'Y')
+ .thenUpdateSet({ has_pets: 'Y' })
+ .whenNotMatchedBySourceAnd('target.has_pets', '=', 'Y')
+ .thenUpdateSet({ has_pets: 'N' })
+ .executeTakeFirstOrThrow()
+
+console.log(result.numChangedRows)`
\ No newline at end of file
diff --git a/site/docs/examples/merge/0010-update-target-column-based-on-existence-of-source-row.mdx b/site/docs/examples/merge/0010-update-target-column-based-on-existence-of-source-row.mdx
new file mode 100644
index 000000000..a7d0a589f
--- /dev/null
+++ b/site/docs/examples/merge/0010-update-target-column-based-on-existence-of-source-row.mdx
@@ -0,0 +1,36 @@
+---
+title: 'Update target column based on existence of source row'
+---
+
+# Update target column based on existence of source row
+
+Update a target column based on the existence of a source row:
+
+import {
+ Playground,
+ exampleSetup,
+} from '../../../src/components/Playground'
+
+import {
+ updateTargetColumnBasedOnExistenceOfSourceRow
+} from './0010-update-target-column-based-on-existence-of-source-row'
+
+
+
+:::info[More examples]
+The API documentation is packed with examples. The API docs are hosted [here](https://kysely-org.github.io/kysely-apidoc/),
+but you can access the same documentation by hovering over functions/methods/classes in your IDE. The examples are always
+just one hover away!
+
+For example, check out these sections:
+ - [mergeInto method](https://kysely-org.github.io/kysely-apidoc/classes/Kysely.html#mergeInto)
+ - [using method](https://kysely-org.github.io/kysely-apidoc/classes/MergeQueryBuilder.html#using)
+ - [whenMatched method](https://kysely-org.github.io/kysely-apidoc/classes/WheneableMergeQueryBuilder.html#whenMatched)
+ - [thenUpdateSet method](https://kysely-org.github.io/kysely-apidoc/classes/MatchedThenableMergeQueryBuilder.html#thenUpdateSet)
+ - [thenDelete method](https://kysely-org.github.io/kysely-apidoc/classes/MatchedThenableMergeQueryBuilder.html#thenDelete)
+ - [thenDoNothing method](https://kysely-org.github.io/kysely-apidoc/classes/MatchedThenableMergeQueryBuilder.html#thenDoNothing)
+ - [whenNotMatched method](https://kysely-org.github.io/kysely-apidoc/classes/WheneableMergeQueryBuilder.html#whenNotMatched)
+ - [thenInsertValues method](https://kysely-org.github.io/kysely-apidoc/classes/NotMatchedThenableMergeQueryBuilder.html#thenInsertValues)
+:::
diff --git a/site/docs/examples/merge/_category_.json b/site/docs/examples/merge/_category_.json
new file mode 100644
index 000000000..add6bbea8
--- /dev/null
+++ b/site/docs/examples/merge/_category_.json
@@ -0,0 +1,8 @@
+{
+ "label": "MERGE",
+ "position": 7,
+ "link": {
+ "type": "generated-index",
+ "description": "Short and simple examples of how to write MERGE queries."
+ }
+}
diff --git a/site/docs/examples/transactions/_category_.json b/site/docs/examples/transactions/_category_.json
index c304bc27f..8fa52772e 100644
--- a/site/docs/examples/transactions/_category_.json
+++ b/site/docs/examples/transactions/_category_.json
@@ -1,6 +1,6 @@
{
"label": "Transactions",
- "position": 6,
+ "position": 8,
"link": {
"type": "generated-index",
"description": "Short and simple examples of how to use transactions."
diff --git a/site/src/components/Playground.tsx b/site/src/components/Playground.tsx
index 17c664000..ee823e951 100644
--- a/site/src/components/Playground.tsx
+++ b/site/src/components/Playground.tsx
@@ -77,8 +77,8 @@ interface PlaygroundState {
export const exampleSetup = `import { Generated } from 'kysely'
export interface Database {
- person: PersonTable
- pet: PetTable
+ person: PersonTable
+ pet: PetTable
}
interface PersonTable {
@@ -87,6 +87,7 @@ interface PersonTable {
last_name: string | null
created_at: Generated
age: number
+ has_pets: Generated<'Y' | 'N'>
}
interface PetTable {
diff --git a/src/query-creator.ts b/src/query-creator.ts
index 5291fee28..c1f330427 100644
--- a/src/query-creator.ts
+++ b/src/query-creator.ts
@@ -512,14 +512,18 @@ export class QueryCreator {
*
* ### Examples
*
+ *
+ *
+ * Update a target column based on the existence of a source row:
+ *
* ```ts
* const result = await db
- * .mergeInto('person')
- * .using('pet', 'pet.owner_id', 'person.id')
- * .whenMatched((and) => and('has_pets', '!=', 'Y'))
+ * .mergeInto('person as target')
+ * .using('pet as source', 'source.owner_id', 'target.id')
+ * .whenMatchedAnd('target.has_pets', '!=', 'Y')
* .thenUpdateSet({ has_pets: 'Y' })
- * .whenNotMatched()
- * .thenDoNothing()
+ * .whenNotMatchedBySourceAnd('target.has_pets', '=', 'Y')
+ * .thenUpdateSet({ has_pets: 'N' })
* .executeTakeFirstOrThrow()
*
* console.log(result.numChangedRows)
@@ -529,11 +533,12 @@ export class QueryCreator {
*
* ```sql
* merge into "person"
- * using "pet" on "pet"."owner_id" = "person"."id"
- * when matched and "has_pets" != $1 then
- * update set "has_pets" = $2
- * when not matched then
- * do nothing
+ * using "pet"
+ * on "pet"."owner_id" = "person"."id"
+ * when matched and "has_pets" != $1
+ * then update set "has_pets" = $2
+ * when not matched by source and "has_pets" = $3
+ * then update set "has_pets" = $4
* ```
*/
mergeInto(