Skip to main content ホーム クリエイター comeonoliver skillshub clickhouse-sdk-patterns
clickhouse-sdk-patterns Production-ready patterns for @clickhouse/client — streaming inserts, typed queries,
error handling, and connection management.
Use when building robust ClickHouse integrations, implementing streaming,
or establishing team coding standards.
Trigger: "clickhouse SDK patterns", "clickhouse client patterns",
"clickhouse best practices", "clickhouse streaming insert".
インストールへ移動 Skills Marketplace コミュニティが作成したAIスキルを発見・探索
Codex または Claude でインストール この Prompt をコピーして Codex、Claude、または他のアシスタントに貼り付けると、Skill ページを確認してインストールできます。
直接コマンドでは確認用 Prompt が省略されます。実行前にソースを確認してください。
npx skills add https://github.com/ComeOnOliver/skillshub --skill clickhouse-sdk-patternsコマンドは1行のまま表示されます。コピー前に横へスクロールして全体を確認してください。
ローカルで確認しますか？SkillsMP が現在取得できるファイルをダウンロードできます。
Zipをダウンロード ダウンロード中... このリポジトリの他の Skills Review product and feature risk before an AI coding agent starts implementation.
Use Xquik for X data and confirmation-gated X actions: tweet search, user lookup, follower export, media download, monitors, webhooks, MCP, and SDK workflows.
Canton Network open-source ecosystem guide covering DAML SDK, Canton runtime, and Splice applications. Use when working with Canton Network, DAML smart contracts, or building decentralized applications.
name clickhouse-sdk-patterns description Production-ready patterns for @clickhouse/client — streaming inserts, typed queries,
error handling, and connection management.
Use when building robust ClickHouse integrations, implementing streaming,
or establishing team coding standards.
Trigger: "clickhouse SDK patterns", "clickhouse client patterns",
"clickhouse best practices", "clickhouse streaming insert".
allowed-tools Read, Write, Edit version 1.0.0 license MIT author Jeremy Longshore <jeremy@intentsolutions.io> tags ["saas","database","analytics","clickhouse","olap"] compatible-with claude-code
ClickHouse SDK Patterns
Overview
Production patterns for @clickhouse/client — typed queries, streaming inserts,
error handling, and connection lifecycle management.
Prerequisites
@clickhouse/client installed (see clickhouse-install-auth)Familiarity with async/await and Node.js streams
Instructions
Pattern 1: Typed Query Helper
import { createClient } from '@clickhouse/client' ;
const client = createClient ({
url : process.env .CLICKHOUSE_HOST !,
username : process.env .CLICKHOUSE_USER ?? 'default' ,
password : process.env .CLICKHOUSE_PASSWORD ?? '' ,
});
async function query<T>(sql : string , params ?: Record <string , unknown >): Promise <T[]> {
const rs = await client.query ({
query : sql,
query_params : params,
format : 'JSONEachRow' ,
});
return rs.json <T>();
}
interface EventCount {
event_type : string ;
cnt : string
const
await
EventCount
'SELECT event_type, count() AS cnt FROM events WHERE user_id = {user_id:UInt64} GROUP BY event_type'
user_id
42
Note on parameterized queries: ClickHouse uses {name:Type} syntax for parameters,
not $1 or ?. Always use typed parameters to prevent SQL injection.
Pattern 2: Streaming Insert (Backpressure-Safe) import { createClient } from '@clickhouse/client' ;
import { Readable } from 'stream' ;
async function streamInsert (rows : AsyncIterable <Record <string , unknown >>const stream = new Readable ({
objectMode : true ,
read (const insertPromise = client.insert ({
table : 'events' ,
values : stream,
format : 'JSONEachRow' ,
});
for await (const row of rows) {
if (!stream.push (row)) {
await new Promise <void >((resolve ) => stream.once ('drain' , resolve));
}
}
stream.push (null );
await insertPromise;
}
Pattern 3: Batch Insert with Retry async function batchInsert<T extends Record <string , unknown >>(
table : string ,
rows : T[],
batchSize = 10_000 ,
maxRetries = 3 ,
): Promise <{ inserted : number ; errors : Error [] }> {
let inserted = 0 ;
const errors : Error [] = [];
for (let i = 0 ; i < rows.length ; i += batchSize) {
const batch = rows.slice (i, i + batchSize);
let attempt = 0 ;
while (attempt < maxRetries) {
try {
await client.insert ({
table,
values : batch,
format : 'JSONEachRow' ,
});
inserted += batch.length ;
break ;
} catch (err) {
attempt++;
if (attempt === maxRetries) {
errors.push (err as Error );
} else {
await new Promise ((r ) => setTimeout (r, 1000 * Math .pow (2 , attempt)));
}
}
}
}
return { inserted, errors };
}
Pattern 4: Streaming SELECT (Low Memory)
async function * streamQuery<T>(sql : string ): AsyncGenerator <T> {
const rs = await client.query ({ query : sql, format : 'JSONEachRow' });
const stream = rs.stream ();
for await (const rows of stream) {
for (const row of rows) {
yield (row as { json : () => T }).json ();
}
}
}
for await (const event of streamQuery<{ event_type : string }>('SELECT * FROM events' )) {
process.stdout .write (`${event.event_type} \n` );
}
Pattern 5: Error Handling import { ClickHouseError } from '@clickhouse/client' ;
async function safeQuery<T>(sql : string ): Promise <{ data : T[] | null ; error : string | null }> {
try {
const rs = await client.query ({ query : sql, format : 'JSONEachRow' });
return { data : await rs.json <T>(), error : null };
} catch (err) {
if (err instanceof ClickHouseError ) {
console .error (`ClickHouse error ${err.code} : ${err.message} ` );
return { data : null , error : `CH-${err.code} : ${err.message} ` };
}
console .error ('Client error:' , (err as Error ).message );
return { data : null , error : (err as Error ).message };
}
}
Pattern 6: Connection Lifecycle
process.on ('SIGTERM' , async () => {
console .log ('Closing ClickHouse connection...' );
await client.close ();
process.exit (0 );
});
async function isHealthy (Promise <boolean > {
try {
const { success } = await client.ping ();
return success;
} catch {
return false ;
}
}
Pattern 7: ClickHouse Settings Per Query
const rs = await client.query ({
query : 'SELECT * FROM huge_table' ,
format : 'JSONEachRow' ,
clickhouse_settings : {
max_threads : 4 ,
max_memory_usage : 1_000_000_000 ,
max_execution_time : 30 ,
max_result_rows : 100_000 ,
},
});
Format Reference Format Use Case Streaming JSONEachRowStandard JSON rows (NDJSON) Yes JSONCompactEachRowArrays instead of objects (smaller) Yes CSVExport/import Yes TabSeparatedCLI-compatible output Yes ParquetAnalytics interchange Yes NativeFastest binary format Yes
Error Handling Error Code Meaning Action SYNTAX_ERROR (62)Bad SQL Fix query syntax UNKNOWN_TABLE (60)Table doesn't exist Check table name, database TOO_MANY_SIMULTANEOUS_QUERIES (202)Connection overload Reduce concurrency or pool MEMORY_LIMIT_EXCEEDED (241)Query uses too much RAM Add filters, use streaming TIMEOUT_EXCEEDED (159)Query too slow Optimize ORDER BY, add indexes
Resources
Next Steps Apply these patterns in clickhouse-core-workflow-a for real data modeling.
