البروتوكول الأصلي

البروتوكول الأصلي هو بروتوكول ثنائي موجَّه بالاتصال تتخاطب به عملاء وخوادم ClickHouse عبر TCP. وهو ينقل استعلامات SQL، وبيانات النتائج، وحمولات INSERT، وبيانات القياس عن بُعد الخاصة بالتنفيذ، وإشارات الأخطاء. وهو البروتوكول الذي يستند إليه عميل سطر الأوامر وC++ ومعظم برامج التشغيل الأصلية من جهات خارجية.

تغطي هذه الصفحة البروتوكول نفسه: تأطير الحزم، وآلة حالات الاتصال، والتفاوض على الإصدار، وجسم كل رسالة لا تنتمي إلى Block. أما البايتات داخل حزم عائلة Data (أي Block، وأعمدته، وترميزات كل نوع) فهي موضوع منفصل، موثَّق في مواصفة Native Format.

هناك بعض الخصائص التي تنطبق على امتداد البروتوكول. فالبروتوكول ثنائي وموضعي: لا توجد وسوم للحقول إلا داخل BlockInfo، لذا فإن أي بايت يوضع في غير موضعه يفقد المزامنة مع كل ما يليه. وهو بروتوكول ذو حالة، ويعالج كل اتصال TCP استعلامًا واحدًا في كل مرة — ولا توجد فيه آلية تعدد الإرسال. أما الأعداد الصحيحة ثابتة العرض فتُخزَّن بترتيب little-endian.

تبدأ كل رسالة برمز نوع حزمة VarUInt، يتبعه جسم يعتمد شكله على ذلك الرمز وعلى إصدار البروتوكول المتفاوض عليه.

يمر الاتصال عبر ثلاث مراحل — مصافحة لمرة واحدة، ثم أي عدد من عمليات تبادل Ping أو Query، ثم الإغلاق:

sequenceDiagram
    autonumber
    participant C as Client
    participant S as Server

    C->>S: TCP connect

    rect rgb(220, 235, 255)
        Note over C,S: Handshake
        C->>S: ClientHello (name, version, db, user, password)
        S->>C: ServerHello (server_name, version, [timezone, display_name, ...])
        Note over C,S: negotiated_version = min(client, server)
        opt negotiated_version ≥ 54458
            C->>S: Addendum (quota_key)
        end
    end

    rect rgb(220, 245, 225)
        Note over C,S: Query phase
        C->>S: Query packet (ClientInfo, settings, params, SQL)
        C->>S: External-table Data packets (0 or more)
        C->>S: Empty Data marker — the "go" signal
        loop until EndOfStream or Exception
            S->>C: Data / Progress / Log / ProfileInfo / Totals / ...
        end
        S->>C: EndOfStream
    end

ينقل بروتوكول TCP الأصلي دائمًا البيانات الجدولية بتنسيق Native، بغضّ النظر عن أي عبارة FORMAT في SQL. أمّا إعادة تنسيقها إلى RowBinary وCSV وJSON وما إلى ذلك، فهي من مهام العميل، وتتم بعد فك ترميز كتل Native. (أمّا واجهة HTTP فلها مسار برمجي مختلف يلتزم فعلًا بعبارة FORMAT؛ لكن HTTP خارج نطاق هذا المحتوى هنا.)

يقع TLS في طبقة النقل، أسفل البروتوكول. وعند تفعيله، يُشفَّر تيار TCP بالكامل، وتظل رسائل البروتوكول متطابقة تمامًا، بايتًا ببايت، سواء استُخدم TLS أم لا.

تحدث المصادقة أثناء المصافحة، في رسالة ClientHello. يُنقل الحقلان user وpassword كسلاسل نصية غير مشفّرة، لذا فإن التشفير على مستوى النقل (TLS) هو ما يحمي بيانات الاعتماد أثناء انتقالها.

يفسّر الخادم حقل user الفارغ على أنه مستخدم الجلسة الافتراضي المُهيأ: إعداد الخادم default_session_user (الذي قيمته الافتراضية هي default)، والذي قد يُتجاوز لكل مستمع في قسم protocols. إذا كان الخادم مُهيأً بمستخدم جلسة افتراضي فارغ، أو كان أقدم من الإصدار 26.8، يُرفض حقل user الفارغ مع استثناء. لاحظ أن clickhouse-client لا يرسل اسم مستخدم فارغًا مطلقًا: إذ يستبدل به default من جهة العميل.

تتوفر مصادقة التحدي والاستجابة عبر SSH بدءًا من إصدار البروتوكول 54466 — راجع مصادقة التحدي والاستجابة عبر SSH.

لتنفيذ الاستعلامات الموزعة، تتحقق الخوادم من هوية بعضها بعضًا عبر إثبات معرفة سر مشترك — من دون إرسال السر نفسه عبر الشبكة. تتضمن كل Query قيمة auth_hash بطول 32 بايت من نوع SHA-256 في الحقل 4 من Query، وتُحتسب استنادًا إلى salt وnonce والسر المُعدّ والاستعلام، ثم يعيد الخادم المستقبِل احتسابها ويقارنها. ولا يُفعَّل ذلك إلا مع الميزة INTERSERVER_SECRET ‏(v54441). وترسل البرامج العميلة الخارجية دائمًا سلسلة فارغة هنا. راجع المصادقة بين الخوادم.

يُعلن كلٌّ من العميل والخادم عن الحد الأقصى لإصدار البروتوكول الذي يدعمه أثناء المصافحة. ويكون الإصدار المتفَق عليه هو الأصغر بين الاثنين:

negotiated_version = min(client_version, server_version)

تستخدم كل رسالة بعد ذلك الإصدار المتفق عليه لتحديد الحقول الموجودة في البيانات المنقولة.

تُحدَّد كل ميزة بإصدار البروتوكول الذي أدخلها، وتكون مفعّلة عندما يكون الإصدار المتفاوض عليه أكبر من هذا الرقم أو مساويًا له.

تشترك كل رسالة متبادلة عبر الشبكة في البنية الخارجية نفسها، في كلا الاتجاهين:

[VarUInt: packet_type_code]    always encoded as VarUInt
[message body]                 format depends on packet_type_code

توجد جداول أنواع الحزم الكاملة في مرجع نوع الحزمة.

