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명령은 한 줄로 유지됩니다. 복사하기 전에 가로로 스크롤해 전체 내용을 확인하세요.
로컬 사본을 원하시나요? 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.
