first example.

kysely-org · Oct 23, 2024 · 8bd213e · 8bd213e
1 parent 0acc7a4
commit 8bd213e
Show file tree

Hide file tree

Showing 8 changed files with 92 additions and 14 deletions.
diff --git 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
@@ -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
@@ -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)`
diff --git a/...s/examples/merge/0010-update-target-column-based-on-existence-of-source-row.mdx b/...s/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'
+
+<div style={{ marginBottom: '1em' }}>
+  <Playground code={updateTargetColumnBasedOnExistenceOfSourceRow} setupCode={exampleSetup} />
+</div>
+
+:::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
@@ -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
@@ -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
@@ -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<Date>
   age: number
+  has_pets: Generated<'Y' | 'N'>
 }
 
 interface PetTable {

diff --git a/src/query-creator.ts b/src/query-creator.ts
@@ -512,14 +512,18 @@ export class QueryCreator<DB> {
    *
    * ### Examples
    *
+   * <!-- siteExample("merge", "Update target column based on existence of source row", 10) -->
+   *
+   * 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<DB> {
    *
    * ```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<TR extends keyof DB & string>(