system.documentation

جدول نظامي يجمع الوثائق المضمّنة لمكوّنات النظام الموحّدة (مثل الدوال، ومحركات الجداول، وأنواع البيانات، وغير ذلك) في جدول واحد، مع عرض الوثائق المرجعية بصيغة Markdown.

​

الوصف

يجمع هذا الجدول الوثائق المضمّنة للمكوّنات الموحّدة في النظام في جدول واحد. ويمثّل كل صف كيانًا واحدًا (مثل دالة، أو محرك جدول، أو نوع بيانات، وما إلى ذلك)، ويحتوي على وثائقه المرجعية المضمّنة معروضة بصيغة Markdown. ويستند إلى هذا المحتوى ما يُولَّد من وثائق الموقع الإلكتروني وجداول system.* الخاصة بكل نوع؛ وقد تضيف صفحات الموقع الإلكتروني مقدّمات أو إرشادات خاصة بصيغة MDX خارج المتون المُولَّدة.

يُجمَّع description من الأجزاء المنظَّمة للوثائق المضمّنة (description وsyntax والوسيطات والأمثلة وما إلى ذلك)، بحيث يحتوي عمود واحد على الوثائق المضمّنة الكاملة للكيان. وعندما تتضمّن الوثائق المضمّنة الصفحة المرجعية كاملةً داخل description الخاص بها (كما هو الحال بالنسبة إلى المكوّنات التي تُولَّد صفحات موقعها الإلكتروني منها تلقائيًا: محركات الجداول، ومحركات قواعد البيانات، وأنواع البيانات، والتنسيقات، ودوال الجداول)، تُنشر الصفحة كما هي، من دون إلحاق أقسام مُنشأة من حقول البيانات الوصفية المنظَّمة — لأن متن الصفحة يغطي هذه المادة بالفعل. وتُعرض الأسماء المستعارة كإحالة مرجعية قصيرة إلى الكيان المرجعي، مثل: Alias of `trunc`.

يجمع هذا الجدول، إلى حدٍّ ما، المعلومات المتاحة في جداول الوثائق الخاصة بكل نوع (system.functions، وsystem.table_engines، وsystem.data_type_families، وغيرها). وهو مخصّص، على وجه الخصوص، لدعم أمر help تفاعلي في العميل، لكنه مفيد أيضًا بحد ذاته.

تُجمع الأنواع التالية من الكيانات (وتظهر قيمة العمود type بين قوسين):

• الدوال (Function)
• الدوال التجميعية (Aggregate Function)
• دوال الجداول (Table Function)
• محركات الجداول (Table Engine)
• محركات قواعد البيانات (Database Engine)
• أنواع البيانات (Data Type)
• تخطيطات القواميس (Dictionary Layout)
• مصادر القواميس (Dictionary Source)
• مُركِّبات الدوال التجميعية (Aggregate Function Combinator)
• أنواع فهارس تخطي البيانات (Data Skipping Index)
• أنواع الأقراص (Disk Type)
• الإعدادات (Setting)
• إعدادات MergeTree (MergeTree Setting)
• إعدادات الخادم (Server Setting)
• التنسيقات (Format)
• ترميزات الضغط (Compression Codec)
• أحداث الملف الشخصي (Profile Event)
• المقاييس الحالية (Current Metric)
• المقاييس غير المتزامنة (Asynchronous Metric)
• الجداول النظامية (System Table)
• عبارات SQL (Statement)

بالنسبة إلى الإعدادات (من أي نوع)، تكون الوثائق هي وصف الإعداد، إلى جانب نوعه وقيمته الافتراضية؛ ولا تُعرض الإعدادات المتقادمة. كما تتضمن سجل التغييرات التي طرأت على القيمة الافتراضية للإعداد عبر إصدارات ClickHouse: الإصدار الذي أُضيف فيه الإعداد وكل تغيير لاحق لقيمته الافتراضية، مع القيمة السابقة والقيمة الجديدة وسبب التغيير. وهذه هي البيانات نفسها التي يستند إليها إعداد compatibility وsystem.settings_changes، لذا فهي تغطي التغييرات المسجّلة منذ إدخال تلك الآلية: فالإعداد الأقدم الذي لم تتغير قيمته الافتراضية مطلقًا ليس له سجل، وكذلك إعدادات الخادم التي لا يغطيها compatibility. وينتمي التغيير المسجل تحت اسم مستعار لإعداد إلى سجل ذلك الإعداد، بالطريقة نفسها التي يطبقه بها compatibility، لذا لا ينقطع سجل الإعداد الذي أُعيدت تسميته عند إعادة التسمية؛ والاستثناء هو سجل مكتوب تحت اسم مستعار لغرض وحيد هو تسجيل ذلك الاسم المستعار، إذ يكون ضمن سجل الاسم المستعار وحده. ويحمل الاسم المستعار سجل اسمه الخاص: كل سجل كُتب تحته، إضافة إلى السجل الذي عرّفه اسمًا مستعارًا، والذي يكتبه ملف السجل أحيانًا تحت اسم آخر للإعداد نفسه.

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