نوع الحزمة هو VarUInt، وليس بايتًا ثابت العرض. بالنسبة إلى القيم الأقل من 128، ينتج VarUInt البايت المفرد نفسه، لكن يجب على التطبيقات استخدام ترميز VarUInt حتى تظل متوافقة إذا وصلت أنواع الحزم المستقبلية إلى 128 أو أكثر.

يوثّق مرجع الرسائل جسم كل حزمة فقط — أي البايتات التي تأتي بعد رمز نوع الحزمة. يبدأ ترقيم الحقول من 1 مع أول حقل في الجسم.

عند التفاوض على الميزة CHUNKED_PROTOCOL (راجع المصافحة)، تُغلَّف كل حزمة على مستوى النقل بتأطير مُجزّأ. ويكون هذا التغليف منفصلًا لكل اتجاه: إذ يجري التفاوض على client→server و server→client كلٌّ على حدة، وقد ينتهي كل منهما إلى وضع مختلف (مُجزّأ أو غير مؤطَّر).

البنية على مستوى النقل لكل حزمة:

<chunk>...   one or more chunks; their payloads concatenated form the whole packet
[u32 LE = 0] zero-size terminator marking end of packet

تنسيق wire لكل chunk:

[u32 LE: chunk_size]   chunk_size in [1, UINT32_MAX]
[chunk_size bytes]     packet bytes (see note below)

نوع الحزمة VarUInt يكون داخل التدفق المُجزّأ: فهو البايت الأول من حمولة الحزمة (أي البايت الأول من أول جزء)، وليس بايتًا منفصلًا يُرسَل مسبقًا قبل التأطير. حمولة الجزء لكل حزمة هي [VarUInt packet_type_code][message body] كاملةً كما ترد في غلاف الحزمة. وأي عميل يترك نوع الحزمة خارج التدفق المُجزّأ يجعل الطرف الآخر يقرأ بايت النوع هذا على أنه البايت الأول من حجم الجزء u32، ما يؤدي إلى فقدان تزامن الاتصال.

قد تُقسَّم الحزمة الواحدة على عدة أجزاء إذا امتلأ المخزن المؤقت الخاص بالكاتب أثناء كتابة الحزمة؛ ويمكن أن يقع هذا الانقسام في أي موضع، بما في ذلك داخل VarUInt الخاص بنوع الحزمة. يقوم القارئ بضم حمولات الأجزاء، ويتعامل مع الصفر اللاحق المكوَّن من 4 بايتات على أنه حد شفاف للحزمة — فيستهلكه، لكنه لا يمرّره إلى أي مكوّن يقرأ أجسام الحزم.

الحزم التي لا تحتوي على جسم تُغلَّف أيضًا: فالحزمة أحادية البايت مثل Ping أو Pong تصبح [u32 size = 1][0x04][u32 0] بمجرد الاتفاق على التجزئة. وأي وصف من نوع "بايت واحد على مستوى النقل" في موضع آخر من هذه الصفحة يشير إلى الصيغة السابقة للتجزئة.

التفاوض. يحمل كلٌّ من ServerHello وAddendum حقلي String، واحدًا لكل اتجاه، بقيم مأخوذة من {"chunked", "notchunked", "chunked_optional", "notchunked_optional"}:

• chunked / notchunked وضعان صارمان: ذلك الجانب يشترط هذا الوضع تحديدًا.
• صيغ _optional مرنة: فهي تقبل أيًّا من الوضعين الذي يختاره الطرف الآخر.

تُحتسب القيمة المتفق عليها لكل اتجاه على أساس ثنائي:

على جانب العميل، يُفاوَض تفضيل SEND الخاص بالعميل مع تفضيل RECV الخاص بالخادم، والعكس صحيح.

التوقيت. تنتقل سلاسل التفاوض عبر قناة غير مؤطَّرة: ClientHello → ServerHello (تفضيلات الخادم) → Addendum (القيم التي تفاوض عليها العميل). ويُطبَّق التحول إلى التأطير على كل بايت يُرسَل بعد تفريغ Addendum. أما Addendum نفسه وClientHello وServerHello فتبقى دائمًا غير مؤطَّرة.

في أي وقت، يكون الاتصال في واحدة فقط من أربع حالات: HANDSHAKE أو READY أو READING_RESPONSE أو يكون قد انتهى. وبما أن البروتوكول لا يدعم تعدد الإرسال، فإن العميل الذي يرسل طلبًا جديدًا قبل قراءة الاستجابة السابقة بالكامل سيتسبب في تداخل البايتات أثناء النقل وإفساد التدفق.

stateDiagram-v2
    [*] --> HANDSHAKE: TCP connect

    HANDSHAKE --> READY: handshake ok
    READY --> READING_RESPONSE: send Query
    READING_RESPONSE --> READY: EndOfStream / Exception
    READY --> READY: Ping / Pong

    HANDSHAKE --> Terminated: handshake error
    READING_RESPONSE --> Terminated: protocol violation / I/O error
    READY --> Terminated: close
    Terminated --> [*]

يسير المسار المثالي مباشرةً إلى الأسفل — HANDSHAKE → READY → READING_RESPONSE → READY — مع الحلقة الذاتية لـ Ping/Pong، فيما تصبّ جميع حواف الفشل في المصب الوحيد Terminated.

تتم المصادقة والتفاوض على إصدار البروتوكول. يحدث ذلك مرة واحدة فقط لكل اتصال، قبل أي شيء آخر.

فُتح اتصال TCP للتو، ولم تُتبادل أي رسائل بعد. ويكون التسلسل كالتالي:

sequenceDiagram
    autonumber
    participant C as Client
    participant S as Server

    C->>S: ClientHello
    alt success
        S->>C: ServerHello
    else error
        S->>C: Exception — connection terminates
    end
    Note over C,S: negotiated_version = min(client, server)
    opt negotiated_version ≥ 54458
        C->>S: Addendum
    end

1. يرسل العميل ClientHello مع أعلى إصدار بروتوكول يدعمه.

2. يقرأ العميل الاستجابة ويعالجها وفقًا لنوع الحزمة:

   نوع الحزمة	الإجراء
   Hello (0)	فك ترميز ServerHello. احسب negotiated_version = min(client_ver, server_ver). ثم انتقل إلى الخطوة 3.
   Exception (2)	فك ترميز Exception. أعده كخطأ وأنهِ الاتصال.
   anything else	انتهاك للبروتوكول. أنهِ الاتصال.

