> ## Documentation Index > Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-fbfa8bee.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. > توثيق خاص بتنسيق AvroConfluent # AvroConfluent | الإدخال | الإخراج | اسم بديل | | ------- | ------- | -------- | | ✔ | ✔ | |
## الوصف
يُعد [Apache Avro](https://avro.apache.org/) تنسيق تسلسل موجَّهًا للصفوف يستخدم الترميز الثنائي لمعالجة البيانات بكفاءة. ويدعم تنسيق `AvroConfluent` قراءة الرسائل المرمّزة بـ Avro وكتابتها باستخدام [Confluent Schema Registry](https://docs.confluent.io/current/schema-registry/index.html) (أو الخدمات المتوافقة مع واجهة برمجة التطبيقات). تستخدم كل رسالة تنسيق Confluent wire: بايت سحري (`0x00`) يتبعه معرّف مخطط بطول 4 بايت بترتيب big-endian، ثم بيانات Avro الثنائية. عند القراءة، يحدّد ClickHouse معرّف مخطط عبر الاستعلام من السجل. وعند الكتابة، يسجّل ClickHouse المخطط المستمد من أعمدة الإخراج ويضيف المعرّف الناتج إلى بداية كل صف. وتُخزَّن المخططات مؤقتًا لتحقيق أفضل أداء.
## تعيين أنواع البيانات
يوضح الجدول أدناه جميع أنواع البيانات التي يدعمها تنسيق Apache Avro، وأنواع بيانات ClickHouse [المقابلة](/ar/reference/data-types/index) في استعلامات `INSERT` و`SELECT`. | نوع بيانات Avro `INSERT` | نوع بيانات ClickHouse | نوع بيانات Avro `SELECT` | | ------------------------------------------- | ----------------------------------------------------------------------------------------------------- | -------------------------------- | | `boolean`, `int`, `long`, `float`, `double` | [Int(8\16\32)](/ar/reference/data-types/int-uint), [UInt(8\16\32)](/ar/reference/data-types/int-uint) | `int` | | `boolean`, `int`, `long`, `float`, `double` | [Int64](/ar/reference/data-types/int-uint), [UInt64](/ar/reference/data-types/int-uint) | `long` | | `boolean`, `int`, `long`, `float`, `double` | [Float32](/ar/reference/data-types/float) | `float` | | `boolean`, `int`, `long`, `float`, `double` | [Float64](/ar/reference/data-types/float) | `double` | | `bytes`, `string`, `fixed`, `enum` | [String](/ar/reference/data-types/string) | `bytes` أو `string` \* | | `bytes`, `string`, `fixed` | [FixedString(N)](/ar/reference/data-types/fixedstring) | `fixed(N)` | | `enum` | [Enum(8\16)](/ar/reference/data-types/enum) | `enum` | | `array(T)` | [Array(T)](/ar/reference/data-types/array) | `array(T)` | | `map(V, K)` | [Map(V, K)](/ar/reference/data-types/map) | `map(string, K)` | | `union(null, T)`, `union(T, null)` | [Nullable(T)](/ar/reference/data-types/date) | `union(null, T)` | | `union(T1, T2, …)` \*\* | [Variant(T1, T2, …)](/ar/reference/data-types/variant) | `union(T1, T2, …)` \*\* | | `null` | [Nullable(Nothing)](/ar/reference/data-types/special-data-types/nothing) | `null` | | `int (date)` \*\*\* | [Date](/ar/reference/data-types/date), [Date32](/ar/reference/data-types/date32) | `int (date)` \*\*\* | | `long (timestamp-millis)` \*\*\* | [DateTime64(3)](/ar/reference/data-types/datetime) | `long (timestamp-millis)` \*\*\* | | `long (timestamp-micros)` \*\*\* | [DateTime64(6)](/ar/reference/data-types/datetime) | `long (timestamp-micros)` \*\*\* | | `bytes (decimal)` \*\*\* | [DateTime64(N)](/ar/reference/data-types/datetime) | `bytes (decimal)` \*\*\* | | `int` | [IPv4](/ar/reference/data-types/ipv4) | `int` | | `fixed(16)` | [IPv6](/ar/reference/data-types/ipv6) | `fixed(16)` | | `bytes (decimal)` \*\*\* | [Decimal(P, S)](/ar/reference/data-types/decimal) | `bytes (decimal)` \*\*\* | | `string (uuid)` \*\*\* | [UUID](/ar/reference/data-types/uuid) | `string (uuid)` \*\*\* | | `fixed(16)` | [Int128/UInt128](/ar/reference/data-types/int-uint) | `fixed(16)` | | `fixed(32)` | [Int256/UInt256](/ar/reference/data-types/int-uint) | `fixed(32)` | | `record` | [Tuple](/ar/reference/data-types/tuple) | `record` | * `bytes` هو الخيار الافتراضي، ويُتحكم فيه عبر الإعداد [`output_format_avro_string_column_pattern`](/ar/reference/settings/formats#output_format_avro_string_column_pattern) \*\* يقبل [نوع Variant](/ar/reference/data-types/variant) القيمة `null` ضمنيًا كقيمة للحقل، لذلك سيُحوَّل Avro `union(T1, T2, null)`، على سبيل المثال، إلى `Variant(T1, T2)`. ونتيجةً لذلك، عند إنشاء Avro من ClickHouse، يجب علينا دائمًا تضمين النوع `null` ضمن مجموعة أنواع Avro `union` لأننا لا نعرف أثناء استدلال المخطط ما إذا كانت أي قيمة هي بالفعل `null`. \*\*\* [الأنواع المنطقية في Avro](https://avro.apache.org/docs/current/spec.html#Logical+Types) أنواع البيانات المنطقية غير المدعومة في Avro: * `time-millis` * `time-micros` * `duration`
## إعدادات التنسيق
[//]: # "ملاحظة: يمكن ضبط هذه الإعدادات على مستوى الجلسة، لكن هذا غير شائع، وقد يؤدي توثيق ذلك بشكل بارز جدًا إلى إرباك المستخدمين." | الإعداد | الوصف | القيمة الافتراضية | | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------- | | `input_format_avro_allow_missing_fields` | ما إذا كان سيتم استخدام قيمة افتراضية بدلًا من إصدار خطأ عند عدم العثور على حقل في المخطط. | `0` | | `input_format_avro_null_as_default` | ما إذا كان سيتم استخدام قيمة افتراضية بدلًا من إصدار خطأ عند إدراج قيمة `null` في عمود لا يقبل NULL. | `0` | | `format_avro_schema_registry_url` | عنوان URL الخاص بـ Confluent Schema Registry. عند استخدام المصادقة الأساسية، يمكن تضمين بيانات الاعتماد المرمّزة بتنسيق URL مباشرةً في مسار URL. | | | `format_avro_schema_registry_connection_timeout` | مهلة الاتصال بالثواني لعميل HTTP الخاص بـ Schema Registry (تُستخدم لكل من جلب المخطط والتسجيل). يجب أن تكون أكبر من 0 وأقل من 600 (10 دقائق). | `1` | | `format_avro_schema_registry_send_timeout` | مهلة الإرسال بالثواني لعميل HTTP الخاص بـ Schema Registry. يجب أن تكون أكبر من 0 وأقل من 600 (10 دقائق). | `1` | | `format_avro_schema_registry_receive_timeout` | مهلة الاستلام بالثواني لعميل HTTP الخاص بـ Schema Registry. يجب أن تكون أكبر من 0 وأقل من 600 (10 دقائق). | `1` | | `output_format_avro_confluent_subject` | للإخراج: اسم subject الذي يُسجَّل المخطط تحته في Schema Registry. وهو مطلوب عند الكتابة. | | | `output_format_avro_string_column_pattern` | للإخراج: تعبير نمطي لأعمدة String لتسلسلها كـ Avro `string` (القيمة الافتراضية هي `bytes`). | |
## أمثلة
### القراءة من Kafka
لقراءة موضوع Kafka مُشفَّرًا باستخدام Avro عبر [محرك جدول Kafka](/ar/reference/engines/table-engines/integrations/kafka)، استخدم الإعداد `format_avro_schema_registry_url` لتحديد URL لسجل المخططات. ```sql theme={null} CREATE TABLE topic1_stream ( field1 String, field2 String ) ENGINE = Kafka() SETTINGS kafka_broker_list = 'kafka-broker', kafka_topic_list = 'topic1', kafka_group_name = 'group1', kafka_format = 'AvroConfluent', format_avro_schema_registry_url = 'http://schema-registry-url'; SELECT * FROM topic1_stream; ```
### الكتابة إلى Kafka
لكتابة رسائل AvroConfluent إلى موضوع Kafka، عيّن عنوان URL لسجل المخططات واسم الـsubject. يُسجَّل المخطط تلقائيًا في السجل عند أول عملية كتابة. ```sql theme={null} CREATE TABLE topic1_sink ( field1 String, field2 String ) ENGINE = Kafka() SETTINGS kafka_broker_list = 'kafka-broker', kafka_topic_list = 'topic1', kafka_format = 'AvroConfluent', format_avro_schema_registry_url = 'http://schema-registry-url', output_format_avro_confluent_subject = 'topic1-value'; INSERT INTO topic1_sink VALUES ('hello', 'world'); ```
#### استخدام المصادقة الأساسية
إذا كان سجل المخططات لديك يتطلب المصادقة الأساسية (على سبيل المثال، إذا كنت تستخدم Confluent Cloud)، فيمكنك تمرير بيانات الاعتماد المرمَّزة وفق URL في الإعداد `format_avro_schema_registry_url`. ```sql theme={null} CREATE TABLE topic1_stream ( field1 String, field2 String ) ENGINE = Kafka() SETTINGS kafka_broker_list = 'kafka-broker', kafka_topic_list = 'topic1', kafka_group_name = 'group1', kafka_format = 'AvroConfluent', format_avro_schema_registry_url = 'https://:@schema-registry-url'; ```
## استكشاف الأخطاء وإصلاحها
لمراقبة تقدّم الإدخال واستكشاف أخطاء مستهلك Kafka، يمكنك الاستعلام عن [جدول النظام `system.kafka_consumers`](/ar/reference/system-tables/kafka_consumers). إذا كان النشر لديك يتضمن عدة نُسخ متماثلة (على سبيل المثال، ClickHouse Cloud)، فيجب عليك استخدام [دالة الجدول `clusterAllReplicas`](/ar/reference/functions/table-functions/cluster). ```sql theme={null} SELECT * FROM clusterAllReplicas('default',system.kafka_consumers) ORDER BY assignments.partition_id ASC; ``` إذا واجهت مشكلات في التعرّف على المخطط، يمكنك استخدام [kafkacat](https://github.com/edenhill/kafkacat) مع [clickhouse-local](/ar/concepts/features/tools-and-utilities/clickhouse-local) لتشخيص المشكلة: ```bash theme={null} $ kafkacat -b kafka-broker -C -t topic1 -o beginning -f '%s' -c 3 | clickhouse-local --input-format AvroConfluent --format_avro_schema_registry_url 'http://schema-registry' -S "field1 Int64, field2 String" -q 'select * from table' 1 a 2 b 3 c ```