البحث في الوثائق

توثيق لواجهة الويب المدمجة للبحث في الوثائق، والمتاحة على المسار /docs ضمن واجهة HTTP والمستندة إلى الجدول system.documentation

صفحة البحث في الوثائق هي واجهة ويب صغيرة ومستقلة تتيح البحث الفوري في الوثائق المرجعية المضمّنة. وهي متاحة على المسار /docs عبر أي منفذ HTTP في ClickHouse.

انتقل إلى /docs على أي منفذ HTTP في ClickHouse (على سبيل المثال، http://localhost:8123/docs) لفتحها.

​

ما الذي تفعله

تستعلم الصفحة من جدول system.documentation عبر HTTP أثناء الكتابة، وتعرض محتوى Markdown الخاص بالكيان المحدد. ولأنها تقرأ من system.documentation، فهي تغطي كل كيان يتيحه ذلك الجدول — الدوال، والدوال التجميعية، ودوال الجداول، ومحركات الجداول، ومحركات قواعد البيانات، وأنواع البيانات، والإعدادات، والتنسيقات، ومرمّزات الضغط، وأحداث profile، والمقاييس، وجداول النظام نفسها، وغير ذلك — وتطابق دائمًا الوثائق المضمّنة في الخادم قيد التشغيل.

اكتب في مربع البحث، فتظهر المطابقات في قائمة ملوّنة بحسب النوع؛ وعند تحديد إحدى المطابقات، تُعرض وثائقها. ويتضمن العرض ما يلي:

• رابط بأيقونة قلم بجوار عنوان الكيان يفتح ملفه المصدري على GitHub، ويُؤخذ من العمود source في system.documentation;
• تمييز بناء الجملة لشيفرة ClickHouse SQL في كتل الشيفرة، باستخدام نفس المحلل المضمّن (Lexer.wasm) كما في واجهة /play;
• عرض معادلات TeX عبر KaTeX (على سبيل المثال، الصيغة في صفحة corr);
• تنبيهات :::note/:::tip/…، وروابط ارتساء للعناوين مع روابط قابلة للمشاركة، وزر “Copy” يظهر عند تمرير المؤشر فوق كتل الشيفرة;
• تُحل الروابط النسبية إلى كيان موثّق آخر داخل التطبيق عند وجوده، وإلا فإلى https://clickhouse.com/docs; كما تتحول مراجع “Related” و”Alias of” إلى روابط داخل التطبيق.

تُعكس عبارة البحث الحالية، والكيان المفتوح، والقسم في جزء URL، بحيث يمكن الربط مباشرة بصفحة أو قسم معيّن، كما يمكن استعادتهما عبر أزرار الرجوع/التقدم في المتصفح. ويوجد أيضًا مبدّل للنسق الفاتح/الداكن (مع الاكتشاف التلقائي) يتطابق مع /play.

​

الاتصال

تتضمن الترويسة حقول إدخال URL وuser وpassword، تمامًا كما في /play. عند تقديم الصفحة عبر ClickHouse، تكون قيمة URL الافتراضية هي الأصل الحالي؛ وعند فتح الصفحة كملف محلي، تكون القيمة الافتراضية http://localhost:8123/، لذلك يمكن أيضًا فتح الصفحة محليًا للاتصال بخادم بعيد. يُعاد إنشاء ذاكرة التخزين المؤقت لأسماء الروابط المتقاطعة تلقائيًا عند تغيّر الاتصال.

​

الأصول

تُخدَّم جميع الأصول — بما في ذلك مُصيّر Markdown (Marked)، ومُصيّر الرياضيات (KaTeX مع خطوطه)، والمحلل المعجمي لـ SQL — من الملف التنفيذي لـ ClickHouse نفسه عند خدمة الصفحة عبر HTTP. لا يتم تحميل أي شبكات CDN تابعة لجهات خارجية من أصل HTTP الخاص بـ ClickHouse، لذا تكون الصفحة مكتفية ذاتيًا، وتعمل دون اتصال، ولا تُشغِّل أي شيفرة شبكة تابعة لجهة خارجية إلى جانب بيانات الاعتماد التي تتعامل معها.

​

اعتبارات الأمان

ترسل الصفحة استعلامات إلى endpoint ‏HTTP الخاص بـ ClickHouse باستخدام credentials المُدخلة في header، لذا تنطبق هنا التحذيرات نفسها الخاصة ببروتوكول HTTP:

• احرص دائمًا على تقديم /docs عبر HTTPS في البيئات غير الموثوقة لحماية credentials.
• قيّد الوصول على مستوى الشبكة (firewall، أو reverse proxy، أو إعداد listen_host) بالطريقة نفسها التي تقيّد بها الوصول إلى بروتوكول HTTP.

لا يحتوي system.documentation إلا على الوثائق المرجعية الثابتة المضمنة في server، لذلك لا تكشف الصفحة أي بيانات من جداولك.