> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-trino-dialect.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# مرجع

> يتناول بالتفصيل التنسيقات والمصادر ودلالات التسليم والمصادقة والميزات التجريبية التي يدعمها Kafka ClickPipes.

export const ExperimentalBadge = () => {
  return <a href="https://clickhouse.com/docs/reference/settings/beta-and-experimental-features#experimental-features" className="experimentalBadge">
            <div className="experimentalIcon">
            <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
                <path strokeWidth="1.25" d="M5.5 2H10.5" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path strokeWidth="1.25" d="M9.50015 2V6.19625L13.4283 12.7425C13.4738 12.8183 13.4985 12.9049 13.4996 12.9934C13.5008 13.0818 13.4785 13.169 13.435 13.246C13.3914 13.323 13.3283 13.3871 13.2519 13.4317C13.1755 13.4764 13.0886 13.4999 13.0002 13.5H3.00015C2.91164 13.5 2.8247 13.4766 2.74822 13.432C2.67174 13.3874 2.60847 13.3233 2.56487 13.2463C2.52126 13.1693 2.49889 13.082 2.50004 12.9935C2.50119 12.905 2.52582 12.8184 2.5714 12.7425L6.50015 6.19625V2" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path strokeWidth="1.25" d="M4.47656 9.56754C5.30344 9.41254 6.47656 9.47942 7.99969 10.25C10.0153 11.2707 11.4216 11.0569 12.2184 10.7282" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
            </svg>
        </div>
            ميزة تجريبية
        </a>;
};

export const Image = ({img, alt, size = "lg"}) => {
  const normalizedSize = ["sm", "md", "lg"].includes(size) ? size : "lg";
  return <div className={`ch-image-${normalizedSize}`}>
      <Frame>
        <img src={img} alt={alt} />
      </Frame>
    </div>;
};

<div id="supported-data-sources">
  ## مصادر البيانات المدعومة
</div>

| الاسم            | الشعار                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | النوع | الحالة | الوصف                                                                                |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | ------ | ------------------------------------------------------------------------------------ |
| Apache Kafka     | <img src="https://mintcdn.com/private-7c7dfe99-trino-dialect/SwBmQiR_ocl5w4KS/images/integrations/logos/kafka.svg?fit=max&auto=format&n=SwBmQiR_ocl5w4KS&q=85&s=0f8a4d7f58e46d6bde9775449d67082d" alt="شعار Apache Kafka" width="32" data-path="images/integrations/logos/kafka.svg" />                                                                                           | البث  | مستقر  | هيّئ ClickPipes وابدأ باستيعاب بيانات البث من Apache Kafka إلى ClickHouse Cloud.     |
| Confluent Cloud  | <img src="https://mintcdn.com/private-7c7dfe99-trino-dialect/qOv7KJkvDWsDYhyE/images/integrations/logos/confluent.svg?fit=max&auto=format&n=qOv7KJkvDWsDYhyE&q=85&s=5c1250cc83ff9174a248cf7861453053" alt="شعار Confluent Cloud" width="32" data-path="images/integrations/logos/confluent.svg" />                                                          | البث  | مستقر  | استفد من الإمكانات المشتركة لـ Confluent وClickHouse Cloud من خلال تكاملنا المباشر.  |
| Redpanda         | <img src="https://mintcdn.com/private-7c7dfe99-trino-dialect/SwBmQiR_ocl5w4KS/images/integrations/logos/logo_redpanda.webp?fit=max&auto=format&n=SwBmQiR_ocl5w4KS&q=85&s=9801702fbf433590121049112726f0da" alt="شعار Redpanda" width="32" data-path="images/integrations/logos/logo_redpanda.webp" />                       | البث  | مستقر  | هيّئ ClickPipes وابدأ باستيعاب بيانات البث من Redpanda إلى ClickHouse Cloud.         |
| AWS MSK          | <img src="https://mintcdn.com/private-7c7dfe99-trino-dialect/SwBmQiR_ocl5w4KS/images/integrations/logos/msk.svg?fit=max&auto=format&n=SwBmQiR_ocl5w4KS&q=85&s=fa6910c6bf59963aa3939f545c736923" alt="شعار AWS MSK" width="32" data-path="images/integrations/logos/msk.svg" />                                                                                                                  | البث  | مستقر  | هيّئ ClickPipes وابدأ باستيعاب بيانات البث من AWS MSK إلى ClickHouse Cloud.          |
| Azure Event Hubs | <img src="https://mintcdn.com/private-7c7dfe99-trino-dialect/qOv7KJkvDWsDYhyE/images/integrations/logos/azure_event_hubs.svg?fit=max&auto=format&n=qOv7KJkvDWsDYhyE&q=85&s=8c141592829048dbd203e9d45714d300" alt="شعار Azure Event Hubs" width="32" data-path="images/integrations/logos/azure_event_hubs.svg" /> | البث  | مستقر  | هيّئ ClickPipes وابدأ باستيعاب بيانات البث من Azure Event Hubs إلى ClickHouse Cloud. |
| WarpStream       | <img src="https://mintcdn.com/private-7c7dfe99-trino-dialect/P37Ln6i-rM2atqdZ/images/integrations/logos/warpstream.svg?fit=max&auto=format&n=P37Ln6i-rM2atqdZ&q=85&s=81f63e78a47121c090b18c67f8387c9f" alt="شعار WarpStream" width="32" data-path="images/integrations/logos/warpstream.svg" />                                                       | البث  | مستقر  | هيّئ ClickPipes وابدأ باستيعاب بيانات البث من WarpStream إلى ClickHouse Cloud.       |