3. إذا كانت قيمة negotiated_version ≥ 54458 (ميزة ADDENDUM)، يرسل العميل Addendum. يستند هذا القرار إلى الإصدار المتفق عليه، لا إلى الإصدار الذي أعلنه العميل.

عند النجاح، ينتقل الاتصال إلى READY؛ وعند حدوث أي خطأ، ينتهي.

فحص حيوية على مستوى التطبيق، مستقل عن TCP keepalive. تؤكد دورة Ping/Pong الناجحة ذهابًا وإيابًا أن اتصال TCP حيّ في كلا الاتجاهين وأن الخادم يستجيب. تكون Ping عديمة الحالة وغير مرتبطة بأي استعلام، لذا فإن عمليات Ping المتتالية مستقلة بعضها عن بعض.

بدءًا من جاهز، يكون التدفق كما يلي:

sequenceDiagram
    autonumber
    participant C as Client
    participant S as Server

    C->>S: Ping (0x04)
    alt responsive
        S->>C: Pong (0x04)
    else error
        S->>C: Exception
    end

1. يرسل العميل Ping.

2. يقرأ العميل الاستجابة:

   نوع الحزمة	الإجراء
   Pong (4)	تم تأكيد أن الاتصال ما يزال حيًا. عُد إلى جاهز.
   Exception (2)	فك ترميز Exception وأرجِعه كخطأ.
   أي شيء آخر	مخالفة للبروتوكول.

يرسل العميل عبارة SQL، ثم يعيد الخادم بث كتل النتائج وبيانات القياس عن بُعد الخاصة بالتنفيذ. وتكون الاستجابة تسلسلاً من الحزم ينتهي بحزمة واحدة فقط، إما EndOfStream أو Exception.

بدءًا من جاهز، يكون التدفق كما يلي:

sequenceDiagram
    autonumber
    participant C as Client
    participant S as Server

    C->>S: Query message
    C->>S: External-table Data packets (0 or more)
    C->>S: Empty Data marker — end-of-client-data (required)
    S->>C: Data — header block (N cols, 0 rows)
    loop until EndOfStream or Exception
        S->>C: Progress / Log (interleaved)
        S->>C: Data — result block (N cols, M rows)
        S->>C: Totals / Extremes (aggregation queries)
        S->>C: ProfileInfo / ProfileEvents (profiling)
    end
    S->>C: Data — empty block (boundary marker)
    S->>C: Progress — final updates
    S->>C: EndOfStream — authoritative end of query

عند حدوث خطأ في أي مرحلة، يرسل الخادم Exception بدلًا من EndOfStream، مما يُنهي الاستعلام.

1. يرسل العميل Query مع query_id فريد (عادةً ما يكون UUID).

2. يرسل العميل أي جداول خارجية، ثم وسم Data فارغًا. تحتوي حزمة Data الفارغة على table_name = "" و num_columns = 0 و num_rows = 0. ولا يبدأ الخادم تنفيذ الاستعلام حتى يتلقى هذا الوسم.

3. ينتقل العميل إلى READING_RESPONSE ويُفرغ مخزن الكتابة المؤقت لديه.

4. يقرأ العميل حزم الاستجابة في حلقة، ويوجّه المعالجة حسب النوع:

   Packet type	الإجراء
   Data (1)	فك ترميز block. تمثل أول حزمة Data ترويسة schema، أما الحزم اللاحقة فهي blocks نتائج (تُجمَّع)، ويمثل block الفارغ وسمًا فاصلًا. لا يعني num_rows == 0 عدم انتهاء الاستعلام.
   Progress (3)	مقاييس التنفيذ. كل حزمة تمثل زيادة منذ الحزمة السابقة — وتُجمَّع محليًا.
   EndOfStream (5)	اكتمل الاستعلام. اخرج من الحلقة وارجع إلى جاهز.
   ProfileInfo (6)	بيانات profiling بعد التنفيذ.
   Totals (7)	block إجماليات التجميع (بنفس wire format الخاص بـ Data).
   Extremes (8)	block القيم الدنيا/العظمى (بنفس wire format الخاص بـ Data).
   Log (10)	سطر من server log.
   TableColumns (11)	metadata القيم الافتراضية للأعمدة.
   ProfileEvents (14)	عدادات الأداء.
   Exception (2)	فك الترميز وإرجاعه كخطأ. اخرج من الحلقة وارجع إلى جاهز.
   anything else	غير متوقع أثناء Query phase. أنهِ connection.

عند EndOfStream أو Exception تمت معالجته، تعود connection إلى جاهز. أما مخالفة protocol أو خطأ I/O فيُنهيانها.

مرحلة INSERT هي مرحلة الاستعلام مع تبادلين إضافيين. يرسل العميل عبارة INSERT؛ ويرد الخادم بـ كتلة مخطط تصف الجدول الهدف؛ ثم يرسل العميل حزم Data التي تحتوي على الصفوف، ثم وسم Data الفارغ؛ ويُنهي الخادم العملية بـ EndOfStream أو Exception.

بدءًا من الحالة جاهز، تكون SQL عبارة INSERT بالصيغة INSERT INTO <table> [(<cols>)] VALUES — من دون قيمة حرفية مضمنة من الشكل VALUES (...)، لأن بيانات الصفوف تتدفق عبر حزم Data. التدفق:

sequenceDiagram
    autonumber
    participant C as Client
    participant S as Server

    C->>S: Query packet (INSERT body)
    C->>S: External-table Data packets (0 or more)
    Note over C,S: No empty Data marker here —<br/>it would end the row stream before it starts
    opt metadata before schema
        S->>C: TableColumns / Progress / ...
    end
    S->>C: Data packet — schema block (columns, 0 rows)
    Note over C,S: Schema block is the contract:<br/>rows sent next must match these column shapes
    loop one or more blocks
        C->>S: Data packet (rows N)
    end
    C->>S: Data packet — empty block (0 rows), end-of-input terminator
    loop until EndOfStream or Exception
        S->>C: Progress / ProfileInfo / Log / ProfileEvents
    end
    opt async_insert = 1 and negotiated_version ≥ 54484
        S->>C: trailing Progress, then insert ProfileEvents
    end
    S->>C: EndOfStream

