improve subquery insert example

kysely-org · Mar 22, 2024 · 0e194b0 · 0e194b0
1 parent ead3489
commit 0e194b0
Show file tree

Hide file tree

Showing 2 changed files with 6 additions and 2 deletions.
diff --git a/site/docs/examples/INSERT/0050-insert-subquery.mdx b/site/docs/examples/INSERT/0050-insert-subquery.mdx
@@ -4,7 +4,9 @@ title: 'Insert subquery'
 
 # Insert subquery
 
-You can create an `INSERT INTO SELECT FROM` query using the `expression` method:
+You can create an `INSERT INTO SELECT FROM` query using the `expression` method.
+This API doesn't follow our WYSIWYG principles and might be a bit difficult to
+remember. The reasons for this design stem from implementation difficulties.
 
 import {
   Playground,

diff --git a/src/query-builder/insert-query-builder.ts b/src/query-builder/insert-query-builder.ts
@@ -285,7 +285,9 @@ export class InsertQueryBuilder<DB, TB extends keyof DB, O>
    *
    * <!-- siteExample("insert", "Insert subquery", 50) -->
    *
-   * You can create an `INSERT INTO SELECT FROM` query using the `expression` method:
+   * You can create an `INSERT INTO SELECT FROM` query using the `expression` method.
+   * This API doesn't follow our WYSIWYG principles and might be a bit difficult to
+   * remember. The reasons for this design stem from implementation difficulties.
    *
    * ```ts
    * const result = await db.insertInto('person')