Add changelog and more examples

CHANGELOG.md

@@ -1,3 +1,32 @@
+## 0.2.8 (Common, Node.js, Web)
+
+It is now possible to either specify a list of columns to insert the data into or a list of excluded columns:
+
+```ts
+// Generated query: INSERT INTO mytable (message) FORMAT JSONEachRow
+await client.insert({
+  table: 'mytable',
+  format: 'JSONEachRow',
+  values: [{ message: 'foo' }],
+  columns: ['message'],
+})
+
+// Generated query: INSERT INTO mytable (* EXCEPT (message)) FORMAT JSONEachRow
+await client.insert({
+  table: 'mytable',
+  format: 'JSONEachRow',
+  values: [{ id: 42 }],
+  columns: { exclude: ['message'] },
+})
+```
+
+See also the new examples:
+
+- [Including specific columns or excluding certain ones instead](./examples/insert_exclude_columns.ts)
+- [Leveraging this feature](./examples/insert_ephemeral_columns.ts) when working with
+  [ephemeral columns](https://clickhouse.com/docs/en/sql-reference/statements/create/table#ephemeral)
+  ([#217](https://github.com/ClickHouse/clickhouse-js/issues/217))
+
 ## 0.2.7 (Common, Node.js, Web)
 
 ### New features

examples/insert_ephemeral_columns.ts

@@ -10,12 +10,9 @@ void (async () => {
     },
   })
 
-  await client.command({
-    query: `DROP TABLE IF EXISTS ${tableName}`,
-  })
   await client.command({
     query: `
-      CREATE TABLE ${tableName}
+      CREATE OR REPLACE TABLE ${tableName}
       (
         event_type  LowCardinality(String) DEFAULT JSONExtractString(message_raw, 'type'),
         repo_name   LowCardinality(String) DEFAULT JSONExtractString(message_raw, 'repo', 'name'),

examples/insert_exclude_columns.ts

@@ -0,0 +1,65 @@
+import { createClient } from '@clickhouse/client' // or '@clickhouse/client-web'
+
+void (async () => {
+  const tableName = 'insert_exclude_columns'
+  const client = createClient()
+
+  await client.command({
+    query: `
+      CREATE OR REPLACE TABLE ${tableName}
+      (id UInt32, message String)
+      ENGINE MergeTree()
+      ORDER BY (id)
+    `,
+  })
+
+  /**
+   * Explicitly specifying a list of columns to insert the data into
+   */
+  await client.insert({
+    table: tableName,
+    values: [{ message: 'foo' }],
+    format: 'JSONEachRow',
+    // `id` column value for this row will be zero
+    columns: ['message'],
+  })
+
+  await client.insert({
+    table: tableName,
+    values: [{ id: 42 }],
+    format: 'JSONEachRow',
+    // `message` column value for this row will be an empty string
+    columns: ['id'],
+  })
+
+  /**
+   * Alternatively, it is possible to exclude certain columns instead
+   */
+  await client.insert({
+    table: tableName,
+    values: [{ message: 'bar' }],
+    format: 'JSONEachRow',
+    // `id` column value for this row will be zero
+    columns: {
+      except: ['id'],
+    },
+  })
+
+  await client.insert({
+    table: tableName,
+    values: [{ id: 144 }],
+    format: 'JSONEachRow',
+    // `message` column value for this row will be an empty string
+    columns: {
+      except: ['message'],
+    },
+  })
+
+  const rows = await client.query({
+    query: `SELECT * FROM ${tableName} ORDER BY id, message DESC`,
+    format: 'JSONEachRow',
+  })
+
+  console.info(await rows.json())
+  await client.close()
+})()