url

تنشئ الدالة url جدولًا من URL وفق format وstructure المحددين.

يمكن استخدام الدالة url في استعلامات SELECT وINSERT على البيانات الموجودة في جداول URL.

url(URL [,format] [,structure] [,headers])

جدول بالتنسيق والبنية المحدَّدين، ويحتوي على بيانات من URL المحدَّد.

الحصول على أول 3 أسطر من جدول يحتوي على أعمدة من النوع String والنوع UInt32 من خادم HTTP يردّ بتنسيق CSV.

SELECT * FROM url('http://127.0.0.1:12345/', CSV, 'column1 String, column2 UInt32', headers('Accept'='text/csv; charset=utf-8')) LIMIT 3;

إدراج البيانات من URL في جدول:

CREATE TABLE test_table (column1 String, column2 UInt32) ENGINE=Memory;
INSERT INTO FUNCTION url('http://127.0.0.1:8123/?query=INSERT+INTO+test_table+FORMAT+CSV', 'CSV', 'column1 String, column2 UInt32') VALUES ('http interface', 42);
SELECT * FROM test_table;

تعمل الدالة url كغلاف موحّد فوق دوال الجداول الأخرى الخاصة بالملفات وتخزين الكائنات: إذ تُوجِّه إلى الواجهة الخلفية المناسبة استنادًا إلى مخطط URL. يتيح لك ذلك القراءة من أي موقع مدعوم باستخدام صياغة موحّدة واحدة.

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

بالنسبة إلى file://، يُحل المسار النسبي (file://data.csv) داخل الدليل user_files، ويجب أن يشير المسار المطلق (file:///home/user/data.csv) إلى موقع داخله كالمعتاد.

تعمل الوسيطات format وstructure وcompression_method وكذلك الإعداد url_base بالطريقة نفسها بغض النظر عن هدف التوجيه.

SELECT * FROM url('file://data.csv', CSV, 'a UInt32, b String');
SELECT * FROM url('s3://clickhouse-public-datasets/hits_compatible/hits.csv');

لا يزال تمرير الـ مخطط عبر urlCluster غير مدعوم: إذ يُرفَض أي مخطط غير http(s) يُمرَّر إلى urlCluster مع ظهور خطأ. استخدم بدلًا من ذلك دالة cluster المقابلة (s3Cluster, azureBlobStorageCluster, hdfsCluster, …) لهذه الجهات الخلفية.

تُستخدم الأنماط داخل { } لإنشاء مجموعة من الشظايا أو لتحديد عناوين التبديل الاحتياطي. للاطلاع على أنواع الأنماط المدعومة والأمثلة، راجع وصف الدالة remote. يُستخدم المحرف | داخل الأنماط لتحديد عناوين التبديل الاحتياطي. ويجري المرور عليها بالترتيب نفسه الوارد في النمط. ويكون عدد العناوين المُنشأة محدودًا بإعداد glob_expansion_max_elements. للاطلاع على بنية glob للمسار ضمن URL (مثل * و {a,b} و {N..M} و **)، راجع أنماط glob في المسار. لاحظ أن ? يبدأ سلسلة الاستعلام في URL، ولا يمكن استخدامه كحرف بدل في مكوّن المسار.

بالنسبة إلى url ومحرك الجدول URL، يمكن لـ ClickHouse توسيع أحرف البدل من خلال جلب صفحات فهرس HTTP ‏(HTML أو نص عادي) واستخراج عناوين URL من جسم الاستجابة. يتيح ذلك أنماطًا مثل /**/ عندما يوفّر الخادم سردًا للدلائل.

ملاحظات:

