عميل JS الرسمي للاتصال بـ ClickHouse.
العميل مكتوب بلغة TypeScript ويوفر تعريفات نوعية للواجهة البرمجية العامة للعميل.
لا يتضمن أي تبعيات، وهو مُحسَّن لتحقيق أقصى أداء، وقد اختُبر مع إصدارات وتهيئات مختلفة من ClickHouse (عقدة واحدة محلية، وعنقود محلي، وClickHouse Cloud).
تتوفر نسختان مختلفتان من العميل لبيئات مختلفة:
@clickhouse/client - Node.js فقط@clickhouse/client-web - المتصفحات (Chrome/Firefox)، Cloudflare workers
عند استخدام TypeScript، تأكد من أن الإصدار لا يقل عن version 4.5، إذ يتيح صياغة الاستيراد والتصدير المضمّنة.
يتوفر Source Code للعميل في مستودع ClickHouse-JS على GitHub.
مهارات AI agentيأتي عميل JS مزودًا بمهارات AI agent يمكن أن تساعد وكلاء البرمجة على العمل مع العميل. ثبّتها باستخدام:npm skills add ClickHouse/clickhouse-js
| إصدار Node.js | مدعوم؟ |
|---|
| 24.x | ✔ |
| 22.x | ✔ |
| 20.x | ✔ |
| 18.x | بأفضل جهد |
npm i @clickhouse/client-web
| إصدار العميل | ClickHouse |
|---|
| 1.12.0 | 24.8+ |
واجهة برمجة تطبيقات Client
createClient:
import { createClient } from '@clickhouse/client' // or '@clickhouse/client-web'
const client = createClient({
/* configuration */
})
const { createClient } = require('@clickhouse/client');
const client = createClient({
/* configuration */
})
| Setting | Description | Default Value | See Also | |
|---|
| url?: string | عنوان URL لمثيل ClickHouse. | http://localhost:8123 | وثائق تهيئة URL | |
| pathname?: string | مسار اختياري يُضاف إلى عنوان URL الخاص بـ ClickHouse بعد أن يعالجه العميل. | '' | وثائق الوكيل مع pathname | |
| request_timeout?: number | مهلة الطلب بالمللي ثانية. | 30_000 | - | |
compression?: { **response**?: boolean; **request**?: boolean } | تمكين الضغط. | - | وثائق الضغط | |
| username?: string | اسم المستخدم الذي تُرسَل الطلبات نيابةً عنه. | default | - | |
| password?: string | كلمة مرور المستخدم. | '' | - | |
| application?: string | اسم التطبيق الذي يستخدم عميل Node.js. | clickhouse-js | - | |
| database?: string | اسم قاعدة البيانات المراد استخدامها. | default | - | |
| clickhouse_settings?: ClickHouseSettings | إعدادات ClickHouse التي ستُطبَّق على جميع الطلبات. | {} | - | |
log?: { **LoggerClass**?: Logger, **level**?: ClickHouseLogLevel } | تهيئة سجلات العميل الداخلية. | - | وثائق التسجيل | |
| session_id?: string | معرّف جلسة ClickHouse اختياري يُرسَل مع كل طلب. | - | - | |
keep_alive?: { **enabled**?: boolean } | تكون مفعّلة افتراضيًا في كلٍّ من إصداري Node.js والويب. | - | - | |
http_headers?: Record<string, string> | رؤوس HTTP إضافية لطلبات ClickHouse الصادرة. | - | وثائق reverse proxy مع authentication | |
| roles?: string | string[] | أسماء الأدوار في ClickHouse لإرفاقها بالطلبات الصادرة. | - | استخدام الأدوار مع واجهة HTTP |
معلمات الإعداد الخاصة بـ Node.js
| الإعداد | الوصف | القيمة الافتراضية | انظر أيضًا | |
|---|
| max_open_connections?: number | الحد الأقصى لعدد المقابس المتصلة المسموح بها لكل مضيف. | 10 | - | |
tls?: { **ca_cert**: Buffer, **cert**?: Buffer, **key**?: Buffer } | إعداد شهادات TLS. | - | وثائق TLS | |
keep_alive?: { **enabled**?: boolean, **idle_socket_ttl**?: number } | - | - | وثائق Keep Alive | |
| http_agent?: http.Agent | https.Agent
| HTTP agent مخصّص للعميل. | - | وثائق HTTP agent |
set_basic_auth_header?: boolean
| يضبط ترويسة Authorization باستخدام بيانات اعتماد المصادقة الأساسية. | true | استخدام هذا الإعداد في وثائق HTTP agent | |
سيؤدي إعداد URL دائمًا إلى تجاوز القيم المضمّنة في الشيفرة، وسيُسجَّل تحذير في هذه الحالة.
http[s]://[username:password@]hostname:port[/database][?param1=value1¶m2=value2]. في معظم الحالات، يعكس اسم المَعلمة مسارها في واجهة خيارات config، مع بعض الاستثناءات. المَعلمات التالية مدعومة:
| المعلمة | النوع |
|---|
pathname | سلسلة نصية اعتباطية. |
application_id | سلسلة نصية اعتباطية. |
session_id | سلسلة نصية اعتباطية. |
request_timeout | رقم غير سالب. |
max_open_connections | رقم غير سالب وأكبر من الصفر. |
compression_request | قيمة منطقية. انظر أدناه (1) |
compression_response | قيمة منطقية. |
log_level | القيم المسموح بها: OFF, TRACE, DEBUG, INFO, WARN, ERROR. |
keep_alive_enabled | قيمة منطقية. |
clickhouse_setting_* or ch_* | انظر أدناه (2) |
http_header_* | انظر أدناه (3) |
(Node.js only) keep_alive_idle_socket_ttl | رقم غير سالب. |
- (1) بالنسبة إلى القيم المنطقية، تكون القيم الصالحة هي
true/1 وfalse/0.
- (2) ستُزال هذه البادئة من أي مَعلمة تبدأ بـ
clickhouse_setting_ أو ch_، وسيُضاف ما تبقى إلى clickhouse_settings الخاصة بالعميل. على سبيل المثال، سيكون ?ch_async_insert=1&ch_wait_for_async_insert=1 مماثلًا لما يلي:
createClient({
clickhouse_settings: {
async_insert: 1,
wait_for_async_insert: 1,
},
})
clickhouse_settings بصيغة 1/0 في عنوان URL.
- (3) مماثل لـ (2)، ولكن لتهيئة
http_header. على سبيل المثال، يكون ?http_header_x-clickhouse-auth=foobar مكافئًا لـ:
createClient({
http_headers: {
'x-clickhouse-auth': 'foobar',
},
})
اجمع بيانات الاتصال الخاصة بك
| المعلمات | الوصف |
|---|
HOST and PORT | عادةً ما يكون المنفذ 8443 عند استخدام TLS، أو 8123 عند عدم استخدام TLS. |
DATABASE NAME | افتراضيًا، توجد قاعدة بيانات باسم default. استخدم اسم قاعدة البيانات التي تريد الاتصال بها. |
USERNAME and PASSWORD | افتراضيًا، يكون اسم المستخدم default. استخدم اسم المستخدم المناسب لحالة الاستخدام لديك. |
curl.
إذا كنت تستخدم ClickHouse مُدارًا ذاتيًا، فسيُحدِّد مسؤول ClickHouse لديك تفاصيل الاتصال.
يدعم العميل الاتصال عبر بروتوكول HTTP أو HTTPS. دعم RowBinary قيد التنفيذ، راجع المشكلة ذات الصلة.
يوضح المثال التالي كيفية إعداد اتصال بـ ClickHouse Cloud. ويفترض أن قيمتَي url (بما في ذلك
البروتوكول والمنفذ) وpassword محددتان عبر متغيرات البيئة، وأن المستخدم default هو المستخدم المعتمد.
Example: إنشاء مثيل Client في Node.js باستخدام متغيرات البيئة في التهيئة.
import { createClient } from '@clickhouse/client'
const client = createClient({
url: process.env.CLICKHOUSE_HOST ?? 'http://localhost:8123',
username: process.env.CLICKHOUSE_USER ?? 'default',
password: process.env.CLICKHOUSE_PASSWORD ?? '',
})
مجمع الاتصالات (Node.js فقط)
10، ولكن يمكنك تغييره باستخدام خيار configuration max_open_connections.
لا يوجد ما يضمن استخدام الاتصال نفسه داخل المجمع للاستعلامات اللاحقة، ما لم يضبط المستخدم max_open_connections: 1. نادرًا ما تكون هناك حاجة إلى ذلك، لكنه قد يكون مطلوبًا في الحالات التي يستخدم فيها المستخدمون الجداول المؤقتة.
راجع أيضًا: إعداد Keep-Alive.
كل طريقة ترسل استعلامًا أو تعليمة (command, exec, insert, select) ستوفّر query_id في النتيجة. يعيّن العميل هذا المعرّف الفريد لكل استعلام، وقد يكون مفيدًا لاسترجاع البيانات من system.query_log،
إذا كان مفعّلًا في إعدادات الخادم، أو لإلغاء الاستعلامات طويلة التشغيل (راجع المثال). وعند الحاجة، يمكن للمستخدم تجاوز query_id في معاملات طرق command/query/exec/insert.
إذا كنت ستتجاوز المعلَمة query_id، فعليك التأكد من أنها فريدة في كل استدعاء. ويُعد UUID عشوائيًا خيارًا جيدًا.
المعلمات الأساسية لجميع طرق العميل
interface BaseQueryParams {
// ClickHouse settings that can be applied on query level.
clickhouse_settings?: ClickHouseSettings
// Parameters for query binding.
query_params?: Record<string, unknown>
// AbortSignal instance to cancel a query in progress.
abort_signal?: AbortSignal
// query_id override; if not specified, a random identifier will be generated automatically.
query_id?: string
// session_id override; if not specified, the session id will be taken from the client configuration.
session_id?: string
// credentials override; if not specified, the client's credentials will be used.
auth?: { username: string, password: string }
// A specific list of roles to use for this query. Overrides the roles set in the client configuration.
role?: string | Array<string>
}
SELECT، أو لإرسال تعليمات DDL مثل CREATE TABLE، ويجب استخدام await معها. ومن المتوقّع أن يستهلك التطبيق مجموعة النتائج المُعادة.
توجد طريقة مخصّصة هي insert لإدراج البيانات، وcommand لتعليميات DDL. interface QueryParams extends BaseQueryParams {
// Query to execute that might return some data.
query: string
// Format of the resulting dataset. Default: JSON.
format?: DataFormat
}
interface ClickHouseClient {
query(params: QueryParams): Promise<ResultSet>
}
لا تُحدِّد بند FORMAT في query، واستخدم المعلَمة format بدلًا من ذلك.
تجريدات مجموعة النتائج والصفوف
ResultSet عدة أساليب مريحة لمعالجة البيانات في تطبيقك.
يعتمد تنفيذ ResultSet في Node.js على Stream.Readable داخليًا، بينما يستخدم إصدار الويب واجهة Web API ReadableStream.
يمكنك استهلاك ResultSet باستدعاء الأسلوب text أو json على ResultSet، ما يؤدي إلى تحميل مجموعة الصفوف الكاملة التي يُرجعها الاستعلام إلى الذاكرة.
يجب أن تبدأ استهلاك ResultSet في أقرب وقت ممكن، لأنه يُبقي تدفق الاستجابة مفتوحًا، وبالتالي يُبقي الاتصال الأساسي مشغولًا. ولا يخزّن العميل البيانات الواردة مؤقتًا لتجنّب احتمال الاستهلاك المفرط للذاكرة من قِبل التطبيق.
بدلًا من ذلك، إذا كان كبيرًا جدًا بحيث لا يمكن تحميله في الذاكرة دفعةً واحدة، يمكنك استدعاء الأسلوب stream ومعالجة البيانات في وضع التدفق. في هذه الحالة، سيُحوَّل كل جزء من الاستجابة إلى مصفوفات صغيرة نسبيًا من الصفوف (ويعتمد حجم هذه المصفوفة على حجم الجزء الذي يستقبله العميل من الخادم، إذ قد يختلف، وكذلك على حجم الصف الواحد)، جزءًا تلو الآخر.
يُرجى الرجوع إلى قائمة تنسيقات البيانات المدعومة لتحديد التنسيق الأنسب للتدفق في حالتك. على سبيل المثال، إذا كنت تريد تدفق كائنات JSON، فيمكنك اختيار JSONEachRow، وعندها سيُحلَّل كل صف على أنه كائن JS، أو ربما التنسيق الأكثر إحكامًا JSONCompactColumns، حيث تكون كل صف عبارة عن مصفوفة مدمجة من القيم. انظر أيضًا: تدفق الملفات.
إذا لم يتم استهلاك ResultSet أو تدفقه بالكامل، فسيُتلف بعد فترة عدم النشاط request_timeout.
interface BaseResultSet<Stream> {
// See "Query ID" section above
query_id: string
// Consume the entire stream and get the contents as a string
// Can be used with any DataFormat
// Should be called only once
text(): Promise<string>
// Consume the entire stream and parse the contents as a JS object
// Can be used only with JSON formats
// Should be called only once
json<T>(): Promise<T>
// Returns a readable stream for responses that can be streamed
// Every iteration over the stream provides an array of Row[] in the selected DataFormat
// Should be called only once
stream(): Stream
}
interface Row {
// Get the content of the row as a plain string
text: string
// Parse the content of the row as a JS object
json<T>(): T
}
JSONEachRow، ويستهلك التدفق بالكامل ويحلّل المحتويات ككائنات JS.
الشيفرة المصدرية.
const resultSet = await client.query({
query: 'SELECT * FROM my_table',
format: 'JSONEachRow',
})
const dataset = await resultSet.json() // or `row.text` to avoid parsing JSON
JSONEachRow باستخدام الأسلوب التقليدي on('data'). وهذه الطريقة قابلة للتبديل مع صياغة for await const. الشيفرة المصدرية.
const rows = await client.query({
query: 'SELECT number FROM system.numbers_mt LIMIT 5',
format: 'JSONEachRow', // or JSONCompactEachRow, JSONStringsEachRow, etc.
})
const stream = rows.stream()
stream.on('data', (rows: Row[]) => {
rows.forEach((row: Row) => {
console.log(row.json()) // or `row.text` to avoid parsing JSON
})
})
await new Promise((resolve, reject) => {
stream.on('end', () => {
console.log('Completed!')
resolve(0)
})
stream.on('error', reject)
})
CSV باستخدام الأسلوب التقليدي on('data'). ويمكن استخدام هذا بالتبادل مع صياغة for await const.
الشيفرة المصدرية
const resultSet = await client.query({
query: 'SELECT number FROM system.numbers_mt LIMIT 5',
format: 'CSV', // or TabSeparated, CustomSeparated, etc.
})
const stream = resultSet.stream()
stream.on('data', (rows: Row[]) => {
rows.forEach((row: Row) => {
console.log(row.text)
})
})
await new Promise((resolve, reject) => {
stream.on('end', () => {
console.log('Completed!')
resolve(0)
})
stream.on('error', reject)
})
JSONEachRow مع استهلاكها باستخدام صياغة for await const. ويمكن استخدام هذا بالتبادل مع الأسلوب التقليدي on('data').
الشيفرة المصدرية.
const resultSet = await client.query({
query: 'SELECT number FROM system.numbers LIMIT 10',
format: 'JSONEachRow', // or JSONCompactEachRow, JSONStringsEachRow, etc.
})
for await (const rows of resultSet.stream()) {
rows.forEach(row => {
console.log(row.json())
})
}
بنية for await const تتطلب شيفرة أقل قليلًا من أسلوب on('data')، لكنها قد تؤثر سلبًا على الأداء.
راجع هذه التذكرة في مستودع Node.js لمزيد من التفاصيل. ReadableStream للكائنات.
const resultSet = await client.query({
query: 'SELECT * FROM system.numbers LIMIT 10',
format: 'JSONEachRow'
})
const reader = resultSet.stream().getReader()
while (true) {
const { done, value: rows } = await reader.read()
if (done) { break }
rows.forEach(row => {
console.log(row.json())
})
}
export interface InsertResult {
query_id: string
executed: boolean
}
interface ClickHouseClient {
insert(params: InsertParams): Promise<InsertResult>
}
insert، فلن تُرسل تعليمة insert إلى الخادم؛ وبدلًا من ذلك، ستُعيد الطريقة فورًا القيمة { query_id: '...', executed: false }. وإذا لم يتم تمرير query_id ضمن params الخاصة بالطريقة في هذه الحالة، فسيكون عبارة عن سلسلة فارغة في النتيجة، لأن إرجاع UUID عشوائي يُنشئه العميل قد يكون مُربكًا، إذ إن الاستعلام الذي يحمل query_id كهذا لن يكون موجودًا في جدول system.query_log.
إذا أُرسلت تعليمة insert إلى الخادم، فستكون قيمة العلامة executed هي true.
طريقة insert والبث في Node.js
Stream.Readable أو مع Array<T> عادية، وذلك حسب تنسيق البيانات المحدد لطريقة insert. راجع أيضًا هذا القسم حول بثّ الملفات.
يُفترض عادةً انتظار طريقة insert باستخدام await؛ ومع ذلك، يمكن تحديد تدفق إدخال ثم انتظار اكتمال عملية insert لاحقًا، عند اكتمال التدفق فقط (وسيؤدي ذلك أيضًا إلى حلّ الوعد insert). قد يكون هذا مفيدًا في مستمعي الأحداث والسيناريوهات المشابهة، لكن معالجة الأخطاء قد تكون معقدة بسبب كثرة الحالات الطرفية على جانب العميل. بدلًا من ذلك، ننصح باستخدام عمليات الإدخال غير المتزامنة كما هو موضح في هذا المثال.
interface InsertParams<T> extends BaseQueryParams {
// Table name to insert the data into
table: string
// A dataset to insert.
values: ReadonlyArray<T> | Stream.Readable
// Format of the dataset to insert.
format?: DataFormat
// Allows to specify which columns the data will be inserted into.
// - An array such as `['a', 'b']` will generate: `INSERT INTO table (a, b) FORMAT DataFormat`
// - An object such as `{ except: ['a', 'b'] }` will generate: `INSERT INTO table (* EXCEPT (a, b)) FORMAT DataFormat`
// By default, the data is inserted into all columns of the table,
// and the generated statement will be: `INSERT INTO table FORMAT DataFormat`.
columns?: NonEmptyArray<string> | { except: NonEmptyArray<string> }
}
لا يعني إلغاء طلب باستخدام abort_signal بالضرورة أن إدراج البيانات لم يحدث، إذ قد يكون الخادم قد تلقّى بعض البيانات المتدفقة قبل الإلغاء.
await client.insert({
table: 'my_table',
// structure should match the desired format, JSONEachRow in this example
values: [
{ id: 42, name: 'foo' },
{ id: 42, name: 'bar' },
],
format: 'JSONEachRow',
})
await client.insert({
table: 'my_table',
values: fs.createReadStream('./path/to/a/file.csv'),
format: 'CSV',
})
CREATE OR REPLACE TABLE mytable
(id UInt32, message String)
ENGINE MergeTree()
ORDER BY (id)
// Generated statement: INSERT INTO mytable (message) FORMAT JSONEachRow
await client.insert({
table: 'mytable',
values: [{ message: 'foo' }],
format: 'JSONEachRow',
// `id` column value for this row will be zero (default for UInt32)
columns: ['message'],
})
// Generated statement: INSERT INTO mytable (* EXCEPT (message)) FORMAT JSONEachRow
await client.insert({
table: tableName,
values: [{ id: 144 }],
format: 'JSONEachRow',
// `message` column value for this row will be an empty string
columns: {
except: ['message'],
},
})
await client.insert({
table: 'mydb.mytable', // Fully qualified name including the database
values: [{ id: 42, message: 'foo' }],
format: 'JSONEachRow',
})
@clickhouse/client-web إلا مع التنسيقات Array<T> وJSON*.
ولا تزال عمليات الإدراج باستخدام التدفقات غير مدعومة في نسخة الويب بسبب ضعف التوافق مع المتصفحات.
وبناءً على ذلك، تبدو الواجهة InsertParams في نسخة الويب مختلفة قليلًا عن إصدار Node.js،
إذ تقتصر values على النوع ReadonlyArray<T> فقط:
interface InsertParams<T> extends BaseQueryParams {
// Table name to insert the data into
table: string
// A dataset to insert.
values: ReadonlyArray<T>
// Format of the dataset to insert.
format?: DataFormat
// Allows to specify which columns the data will be inserted into.
// - An array such as `['a', 'b']` will generate: `INSERT INTO table (a, b) FORMAT DataFormat`
// - An object such as `{ except: ['a', 'b'] }` will generate: `INSERT INTO table (* EXCEPT (a, b)) FORMAT DataFormat`
// By default, the data is inserted into all columns of the table,
// and the generated statement will be: `INSERT INTO table FORMAT DataFormat`.
columns?: NonEmptyArray<string> | { except: NonEmptyArray<string> }
}
CREATE TABLE أو ALTER TABLE.
يجب انتظارها باستخدام await.
يتم إنهاء response stream فورًا، ما يعني تحرير الـ socket الأساسي.
interface CommandParams extends BaseQueryParams {
// Statement to execute.
query: string
}
interface CommandResult {
query_id: string
}
interface ClickHouseClient {
command(params: CommandParams): Promise<CommandResult>
}
await client.command({
query: `
CREATE TABLE IF NOT EXISTS my_cloud_table
(id UInt64, name String)
ORDER BY (id)
`,
// Recommended for cluster usage to avoid situations where a query processing error occurred after the response code,
// and HTTP headers were already sent to the client.
// See https://clickhouse.com/docs/interfaces/http/#response-buffering
clickhouse_settings: {
wait_end_of_query: 1,
},
})
await client.command({
query: `
CREATE TABLE IF NOT EXISTS my_table
(id UInt64, name String)
ENGINE MergeTree()
ORDER BY (id)
`,
})
await client.command({
query: `INSERT INTO my_table SELECT '42'`,
})
إلغاء طلب باستخدام abort_signal لا يضمن أن الخادم لم ينفّذ التعليمة.
query/insert،
وكنت مهتمًا بالنتيجة، فيمكنك استخدام exec كبديل عن command.
تعيد exec تدفقًا قابلاً للقراءة ويجب أن يستهلكه التطبيق أو يتلفه.
interface ExecParams extends BaseQueryParams {
// Statement to execute.
query: string
}
interface ClickHouseClient {
exec(params: ExecParams): Promise<QueryResult>
}
export interface QueryResult {
stream: Stream.Readable
query_id: string
}
export interface QueryResult {
stream: ReadableStream
query_id: string
}
ping المخصّصة للتحقق من حالة الاتصال القيمة true إذا كان الوصول إلى الخادم ممكنًا.
إذا تعذر الوصول إلى الخادم، فسيُضمَّن الخطأ الأساسي أيضًا في النتيجة.
type PingResult =
| { success: true }
| { success: false; error: Error }
/** Parameters for the health-check request - using the built-in `/ping` endpoint.
* This is the default behavior for the Node.js version. */
export type PingParamsWithEndpoint = {
select: false
/** AbortSignal instance to cancel a request in progress. */
abort_signal?: AbortSignal
/** Additional HTTP headers to attach to this particular request. */
http_headers?: Record<string, string>
}
/** Parameters for the health-check request - using a SELECT query.
* This is the default behavior for the Web version, as the `/ping` endpoint does not support CORS.
* Most of the standard `query` method params, e.g., `query_id`, `abort_signal`, `http_headers`, etc. will work,
* except for `query_params`, which does not make sense to allow in this method. */
export type PingParamsWithSelectQuery = { select: true } & Omit<
BaseQueryParams,
'query_params'
>
export type PingParams = PingParamsWithEndpoint | PingParamsWithSelectQuery
interface ClickHouseClient {
ping(params?: PingParams): Promise<PingResult>
}
/ping، بينما يستخدم إصدار الويب استعلام SELECT 1 بسيطًا لتحقيق نتيجة مماثلة، لأن نقطة النهاية /ping لا تدعم CORS.
مثال: (Node.js/Web) إجراء ping بسيط على مثيل خادم ClickHouse. ملاحظة: بالنسبة إلى إصدار الويب، ستكون الأخطاء التي يتم التقاطها مختلفة.
الشفرة المصدرية.
const result = await client.ping();
if (!result.success) {
// process result.error
}
ping، أو تمرير معلمات إضافية مثل query_id، فيمكنك القيام بذلك على النحو التالي:
const result = await client.ping({ select: true, /* query_id, abort_signal, http_headers, or any other query params */ });
query القياسية — راجع تعريف النوع PingParamsWithSelectQuery.
يغلق جميع الاتصالات المفتوحة ويحرّر الموارد. لا ينفّذ أي إجراء في إصدار الويب.
تدفق الملفات (Node.js فقط)
query (JSONEachRow وCSV وما إلى ذلك) واسم ملف الإخراج.
يتعامل العميل مع تنسيقات البيانات بصيغة JSON أو كنص.
إذا حدّدت format كأحد التنسيقات من عائلة JSON (JSONEachRow وJSONCompactEachRow وما إلى ذلك)، فسيقوم العميل بتسلسل البيانات وفك تسلسلها أثناء نقلها.
أما البيانات المقدَّمة بتنسيقات النص “الخام” (عائلتا CSV وTabSeparated وCustomSeparated) فتُرسل كما هي من دون أي تحويلات إضافية.
قد يحدث التباس بين JSON كتنسيق عام وتنسيق ClickHouse JSON.يدعم العميل تدفق كائنات JSON باستخدام تنسيقات مثل JSONEachRow (راجع الجدول للاطلاع على التنسيقات الأخرى المناسبة للتدفق؛ وراجع أيضًا أمثلة select_streaming_ في مستودع العميل).لكن تنسيقات مثل ClickHouse JSON وبعض التنسيقات الأخرى تُمثَّل ككائن واحد في الاستجابة، لذلك لا يمكن للعميل تدفقها. | التنسيق | الإدخال (مصفوفة) | الإدخال (كائن) | الإدخال/الإخراج (تدفق) | الإخراج (JSON) | الإخراج (نص) |
|---|
| JSON | ❌ | ✔️ | ❌ | ✔️ | ✔️ |
| JSONCompact | ❌ | ✔️ | ❌ | ✔️ | ✔️ |
| JSONObjectEachRow | ❌ | ✔️ | ❌ | ✔️ | ✔️ |
| JSONColumnsWithMetadata | ❌ | ✔️ | ❌ | ✔️ | ✔️ |
| JSONStrings | ❌ | ❌️ | ❌ | ✔️ | ✔️ |
| JSONCompactStrings | ❌ | ❌ | ❌ | ✔️ | ✔️ |
| JSONEachRow | ✔️ | ❌ | ✔️ | ✔️ | ✔️ |
| JSONEachRowWithProgress | ❌️ | ❌ | ✔️ ❗- انظر أدناه | ✔️ | ✔️ |
| JSONStringsEachRow | ✔️ | ❌ | ✔️ | ✔️ | ✔️ |
| JSONCompactEachRow | ✔️ | ❌ | ✔️ | ✔️ | ✔️ |
| JSONCompactStringsEachRow | ✔️ | ❌ | ✔️ | ✔️ | ✔️ |
| JSONCompactEachRowWithNames | ✔️ | ❌ | ✔️ | ✔️ | ✔️ |
| JSONCompactEachRowWithNamesAndTypes | ✔️ | ❌ | ✔️ | ✔️ | ✔️ |
| JSONCompactStringsEachRowWithNames | ✔️ | ❌ | ✔️ | ✔️ | ✔️ |
| JSONCompactStringsEachRowWithNamesAndTypes | ✔️ | ❌ | ✔️ | ✔️ | ✔️ |
| CSV | ❌ | ❌ | ✔️ | ❌ | ✔️ |
| CSVWithNames | ❌ | ❌ | ✔️ | ❌ | ✔️ |
| CSVWithNamesAndTypes | ❌ | ❌ | ✔️ | ❌ | ✔️ |
| TabSeparated | ❌ | ❌ | ✔️ | ❌ | ✔️ |
| TabSeparatedRaw | ❌ | ❌ | ✔️ | ❌ | ✔️ |
| TabSeparatedWithNames | ❌ | ❌ | ✔️ | ❌ | ✔️ |
| TabSeparatedWithNamesAndTypes | ❌ | ❌ | ✔️ | ❌ | ✔️ |
| CustomSeparated | ❌ | ❌ | ✔️ | ❌ | ✔️ |
| CustomSeparatedWithNames | ❌ | ❌ | ✔️ | ❌ | ✔️ |
| CustomSeparatedWithNamesAndTypes | ❌ | ❌ | ✔️ | ❌ | ✔️ |
| Parquet | ❌ | ❌ | ✔️ | ❌ | ✔️❗- انظر أدناه |
JSONEachRowWithProgress هو تنسيق مخصص للإخراج فقط ويدعم الإبلاغ عن التقدم ضمن التدفق. راجع هذا المثال لمزيد من التفاصيل.
تتوفّر القائمة الكاملة لتنسيقات الإدخال والإخراج في ClickHouse
هنا.
أنواع بيانات ClickHouse المدعومة
يكون نوع JS المقابل ذا صلة بأي من تنسيقات JSON*، باستثناء التنسيقات التي تمثل كل شيء كسلسلة نصية (مثل JSONStringEachRow)
| النوع | الحالة | نوع JS |
|---|
| UInt8/16/32 | ✔️ | number |
| UInt64/128/256 | ✔️ ❗- انظر أدناه | string |
| Int8/16/32 | ✔️ | number |
| Int64/128/256 | ✔️ ❗- انظر أدناه | string |
| Float32/64 | ✔️ | number |
| Decimal | ✔️ ❗- انظر أدناه | number |
| Boolean | ✔️ | boolean |
| String | ✔️ | string |
| FixedString | ✔️ | string |
| UUID | ✔️ | string |
| Date32/64 | ✔️ | string |
| DateTime32/64 | ✔️ ❗- انظر أدناه | string |
| Enum | ✔️ | string |
| LowCardinality | ✔️ | string |
| Array(T) | ✔️ | T[] |
| (new) JSON | ✔️ | object |
| Variant(T1, T2…) | ✔️ | T (بحسب البديل) |
| Dynamic | ✔️ | T (بحسب البديل) |
| Nested | ✔️ | T[] |
| Tuple(T1, T2, …) | ✔️ | [T1, T2, …] |
| Tuple(n1 T1, n2 T2…) | ✔️ | { n1: T1; n2: T2; …} |
| Nullable(T) | ✔️ | نوع JS لـ T أو null |
| IPv4 | ✔️ | string |
| IPv6 | ✔️ | string |
| Point | ✔️ | [ number, number ] |
| Ring | ✔️ | Array<Point> |
| Polygon | ✔️ | Array<Ring> |
| MultiPolygon | ✔️ | Array<Polygon> |
| Map(K, V) | ✔️ | Record<K, V> |
| Time/Time64 | ✔️ | string |
Date/Date32 إلا
على هيئة سلاسل نصية.
مثال: أدرِج قيمة من النوع Date.
الشفرة المصدرية
await client.insert({
table: 'my_table',
values: [ { date: '2022-09-05' } ],
format: 'JSONEachRow',
})
DateTime أو DateTime64، يمكنك استخدام كلٍّ من السلاسل النصية وكائنات JS Date. ويمكن تمرير كائنات JS Date إلى insert كما هي عند تعيين date_time_input_format إلى best_effort. راجع هذا المثال لمزيد من التفاصيل.
يمكن إدراج القيم من نوع Decimal باستخدام تنسيقات عائلة JSON*. بافتراض أن لدينا جدولًا معرّفًا على النحو التالي:
CREATE TABLE my_table
(
id UInt32,
dec32 Decimal(9, 2),
dec64 Decimal(18, 3),
dec128 Decimal(38, 10),
dec256 Decimal(76, 20)
)
ENGINE MergeTree()
ORDER BY (id)
await client.insert({
table: 'my_table',
values: [{
id: 1,
dec32: '1234567.89',
dec64: '123456789123456.789',
dec128: '1234567891234567891234567891.1234567891',
dec256: '12345678912345678912345678911234567891234567891234567891.12345678911234567891',
}],
format: 'JSONEachRow',
})
JSON*، سيُرجع ClickHouse قيم Decimal على شكل أرقام افتراضيًا، ما قد يؤدي إلى فقدان الدقة. ولتجنّب ذلك، يمكنك تحويل قيم Decimal إلى سلاسل نصية في الاستعلام:
await client.query({
query: `
SELECT toString(dec32) AS decimal32,
toString(dec64) AS decimal64,
toString(dec128) AS decimal128,
toString(dec256) AS decimal256
FROM my_table
`,
format: 'JSONEachRow',
})
الأنواع الصحيحة: Int64, Int128, Int256, UInt64, UInt128, UInt256
JSON* لتجنّب
تجاوز سعة الأعداد الصحيحة، لأن القيم القصوى لهذه الأنواع أكبر من Number.MAX_SAFE_INTEGER.
ومع ذلك، يمكن تعديل هذا السلوك
باستخدام إعداد output_format_json_quote_64bit_integers
.
مثال: اضبط تنسيق إخراج JSON للأرقام ذات 64 بت.
const resultSet = await client.query({
query: 'SELECT * from system.numbers LIMIT 1',
format: 'JSONEachRow',
})
expect(await resultSet.json()).toEqual([ { number: '0' } ])
const resultSet = await client.query({
query: 'SELECT * from system.numbers LIMIT 1',
format: 'JSONEachRow',
clickhouse_settings: { output_format_json_quote_64bit_integers: 0 },
})
expect(await resultSet.json()).toEqual([ { number: 0 } ])
const client = createClient({
clickhouse_settings: {}
})
client.query({
clickhouse_settings: {}
})
تأكد من أن المستخدم الذي تُنفَّذ الاستعلامات نيابةً عنه يملك الصلاحيات الكافية لتغيير الإعدادات.
name — معرّف بديل.data_type - نوع البيانات لقيمة معلمة التطبيق.
مثال:: استعلام بمعلمات.
الشيفرة المصدرية
.
await client.query({
query: 'SELECT plus({val1: Int32}, {val2: Int32})',
format: 'CSV',
query_params: {
val1: 10,
val2: 20,
},
})
GZIP باستخدام zlib.
createClient({
compression: {
response: true,
request: true
}
})
response: true يوجّه ClickHouse server إلى إرسال محتوى استجابة مضغوط. القيمة الافتراضية: response: falserequest: true يفعّل الضغط لمحتوى طلب العميل. القيمة الافتراضية: request: false
يُعدّ التسجيل ميزة تجريبية وقد يتغيّر مستقبلًا.
logger الافتراضية سجلات التسجيل إلى stdout عبر الطريقتين console.debug/info، وإلى stderr عبر الطريقتين console.warn/error.
يمكنك تخصيص منطق التسجيل من خلال توفير LoggerClass، واختيار مستوى السجل المطلوب عبر المَعلَمة level (القيمة الافتراضية هي WARN):
import type { Logger } from '@clickhouse/client'
// All three LogParams types are exported by the client
interface LogParams {
module: string
message: string
args?: Record<string, unknown>
}
type ErrorLogParams = LogParams & { err: Error }
type WarnLogParams = LogParams & { err?: Error }
class MyLogger implements Logger {
trace({ module, message, args }: LogParams) {
// ...
}
debug({ module, message, args }: LogParams) {
// ...
}
info({ module, message, args }: LogParams) {
// ...
}
warn({ module, message, args }: WarnLogParams) {
// ...
}
error({ module, message, args, err }: ErrorLogParams) {
// ...
}
}
const client = createClient({
log: {
LoggerClass: MyLogger,
level: ClickHouseLogLevel.DEBUG,
}
})
TRACE - معلومات منخفضة المستوى حول دورة حياة اتصالات Keep-AliveDEBUG - معلومات الاستجابة (من دون رؤوس التفويض ومعلومات المضيف)INFO - غير مستخدم في الغالب، وسيطبع مستوى السجل الحالي عند تهيئة العميلWARN - أخطاء غير جسيمة؛ يُسجَّل طلب ping الفاشل كتحذير، لأن الخطأ الأساسي يكون مضمنًا في النتيجة المُعادةERROR - أخطاء جسيمة من طرائق query/insert/exec/command، مثل فشل الطلب
يمكنك العثور على التنفيذ الافتراضي لـ Logger هنا.
شهادات TLS (Node.js فقط)
certs
وأن اسم ملف CA هو CA.pem:
const client = createClient({
url: 'https://<hostname>:<port>',
username: '<username>',
password: '<password>', // if required
tls: {
ca_cert: fs.readFileSync('certs/CA.pem'),
},
})
const client = createClient({
url: 'https://<hostname>:<port>',
username: '<username>',
tls: {
ca_cert: fs.readFileSync('certs/CA.pem'),
cert: fs.readFileSync(`certs/client.crt`),
key: fs.readFileSync(`certs/client.key`),
},
})
إعداد Keep-Alive (Node.js فقط)
Connection: keep-alive. وتبقى المقابس الخاملة في تجمّع الاتصالات لمدة 2500 مللي ثانية افتراضيًا (راجِع الملاحظات حول ضبط هذا الخيار).
يُفترض أن تكون قيمة keep_alive.idle_socket_ttl أقل بفارق ملحوظ من إعداد الخادم/موازن التحميل. والسبب الرئيسي هو أنه نظرًا إلى أن HTTP/1.1 يسمح للخادم بإغلاق المقابس من دون إخطار العميل، فإذا أغلق الخادم أو موازن التحميل الاتصال قبل أن يفعل العميل ذلك، فقد يحاول العميل إعادة استخدام مقبس مغلق، ما يؤدي إلى الخطأ socket hang up.
إذا كنت تعدّل keep_alive.idle_socket_ttl، فضع في اعتبارك أنه ينبغي أن يظل متزامنًا دائمًا مع إعداد Keep-Alive في الخادم/موازن التحميل لديك، ويجب أن يكون أقل منه دائمًا، بما يضمن ألا يغلق الخادم الاتصال المفتوح أولًا.
يضبط العميل keep_alive.idle_socket_ttl على 2500 مللي ثانية، إذ يمكن اعتبارها القيمة الافتراضية الأكثر أمانًا؛ وعلى جانب الخادم، قد يُضبط keep_alive_timeout إلى قيمة منخفضة تصل إلى 3 ثوانٍ في إصدارات ClickHouse الأقدم من 23.11 من دون أي تعديلات على config.xml.
إذا كنت راضيًا عن الأداء ولا تواجه أي مشكلات، فمن المستحسن عدم زيادة قيمة الإعداد keep_alive.idle_socket_ttl، لأن ذلك قد يؤدي إلى أخطاء محتملة من نوع “Socket hang-up”؛ بالإضافة إلى ذلك، إذا كان تطبيقك يرسل الكثير من الاستعلامات ولم تكن هناك فواصل زمنية طويلة بينها، فمن المفترض أن تكون القيمة الافتراضية كافية، لأن المقابس لن تبقى في حالة خمول لمدة كافية، وسيُبقيها العميل في المجمّع.
curl -is --data-binary "SELECT 1" <clickhouse_url>
Connection وKeep-Alive في الاستجابة. على سبيل المثال:
Connection: Keep-Alive
Keep-Alive: timeout=10
keep_alive_timeout 10 ثوانٍ، ويمكنك محاولة زيادة keep_alive.idle_socket_ttl إلى 9000 أو حتى 9500 مللي ثانية لإبقاء المقابس الخاملة مفتوحةً لفترة أطول قليلًا من الإعداد الافتراضي. راقب أخطاء “Socket hang-up” المحتملة، إذ تشير إلى أن الخادم يغلق الاتصالات قبل أن يفعل العميل ذلك، وخفِّض القيمة حتى تختفي الأخطاء.
إذا كنت تواجه أخطاء socket hang up حتى عند استخدام أحدث إصدار من العميل، فإليك الخيارات التالية لحل هذه المشكلة:
-
فعِّل السجلات بمستوى
WARN على الأقل (وهو المستوى الافتراضي). يتيح لك ذلك التحقق مما إذا كان هناك stream غير مُستهلك أو معلّق في شيفرة التطبيق: إذ ستسجّله طبقة النقل عند مستوى WARN، لأن ذلك قد يؤدي إلى إغلاق socket من جانب الخادم. يمكنك تفعيل التسجيل في إعدادات العميل كما يلي:
const client = createClient({
log: { level: ClickHouseLogLevel.WARN },
})
-
تأكد من تطبيق الإعدادات المطلوبة على مثيل العميل الصحيح. إذا كان لديك عدة مثيلات للعميل في تطبيقك، فتحقق مرة أخرى من أن المثيل الذي تستخدمه للاستعلامات يحتوي على القيمة الصحيحة للإعداد
keep_alive.idle_socket_ttl.
-
خفِّض قيمة الإعداد
keep_alive.idle_socket_ttl في إعدادات العميل بمقدار 500 ملي ثانية. في بعض الحالات، مثل ارتفاع كمون الشبكة بين العميل والخادم، قد يكون ذلك مفيدًا لتفادي الحالة التي يحصل فيها الطلب الصادر على socket يكون الخادم على وشك إغلاقها.
-
إذا كان هذا الخطأ يحدث أثناء استعلامات طويلة التشغيل من دون دخول أو خروج أي بيانات (على سبيل المثال،
INSERT FROM SELECT طويلة التشغيل)، فقد يكون السبب هو موازن تحميل أو مكونات شبكة أخرى تغلق الاتصالات طويلة الأمد أو الطلبات طويلة التشغيل. يمكنك محاولة فرض ورود بعض البيانات أثناء الاستعلامات طويلة التشغيل باستخدام مجموعة إعدادات ClickHouse التالية:
const client = createClient({
// هنا نفترض أن لدينا بعض الاستعلامات التي يتجاوز وقت تنفيذها 5 دقائق
request_timeout: 400_000,
/** تسمح هذه الإعدادات مجتمعة بتجنب مشكلات انتهاء مهلة موازن التحميل في حالة الاستعلامات طويلة التشغيل من دون دخول أو خروج بيانات،
* مثل `INSERT FROM SELECT` وما شابهها، إذ قد يعتبر موازن التحميل الاتصال خاملًا ويغلقه بشكل مفاجئ.
* في هذه الحالة، نفترض أن مهلة الاتصال الخامل في موازن التحميل هي 120 ثانية، لذلك نضبط 110 ثوانٍ كقيمة "آمنة". */
clickhouse_settings: {
send_progress_in_http_headers: 1,
http_headers_progress_interval_ms: '110000', // UInt64، يجب تمريره كسلسلة نصية
},
})
mutations لا تُلغى عند فقدان الاتصال. راجع هذا المثال (الجزء 2) لمزيد من التفاصيل.
-
يمكن تعطيل ميزة Keep-Alive بالكامل. في هذه الحالة، سيضيف العميل أيضًا الترويسة
Connection: close إلى كل HTTP request، ولن يعيد وكيل HTTP الأساسي استخدام الاتصالات. وسيتم تجاهل الإعداد keep_alive.idle_socket_ttl، إذ لن تكون هناك sockets خاملة. وسيؤدي ذلك إلى حمل إضافي، لأن اتصالًا جديدًا سيُنشأ لكل طلب.
const client = createClient({
keep_alive: {
enabled: false,
},
})
-
استبعد المشكلات المحتملة في بقية مكدس الشبكة، بما في ذلك Node.js نفسها، وذلك عبر تشغيل اختبار بسيط من سطر الأوامر على مثيل ClickHouse نفسه وعبر مسار الشبكة نفسه (أي من الجهاز نفسه أو من مقطع الشبكة نفسه، مثل Kubernetes pod)، على سبيل المثال باستخدام
curl:
curl -is --user '<user>:<password>' --data-binary "SELECT 1" <clickhouse_url>
curl، فمن المرجح أن المشكلة لا تتعلق بإعدادات العميل، بل بمكدس الشبكة أو إعدادات الخادم.
-
لاختبار الاتصال باستخدام وظائف Node.js الأساسية، يمكنك محاولة إنشاء HTTP request بسيطة إلى ClickHouse server باستخدام واجهة
fetch API المضمنة:
const response = await fetch('<clickhouse_url>?query=SELECT+1', {
method: 'POST',
headers: {
'Authorization': 'Basic ' + Buffer.from('<user>:<password>').toString('base64'),
}
})
-
في بعض الحالات، قد تضيف شيفرة التطبيق أو مهايئات إطار العمل استدعاء
ping() استباقيًا قبل تنفيذ الاستعلام الفعلي، ما قد يؤدي إلى نجاح طلب ping() ثم فشل طلب الاستعلام اللاحق بخطأ “socket hang up” بسبب المشكلة الأساسية نفسها المرتبطة بالاتصالات الخاملة. إذا لاحظت هذا النمط في السجلات، فحاول التحقق مما إذا كان إطار العمل أو شيفرة التطبيق يوفّران خيارًا لتعطيل عمليات ping() الاستباقية. ومن شأن ذلك أيضًا تقليل احتمال فرض قيود على المعدل من أي من مكوّنات الشبكة الوسيطة.
-
تأكد من أن التطبيق نفسه يحصل على وقت CPU كافٍ، وأن الشبكة لا يفرض عليها موفّر الاستضافة تقييدًا على المعدل. كما يمكن أن تساعد وسائل المراقبة المختلفة، مثل مقاييس توقّف GC ومقاييس تأخر حلقة الأحداث وغيرها من المقاييس المشابهة، في استبعاد المشكلات المحتملة المتعلقة بشحّ الموارد.
-
جرّب فحص شيفرة تطبيقك مع تفعيل قاعدة ESLint no-floating-promises، إذ سيساعد ذلك في تحديد الوعود غير المعالَجة التي قد تؤدي إلى تدفقات ومقابس معلّقة.
المستخدمون ذوو صلاحية القراءة فقط
enable_http_compression. سينتج عن التكوين التالي خطأ:
const client = createClient({
compression: {
response: true, // won't work with a readonly=1 user
},
})
readonly=1.
إذا كان مثيل ClickHouse لديك خلف وكيل، وكان عنوان URL يتضمن مسارًا كما في المثال http://proxy:8123/clickhouse_server، فحدِّد clickhouse_server كقيمة لخيار الإعداد pathname (مع أو بدون شرطة مائلة في البداية)؛ وإلا، فإذا أُدرج مباشرةً في url فسيُعامَل على أنه قيمة الخيار database. كما أن المسارات متعددة المقاطع مدعومة، مثل /my_proxy/db.
const client = createClient({
url: 'http://proxy:8123',
pathname: '/clickhouse_server',
})
http_headers لتمرير الترويسات اللازمة من خلاله:
const client = createClient({
http_headers: {
'My-Auth-Header': '...',
},
})
وكيل HTTP/HTTPS مخصّص (تجريبي، Node.js فقط)
هذه ميزة تجريبية وقد تتغير مستقبلًا بطرق غير متوافقة مع الإصدارات السابقة. ينبغي أن يكون التنفيذ الافتراضي والإعدادات التي يوفّرها العميل كافيين لمعظم حالات الاستخدام. لا تستخدم هذه الميزة إلا إذا كنت متأكدًا من حاجتك إليها.
max_open_connections وkeep_alive.enabled وtls) ليتولى إدارة الاتصالات مع خادم ClickHouse. بالإضافة إلى ذلك، إذا استُخدمت شهادات TLS، فسيُهيّأ الوكيل الأساسي بالشهادات اللازمة، وسيُفرض استخدام ترويسات مصادقة TLS الصحيحة.
بعد 1.2.0، أصبح من الممكن تزويد العميل بوكيل HTTP أو HTTPS مخصّص ليحل محل الوكيل الأساسي الافتراضي. وقد يكون ذلك مفيدًا في حالات إعدادات الشبكة المعقدة. تنطبق الشروط التالية إذا جرى توفير وكيل مخصّص:
- لن يكون للخيارين
max_open_connections وtls أي تأثير، وسيتجاهلهما العميل، لأنهما جزء من إعداد الوكيل الأساسي.
- سيقتصر دور
keep_alive.enabled على تحديد القيمة الافتراضية لترويسة Connection (true -> Connection: keep-alive، false -> Connection: close).
- رغم أن إدارة مقابس keep-alive الخاملة ستظل تعمل (لأنها غير مرتبطة بالوكيل بل بالمقبس نفسه)، فقد أصبح الآن من الممكن تعطيلها بالكامل بتعيين قيمة
keep_alive.idle_socket_ttl إلى 0.
أمثلة على استخدام الوكيل المخصّص
const agent = new http.Agent({ // or https.Agent
keepAlive: true,
keepAliveMsecs: 2500,
maxSockets: 10,
maxFreeSockets: 10,
})
const client = createClient({
http_agent: agent,
})
const agent = new https.Agent({
keepAlive: true,
keepAliveMsecs: 2500,
maxSockets: 10,
maxFreeSockets: 10,
ca: fs.readFileSync('./ca.crt'),
})
const client = createClient({
url: 'https://myserver:8443',
http_agent: agent,
// With a custom HTTPS agent, the client won't use the default HTTPS connection implementation; the headers should be provided manually
http_headers: {
'X-ClickHouse-User': 'username',
'X-ClickHouse-Key': 'password',
},
// Important: authorization header conflicts with the TLS headers; disable it.
set_basic_auth_header: false,
})
const agent = new https.Agent({
keepAlive: true,
keepAliveMsecs: 2500,
maxSockets: 10,
maxFreeSockets: 10,
ca: fs.readFileSync('./ca.crt'),
cert: fs.readFileSync('./client.crt'),
key: fs.readFileSync('./client.key'),
})
const client = createClient({
url: 'https://myserver:8443',
http_agent: agent,
// With a custom HTTPS agent, the client won't use the default HTTPS connection implementation; the headers should be provided manually
http_headers: {
'X-ClickHouse-User': 'username',
'X-ClickHouse-Key': 'password',
'X-ClickHouse-SSL-Certificate-Auth': 'on',
},
// Important: authorization header conflicts with the TLS headers; disable it.
set_basic_auth_header: false,
})
Authorization الافتراضية عبر الإعداد set_basic_auth_header (المُضافة في 1.2.0)، لأنها تتعارض مع ترويسات TLS. يجب توفير جميع ترويسات TLS يدويًا.
القيود المعروفة (Node.js/web)
- يعمل البث مع استعلامات SELECT، لكنه معطّل لعمليات الإدراج (وعلى مستوى النوع أيضًا).
- ضغط الطلبات معطّل، ويتم تجاهل التهيئة الخاصة به. أمّا ضغط الاستجابات فيعمل.
- لا يتوفر دعم للتسجيل حتى الآن.
- لتقليل استهلاك ذاكرة التطبيق، فكّر في استخدام التدفقات مع عمليات
insert الكبيرة (مثلًا من الملفات) وعمليات select عند الاقتضاء. وبالنسبة إلى مستمعي الأحداث وحالات الاستخدام المشابهة، قد تكون عمليات insert غير المتزامنة خيارًا جيدًا آخر، إذ تتيح تقليل التجميع على جانب العميل إلى الحد الأدنى، أو حتى تجنّبه تمامًا. تتوفر أمثلة على عمليات insert غير المتزامنة في مستودع العميل، مع async_insert_ كبادئة لاسم الملف.
- لا يفعّل العميل ضغط الطلبات أو الاستجابات افتراضيًا. ومع ذلك، عند تنفيذ عمليات
select أو insert على مجموعات بيانات كبيرة، يمكنك التفكير في تفعيله عبر ClickHouseClientConfigOptions.compression (إما لـ request فقط أو response فقط أو لكليهما).
- يترتب على الضغط أثر ملحوظ على الأداء. فتفعيله لـ
request أو response سيؤثر سلبًا في سرعة عمليات select أو insert، على التوالي، لكنه سيقلّل مقدار حركة مرور الشبكة التي ينقلها التطبيق.
إذا كانت لديك أي أسئلة أو كنت بحاجة إلى مساعدة، فلا تتردد في التواصل معنا عبر Community Slack (القناة #clickhouse-js) أو من خلال المشكلات على GitHub. 
