> ## 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.

> ينشئ جدولًا من `URL` وفق `format` و`structure` المحددين

# url

export const CloudNotSupportedBadge = () => {
  return <div className="cloudNotSupportedBadge">
            <div className="cloudNotSupportedIcon">
            <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
                <path strokeWidth="1.5" d="M6.33366 12.6666L12.3739 12.6667C13.6593 12.6667 14.7073 11.6187 14.7073 10.3334C14.7073 9.04804 13.6593 8.00003 12.3739 8.00003C12.3739 8.00003 12.3337 7.66659 12.0003 7.33325M10.667 5.33322C8.00033 2.33325 4.45395 4.78537 4.14195 6.68203C2.55728 6.7627 1.29395 8.06203 1.29395 9.6667C1.29395 11.3234 2.66699 12.6666 4.00033 12.6666" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path strokeWidth="1.5" d="M2.66699 14L12.0003 4.66663" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
            </svg>

        </div>
            غير مدعوم في ClickHouse Cloud
        </div>;
};

export const ExperimentalBadge = () => {
  return <div className="experimentalBadge">
            <div className="experimentalIcon">
            <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
                <path strokeWidth="1.25" d="M5.5 2H10.5" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path strokeWidth="1.25" d="M9.50015 2V6.19625L13.4283 12.7425C13.4738 12.8183 13.4985 12.9049 13.4996 12.9934C13.5008 13.0818 13.4785 13.169 13.435 13.246C13.3914 13.323 13.3283 13.3871 13.2519 13.4317C13.1755 13.4764 13.0886 13.4999 13.0002 13.5H3.00015C2.91164 13.5 2.8247 13.4766 2.74822 13.432C2.67174 13.3874 2.60847 13.3233 2.56487 13.2463C2.52126 13.1693 2.49889 13.082 2.50004 12.9935C2.50119 12.905 2.52582 12.8184 2.5714 12.7425L6.50015 6.19625V2" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path strokeWidth="1.25" d="M4.47656 9.56754C5.30344 9.41254 6.47656 9.47942 7.99969 10.25C10.0153 11.2707 11.4216 11.0569 12.2184 10.7282" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
            </svg>
        </div>
            ميزة تجريبية. <u><a href="/docs/docs/beta-and-experimental-features#experimental-features">تعرّف على المزيد.</a></u>
        </div>;
};

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

يمكن استخدام الدالة `url` في استعلامات `SELECT` و`INSERT` على البيانات الموجودة في جداول [URL](/docs/ar/reference/engines/table-engines/special/url).

<div id="syntax">
  ## الصيغة
</div>

```sql theme={null}
url(URL [,format] [,structure] [,headers])
```

<div id="parameters">
  ## المعلمات
</div>

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

<div id="returned_value">
  ## القيمة المُعادة
</div>

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

<div id="examples">
  ## أمثلة
</div>

الحصول على أول 3 أسطر من جدول يحتوي على أعمدة من النوع `String` والنوع [UInt32](/docs/ar/reference/data-types/int-uint) من خادم HTTP يردّ بتنسيق [CSV](/docs/ar/reference/formats/CSV/CSV).

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

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

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

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

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

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

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

بالنسبة إلى `file://`، يُحل المسار النسبي (`file://data.csv`) داخل الدليل [user\_files](/docs/ar/reference/settings/server-settings/settings#user_files_path)، ويجب أن يشير المسار المطلق (`file:///home/user/data.csv`) إلى موقع داخله كالمعتاد.

تعمل الوسيطات `format` و`structure` و`compression_method` وكذلك الإعداد [url\_base](#resolving-relative-urls) بالطريقة نفسها بغض النظر عن هدف التوجيه.

```sql theme={null}
SELECT * FROM url('file://data.csv', CSV, 'a UInt32, b String');
SELECT * FROM url('s3://clickhouse-public-datasets/hits_compatible/hits.csv');
```

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

<div id="globs-in-url">
  ## أنماط glob في URL
</div>

تُستخدم الأنماط داخل `{ }` لإنشاء مجموعة من الشظايا أو لتحديد عناوين التبديل الاحتياطي. للاطلاع على أنواع الأنماط المدعومة والأمثلة، راجع وصف الدالة [remote](/docs/ar/reference/functions/table-functions/remote#globs-in-addresses).
يُستخدم المحرف `|` داخل الأنماط لتحديد عناوين التبديل الاحتياطي. ويجري المرور عليها بالترتيب نفسه الوارد في النمط. ويكون عدد العناوين المُنشأة محدودًا بإعداد [glob\_expansion\_max\_elements](/docs/ar/reference/settings/session-settings#glob_expansion_max_elements).
للاطلاع على بنية glob للمسار ضمن URL (مثل `*` و `{a,b}` و `{N..M}` و `**`)، راجع [أنماط glob في المسار](/docs/ar/reference/functions/table-functions/file#globs-in-path). لاحظ أن `?` يبدأ سلسلة الاستعلام في URL، ولا يمكن استخدامه كحرف بدل في مكوّن المسار.

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

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

ملاحظات:

* تُفسَّر عناوين URL النسبية استنادًا إلى عنوان URL لصفحة الفهرس.
* تُوسَّع قوالب `URL` قبل جلب صفحات الفهرس، بما في ذلك توسيع الشرائح المفصولة بفواصل ونطاقات الأرقام وخيارات `|` للتبديل الاحتياطي خارج مكوّن المسار.
* لا تُدعَم أنماط التبديل الاحتياطي `|` داخل مكوّن المسار عند توسيع صفحات فهرس HTTP.
* يُطبَّق تطابق أحرف البدل على مكوّن المسار في عنوان URL.
* إذا كان عنوان URL المُدرَج يحتوي بالفعل على سلسلة استعلام أو جزء مرجعي، فستكون لهما الأولوية على نظيريهما من عنوان URL المصدر. وإلا، فستُستخدم سلسلة الاستعلام والجزء المرجعي من عنوان URL المصدر.
* يُسمح بسرد فارغ؛ أما أخطاء HTTP ‏(مثل 404) في صفحات الفهرس فتؤدي إلى ظهور استثناءات.
* يُقيَّد الحد الأقصى لحجم صفحة الفهرس بواسطة [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).

مثال:

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

<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="hive-style-partitioning">
  ## إعداد use\_hive\_partitioning
</div>

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

**مثال**

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

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

<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).

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

* **نسبي إلى المسار** (مثل `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`.

**مثال**

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

<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 الأساسي المستخدم في resolving عناوين URL نسبية المُمرَّرة إلى الدالة `url`.

<div id="permissions">
  ## الأذونات
</div>

تتطلب الدالة `url` الإذن `CREATE TEMPORARY TABLE`. لذلك، لن تعمل مع المستخدمين الذين لديهم الإعداد [readonly](/docs/ar/concepts/features/configuration/settings/permissions-for-queries#readonly) = 1. ويُشترط أن تكون القيمة على الأقل readonly = 2.

<div id="related">
  ## مواضيع ذات صلة
</div>

* [الأعمدة الافتراضية](/docs/ar/reference/engines/table-engines/index#table_engines-virtual_columns)

{{/*AUTOGENERATED_END*/}}