1. يرسل العميل Query مع ضبط body على عبارة INSERT في SQL.
2. يرسل العميل أي external tables إن وُجدت (وهذا نادر مع INSERT). وعلى خلاف مرحلة الاستعلام، فهو لا يرسل هنا وسم Data فارغًا. تُرسَل حزمة INSERT Query مع وجود بيانات قيد الانتظار، لذلك يُؤجَّل block الفارغ الذي يدل على نهاية البيانات إلى الخطوة 5؛ لأن إرساله قبل schema block سيجعل الخادم يقرأه على أنه نهاية تدفق الصفوف، فيُنهي INSERT بلا أي rows، ثم يُحلّل أول حزمة صفوف فعلية على أنها حزمة شاردة على المستوى الأعلى.
3. يستنزف العميل حزم metadata ‏(TableColumns وProgress وProfileInfo وLog وProfileEvents) إلى أن يقرأ حزمة schema Data — وهي Block تضم 0 rows ولكن ببنية columns كاملة (الأسماء والأنواع). ويُعد schema block بمثابة العقد: يجب أن تطابق rows التي يرسلها العميل بعد ذلك بنية هذه columns.
4. يرسل العميل data block واحدة أو أكثر. ولكل block يكتب VarUInt(ClientPacket::Data = 2)، ثم String("") لاسم external-table الفارغ، ثم الـ Block. يجب أن تتوافق column types مع columns الخاصة بـ schema block بحسب الموضع.
5. يرسل العميل محدِّد نهاية الإدخال: حزمة Data تحتوي على Block فارغ (0 columns, 0 rows).
6. يستنزف العميل تدفق الاستجابة إلى أن يصل إلى EndOfStream (نجاح) أو Exception (فشل).

INSERT غير المتزامن (v54484+). عندما يحمل الاستعلام async_insert = 1، يضع الخادم rows في queue ثم ينفّذ flush لها كجزء من batch. وعند الإصدار المتفاوض عليه ≥ 54484 (PROGRESS_IN_ASYNC_INSERT)، ما إن يكتمل flush حتى يُصدر الخادم حزمة Progress إضافية، تتبعها مباشرة ProfileEvents الخاصة بعملية insert، ثم EndOfStream. أما في الإصدارات الأقدم من 54484، فيتجاوز الخادم حزمة Progress اللاحقة هذه. وهذه الحزمة هي Progress عادية؛ ولأن الخادم يعيد ضبط query pipeline قبل احتساب counts الخاصة بالكتابة، فإن الزيادة لا تتضمن عمليًا سوى الزمن المنقضي، بينما تصل إلى العميل إحصاءات rows والبايتات المكتوبة عبر ProfileEvents المصاحبة. وأي عميل يستنزف بالفعل حزم Progress المتداخلة في الخطوة 6 لا يحتاج إلا إلى قبول حزمة إضافية واحدة.

يعود connection إلى جاهز عند EndOfStream أو عند Exception تمت معالجته. أما مخالفات protocol وأخطاء I/O فتُنهيه.

تُدرج الحقول وفق ترتيبها على wire. ويستخدم العمود Type ما يلي:

• VarUInt — عدد صحيح غير موقّع بطول متغيّر (انظر VarUInt).
• String — بايتات مسبوقة بـ VarUInt (انظر String).
• UInt8 وInt32 وما إلى ذلك — أعداد صحيحة ثابتة العرض بترتيب little-endian.
• Bool — بايت واحد، 0x00 أو 0x01.

يوضح العمود Role الجهة التي تستخدم كل حقل:

• client — يضبطه العملاء الخارجيون.
• inter-server — يكون ذا معنى فقط في الاتصال بين الخوادم؛ ويكتب العملاء الخارجيون قيمة افتراضية.
• universal — يستخدمه الطرفان.

توثّق هذه الجداول جزء body من كل حزمة فقط، بعد رمز نوع الحزمة.

العميل → الخادم. أول رسالة بعد فتح اتصال TCP.

Server → Client. الرد على ClientHello عند نجاح المصادقة.

Rule — عنصر من password_complexity_rules:

تعكس القائمة configuration الخاصة بمشغّل الخادم لسياسة password، وهي استرشادية بحتة — إذ لا يفرض الخادم هذه القواعد أثناء المصافحة. يمكن لـ client الذي يوفّر وظيفة تغيير/تعيين password استخدام هذه القواعد للإشارة إلى الأخطاء قبل إرسال password غير متوافقة إلى الخادم.

العميل → الخادم، ويكون مفعّلًا بواسطة ADDENDUM ‏(v54458). يُرسل مباشرةً بعد اكتمال تبادل المصافحة. وليس نوع حزمة مستقلًا — إذ تُرسل الحقول على الـ wire كما هي، من دون بايت بادئة لنوع الحزمة.

يُطبَّق التحول إلى التأطير المقطّع بعد flush هذا الملحق — أما الملحق نفسه فغير مؤطَّر.

العميل → الخادم. بلا متن — تتكوّن الحزمة من بايت واحد 0x04 قبل التأطير بالمقاطع؛ وعند التفاوض على استخدام التقسيم إلى مقاطع، يصبح هذا البايت حمولةً من بايت واحد لمقطع واحد (انظر التأطير المُجزّأ).

الخادم → العميل. من دون محتوى — تتكوّن الحزمة من بايت واحد 0x04 قبل التأطير المُجزّأ؛ وعند الاتفاق على استخدام التجزئة، يصبح هذا البايت حمولةً من بايت واحد لجزء واحد (انظر التأطير المُجزّأ).

الخادم → العميل. تُرسل عندما يصادف الخادم خطأً أثناء أي مرحلة.

العميل → الخادم.

Client → Server، وهو مضمّن في جسم Query (الحقل 2). ومقيّد بـ CLIENT_INFO ‏(v54032). (بعض الحقول داخل ClientInfo مقيّدة بإصدارات أحدث، كما هو مذكور لكل حقل أدناه.)

ترميز OpenTelemetry (الحقل 16):

[UInt8: has_trace]              0 = no trace data follows, 1 = trace data follows
If has_trace == 1:
  [16 bytes: trace_id]          byte-swapped per-8-bytes
  [8 bytes:  span_id]           byte-swapped
  [String:   trace_state]       W3C trace state
  [UInt8:    trace_flags]       W3C trace flags