وبالنسبة إلى عبارات SQL، تُعرض الوثائق من الحقول المنظَّمة التي يوفّرها system.statements، بما في ذلك syntax والعبارات ذات الصلة عندما لا تكون هذه الأقسام جزءًا من الوصف الذي يملكه المصدر بالفعل.

يحتوي العمود source على مسار مصدري للكيان، نسبةً إلى جذر المستودع. وبالنسبة إلى معظم الكيانات، يُلتقط هذا تلقائيًا في الموضع الذي يُنشأ فيه كائن الوثائق (موضع تسجيل المكوّن)؛ وبالنسبة إلى الجداول النظامية، يكون الملف الذي يملك الوثائق المضمّنة (مثل attachSystemTables.cpp أو SystemLog.h أو مالك وثائق مخصّص)، أما الأنواع التي يُوثَّق كلٌّ منها في ملف مصدري واحد (مثل الإعدادات وأحداث الملف الشخصي والمقاييس الحالية)، فيكون ذلك الملف.

​

الأعمدة

• name (String) — اسم الكيان، مثل domainWithoutWWW أو MergeTree.
• type (Enum8(‘Function’ = 1, ‘Aggregate Function’ = 2, ‘Table Function’ = 3, ‘Table Engine’ = 4, ‘Database Engine’ = 5, ‘Data Type’ = 6, ‘Dictionary Layout’ = 7, ‘Dictionary Source’ = 8, ‘Aggregate Function Combinator’ = 9, ‘Data Skipping Index’ = 10, ‘Disk Type’ = 11, ‘Setting’ = 12, ‘MergeTree Setting’ = 13, ‘Server Setting’ = 14, ‘Format’ = 15, ‘Compression Codec’ = 16, ‘Profile Event’ = 17, ‘Current Metric’ = 18, ‘Asynchronous Metric’ = 19, ‘System Table’ = 20, ‘Statement’ = 21)) — نوع الكيان، مثل Function أو Table Engine.
• description (String) — الوثائق المرجعية للكيان معروضة بتنسيق Markdown، ومجمّعة من الوثائق المضمّنة، وتتضمن syntax والأمثلة والأجزاء المنظَّمة الأخرى، إن وُجدت. وقد تضيف صفحات الموقع الإلكتروني مقدمات أو إرشادات خاصة بـ MDX خارج المتون المولّدة.
• source (String) — المسار إلى الملف المصدري الذي تُعرَّف فيه وثائق الكيان، نسبةً إلى جذر المستودع. يكون فارغًا إذا كان موقع المصدر غير معروف.

​

مثال

راجع وثائق كيان معيّن:

Query

SELECT description
FROM system.documentation
WHERE type = 'Table Engine' AND name = 'MergeTree'
FORMAT TSVRaw;

يمكن أن يشير الاسم نفسه إلى عدة أنواع من الكيانات (على سبيل المثال، توجد file كدالة جدول وكمصدر قاموس)، لذا من المفيد البحث عن الاسم عبر جميع الأنواع:

Query

SELECT type, name
FROM system.documentation
WHERE name = 'file'
ORDER BY type;

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

Query

SELECT type, count()
FROM system.documentation
GROUP BY type
ORDER BY count() DESC;

تعرّف على الإصدار الذي أُضيف فيه إعداد وكيف تغيّرت قيمته الافتراضية منذ ذلك الحين:

Query

SELECT description
FROM system.documentation
WHERE type = 'Setting' AND name = 'async_insert_max_data_size'
FORMAT TSVRaw;

​

انظر أيضًا

• system.functions — الدوال العادية والتجميعية.
• system.table_functions — دوال الجداول.
• system.table_engines — محركات الجداول.
• system.database_engines — محركات قواعد البيانات.
• system.data_type_families — أنواع البيانات.
• system.disk_types — أنواع الأقراص.
• system.settings — الإعدادات.
• system.merge_tree_settings — إعدادات MergeTree.
• system.server_settings — إعدادات الخادم.
• system.settings_changes — سجل تغييرات القيم الافتراضية للإعدادات.
• system.formats — التنسيقات.