<div id="isolation-level">
  ## مستوى العزل
</div>

يحدد مستوى عزل مستهلك Kafka ما إذا كان ClickPipe يقرأ ويُدرج الرسائل التي تم تثبيتها ضمن معاملات Kafka فقط. فعّل إعداد `kafka_read_committed` لاستخدام `read_committed` وتخطي الرسائل الناتجة عن معاملات Kafka المُجهضة. عطّله لاستخدام `read_uncommitted` وقراءة جميع الرسائل. يمكنك تهيئة هذا الإعداد ضمن **الإعدادات المتقدمة**.

<div id="supported-data-formats">
  ## تنسيقات البيانات المدعومة
</div>

التنسيقات المدعومة هي:

* [JSON](/ar/guides/clickhouse/data-formats/json/intro)
* [AvroConfluent](/ar/reference/formats/Avro/AvroConfluent)
* [Protobuf](/ar/reference/formats/Protobuf/Protobuf)

<div id="supported-data-types">
  ## أنواع البيانات المدعومة
</div>

<div id="standard-types-support">
  ### الأنواع القياسية
</div>

أنواع بيانات ClickHouse القياسية التالية مدعومة حاليًا في ClickPipes:

* الأنواع الرقمية الأساسية - \[U]Int8/16/32/64 و Float32/64 و BFloat16
* أنواع الأعداد الصحيحة الكبيرة - \[U]Int128/256
* Decimal Types
* Boolean
* String
* FixedString
* Date و Date32
* DateTime و DateTime64 (مناطق زمنية UTC فقط)
* Enum8/Enum16
* معرّف UUID
* IPv4
* IPv6
* Time و Time64
* JSON
* جميع أنواع LowCardinality في ClickHouse
* Map بمفاتيح وقيم تستخدم أيًا من الأنواع المذكورة أعلاه (بما في ذلك Nullable)
* Tuple و Array بعناصر تستخدم أيًا من الأنواع المذكورة أعلاه (بما في ذلك Nullable، وبعمق مستوى واحد فقط)
* أنواع SimpleAggregateFunction (لوجهات AggregatingMergeTree أو SummingMergeTree)

<div id="variant-type-support">
  ### دعم نوع Variant
</div>

يدعم ClickPipes نوع Variant في الحالات التالية:

