diff --git a/CHANGELOG.md b/CHANGELOG.md index c66e4159..da1601ab 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/examples/insert_ephemeral_columns.ts b/examples/insert_ephemeral_columns.ts index 0bd7af94..c621be10 100644 --- a/examples/insert_ephemeral_columns.ts +++ b/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'), diff --git a/examples/insert_exclude_columns.ts b/examples/insert_exclude_columns.ts new file mode 100644 index 00000000..5a1ff865 --- /dev/null +++ b/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() +})()