CapnProto | ClickHouse Docs

غير مدعوم في ClickHouse Cloud

الإدخال	الإخراج	الاسم المستعار
✔	✔

الوصف

تنسيق CapnProto هو تنسيق رسائل ثنائي يشبه تنسيق Protocol Buffers وThrift، لكنه لا يشبه JSON أو MessagePack. رسائل CapnProto محددة الأنواع بشكل صارم وليست ذاتية الوصف، ما يعني أنها تحتاج إلى وصف خارجي للمخطط. ويُطبَّق المخطط آنيًا ويُخزَّن مؤقتًا لكل استعلام.

راجع أيضًا Format Schema.

مطابقة أنواع البيانات

يوضح الجدول أدناه أنواع البيانات المدعومة وكيف تقابل أنواع البيانات في ClickHouse ضمن استعلامات INSERT وSELECT.

نوع بيانات CapnProto (`INSERT`)	نوع بيانات ClickHouse	نوع بيانات CapnProto (`SELECT`)
`UINT8`, `BOOL`	UInt8	`UINT8`
`INT8`	Int8	`INT8`
`UINT16`	UInt16, Date	`UINT16`
`INT16`	Int16	`INT16`
`UINT32`	UInt32, DateTime	`UINT32`
`INT32`	Int32, Decimal32	`INT32`
`UINT64`	UInt64	`UINT64`
`INT64`	Int64, DateTime64, Decimal64	`INT64`
`FLOAT32`	Float32	`FLOAT32`
`FLOAT64`	Float64	`FLOAT64`
`TEXT, DATA`	String, FixedString	`TEXT, DATA`
`union(T, Void), union(Void, T)`	Nullable(T)	`union(T, Void), union(Void, T)`
`ENUM`	Enum(8/16)	`ENUM`
`LIST`	Array	`LIST`
`STRUCT`	Tuple	`STRUCT`
`UINT32`	IPv4	`UINT32`
`DATA`	IPv6	`DATA`
`DATA`	Int128/UInt128/Int256/UInt256	`DATA`
`DATA`	Decimal128/Decimal256	`DATA`
`STRUCT(entries LIST(STRUCT(key Key, value Value)))`	Map	`STRUCT(entries LIST(STRUCT(key Key, value Value)))`

يمكن تحويل الأنواع الصحيحة فيما بينها أثناء الإدخال والإخراج.
للعمل مع Enum بتنسيق CapnProto، استخدم الإعداد format_capn_proto_enum_comparising_mode.
يمكن أن تكون Array متداخلة، ويمكن أن تتضمن قيمة من النوع Nullable كوسيطة. كما يمكن أيضًا أن تكون الأنواع Tuple وMap متداخلة.

مثال للاستخدام

إدراج البيانات والاستعلام عنها

يمكنك إدراج بيانات CapnProto من ملف في جدول ClickHouse باستخدام الأمر التالي:

$ cat capnproto_messages.bin | clickhouse-client --query "INSERT INTO test.hits SETTINGS format_schema = 'schema:Message' FORMAT CapnProto"

حيث يكون schema.capnp على النحو التالي:

struct Message {
  SearchPhrase @0 :Text;
  c @1 :Uint64;
}

يمكنك تحديد بيانات من جدول ClickHouse وحفظها في ملف بتنسيق CapnProto باستخدام الأمر التالي:

$ clickhouse-client --query = "SELECT * FROM test.hits FORMAT CapnProto SETTINGS format_schema = 'schema:Message'"

استخدام مخطط مُنشأ تلقائيًا

إذا لم يكن لديك مخطط CapnProto خارجي لبياناتك، فلا يزال بإمكانك تصدير البيانات أو استيرادها بتنسيق CapnProto باستخدام مخطط مُنشأ تلقائيًا.

على سبيل المثال:

SELECT * FROM test.hits 
FORMAT CapnProto 
SETTINGS format_capn_proto_use_autogenerated_schema=1

في هذه الحالة، سيُنشئ ClickHouse مخطط CapnProto تلقائيًا وفقًا لبنية الجدول باستخدام الدالة structureToCapnProtoSchema، وسيستخدم هذا المخطط لتسلسل البيانات بتنسيق CapnProto.

يمكنك أيضًا قراءة ملف CapnProto باستخدام مخطط مُنشأ تلقائيًا (في هذه الحالة، يجب إنشاء الملف باستخدام المخطط نفسه):

$ cat hits.bin | clickhouse-client --query "INSERT INTO test.hits SETTINGS format_capn_proto_use_autogenerated_schema=1 FORMAT CapnProto"

إعدادات التنسيق

يكون الإعداد format_capn_proto_use_autogenerated_schema مفعّلًا افتراضيًا، ويُطبَّق إذا لم يتم تعيين format_schema.

يمكنك أيضًا حفظ المخطط المُنشأ تلقائيًا في ملف أثناء عمليات الإدخال/الإخراج باستخدام الإعداد output_format_schema.

على سبيل المثال:

SELECT * FROM test.hits 
FORMAT CapnProto 
SETTINGS 
    format_capn_proto_use_autogenerated_schema=1,
    output_format_schema='path/to/schema/schema.capnp'

في هذه الحالة، سيُحفَظ مخطط CapnProto المُنشأ تلقائيًا في الملف path/to/schema/schema.capnp.