الحقل 4 من الاستعلام (auth_hash) ليس secret الخاص بالـ cluster المشترك على مستوى النقل. إذ إن إرسال السر بصيغته الخام سيؤدي إلى فشل المصادقة وكشفه في الوقت نفسه. وبدلًا من ذلك، يثبت الخادم الذي يعمل كعميل بين الخوادم أنه يعرف السر باستخدام تجزئة SHA-256 مملّحة:

1. الدخول إلى وضع inter-server. يشير الخادم المتصل إلى ذلك داخل ClientHello: تكون قيمة الحقل user هي وسم inter-server ويكون password فارغًا. ثم يُلحق سلسلتين إضافيتين — اسم العنقود وsalt مُولَّد حديثًا بطول 32 بايت (encodeSHA256 لقيمة عشوائية) — مباشرة بعد حقلي user/password، ضمن حزمة ClientHello نفسها. يقرأ الخادم هاتين السلسلتين قبل أن يرسل ServerHello، لذلك يجب على العميل كتابتهما مسبقًا؛ إذ إن انتظار ServerHello أولًا يسبب حالة deadlock، لأن الخادم يكون متوقفًا أثناء قراءتهما.
2. الحصول على nonce. يحمل ServerHello قيمة nonce من النوع UInt64 بطول 8 بايت عند التفاوض على INTERSERVER_SECRET_V2 (v54462).
3. حساب قيمة التجزئة. لكل حزمة Query غير InitialQuery، يكتب العميل encodeSHA256(salt + nonce + cluster_secret + query + query_id + initial_user + external_roles + current_roles) في الحقل 4 — أي ناتج digest بطول 32 بايت. (تكون nonce بصيغة سلسلة عشرية، ولا تكون موجودة إلا عند التفاوض على إصدار ≥ v54462؛ ولا يُلحَق external_roles إلا عند التفاوض على INTERSERVER_EXTERNALLY_GRANTED_ROLES (v54472)؛ وcurrent_roles هي قائمة أسماء الأدوار المُسلسلة — [VarUInt count][String]*count، من دون بايت الوجود — ولا تُلحَق إلا عند التفاوض على INTERSERVER_CURRENT_ROLES (v54488) وعند وجود القائمة.) أما في حالة InitialQuery، أو عند عدم تهيئة أي secret خاص بالـ cluster، فيكتب العميل سلسلة فارغة بدلًا من ذلك.
4. التحقق. يقرأ الخادم الحقل 4 بحد أقصى 32 بايت ويعيد حساب عملية الربط نفسها باستخدام نسخته الخاصة من secret الخاص بالـ cluster المشترك؛ ويُرفض الاتصال إذا اختلفت قيمتا digest.

العملاء الخارجيون (غير العاملين بين الخوادم) لا يدخلون هذا الوضع مطلقًا، ويرسلون دائمًا auth_hash فارغًا.

يُرمَّز هذا مضمّنًا داخل قائمة الإعدادات في جسم Query (حزمة Query، الحقل 3). تكون القائمة موجودة دائمًا، بغضّ النظر عن الإصدار المتفاوض عليه، وتنتهي بإعداد ذي مفتاح فارغ — أي VarUInt 0 واحد، من دون أي flags أو قيمة بعده. ويعتمد ترميز كل إعداد فقط على الإصدار المتفاوض عليه، وتتحكم فيه SETTINGS_SERIALIZED_AS_STRINGS ‏(v54429).

v54429+ (STRINGS_WITH_FLAGS) — يكون كل إعداد هو الثلاثي الموضّح هنا:

يغيب الحقلان 2 و3 عندما يكون key فارغًا.

قبل 54429 (BINARY) — يكون كل إعداد بالشكل [String key][type-specific binary value]: لا يُكتب الحقل flags إطلاقًا، وتُرمَّز القيمة بصيغتها الثنائية الأصلية الخاصة بالإعداد (على سبيل المثال، عدد صحيح ثابت العرض أو سلسلة مسبوقة بالطول) بدلًا من سلسلة عشرية/نصية. وتظل القائمة منتهيةً بـ key فارغ. يجب على العميل الذي يستهدف إصدارًا متفاوضًا عليه أقل من 54429 أن يقرأ هذه الصيغة الثنائية ويكتبها، لا الثلاثي أعلاه. (الإعدادات المخصّصة المعرّفة من قبل المستخدم هي الاستثناء: فهي تتضمن دائمًا flags وقيمة نصية، في كلا الترميزين.)

يحتوي الحقل flags على:

• 0x01 — مهم: يؤثر الإعداد في نتائج الاستعلام، ويجب ألا تتجاهله النظراء الأقدم بصمت.
• 0x02 — مخصّص: إعداد مخصّص معرّف من قبل المستخدم.
• 0x0c — حقل tier من 2 بت، وليس علامة مستقلة: 0x00 = Production، 0x04 = Obsolete، 0x08 = Experimental، 0x0c = Beta. اقرأ البتين معًا (flags & 0x0c) — لأن اختبارًا ساذجًا مثل flags & 0x04 سيُصنّف Beta (0x0c) خطأً على أنها Obsolete.
• 0x80 — HotReload (إعادة تحميل config من دون إعادة تشغيل؛ معرّف في تعداد العلامات، ويظهر أساسًا في إعدادات coordination).

معلمات الاستعلام، للاستعلامات ذات المعلَمات مثل SELECT {x:UInt64}. تُرمَّز بالطريقة نفسها تمامًا مثل إعداد مع ضبط العلامة Custom (0x02)، وتُنهى بمفتاح فارغ بالطريقة نفسها.

في كلا الاتجاهين. تحمل كتل النتائج، وبيانات INSERT، والجداول الخارجية، وعلامات نهاية البيانات.

تنسيق النقل متماثلة — إذ يتضمن كلا الاتجاهين بادئة table_name قبل Block. والاختلاف الوحيد هو بايت نوع الحزمة.

[VarUInt: packet_type]     1 (server→client) or 2 (client→server)
[String:  table_name]      External table name; empty in most cases
[Block]                    See the Native Format spec for the Block layout

وسم نهاية البيانات هو حزمة يكون فيها Block فارغًا — 0 أعمدة و0 صفوف — بغض النظر عن table_name. ويتعامل الخادم مع حزمة Data من العميل على أنها المُنهِي فقط عندما تكون كتلة البيانات المفككة فارغة (block.empty())؛ أما الحزمة التي فيها table_name = "" وBlock غير فارغ، فهي حزمة صفوف عادية وليست مُنهِيًا. لذا فإن تدفق صفوف INSERT هو تسلسل من كتل Data غير الفارغة، تتبعها كتلة Data فارغة واحدة تُنهيه.

