url - ClickHouse Documentation

تنشئ الدالة url جدولًا من URL وفق format وstructure المحددين. يمكن استخدام الدالة url في استعلامات SELECT وINSERT على البيانات الموجودة في جداول URL.

الصيغة

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

المعلمات

المعلمة	الوصف
`URL`	عنوان URL محاط بعلامتَي اقتباس مفردتين، ويحدد مخططه الواجهة الخلفية. ويكون عنوان URL من نوع `http`/`https` (أو غير المعروف) عنوان خادم يقبل طلبات `GET` أو `POST` (لاستعلامات `SELECT` أو `INSERT` على الترتيب)؛ أما المخطط المعروف غير HTTP (`file://`, `s3://`, `az://`, `hdfs://`, …) فتتم إحالته إلى table function المطابقة — راجع التوجيه حسب مخطط URL. النوع: String.
`format`	تنسيق البيانات. النوع: String.
`structure`	بنية الجدول بصيغة `'UserID UInt64, Name String'`. ويحدد أسماء الأعمدة وأنواعها. النوع: String.
`headers`	الرؤوس بصيغة `'headers('key1'='value1', 'key2'='value2')'`. يمكنك تعيين رؤوس لاستدعاء HTTP.

القيمة المُعادة

جدول بالتنسيق والبنية المحدَّدين، ويحتوي على بيانات من 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 كغلاف موحّد فوق دوال الجداول الأخرى الخاصة بالملفات وتخزين الكائنات: إذ تُوجِّه إلى الواجهة الخلفية المناسبة استنادًا إلى مخطط URL. يتيح لك ذلك القراءة من أي موقع مدعوم باستخدام صياغة موحّدة واحدة.

المخطط	يوجّه إلى
`http`, `https` (وأي مخطط غير معروف)	المحرك `URL` نفسه (HTTP `GET`/`POST`)
`file`	الدالة `file`
`s3`, `gs`, `gcs`, `oss`	الدالة `s3`
`az`, `azure`, `abfss`, `abfs`	الدالة `azureBlobStorage`
`hdfs`	الدالة `hdfs`

لا تُوجَّه إلا مخططات 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, …) لهذه الجهات الخلفية.

أنماط glob في URL

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

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

بالنسبة إلى 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

عند تعيين 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 النسبية

يتيح الإعداد 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.

مثال

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.

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

​الصيغة

​المعلمات

​القيمة المُعادة

​أمثلة

​التوجيه وفق مخطط URL

​أنماط glob في URL

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

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

​إعداد use_hive_partitioning

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

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

​الأذونات

​مواضيع ذات صلة