محرك جدول URL

يستعلم البيانات من خادم HTTP/HTTPS بعيد وإليه. هذا المحرك مشابه لمحرك File.

يستعلم البيانات من خادم HTTP/HTTPS بعيد وإليه. هذا المحرك مشابه لمحرك File.

يُعدّ محرك URL أيضًا طبقة موحّدة يوجّه إلى الواجهة الخلفية المناسبة استنادًا إلى مخطط URL، لذلك يُفوَّض أي مخطط معروف غير HTTP إلى المحرك المطابق — انظر Dispatching by URL scheme أدناه.

البنية: URL(URL [,Format] [,CompressionMethod])

• يجب أن تتوافق المعلَمة URL مع بنية محدد موقع الموارد الموحّد. وبالنسبة إلى عنوان URL من نوع http/https (الواجهة الخلفية الافتراضية)، يجب أن يشير إلى خادم يستخدم HTTP أو HTTPS، وألا يتطلب الحصول على استجابة من الخادم أي رؤوس إضافية. أما عنوان URL ذو مخطط غير HTTP معروف (file://، s3://، az://، hdfs://، …) فيُحال بدلًا من ذلك إلى المحرك المطابق — انظر Dispatching by URL scheme أدناه.

• يجب أن يكون Format من التنسيقات التي يمكن لـ ClickHouse استخدامها في استعلامات SELECT، وعند الحاجة، في عمليات INSERT. للاطلاع على القائمة الكاملة بالتنسيقات المدعومة، انظر Formats.

  إذا لم يتم تحديد هذه الوسيطة، يكتشف ClickHouse التنسيق تلقائيًا من لاحقة المعلَمة URL. وإذا لم تطابق لاحقة المعلَمة URL أيًا من التنسيقات المدعومة، فسيفشل إنشاء الجدول. على سبيل المثال، في تعبير المحرك URL('http://localhost/test.json')، يُطبَّق تنسيق JSON.

• يحدد CompressionMethod ما إذا كان يجب ضغط حمولة HTTP. وإذا كان الضغط مُمكّنًا، فستتضمن حزم HTTP التي يرسلها محرك URL الترويسة ‘Content-Encoding’ للإشارة إلى طريقة الضغط المستخدمة.

لتمكين الضغط، يُرجى أولًا التأكد من أن نقطة نهاية HTTP البعيدة المشار إليها بواسطة المعلَمة URL تدعم خوارزمية الضغط المقابلة.

يجب أن تكون قيمة CompressionMethod المدعومة واحدة مما يلي:

• gzip or gz
• deflate
• brotli or br
• lzma or xz
• zstd or zst
• lz4
• bz2
• snappy
• none
• auto

إذا لم يتم تحديد CompressionMethod، فستكون القيمة الافتراضية هي auto. وهذا يعني أن ClickHouse يكتشف طريقة الضغط تلقائيًا من لاحقة المعلَمة URL. وإذا طابقت اللاحقة أيًّا من طرق الضغط المذكورة أعلاه، فسيتم تطبيق الضغط المقابل، وإلا فلن يُفعَّل أي ضغط.

على سبيل المثال، في تعبير المحرك URL('http://localhost/test.gzip')، تُطبَّق طريقة الضغط gzip، أما في URL('http://localhost/test.fr')، فلن يُفعَّل أي ضغط لأن اللاحقة fr لا تطابق أيًّا من طرق الضغط المذكورة أعلاه.

​

التوجيه بحسب مخطط URL

يمثّل المحرك URL طبقةً موحّدة فوق محركات الملفات وتخزين الكائنات الأخرى: إذ يوجّه الطلبات إلى الواجهة الخلفية المناسبة استنادًا إلى مخطط URL. ويتولى المحرك URL نفسه خدمة http/https (وأي مخطط غير معروف)؛ بينما يتولى محرك File خدمة file://؛ ويتولى محرك S3 خدمة s3:// وgs:// وgcs:// وoss://؛ ويتولى محرك AzureBlobStorage خدمة az:// وazure:// وabfss:// وabfs://؛ ويتولى محرك HDFS خدمة hdfs://.

لا يُوجَّه إلا مخططات S3 التي يستطيع معيّن عناوين URI الخاص بـ S3 حلّها إلى نقطة نهاية فعلية من دون أي تهيئة إضافية (s3، بالإضافة إلى gs/gcs/oss). أما مخططات المورّدين الأخرى المتوافقة مع S3 (cos وobs وeos و…) فهي خاصة بكل Region ولا تملك تعيين نقطة نهاية افتراضيًا، لذلك فإن تمرير URL من هذا النوع إلى المحرك URL يُعامَل على أنه مخطط غير معروف ويُبلَّغ عنه كـ خطأ؛ استخدم محرك S3 مباشرةً (مع تهيئة url_scheme_mappers) لهذه الواجهات الخلفية.

يُطبَّق الإعداد url_base قبل التوجيه بحسب المخطط، لذا يُحلّ المرجع النسبي أولًا استنادًا إلى الأساس ثم يُوجَّه إلى المحرك المطابق.

CREATE TABLE file_via_url (a UInt32, b String) ENGINE = URL('file://data.csv', CSV);
CREATE TABLE s3_via_url (a UInt32, b String) ENGINE = URL('s3://bucket/key.csv', CSV);

​

الاستخدام

تُحوَّل استعلامات INSERT وSELECT إلى طلبات POST وGET، على التوالي. ولمعالجة طلبات POST، يجب أن يدعم الخادم البعيد ترميز النقل المُجزّأ.

يمكنك تحديد الحد الأقصى لعدد مرات إعادة توجيه HTTP GET باستخدام الإعداد max_http_get_redirects.

​

أحرف البدل مع صفحات فهرس HTTP

عند تمكين allow_url_wildcard_from_index_pages، يمكن لمحرك جدول URL توسيع أحرف البدل من خلال جلب صفحات فهرس HTTP واستخراج الروابط منها. وهذه هي الآلية نفسها المستخدمة في دالة الجدول url.

يكون التوسيع مقيّدًا بواسطة max_http_index_page_size لكل صفحة فهرس يتم جلبها، وبواسطة url_wildcard_max_directories_to_read عند اجتياز المجلدات بشكل متكرر.

​

مثال

1. أنشئ جدول url_engine_table على الخادم:

CREATE TABLE url_engine_table (word String, value UInt64)
ENGINE=URL('http://127.0.0.1:12345/', CSV)

2. أنشئ خادم HTTP بسيطًا باستخدام أدوات بايثون 3 القياسية، ثم شغّله:

from http.server import BaseHTTPRequestHandler, HTTPServer

class CSVHTTPServer(BaseHTTPRequestHandler):
    def do_GET(self):
        self.send_response(200)
        self.send_header('Content-type', 'text/csv')
        self.end_headers()

        self.wfile.write(bytes('Hello,1\nWorld,2\n', "utf-8"))

if __name__ == "__main__":
    server_address = ('127.0.0.1', 12345)
    HTTPServer(server_address, CSVHTTPServer).serve_forever()

$ python3 server.py

3. اطلب البيانات:

SELECT * FROM url_engine_table

┌─word──┬─value─┐
│ Hello │     1 │
│ World │     2 │
└───────┴───────┘

​

تفاصيل التنفيذ

• يمكن تنفيذ عمليات القراءة والكتابة بالتوازي
• لا يتم دعم ما يلي:
  • عمليتا ALTER وSELECT...SAMPLE.
  • الفهارس.
  • النسخ المتماثل.

​

الأعمدة الافتراضية

• _path — المسار إلى URL. النوع: LowCardinality(String).
• _file — اسم مورد URL. النوع: LowCardinality(String).
• _size — حجم المورد بالبايت. النوع: Nullable(UInt64). إذا كان الحجم غير معروف، تكون القيمة NULL.
• _time — وقت آخر تعديل للملف. النوع: Nullable(DateTime). إذا كان الوقت غير معروف، تكون القيمة NULL.
• _headers - رؤوس استجابة HTTP. النوع: Map(LowCardinality(String), LowCardinality(String)).

​

حلّ عناوين URL النسبية

يتيح الإعداد url_base استخدام عنوان URL نسبي في المحرك URL. عند تعيين url_base، يُفسَّر عنوان URL الذي يُمرَّر إلى المحرك بالاستناد إليه وفقًا لـ RFC 3986. للحصول على وصف كامل لقواعد الحلّ، راجع وثائق دالة الجدول url.

مثال

SET url_base = 'http://127.0.0.1:12345/';
CREATE TABLE url_engine_table (word String, value UInt64) ENGINE = URL('hello.csv', CSV);
SELECT * FROM url_engine_table;

​

إعدادات التخزين

• engine_url_skip_empty_files - يسمح بتجاوز الملفات الفارغة أثناء القراءة. يكون معطّلًا افتراضيًا.
• enable_url_encoding - يتيح تمكين/تعطيل فك ترميز/ترميز المسار في عنوان URI. يكون مُمكّنًا افتراضيًا.
• url_base - عنوان URL الأساسي لاستكمال عناوين URL النسبية المُمرَّرة إلى المحرّك.