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(