CapnProto

وثائق CapnProto

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

​

الوصف

تنسيق 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.