> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-fbfa8bee.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> يوفّر واجهة مشابهة للجداول لتنفيذ select/insert على الملفات في Azure Blob Storage. وهي مشابهة لدالة s3.

# azureBlobStorage

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/beta-and-experimental-features#experimental-features">تعرّف على المزيد.</a></u>
        </div>;
};

<div id="azureblobstorage-table-function">
  # دالة الجدول azureBlobStorage
</div>

توفر واجهة شبيهة بالجدول لإجراء عمليتي select/insert على الملفات في [Azure Blob Storage](https://azure.microsoft.com/en-us/products/storage/blobs). دالة الجدول هذه مشابهة لـ [دالة s3](/ar/reference/functions/table-functions/s3).

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

<Tabs>
  <Tab title="سلسلة اتصال">
    تكون بيانات الاعتماد مضمنة في سلسلة اتصال، لذلك لا حاجة إلى `account_name`/`account_key` بشكل منفصل:

    ```sql theme={null}
    azureBlobStorage(connection_string, container_name, blobpath [, format, compression, structure])
    ```
  </Tab>

  <Tab title="عنوان URL لحساب التخزين">
    يتطلب `account_name` و`account_key` كوسيطتين منفصلتين:

    ```sql theme={null}
    azureBlobStorage(storage_account_url, container_name, blobpath, account_name, account_key [, format, compression, structure])
    ```
  </Tab>

  <Tab title="مجموعة مسماة">
    راجع [المجموعات المسماة](#named-collections) أدناه للاطلاع على القائمة الكاملة بالمفاتيح المدعومة:

    ```sql theme={null}
    azureBlobStorage(named_collection[, option=value [,..]])
    ```
  </Tab>
</Tabs>

<div id="arguments">
  ## الوسيطات
</div>

| Argument                         | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `connection_string`              | سلسلة اتصال تتضمن بيانات اعتماد مضمّنة (اسم الحساب + مفتاح الحساب أو SAS token). عند استخدام هذا الشكل، يجب **ألا** يتم تمرير `account_name` و`account_key` بشكل منفصل. راجع [Configure a connection string](https://learn.microsoft.com/en-us/azure/storage/common/storage-configure-connection-string?toc=%2Fazure%2Fstorage%2Fblobs%2Ftoc.json\&bc=%2Fazure%2Fstorage%2Fblobs%2Fbreadcrumb%2Ftoc.json#configure-a-connection-string-for-an-azure-storage-account). |
| `storage_account_url`            | عنوان URL لنقطة نهاية حساب التخزين، على سبيل المثال `https://myaccount.blob.core.windows.net/`. عند استخدام هذا الشكل، **يجب** أيضًا تمرير `account_name` و`account_key`.                                                                                                                                                                                                                                                                                             |
| `container_name`                 | اسم الحاوية.                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `blobpath`                       | مسار الملف. يدعم أحرف البدل التالية في وضع القراءة فقط: `*`, `**`, `?`, `{abc,def}` و`{N..M}`، حيث إن `N` و`M` — أرقام، و`'abc'` و`'def'` — سلاسل نصية.                                                                                                                                                                                                                                                                                                               |
| `account_name`                   | اسم حساب التخزين. **مطلوب** عند استخدام `storage_account_url` بدون SAS؛ ويجب **ألا** يتم تمريره عند استخدام `connection_string`.                                                                                                                                                                                                                                                                                                                                      |
| `account_key`                    | مفتاح حساب التخزين. **مطلوب** عند استخدام `storage_account_url` بدون SAS؛ ويجب **ألا** يتم تمريره عند استخدام `connection_string`.                                                                                                                                                                                                                                                                                                                                    |
| `format`                         | [تنسيق](/ar/reference/formats/index) الملف.                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `compression`                    | القيم المدعومة: `none`, `gzip/gz`, `brotli/br`, `xz/LZMA`, `zstd/zst`. افتراضيًا، سيُكتشف الضغط تلقائيًا استنادًا إلى امتداد الملف (كما لو كان الإعداد `auto`).                                                                                                                                                                                                                                                                                                       |
| `structure`                      | بنية الجدول. الصيغة: `'column1_name column1_type, column2_name column2_type, ...'`.                                                                                                                                                                                                                                                                                                                                                                                   |
| `partition_strategy`             | اختياري. القيم المدعومة: `WILDCARD` أو `HIVE`. تتطلب `WILDCARD` وجود `{_partition_id}` في المسار، ويُستبدل بمفتاح التقسيم. أما `HIVE` فلا يسمح بأحرف البدل، ويفترض أن المسار هو جذر الجدول، ويُنشئ أدلة مقسّمة بأسلوب Hive مع Snowflake IDs كأسماء ملفات وتنظيم الملف كامتداد. القيمة الافتراضية هي الإعداد `file_like_engine_default_partition_strategy` (`WILDCARD` ضمن إعدادات `compatibility` الأقدم من `26.6`، و`HIVE` بخلاف ذلك).                               |
| `partition_columns_in_data_file` | اختياري. يُستخدم فقط مع استراتيجية التقسيم `HIVE`. يحدد لـ ClickHouse ما إذا كان ينبغي توقّع كتابة أعمدة التقسيم داخل ملف البيانات. القيمة الافتراضية `false`.                                                                                                                                                                                                                                                                                                        |
| `extra_credentials`              | استخدم `client_id` و`tenant_id` للمصادقة. إذا تم توفير `extra_credentials`، فستُعطى لهما الأولوية على `account_name` و`account_key`.                                                                                                                                                                                                                                                                                                                                  |

<div id="named-collections">
  ## المجموعات المسماة
</div>

يمكن أيضًا تمرير الوسائط باستخدام [المجموعات المسماة](/ar/concepts/features/configuration/server-config/named-collections). في هذه الحالة، تكون المفاتيح التالية مدعومة:

| المفتاح               | مطلوب | الوصف                                                                                                           |
| --------------------- | ----- | --------------------------------------------------------------------------------------------------------------- |
| `container`           | نعم   | اسم الحاوية. يقابل الوسيط الموضعي `container_name`.                                                             |
| `blob_path`           | نعم   | مسار الملف (مع أحرف بدل اختيارية). يقابل الوسيط الموضعي `blobpath`.                                             |
| `connection_string`   | لا\*  | سلسلة اتصال تتضمن بيانات اعتماد مضمّنة. \*يجب توفير أحد الخيارين: `connection_string` أو `storage_account_url`. |
| `storage_account_url` | لا\*  | عنوان URL لنقطة نهاية حساب التخزين. \*يجب توفير أحد الخيارين: `connection_string` أو `storage_account_url`.     |
| `account_name`        | لا    | مطلوب عند استخدام `storage_account_url`                                                                         |
| `account_key`         | لا    | مطلوب عند استخدام `storage_account_url`                                                                         |
| `format`              | لا    | تنسيق الملف.                                                                                                    |
| `compression`         | لا    | نوع الضغط.                                                                                                      |
| `structure`           | لا    | بنية الجدول.                                                                                                    |
| `client_id`           | لا    | معرّف العميل للمصادقة.                                                                                          |
| `tenant_id`           | لا    | معرّف المستأجر للمصادقة.                                                                                        |

<Note>
  تختلف أسماء مفاتيح المجموعات المسماة عن أسماء الوسائط الموضعية للدالة: `container` (وليس `container_name`) و`blob_path` (وليس `blobpath`).
</Note>

**مثال:**

```sql theme={null}
CREATE NAMED COLLECTION azure_my_data AS
    storage_account_url = 'https://myaccount.blob.core.windows.net/',
    container = 'mycontainer',
    blob_path = 'data/*.parquet',
    account_name = 'myaccount',
    account_key = 'mykey...==',
    format = 'Parquet';

SELECT *
FROM azureBlobStorage(azure_my_data)
LIMIT 5;
```

يمكنك أيضًا تجاوز قيم المجموعة المُسمّاة وقت تنفيذ الاستعلام:

```sql theme={null}
SELECT *
FROM azureBlobStorage(azure_my_data, blob_path = 'other_data/*.csv', format = 'CSVWithNames')
LIMIT 5;
```

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

جدول ذو البنية المحددة لقراءة البيانات من الملف المحدد أو كتابتها فيه.

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

<div id="reading-with-storage-account-url">
  ### القراءة بصيغة `storage_account_url`
</div>

```sql theme={null}
SELECT *
FROM azureBlobStorage(
    'https://myaccount.blob.core.windows.net/',
    'mycontainer',
    'data/*.parquet',
    'myaccount',
    'mykey...==',
    'Parquet'
)
LIMIT 5;
```

<div id="reading-with-connection-string">
  ### القراءة باستخدام صيغة `connection_string`
</div>

```sql theme={null}
SELECT *
FROM azureBlobStorage(
    'DefaultEndpointsProtocol=https;AccountName=myaccount;AccountKey=mykey...==;EndPointSuffix=core.windows.net',
    'mycontainer',
    'data/*.csv',
    'CSVWithNames'
)
LIMIT 5;
```

<div id="writing-with-partitions">
  ### الكتابة باستخدام التقسيمات
</div>

```sql theme={null}
INSERT INTO TABLE FUNCTION azureBlobStorage(
    'DefaultEndpointsProtocol=https;AccountName=myaccount;AccountKey=mykey...==;EndPointSuffix=core.windows.net',
    'mycontainer',
    'test_{_partition_id}.csv',
    'CSV',
    'auto',
    'column1 UInt32, column2 UInt32, column3 UInt32'
) PARTITION BY column3
VALUES (1, 2, 3), (3, 2, 1), (78, 43, 3);
```

ثم أعد قراءة قسم محدد:

```sql theme={null}
SELECT *
FROM azureBlobStorage(
    'DefaultEndpointsProtocol=https;AccountName=myaccount;AccountKey=mykey...==;EndPointSuffix=core.windows.net',
    'mycontainer',
    'test_1.csv',
    'CSV',
    'auto',
    'column1 UInt32, column2 UInt32, column3 UInt32'
);
```

```response theme={null}
┌─column1─┬─column2─┬─column3─┐
│       3 │       2 │       1 │
└─────────┴─────────┴─────────┘
```

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

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

<div id="partitioned-write">
  ## الكتابة مع التقسيم
</div>

<div id="partition-strategy">
  ### استراتيجية التقسيم
</div>

مدعومة فقط مع استعلامات `INSERT`.

`WILDCARD`: يستبدل الرمز البديل `{_partition_id}` في مسار الملف بمفتاح التقسيم الفعلي. ويُختار افتراضيًا فقط ضمن إعدادات `compatibility` الأقدم من `26.6`؛ وإلا تكون القيمة الافتراضية هي `HIVE` (راجع الإعداد `file_like_engine_default_partition_strategy`).

يعتمد `HIVE` التقسيم بأسلوب Hive لعمليات القراءة والكتابة. ويُنشئ الملفات بالتنسيق التالي: `<prefix>/<key1=val1/key2=val2...>/<snowflakeid>.<toLower(file_format)>`.

**مثال على استراتيجية التقسيم `HIVE`**

```sql theme={null}
INSERT INTO TABLE FUNCTION azureBlobStorage(
    azure_conf2,
    storage_account_url = 'https://myaccount.blob.core.windows.net/',
    container = 'cont',
    blob_path = 'azure_table_root',
    format = 'CSVWithNames',
    compression = 'auto',
    structure = 'year UInt16, country String, id Int32',
    partition_strategy = 'hive'
) PARTITION BY (year, country)
VALUES (2020, 'Russia', 1), (2021, 'Brazil', 2);
```

```result theme={null}
SELECT _path, * FROM azureBlobStorage(
    azure_conf2,
    storage_account_url = 'https://myaccount.blob.core.windows.net/',
    container = 'cont',
    blob_path = 'azure_table_root/**.csvwithnames'
)

   ┌─_path───────────────────────────────────────────────────────────────────────────┬─id─┬─year─┬─country─┐
1. │ cont/azure_table_root/year=2021/country=Brazil/7351307847391293440.csvwithnames │  2 │ 2021 │ Brazil  │
2. │ cont/azure_table_root/year=2020/country=Russia/7351307847378710528.csvwithnames │  1 │ 2020 │ Russia  │
   └─────────────────────────────────────────────────────────────────────────────────┴────┴──────┴─────────┘
```

<div id="hive-style-partitioning">
  ## إعداد use\_hive\_partitioning
</div>

هذا تلميح لـ ClickHouse لتحليل الملفات المُقسَّمة بأسلوب Hive عند القراءة. ولا يؤثر في الكتابة. ولجعل عمليتَي القراءة والكتابة متناظرتين، استخدم الوسيط `partition_strategy`.

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

**مثال**

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

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

<div id="using-shared-access-signatures-sas-sas-tokens">
  ## استخدام Shared Access Signatures (SAS)
</div>

Shared Access Signature ‏(SAS) هو URI يمنح وصولًا مقيّدًا إلى حاوية أو ملف في Azure Storage. استخدمه لتوفير وصول محدود زمنيًا إلى موارد حساب التخزين من دون مشاركة مفتاح حساب التخزين. مزيد من التفاصيل [هنا](https://learn.microsoft.com/en-us/rest/api/storageservices/delegate-access-with-shared-access-signature).

تدعم الدالة `azureBlobStorage` Shared Access Signatures ‏(SAS).

يحتوي [Blob SAS token](https://learn.microsoft.com/en-us/azure/ai-services/translator/document-translation/how-to-guides/create-sas-tokens?tabs=Containers) على جميع المعلومات اللازمة لمصادقة الطلب، بما في ذلك الـ blob المستهدف، والأذونات، وفترة الصلاحية. ولإنشاء URL للـ blob، ألحِق SAS token بنقطة نهاية خدمة الـ blob. على سبيل المثال، إذا كانت نقطة النهاية هي `https://clickhousedocstest.blob.core.windows.net/`، يصبح الطلب كما يلي:

```sql theme={null}
SELECT count()
FROM azureBlobStorage('BlobEndpoint=https://clickhousedocstest.blob.core.windows.net/;SharedAccessSignature=sp=r&st=2025-01-29T14:58:11Z&se=2025-01-29T22:58:11Z&spr=https&sv=2022-11-02&sr=c&sig=Ac2U0xl4tm%2Fp7m55IilWl1yHwk%2FJG0Uk6rMVuOiD0eE%3D', 'exampledatasets', 'example.csv')

┌─count()─┐
│      10 │
└─────────┘

1 row in set. Elapsed: 0.425 sec.
```

بدلًا من ذلك، يمكن للمستخدمين استخدام [Blob SAS URL](https://learn.microsoft.com/en-us/azure/ai-services/translator/document-translation/how-to-guides/create-sas-tokens?tabs=Containers) الذي أُنشئ:

```sql theme={null}
SELECT count()
FROM azureBlobStorage('https://clickhousedocstest.blob.core.windows.net/?sp=r&st=2025-01-29T14:58:11Z&se=2025-01-29T22:58:11Z&spr=https&sv=2022-11-02&sr=c&sig=Ac2U0xl4tm%2Fp7m55IilWl1yHwk%2FJG0Uk6rMVuOiD0eE%3D', 'exampledatasets', 'example.csv')

┌─count()─┐
│      10 │
└─────────┘

1 row in set. Elapsed: 0.153 sec.
```

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

* [محرك الجدول AzureBlobStorage](/ar/reference/engines/table-engines/integrations/azureBlobStorage)