* اتحادات Avro. إذا كان مخطط Avro لديك يحتوي على `union` يضم عدة أنواع غير NULL، فسيستنتج ClickPipes نوع Variant المناسب. بخلاف ذلك، لا تكون أنواع Variant مدعومة في بيانات Avro.
* حقول JSON. يمكنك تحديد نوع Variant يدويًا (مثل `Variant(String, Int64, DateTime)`) لأي حقل JSON في مصدر تدفق البيانات. لا تُدعَم الأنواع الفرعية المعقدة (arrays/maps/tuples). بالإضافة إلى ذلك، ونظرًا للطريقة التي يحدد بها ClickPipes النوع الفرعي الصحيح من Variant الذي يجب استخدامه، لا يمكن استخدام أكثر من نوع عدد صحيح واحد أو نوع DateTime واحد في تعريف Variant — على سبيل المثال، `Variant(Int64, UInt32)` غير مدعوم.

<div id="json-type-support">
  ### دعم نوع JSON
</div>

تدعم ClickPipes نوع JSON في الحالات التالية:

* يمكن دائمًا إسناد حقول Avro Record وProtobuf Message إلى عمود JSON.
* يمكن إسناد حقول Avro String وBytes إلى عمود JSON إذا كان حقل Avro يحتوي فعليًا على كائنات JSON مخزنة كسلاسل نصية.
* يمكن إسناد أنواع Protobuf String وBytes إلى عمود JSON إذا كان حقل Protobuf يحتوي فعليًا على كائنات JSON مخزنة كسلاسل نصية.
* يمكن إسناد حقول JSON التي تكون دائمًا كائنات JSON إلى عمود JSON في الوجهة.

لاحظ أنك ستحتاج إلى تغيير عمود الوجهة يدويًا إلى نوع JSON المطلوب، بما في ذلك أي مسارات ثابتة أو متخطاة.

<div id="avro">
  ### Avro
</div>

<div id="supported-avro-data-types">
  #### أنواع بيانات Avro المدعومة
</div>