تُوثَّق متغيرات Block وما تعنيه ضمن متغيرات Block.

الخادم → العميل. تُرسَل دوريًا أثناء تنفيذ الاستعلام. جميع الحقول من نوع VarUInt، وتحمل كل حزمة الزيادات منذ حزمة Progress السابقة، لا الإجماليات التراكمية. قبل الإرسال، يقرأ الخادم عدّاداته ويُعيد ضبطها ذريًا إلى الصفر، ويحسب elapsed_ns على أنه فرق الزمن منذ آخر إرسال. لذلك يجب على العميل تجميع الحزم المتعاقبة محليًا للحصول على الإجماليات الجارية — فالتعامل مع الحزمة على أنها قيمة مطلقة يجعل عرض التقدّم يرتد إلى الخلف أو يقلّل العدد عند وصول أكثر من حزمة واحدة.

الخادم → العميل. يُرسل مرة واحدة لكل استعلام، قرب نهاية التنفيذ.

الخادوم → العميل. يُرسَل للاستعلامات التي تتضمن WITH TOTALS. تنسيق النقل على مستوى النقل مطابق تمامًا لـ Data: سلسلة table_name (وتكون فارغة دائمًا) تليها كتلة. والاختلاف الوحيد هو بايت نوع الحزمة.

[VarUInt: 7]                packet type
[String:  table_name]       always empty
[Block]                     see the Native Format spec

الخادم → العميل. تُرسَل عندما يكون الإعداد extremes مفعّلًا. تنسيق النقل مطابق تمامًا لـ Data. تحتوي الكتلة على صفّين بالضبط: يحتوي الصف 0 على الحد الأدنى لكل عمود، ويحتوي الصف 1 على الحد الأقصى.

[VarUInt: 8]                packet type
[String:  table_name]       always empty
[Block]                     num_rows = 2

الخادم → العميل. تُرسَل هذه الحزمة عندما تكون للاستعلام قائمة انتظار سجلات نشطة (إعداد send_logs_level؛ راجع بث السجلات).

تنسيق الغلاف والمحتوى مطابق لتنسيق Data. تحتوي الكتلة على قيمة ثابتة num_columns = 8 ومخطط محدد مسبقًا. ويمثّل كل سطر سجل صفًا واحدًا عبر الأعمدة الثمانية جميعها، وقد تتضمن حزمة Log واحدة صفوفًا عديدة.

[VarUInt: 10]               packet type
[String:  table_name]       always empty
[Block]                     num_columns = 8, num_rows = number of log lines

الأعمدة الثمانية، بهذا الترتيب تمامًا:

الخادم → العميل. يحمل عدّادات أداء لكل استعلام.

له نفس تنسيق الغلاف والمحتوى كما في Data. تحتوي الكتلة على قيمة ثابتة لـ num_columns = 6 ومخطط محدد مسبقًا. ويمثل كل حدث صفًا واحدًا.

[VarUInt: 14]               packet type
[String:  table_name]       always empty
[Block]                     num_columns = 6, num_rows = number of events

الأعمدة الستة:

الخادم → العميل، ويكون إرسالها مشروطًا بـ COLUMN_DEFAULTS_METADATA ‏(v54410). يرسلها الخادم قبل كتلة المخطط الخاصة بـ INSERT لنقل البيانات الوصفية للقيم الافتراضية للأعمدة، ولكن فقط عندما يكون الإصدار المتفاوض عليه ≥ 54410 و يكون الإعداد input_format_defaults_for_omitted_fields مفعّلًا. في الإصدارات الأقدم من 54410، لا تُرسل هذه الحزمة مطلقًا، لذلك يجب على العميل الأقدم ألا ينتظرها — إذ تأتي كتلة المخطط Data مباشرةً. ينبغي أن يكون عميل v54410+ مستعدًا لأيٍّ من الترتيبين: TableColumns اختيارية، ثم كتلة المخطط.

الخادم → العميل، ويخضع لـ TIMEZONE_UPDATES ‏(v54464). تُرسَل في موضع واحد فقط: مُهيِّئ دالة الجدول input (استعلام بالصيغة INSERT INTO <table> SELECT ... FROM input('<structure>')، حيث تتدفق الصفوف من العميل). مباشرةً بعد أن يرسل الخادم كتلة Data الخاصة بمخطط الإدخال (انظر مرحلة INSERT)، يُرسل TimezoneUpdate حاملةً قيمة session_timezone الحالية في سياق الاستعلام، لكي يفسِّر العميل الصفوف التي يوشك على إرسالها باستخدام المنطقة الزمنية نفسها. لا يرسل الخادم هذه الحزمة عند أي تغييرات لاحقة على SET session_timezone أثناء الاستعلام، ولا لإبلاغ العميل بكيفية تنسيق كتل النتائج اللاحقة.

تصل الحزمة مرة واحدة، مباشرةً بعد كتلة مخطط الإدخال وقبل أن يبدأ العميل في إرسال كتل الصفوف. ويجب على decoder الذي يتجاهل TimezoneUpdate أن يستهلك أيضًا قيمة String اللاحقة للحفاظ على محاذاة wire.

تخضع لـ SSH_AUTHENTICATION ‏(v54466)، ولا تُفعَّل إلا عند الاختيار الصريح. يدخل الاتصال في مسار SSH عندما يرسل ClientHello القيمة user = " SSH KEY AUTHENTICATION " + <real_user> (مع المسافات البادئة واللاحقة) وpassword = "". يقرأ الخادم البادئة، ويزيلها لاستعادة اسم المستخدم الحقيقي، ثم ينتقل إلى نمط التحدي والاستجابة.

يعمل هذا المسار بدلًا من password authentication، ويحدث تبادل التحدي والاستجابة قبل ServerHello — إذ يؤجل الخادم رد Hello الخاص به حتى تنجح المصادقة:

1. يرسل العميل ClientHello مع بادئة وسم SSH وكلمة مرور فارغة.

2. يرسل العميل SSHChallengeRequest (الحزمة 11). لم يرسل الخادم ServerHello بعد — إذ يعالج المصادقة أولًا ويتوقف هنا منتظرًا هذه الحزمة.

