> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

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

# محرك جدول URL

يستعلم البيانات من خادم HTTP/HTTPS بعيد وإليه. هذا المحرك مشابه لمحرك [File](/docs/ar/reference/engines/table-engines/special/file).

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

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

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

* يجب أن يكون `Format` من التنسيقات التي يمكن لـ ClickHouse استخدامها في استعلامات `SELECT`، وعند الحاجة، في عمليات `INSERT`. للاطلاع على القائمة الكاملة بالتنسيقات المدعومة، انظر [Formats](/docs/ar/reference/formats/index#formats-overview).

  إذا لم يتم تحديد هذه الوسيطة، يكتشف 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` لا تطابق أيًّا من طرق الضغط المذكورة أعلاه.

<div id="scheme-dispatch">
  ## التوجيه بحسب مخطط URL
</div>

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

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

يُطبَّق الإعداد [url\_base](/docs/ar/reference/settings/session-settings#url_base) قبل التوجيه بحسب المخطط، لذا يُحلّ المرجع النسبي أولًا استنادًا إلى الأساس ثم يُوجَّه إلى المحرك المطابق.

```sql theme={null}
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);
```

<div id="using-the-engine-in-the-clickhouse-server">
  ## الاستخدام
</div>

تُحوَّل استعلامات `INSERT` و`SELECT` إلى طلبات `POST` و`GET`،
على التوالي. ولمعالجة طلبات `POST`، يجب أن يدعم الخادم البعيد
[ترميز النقل المُجزّأ](https://en.wikipedia.org/wiki/Chunked_transfer_encoding).

يمكنك تحديد الحد الأقصى لعدد مرات إعادة توجيه HTTP GET باستخدام الإعداد [max\_http\_get\_redirects](/docs/ar/reference/settings/session-settings#max_http_get_redirects).

<div id="wildcards-with-http-index-pages">
  ## أحرف البدل مع صفحات فهرس HTTP
</div>

عند تمكين [allow\_experimental\_url\_wildcard\_from\_index\_pages](/docs/ar/reference/settings/session-settings#allow_experimental_url_wildcard_from_index_pages)، يمكن لمحرك الجدول `URL` توسيع أحرف البدل من خلال جلب صفحات فهرس HTTP واستخراج الروابط منها.
وهذه هي الآلية نفسها المستخدمة في دالة الجدول [`url`](/docs/ar/reference/functions/table-functions/url#wildcards-with-http-index-pages).

يكون التوسيع مقيّدًا بواسطة [max\_http\_index\_page\_size](/docs/ar/reference/settings/server-settings/settings#max_http_index_page_size) لكل صفحة فهرس يتم جلبها، وبواسطة [url\_wildcard\_max\_directories\_to\_read](/docs/ar/reference/settings/session-settings#url_wildcard_max_directories_to_read) عند اجتياز المجلدات بشكل متكرر.

<div id="example">
  ## مثال
</div>

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

```sql theme={null}
CREATE TABLE url_engine_table (word String, value UInt64)
ENGINE=URL('http://127.0.0.1:12345/', CSV)
```

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

```python3 theme={null}
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()
```

```bash theme={null}
$ python3 server.py
```

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

```sql theme={null}
SELECT * FROM url_engine_table
```

```text theme={null}
┌─word──┬─value─┐
│ Hello │     1 │
│ World │     2 │
└───────┴───────┘
```

<div id="details-of-implementation">
  ## تفاصيل التنفيذ
</div>

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

<div id="virtual-columns">
  ## الأعمدة الافتراضية
</div>

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

<div id="resolving-relative-urls">
  ## حلّ عناوين URL النسبية
</div>

يتيح الإعداد [url\_base](/docs/ar/reference/settings/session-settings#url_base) استخدام عنوان URL نسبي في المحرك `URL`. عند تعيين `url_base`، يُفسَّر عنوان URL الذي يُمرَّر إلى المحرك بالاستناد إليه وفقًا لـ [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986). للحصول على وصف كامل لقواعد الحلّ، راجع [وثائق دالة الجدول url](/docs/ar/reference/functions/table-functions/url#resolving-relative-urls).

**مثال**

```sql theme={null}
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;
```

<div id="storage-settings">
  ## إعدادات التخزين
</div>

* [engine\_url\_skip\_empty\_files](/docs/ar/reference/settings/session-settings#engine_url_skip_empty_files) - يسمح بتجاوز الملفات الفارغة أثناء القراءة. يكون معطّلًا افتراضيًا.
* [enable\_url\_encoding](/docs/ar/reference/settings/session-settings#enable_url_encoding) - يتيح تمكين/تعطيل فك ترميز/ترميز المسار في عنوان URI. يكون مُمكّنًا افتراضيًا.
* [url\_base](/docs/ar/reference/settings/session-settings#url_base) - عنوان URL الأساسي لاستكمال عناوين URL النسبية المُمرَّرة إلى المحرّك.