improve select function calls example

Author: koskimas

site/docs/examples/SELECT/0060-function-calls.js

@@ -1,15 +1,29 @@
-export const functionCalls = `const result = await db.selectFrom('person')
+export const functionCalls = `import { sql } from 'kysely'
+
+const result = await db.selectFrom('person')
   .innerJoin('pet', 'pet.owner_id', 'person.id')
-  .select(({ fn }) => [
+  .select(({ fn, val, ref }) => [
     'person.id',
 
     // The \`fn\` module contains the most common
     // functions.
     fn.count<number>('pet.id').as('pet_count'),
 
-    // You can call any function using the
-    // \`agg\` method
-    fn.agg<string[]>('array_agg', ['pet.name']).as('pet_names')
+    // You can call any function by calling \`fn\` directly.
+    // The arguments are treated as column references by
+    // default. If you want  to pass in values, use the
+    // \`val\` function.
+    fn<string>('concat', [val('Ms. '), 'first_name', 'last_name']).as('full_name_with_title'),
+
+    // You can call any aggregate function using the
+    // \`fn.agg\` function.
+    fn.agg<string[]>('array_agg', ['pet.name']).as('pet_names'),
+
+    // And once again, you can use the \`sql\` template tag.
+    // The template tag substitutions are treated as values
+    // by default. If you want to reference columns, you can
+    // use the \`ref\` function.
+    sql<string>\`concat(\${ref('first_name')}, \${ref('last_name')})\`.as('full_name')
   ])
   .groupBy('person.id')
   .having((eb) => eb.fn.count('pet.id'), '>', 10)

src/query-builder/function-module.ts

@@ -34,18 +34,32 @@ import { Selectable } from '../util/column-type.js'
  * This example uses the `fn` module to select some aggregates:
  *
  * ```ts
+ * import { sql } from 'kysely'
+ *
  * const result = await db.selectFrom('person')
  *   .innerJoin('pet', 'pet.owner_id', 'person.id')
- *   .select(({ fn }) => [
+ *   .select(({ fn, val, ref }) => [
  *     'person.id',
  *
  *     // The `fn` module contains the most common
  *     // functions.
  *     fn.count<number>('pet.id').as('pet_count'),
  *
- *     // You can call any function using the
- *     // `agg` method
- *     fn.agg<string[]>('array_agg', ['pet.name']).as('pet_names')
+ *     // You can call any function by calling `fn` directly.
+ *     // The arguments are treated as column references by
+ *     // default. If you want  to pass in values, use the
+ *     // `val` function.
+ *     fn<string>('concat', [val('Ms. '), 'first_name', 'last_name']).as('full_name_with_title'),
+ *
+ *     // You can call any aggregate function using the
+ *     // `fn.agg` function.
+ *     fn.agg<string[]>('array_agg', ['pet.name']).as('pet_names'),
+ *
+ *     // And once again, you can use the `sql` template tag.
+ *     // The template tag substitutions are treated as values
+ *     // by default. If you want to reference columns, you can
+ *     // use the `ref` function.
+ *     sql<string>`concat(${ref('first_name')}, ${ref('last_name')})`.as('full_name')
  *   ])
  *   .groupBy('person.id')
  *   .having((eb) => eb.fn.count('pet.id'), '>', 10)
@@ -58,11 +72,13 @@ import { Selectable } from '../util/column-type.js'
  * select
  *   "person"."id",
  *   count("pet"."id") as "pet_count",
- *   array_agg("pet"."name") as "pet_names"
+ *   concat($1, "first_name", "last_name") as "full_name_with_title",
+ *   array_agg("pet"."name") as "pet_names",
+ *   concat("first_name", "last_name") as "full_name"
  * from "person"
  * inner join "pet" on "pet"."owner_id" = "person"."id"
  * group by "person"."id"
- * having count("pet"."id") > $1
+ * having count("pet"."id") > $2
  * ```
  */
 export interface FunctionModule<DB, TB extends keyof DB> {