3. يرد الخادم بـ SSHChallenge متضمنةً بايتات عشوائية (الحزمة 18).

4. ينشئ العميل السلسلة المطلوب توقيعها ويوقّع هذه السلسلة، لا challenge الخام، ثم يرسل SSHChallengeResponse (الحزمة 12) مع التوقيع. الرسالة الموقَّعة هي ربط بايت-ببايت، من دون فواصل، لأربعة أجزاء بهذا الترتيب الدقيق:

   to_sign = decimal(protocol_version) + default_database + user + challenge

   Part	Source
   decimal(protocol_version)	إصدار البروتوكول الخاص بالعميل على هيئة سلسلة ASCII عشرية (مثل "54466") — رقم الإصدار كسلسلة، وليس VarUInt أو عددًا صحيحًا ثابت العرض. يتحقق الخادم باستخدام إصدار البروتوكول نفسه الذي استلمه في ClientHello.
   default_database	الحقل database من ClientHello (سلسلة فارغة إذا لم تكن هناك قيمة).
   user	اسم المستخدم الحقيقي بعد إزالة بادئة الوسم " SSH KEY AUTHENTICATION " — وهو الاسم نفسه الذي يستعيده الخادم بعد إزالة البادئة.
   challenge	بايتات challenge الخام من حزمة SSHChallenge.

5. يتحقق الخادم من التوقيع باستخدام public key المسجل للمستخدم، مع إعادة تكوين السلسلة نفسها decimal(protocol_version) + default_database + user + challenge. عند النجاح، يرسل ServerHello — وهو الرد نفسه كما في مسار كلمة المرور — وتستمر المصافحة بشكل طبيعي (Addendum، إلخ)؛ وعند الفشل، يعيد Exception وينهي الاتصال. سيفشل العميل الذي يوقّع بايتات التحدي الخام فقط في المصادقة.

sequenceDiagram
    autonumber
    participant C as Client
    participant S as Server

    C->>S: ClientHello (SSH marker user, empty password)
    C->>S: SSHChallengeRequest (11)
    Note over C,S: Server has NOT sent ServerHello yet —<br/>it authenticates first and blocks here
    S->>C: SSHChallenge (18) — random bytes to sign
    C->>S: SSHChallengeResponse (12) — signature over version+db+user+challenge
    alt signature verifies
        S->>C: ServerHello — handshake continues normally
    else verification fails
        S->>C: Exception — connection terminates
    end

العملاء الخارجيون الذين لا يستخدمون مصادقة SSH لا يرون الحزم 11 أو 12 أو 18 مطلقًا — إذ لا تظهر على wire إلا إذا اختار المستخدم ذلك صراحةً عبر بادئة اسم المستخدم.

العميل → الخادم، للاستخدام بين الخوادم فقط. ولا يكون متاحًا إلا عند parallel_replicas_protocol_version ≥ 8 (راجع VERSIONED_PARALLEL_REPLICAS_PROTOCOL). ولا ترسل البرامج العميلة الخارجية هذه الحزمة مطلقًا.

عندما يكون إصدار parallel-replicas المتفق عليه هو ≥ 8، تتغيّر دورة الطلب/الاستجابة لدى المُبادِر الخاصة بـ MergeTreeAllRangesAnnouncement الصادر من التابع (نوع الحزمة 15، باتجاه الخادم→العميل):

1. يفتح التابع مسار القراءة الخاص به ويرسل MergeTreeAllRangesAnnouncement إلى المُبادِر.
2. فقط عندما تكون قيمة mode في الإعلان غير Default (WithOrder = 1 أو ReverseOrder = 2، وكلاهما يُستخدم للقراءات المتوازية المرتبة) يردّ المُبادِر بـ MergeTreeAllRangesAnnouncementResponse. أمّا عند mode = Default = 0 فيبقى المُبادِر صامتًا ولا ينتظر التابع — إذ يوزّع وضع Default النطاقات مع كل MergeTreeReadTaskRequest ولا يحتاج أبدًا إلى قائمة الأجزاء المسبقة.
3. ينتظر التابع الاستجابة (عند توقّعها) قبل إرسال أول MergeTreeReadTaskRequest له (حزمة الخادم 16 — تُرسل من التابع→المُبادِر؛ ويردّ المُبادِر بـ MergeTreeReadTaskResponse، حزمة العميل 10) مستخدمًا قائمة الأجزاء المُعادة لتصفية إنشاء المصدر بحيث يقتصر تمامًا على الأجزاء التي يملكها تدفّق #split_i الخاص به.

في الإصدارات الأقدم من 8، يكون الإعلان بنمط fire-and-forget بغضّ النظر عن الوضع، وينشئ التابع المصادر فوق كل جزء معروف محليًا (السلوك القديم).

يغطي هذا القسم الإعدادات القابلة للضبط التي تُحدِّد سلوك اتصالات البروتوكول الأصلي:

• إعدادات طبقة النقل — خيارات مقبس TCP والمهلات الزمنية التي تؤثر في كيفية عمل اتصال TCP نفسه.
• إعدادات طبقة التطبيق — إعدادات خاصة بكل استعلام تُنقَل ضمن قائمة إعدادات حزمة Query، وتؤثر في ما يرسله الخادم عبر الاتصال أو في كيفية تأطيره.
• إعدادات خارج النطاق — إعدادات يكثر الخلط بينها وبين إعدادات البروتوكول، لكنها تتحكم فعليًا في تنفيذ SQL أو التخزين.

تعكس القيم الافتراضية أدناه إصدارًا حديثًا من الخادم؛ وقد تختلف بين الإصدارات وعمليات النشر.

تتداخل المهلات الزمنية على النحو التالي:

tcp_keep_alive_timeout (290s)
      < receive_timeout (300s)
      < idle_connection_timeout (3600s)
      < tcp_close_connection_after_queries_seconds (0 = unlimited by default)

تعمل آلية keepalive في نظام التشغيل أولًا، وقد تكتشف الأطراف النظيرة المتوقفة بصمت على مستوى النواة. وتُعد مهلة الاستقبال في التطبيق خط الدفاع التالي. أما مهلة الخمول فهي الملاذ الأخير للتخلص من الاتصالات غير المستخدمة منذ وقت طويل.

