azureBlobStorage

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

​

دالة الجدول azureBlobStorage

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

​

الصياغة

سلسلة اتصال

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

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

عنوان URL لحساب التخزين

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

azureBlobStorage(storage_account_url, container_name, blobpath, account_name, account_key [, format, compression, 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 كأسماء ملفات وتنظيم الملف كامتداد. القيمة الافتراضية هي الإعداد 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.

​

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

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

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

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

مثال:

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;

​

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

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

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

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} في مسار الملف بمفتاح التقسيم الفعلي. ويُختار افتراضيًا فقط ضمن إعدادات compatibility الأقدم من 26.6؛ وإلا تكون القيمة الافتراضية هي HIVE (راجع الإعداد file_like_engine_default_partition_strategy).

يعتمد 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')

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

1 row in set. Elapsed: 0.425 sec.

بدلًا من ذلك، يمكن للمستخدمين استخدام 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')

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

1 row in set. Elapsed: 0.153 sec.

​

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

• محرك الجدول AzureBlobStorage