تدعم ClickPipes جميع أنواع Avro البدائية والمركبة، وجميع أنواع Avro المنطقية باستثناء `local-timestamp-millis` و`local_timestamp-micros`. تُحوَّل أنواع Avro `record` إلى Tuple، وأنواع `array` إلى Array، و`map` إلى Map (بمفاتيح نصية فقط). وبوجه عام، تتوفر التحويلات المذكورة [هنا](/ar/concepts/features/interfaces/schema-inference#avro). نوصي باستخدام المطابقة الدقيقة للأنواع الرقمية في Avro، لأن ClickPipes لا تتحقق من تجاوز السعة أو فقدان الدقة عند تحويل الأنواع. وبدلاً من ذلك، يمكن إدراج جميع أنواع Avro في عمود `String`، وستُمثَّل في هذه الحالة كسلسلة JSON صالحة.

<div id="nullable-types-and-avro-unions">
  #### أنواع Nullable واتحاد في Avro
</div>

تُعرَّف أنواع Nullable في Avro باستخدام مخطط اتحاد بالشكل `(T, null)` أو `(null, T)`، حيث إن T هو نوع Avro الأساسي. أثناء استنتاج المخطط، تُربَط أنواع اتحاد هذه بعمود "Nullable" في ClickHouse. لاحظ أن ClickHouse لا يدعم الأنواع `Nullable(Array)` و`Nullable(Map)` و`Nullable(Tuple)`. ستُحوَّل اتحادات null في Avro لهذه الأنواع إلى إصدارات غير Nullable (وتُحوَّل أنواع Avro Record إلى Tuple مُسمّى في ClickHouse). وستُدرَج قيم Avro "nulls" لهذه الأنواع على النحو التالي:

* Array فارغة لصفيف Avro null
* Map فارغة لـ Avro Map null
* Tuple مُسمّى تحتوي على جميع القيم الافتراضية/الصفرية لـ Avro Record null

<div id="protobuf">
  ### Protobuf
</div>

<div id="supported-protobuf-data-types">
  #### أنواع بيانات Protobuf المدعومة
</div>

يدعم ClickPipes جميع أنواع Protobuf 2 و3، باستثناء النوع `group` في proto 2، وهو نوع أُعلن عن إهماله منذ وقت طويل. وتستخدم تحويلات الأنواع الأساسية عمليات التحويل التالية:

<Note>
  تتوفّر أيضًا متغيرات `Array` و`Map` و`Nullable` لجميع الأنواع الأساسية.
</Note>

| نوع Protobuf                  | نوع ClickHouse |
| ----------------------------- | -------------- |
| `bool`                        | `UInt8`        |
| `float`                       | `Float32`      |
| `double`                      | `Float64`      |
| `int32`, `sint32`, `sfixed32` | `Int32`        |
| `int64`, `sint64`, `sfixed64` | `Int64`        |
| `uint32`, `fixed32`           | `UInt32`       |
| `uint64`, `fixed64`           | `UInt64`       |
| `string`, `bytes`             | `String`       |
| `enum`                        | `Enum`         |
| `repeated T`                  | `Array(T)`     |
| `message`                     | `Tuple`        |

<Tip>
  بالنسبة إلى الأنواع الرقمية، يُوصى باستخدام تطابق تام لتجنّب تجاوز السعة أو فقدان الدقة.
</Tip>

الأنواع [الشائعة المعروفة](https://protobuf.dev/reference/protobuf/google.protobuf/) التالية مدعومة أيضًا:

| النوع الشائع المعروف                                                                         | نوع ClickHouse           |
| -------------------------------------------------------------------------------------------- | ------------------------ |
| `google.protobuf.Timestamp`                                                                  | `DateTime`, `DateTime64` |
| `google.protobuf.Duration`                                                                   | `Time`, `Time64`         |
| `google.protobuf.StringValue`, `google.protobuf.BytesValue`                                  | `Nullable(String)`       |
| `google.protobuf.Int32Value`, `google.protobuf.SInt32Value`, `google.protobuf.SFixed32Value` | `Nullable(Int32)`        |
| `google.protobuf.Int64Value`, `google.protobuf.SInt64Value`, `google.protobuf.SFixed64Value` | `Nullable(Int64)`        |
| `google.protobuf.UInt32Value`, `google.protobuf.Fixed32Value`                                | `Nullable(UInt32)`       |
| `google.protobuf.UInt64Value`, `google.protobuf.Fixed64Value`                                | `Nullable(UInt64)`       |
| `google.protobuf.FloatValue`                                                                 | `Nullable(Float32)`      |
| `google.protobuf.DoubleValue`                                                                | `Nullable(Float64)`      |
| `google.protobuf.BoolValue`                                                                  | `Nullable(UInt8)`        |

<div id="protobuf-one-ofs">
  #### ‏Protobuf `oneof`
</div>

أثناء استنتاج المخطط، تُربَط حقول Protobuf `oneof` افتراضيًا بـ `Tuple` مُسمّى، بحيث لا يحمل قيمة غير افتراضية سوى حقل واحد كحد أقصى.
ويمكن أيضًا ربط هذه الحقول تلقائيًا بعمود `Variant`، بحيث تأخذ القيمة النشطة نوع الحقل المكوّن الذي جرى تعيينه.
وبدلاً من ذلك، يمكن ربط كل حقل مكوّن يدويًا بعمود ClickHouse خاص به؛ ونظرًا إلى أن حقول `oneof` متنافية فيما بينها، فلن يُملأ لكل سجل سوى عمود واحد.

<div id="protobuf-message-lists">
  #### قوائم الرسائل
</div>

إذا كان مخطط Protobuf المعرّف لـ ClickPipe على المستوى الأعلى يحتوي على حقل متكرر واحد يكون بحد ذاته رسالة protobuf، فسيعتمد استنتاج المخطط وتعيين الأعمدة على حقل الرسالة "المضمَّنة". وستُعالَج رسالة Kafka على أنها قائمة من هذه الرسائل، كما ستُفكَّك رسالة Kafka واحدة إلى عدة صفوف في ClickHouse.

<div id="kafka-virtual-columns">
  ## الأعمدة الافتراضية في Kafka
</div>

الأعمدة الافتراضية التالية مدعومة لمصادر البيانات المتدفقة المتوافقة مع Kafka. عند إنشاء وجهة جديدة، يمكن إضافة الأعمدة الافتراضية إلى الجدول الهدف باستخدام الزر `Add Column`.

| الاسم            | الوصف                                       | نوع البيانات الموصى به |
| ---------------- | ------------------------------------------- | ---------------------- |
| `_key`           | مفتاح رسالة Kafka                           | `String`               |
| `_timestamp`     | الطابع الزمني في Kafka (بدقة الملّي ثانية)  | `DateTime64(3)`        |
| `_partition`     | قسم Kafka                                   | `Int32`                |
| `_offset`        | إزاحة Kafka                                 | `Int64`                |
| `_topic`         | موضوع Kafka                                 | `String`               |
| `_header_keys`   | مصفوفة موازية من المفاتيح في ترويسات السجل  | `Array(String)`        |
| `_header_values` | مصفوفة موازية من الترويسات في ترويسات السجل | `Array(String)`        |
| `_raw_message`   | رسالة Kafka الكاملة                         | `String`               |

لاحظ أن العمود `_raw_message` يُوصى به فقط لبيانات JSON.
وفي حالات الاستخدام التي تكون فيها سلسلة JSON فقط هي المطلوبة (مثل استخدام دوال ClickHouse [`JsonExtract*`](/ar/reference/functions/regular-functions/json-functions#jsonextract-functions) من أجل
ملء عرض مادي لاحق)، قد يؤدي حذف جميع الأعمدة "غير الافتراضية" إلى تحسين أداء ClickPipes.

<div id="structured-message-keys">
  ### مفاتيح الرسائل المهيكلة
</div>

تؤدي مطابقة `_key` بعمود `String` إلى تخزين مفتاح رسالة Kafka الأصلي. تتجاوز هذه المطابقة فك ترميز المفتاح والبحث عن المخطط. لاستخراج الحقول من مفتاح مهيكل، طابِق حقول المصدر التي تبدأ بـ `_key.`. على سبيل المثال، لمفتاح JSON ‏`{"customer":{"id":42}}`، طابِق `_key.customer.id` بعمود وجهة مثل `customer_id`.

بالنسبة إلى مطابقات `_key.*` أو المطابقة المباشرة لـ `_key` بنوع غير `String`، يتحقق ClickPipes أولاً مما إذا كان المفتاح مُرمَّزًا باستخدام سجل المخططات المُهيأ. وإذا لم يكن كذلك، يتحقق مما إذا كان المفتاح كائن JSON. يجب أن يستخدم المفتاح المُرمَّز عبر السجل التنسيق نفسه وعائلة السجل نفسها التي تستخدمها قيمة السجل، لكنه قد يستخدم معرّف مخطط مختلفًا. تُكتشف تغييرات مخطط المفتاح تلقائيًا.

عند تمكين فك الترميز، لا تملأ المفاتيح الخام وقيم JSON القياسية أو المصفوفات أو JSON غير الصالح حقول المفاتيح المتداخلة؛ وتتلقى أعمدة الوجهة القيم الافتراضية لنوعها. إذا تعرّف ClickPipes على مفتاح مُرمَّز عبر السجل، لكنه لم يتمكن من استرداد مخططه أو تطبيقه، فإنه يكتب سجل Kafka في جدول أخطاء ClickPipes.

يمكن أن يكون لمفتاح Avro أيضًا مخطط جذر غير سجل، مثل نوع بدائي أو مصفوفة أو خريطة أو نوع ثابت. لفك ترميز أحدها، طابِق `_key` مباشرةً بنوع وجهة متوافق غير `String`. لا تستطيع المخططات غير السجل ملء حقول المفاتيح المتداخلة.