azureBlobStorage

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

الصياغة

تكون بيانات الاعتماد مضمنة في سلسلة اتصال، لذلك لا حاجة إلى account_name/account_key بشكل منفصل:

azureBlobStorage(connection_string, container_name, blobpath [, format, compression, partition_strategy, structure])

يتطلب account_name وaccount_key كوسيطتين منفصلتين:

azureBlobStorage(storage_account_url, container_name, blobpath, account_name, account_key [, format, compression, partition_strategy, structure])

راجع المجموعات المسماة أدناه للاطلاع على القائمة الكاملة بالمفاتيح المدعومة:

azureBlobStorage(named_collection[, option=value [,..]])

وسيطات الدالة

Argument	Description
`connection_string`	سلسلة اتصال تتضمن بيانات اعتماد مضمّنة (اسم الحساب + مفتاح الحساب أو SAS token). عند استخدام هذا الشكل، يجب ألا يتم تمرير `account_name` و`account_key` بشكل منفصل. راجع Configure a connection string.
`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`	تنسيق الملف.
`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 كأسماء ملفات وتنسيق الملف كامتداد. دون استراتيجية صريحة، يستخدم المسار الذي يحتوي على `{_partition_id}` الاستراتيجية `WILDCARD`. أما المسار الذي يحتوي على نمط glob آخر، فلا يستخدم استراتيجية تقسيم ويتجاهل `PARTITION BY`. ويستخدم المسار الذي لا يحتوي على glob الاستراتيجية `HIVE` عندما تكون قيمة `file_like_engine_default_partition_strategy` هي `HIVE`؛ وبخلاف ذلك لا يستخدم أي استراتيجية تقسيم.
`partition_columns_in_data_file`	اختياري. يُستخدم فقط مع استراتيجية التقسيم `HIVE`. يحدد لـ ClickHouse ما إذا كان ينبغي توقّع كتابة أعمدة التقسيم داخل ملف البيانات. القيمة الافتراضية `false`.
`extra_credentials`	استخدم `client_id` و`tenant_id` للمصادقة. إذا تم توفير `extra_credentials`، فستُعطى لهما الأولوية على `account_name` و`account_key`.

المجموعات المسماة

يمكن أيضًا تمرير الوسائط باستخدام المجموعات المسماة. في هذه الحالة، تكون المفاتيح التالية مدعومة:

المفتاح	مطلوب	الوصف
`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`	لا	معرّف المستأجر للمصادقة.

مثال:

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;

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

SELECT *
FROM azureBlobStorage(azure_my_data, blob_path = 'other_data/*.csv', format = 'CSVWithNames')
LIMIT 5;

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

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

أمثلة

القراءة بصيغة `storage_account_url`

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

القراءة باستخدام صيغة `connection_string`

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

الكتابة باستخدام التقسيمات

يشير المسار الذي يحتوي على {_partition_id} إلى استراتيجية التقسيم WILDCARD. لا يستخدم المسار الذي يحتوي على نمط glob آخر استراتيجية تقسيم ويتجاهل PARTITION BY. يستخدم المسار الذي لا يحتوي على نمط glob استراتيجية HIVE عندما يكون file_like_engine_default_partition_strategy مضبوطًا على HIVE؛ وإلا فلا يستخدم استراتيجية تقسيم.

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

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

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'
);

┌─column1─┬─column2─┬─column3─┐
│       3 │       2 │       1 │
└─────────┴─────────┴─────────┘

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

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

الكتابة مع التقسيم

استراتيجية التقسيم

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

WILDCARD: يستبدل الرمز البديل {_partition_id} في مسار الملف بمفتاح التقسيم الفعلي. ويُختار افتراضيًا عندما يحتوي المسار على {_partition_id}.

عند عدم تعيين partition_strategy، لا يستخدم المسار الذي يحتوي على نمط glob آخر أي استراتيجية للتقسيم ويتجاهل PARTITION BY. أما المسار الذي لا يحتوي على glob، فيستخدم HIVE إذا كانت قيمة file_like_engine_default_partition_strategy هي HIVE؛ وإلا فلا يستخدم أي استراتيجية للتقسيم.

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

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

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

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  │
   └─────────────────────────────────────────────────────────────────────────────────┴────┴──────┴─────────┘

إعداد use_hive_partitioning

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

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

مثال

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

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;

استخدام Shared Access Signatures (SAS)

Shared Access Signature ‏(SAS) هو URI يمنح وصولًا مقيّدًا إلى حاوية أو ملف في Azure Storage. استخدمه لتوفير وصول محدود زمنيًا إلى موارد حساب التخزين من دون مشاركة مفتاح حساب التخزين. مزيد من التفاصيل هنا.

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

يحتوي Blob SAS token على جميع المعلومات اللازمة لمصادقة الطلب، بما في ذلك الـ blob المستهدف، والأذونات، وفترة الصلاحية. ولإنشاء URL للـ blob، ألحِق SAS token بنقطة نهاية خدمة الـ blob. على سبيل المثال، إذا كانت نقطة النهاية هي https://clickhousedocstest.blob.core.windows.net/، يصبح الطلب كما يلي:

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

┌

بدلًا من ذلك، يمكن للمستخدمين استخدام Blob SAS URL الذي أُنشئ:

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

┌

محرك الجدول AzureBlobStorage