يمكن للاتصال الذي يرسل استعلامات بانتظام أن يبقى مفتوحًا إلى أجل غير مسمى. ولا تُغلق بعد ساعة إلا الاتصالات الخاملة، ولا يوجد حد أقصى افتراضي لمدة الاتصال.

تُنقل هذه الإعدادات مع كل استعلام ضمن قائمة إعدادات حزمة Query. وهي تغيّر ما يرسله الخادم على الـwire، أو كيفية تأطيره.

تؤدي العلامة compression في حزمة Query (الحقل 6) إلى تفعيل الضغط أو تعطيله؛ وتحدد هذه الإعدادات ترميز الضغط المستخدم عند تفعيله.

يؤدي ضبط send_logs_level على أي قيمة غير "none" إلى جعل الخادم يرسل حزم Log أثناء تنفيذ الاستعلام.

هذا حد أدنى مستهدف، وليس حدًا أقصى صارمًا: قد يرسل الخادوم حزم Progress بوتيرة أبطأ عندما لا يولّد الاستعلام عملاً بالسرعة الكافية.

يُظَنّ أحيانًا، خطأً، أن هذه الإعدادات تخص مستوى البروتوكول، لكنها تتحكم في تنفيذ SQL أو التخزين أو استخدام CPU، لا في السلوك على مستوى النقل عبر السلك. لذلك لا يحتاج تنفيذ البروتوكول إلى التعامل معها بشكل خاص.

• max_threads — التوازي داخل تنفيذ الاستعلام.
• max_memory_usage — الحد الأقصى للذاكرة لكل استعلام.
• max_block_size, preferred_block_size_bytes — تحديد حجم الكتل داخليًا أثناء معالجة الاستعلام؛ أما كتل النقل عبر السلك فهي مستقلة عن هذه الإعدادات.
• compile_expressions — الترجمة الفورية JIT؛ تخص CPU فقط.
• async_insert_max_data_size — مخزن queue المؤقت على جهة الخادم.
• جميع إعدادات input_format_* وoutput_format_* باستثناء مجموعة input_format_native_* / output_format_native_* — الإعدادات غير native تختار تنسيقات أخرى أو تضبطها (على سبيل المثال عبر HTTP) ولا تغيّر كتل Data في البروتوكول الأصلي.

تمثل إعدادات *_native_* الاستثناء: فهي تغيّر البايتات داخل كتل Data في native TCP، لذا يجب على أي تنفيذ للبروتوكول أن يراعيها. يبدّل output_format_native_encode_types_in_binary_format حقل type في العمود من سلسلة نصية إلى ترميز نوع ثنائي، ويُخرج output_format_native_write_json_as_string أعمدة JSON على هيئة String، ويختار output_format_native_use_flattened_dynamic_and_json_serialization تخطيط Dynamic/JSON من نوع FLATTENED. ولأن هذه الإعدادات تؤثر في جسم الكتلة لا في غلاف الحزمة، فهي محددة في مواصفة Native Format — راجع بنية الأعمدة على السلك والأنواع ذات الإصدارات.

Cancel — حزمة يبدأها العميل (النوع 3) لإلغاء query قيد التنفيذ. لا تُعرض تفاصيلها في هذه الصفحة.

وسم نهاية بيانات العميل — حزمة Data فارغة (0 columns, 0 rows) يرسلها العميل لإغلاق stream الإدخال. يختلف موضعها بحسب نوع query:

• query عادي (SELECT, etc.): تُرسل بعد حزمة Query وأي حزم Data للجداول الخارجية للإشارة إلى "لا مزيد من البيانات الخارجية". بعدها يبدأ server التنفيذ.
• INSERT: لا يرسل العميل وسمًا قبل schema. يرسل server أولًا كتلة المخطط، ثم يبث العميل data blocks الخاصة بالصفوف، وبعد ذلك فقط يرسل حزمة Data الفارغة لإنهاء stream الصفوف. إن إرسال وسم فارغ قبل كتلة المخطط سيُفسَّر على أنه نهاية فورية للصفوف، ما يؤدي إلى فقدان البيانات.

Feature — تغيير في تنسيق النقل أُدخل في إصدار محدد من protocol. تكون الميزة نشطة عندما تكون protocol version المتفاوض عليها مساوية لإصدار الميزة أو أعلى منه. راجع الإصدار وبوابات الميزات.

Inter-server — تسمية دور لحقل لا يكون ذا معنى إلا في distributed queries بين الخوادم. ويكتب العملاء الخارجيون default value (عادةً سلسلة فارغة أو 0 أو false).

الإصدار المتفاوض عليه — min(client_version, server_version)، ويُحتسب أثناء المصافحة. ويحدد الميزات النشطة طوال lifetime الخاص بالاتصال.

Packet — رسالة wire: رمز packet type من نوع VarUInt يتبعه body يعتمد تنسيقه على النوع. راجع غلاف الحزمة.

رمز نوع الحزمة — قيمة VarUInt الأولى في الحزمة، وهي التي تحدد تنسيقها. القيم من 0 إلى 18 مخصَّصة حاليًا. راجع مرجع أنواع الحزم.

تدفق الاستجابة — تسلسل الحزم التي يصدرها server أثناء query. وهو مفتوح الطول، وينتهي بـ EndOfStream واحد فقط (نجاح) أو Exception (فشل). راجع مرحلة query.

كتلة المخطط — header block (أي Block يحتوي على columns لكن 0 rows) يرسله server أثناء مرحلة INSERT للإعلان عن أشكال columns المتوقعة قبل أن يرسل العميل البيانات.

قائمة الإعدادات — تسلسل من tuples بالشكل (key, flags, value) داخل body الخاص بـ Query، وينتهي بمفتاح فارغ. يحمل configuration على مستوى التطبيق لكل query. راجع Setting.

Stage — حقل VarUInt في حزمة Query (الحقل 5) يحدد إلى أي مدى ينفّذ server الـ query. يرسل العملاء الخارجيون عادةً 2 (Complete)، بينما تستخدم distributed queries وquery plans المُسلسلة القيم الأعلى. راجع الحقل 5 في Query للاطلاع على المجموعة الكاملة من قيم wire.

Terminator — حزمة تُنهي stream. تنتهي استجابة Query عند EndOfStream (نجاح) أو Exception (فشل). وينتهي stream الإدخال الخاص بالعميل عند وسم Data الفارغ.