• تُفسَّر عناوين URL النسبية استنادًا إلى عنوان URL لصفحة الفهرس.
• تُوسَّع قوالب URL قبل جلب صفحات الفهرس، بما في ذلك توسيع الشظايا المفصولة بفواصل ونطاقات الأرقام وخيارات | للتبديل الاحتياطي خارج مكوّن المسار.
• لا تُدعَم أنماط التبديل الاحتياطي | داخل مكوّن المسار عند توسيع صفحات فهرس HTTP.
• يُطبَّق تطابق أحرف البدل على مكوّن المسار في عنوان URL.
• إذا كان عنوان URL المُدرَج يحتوي بالفعل على سلسلة استعلام أو جزء، فستكون لهما الأولوية على نظيريهما من عنوان URL المصدر. وإلا، فستُستخدم سلسلة الاستعلام والجزء من عنوان URL المصدر.
• يُسمح بسرد فارغ؛ أما أخطاء HTTP ‏(مثل 404) في صفحات الفهرس فتؤدي إلى ظهور استثناءات.
• يُقيَّد الحد الأقصى لحجم صفحة الفهرس بواسطة max_http_index_page_size.
• يُقيَّد الحد الأقصى لعدد الدلائل المقروءة أثناء التوسيع التكراري بواسطة url_wildcard_max_directories_to_read.

مثال:

SELECT count()
FROM url('https://ftp.gnu.org/gnu/wget/wget-1.21*.tar.gz', 'RawBLOB')
SETTINGS max_threads = 1, allow_experimental_url_wildcard_from_index_pages = 1;

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

عند تعيين use_hive_partitioning إلى 1، سيكتشف ClickHouse التقسيم بنمط Hive في المسار (/name=value/) وسيتيح استخدام أعمدة التقسيم كأعمدة افتراضية في الاستعلام. وستكون لهذه الأعمدة الافتراضية الأسماء نفسها الموجودة في مسار التقسيم.

مثال

استخدام عمود افتراضي مُنشأ باستخدام التقسيم بنمط Hive

SELECT * FROM url('http://data/path/date=*/country=*/code=*/*.parquet') WHERE date > '2020-01-01' AND country = 'Netherlands' AND code = 42;

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

قواعد الحلّ هي:

• نسبي إلى المسار (مثل data.csv): يُدمج مع مسار عنوان URL الأساسي — بحيث يُستبدل كل ما يلي آخر / في المسار الأساسي. وتُعد الشرطة المائلة الختامية مهمة: https://example.com/dir/ + data.csv ينتج https://example.com/dir/data.csv، بينما https://example.com/dir + data.csv ينتج https://example.com/data.csv. كما تُطبَّع مقاطع النقاط (./ و ../).
• نسبي إلى المضيف (مثل /test/data.csv): يُحلّ باستخدام المخطط والمضيف لعنوان URL الأساسي.
• نسبي إلى المخطط (مثل //other.com/test/data.csv): يُحلّ باستخدام مخطط عنوان URL الأساسي.
• استعلام فقط (مثل ?x=1): يُلحَق بالمسار الأساسي الكامل، مع استبدال أي استعلام أو جزء موجود.
• جزء فقط (مثل #frag): يُلحَق بعنوان URL الأساسي، مع الاحتفاظ بالاستعلام واستبدال أي جزء موجود.
• فارغ: يعيد عنوان URL الأساسي من دون جزء.
• عنوان URL مطلق: يُمرَّر كما هو من دون تغيير؛ ويُتجاهل url_base. لا يُعد عنوان URL مطلقًا إلا إذا كان يبدأ بـ scheme://: فالاسم الذي يحتوي مقطعه الأول من المسار على نقطتين رأسيتين (مثل report:2026.csv)، والذي سيحلله RFC 3986 باعتباره عنوان URI مطلقًا بالمخطط report، يُحل بدلًا من ذلك كمرجع نسبي إلى المسار، لأن هذا الاسم ليس عنوان URL صالحًا للاستخدام.
• أساسي ذو مخطط فقط (مثل file://): يُلحَق عنوان URL النسبي إلى المسار بالعنوان الأساسي مباشرةً: file:// + data.csv = file://data.csv، وهو ما يعني، بالنسبة إلى مخطط file://، مسارًا نسبيًا إلى الدليل user_files (الدليل الحالي لـ clickhouse-local). وتُبقى مقاطع النقاط كما هي في هذه الحالة.

مثال

SET url_base = 'https://raw.githubusercontent.com/ClickHouse/ClickHouse/master/';
SELECT * FROM url('tests/queries/0_stateless/data_csv/data.csv', CSV) LIMIT 3;

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

تتطلب الدالة url الإذن CREATE TEMPORARY TABLE. لذلك، لن تعمل مع المستخدمين الذين لديهم الإعداد readonly = 1. ويُشترط أن تكون القيمة على الأقل readonly = 2.

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