gcs

يوفّر واجهة شبيهة بالجدول لـ SELECT وINSERT البيانات من Google Cloud Storage. ويتطلب دور IAM Storage Object User.

يوفّر واجهة شبيهة بالجدول لـ SELECT وINSERT البيانات من Google Cloud Storage. ويتطلب دور IAM Storage Object User.

هذا اسم مستعار لـ دالة الجدول s3.

إذا كان لديك عدة نُسخ متماثلة في العنقود، فيمكنك استخدام الدالة s3Cluster (التي تعمل مع GCS) بدلًا من ذلك لتنفيذ عمليات INSERT بشكل متوازٍ.

​

البنية

gcs(url [, NOSIGN | hmac_key, hmac_secret] [,format] [,structure] [,compression_method] [,partition_strategy])
gcs(named_collection[, option=value [,..]])

GCS

تتكامل دالة الجدول GCS مع Google Cloud Storage باستخدام واجهة برمجة تطبيقات GCS XML ومفاتيح HMAC. راجع وثائق التشغيل البيني من Google لمزيد من التفاصيل حول نقطة النهاية وHMAC.

​

الوسيطات

Argument	Description
url	مسار الـ حاوية إلى الملف. يدعم أحرف البدل التالية في وضع readonly: *, **, ?, {abc,def} و {N..M}، حيث إن N و M — أرقام، و 'abc' و 'def' — سلاسل نصية.
NOSIGN	إذا استُخدمت هذه الكلمة المفتاحية بدلًا من بيانات الاعتماد، فلن تُوقَّع أي من الطلبات.
hmac_key and hmac_secret	مفاتيح تحدد بيانات الاعتماد المطلوب استخدامها مع نقطة النهاية المحددة. اختيارية.
format	تنسيق الملف.
structure	بنية الجدول. التنسيق هو 'column1_name column1_type, column2_name column2_type, ...'.
compression_method	هذه المعلمة اختيارية. القيم المدعومة: none و gzip أو gz و brotli أو br و xz أو LZMA و zstd أو zst. افتراضيًا، سيُكتشف أسلوب الضغط تلقائيًا من امتداد الملف.
partition_strategy	اختياري. القيم المدعومة: wildcard أو hive. يتطلب wildcard وجود {_partition_id} في المسار. ويكون هو الخيار الافتراضي عندما يحتوي المسار على {_partition_id} (إذ إنها الاستراتيجية الوحيدة المتوافقة مع مثل هذا المسار)، أو عندما تكون compatibility أقدم من 26.6؛ وإلا، بما في ذلك عند تطبيق القيم الافتراضية الحالية، تكون القيمة الافتراضية هي hive.

GCS

يأتي مسار GCS بهذا التنسيق لأن نقطة النهاية الخاصة بـ Google XML API تختلف عن JSON API:

  https://storage.googleapis.com/<bucket>/<folder>/<filename(s)>

وليس https://storage.cloud.google.com.

يمكن أيضًا تمرير الوسيطات باستخدام المجموعات المسماة. في هذه الحالة، تعمل url و format و structure و compression_method و partition_strategy بالطريقة نفسها، مع دعم بعض المعلمات الإضافية:

Parameter	Description
access_key_id	hmac_key، اختياري.
secret_access_key	hmac_secret، اختياري.
filename	يُلحَق بـ url إذا تم تحديده.
use_environment_credentials	مُمكَّن افتراضيًا، ويتيح تمرير معلمات إضافية باستخدام متغيرات البيئة AWS_CONTAINER_CREDENTIALS_RELATIVE_URI, AWS_CONTAINER_CREDENTIALS_FULL_URI, AWS_CONTAINER_AUTHORIZATION_TOKEN, AWS_EC2_METADATA_DISABLED.
no_sign_request	مُعطَّل افتراضيًا.
expiration_window_seconds	القيمة الافتراضية هي 120.

​

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

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

​

أمثلة

اختيار أول صفّين من ملف GCS https://storage.googleapis.com/clickhouse_public_datasets/my-test-bucket-768/data.csv.gz. تُكتشَف أسلوب الضغط تلقائيًا من امتداد الملف .gz:

SELECT *
FROM gcs('https://storage.googleapis.com/clickhouse_public_datasets/my-test-bucket-768/data.csv.gz', 'CSV', 'column1 UInt32, column2 UInt32, column3 UInt32')
LIMIT 2;

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

الاستعلام نفسه كما أعلاه، ولكن مع تحديد أسلوب الضغط gzip صراحةً بدلًا من الاعتماد على الاكتشاف التلقائي:

SELECT *
FROM gcs('https://storage.googleapis.com/clickhouse_public_datasets/my-test-bucket-768/data.csv.gz', 'CSV', 'column1 UInt32, column2 UInt32, column3 UInt32', 'gzip')
LIMIT 2;

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

​

الاستخدام

لنفترض أن لدينا عدة ملفات بعناوين URI التالية على GCS:

• ‘https://storage.googleapis.com/my-test-bucket-768/some_prefix/some_file_1.csv'
• ‘https://storage.googleapis.com/my-test-bucket-768/some_prefix/some_file_2.csv'
• ‘https://storage.googleapis.com/my-test-bucket-768/some_prefix/some_file_3.csv'
• ‘https://storage.googleapis.com/my-test-bucket-768/some_prefix/some_file_4.csv'
• ‘https://storage.googleapis.com/my-test-bucket-768/another_prefix/some_file_1.csv'
• ‘https://storage.googleapis.com/my-test-bucket-768/another_prefix/some_file_2.csv'
• ‘https://storage.googleapis.com/my-test-bucket-768/another_prefix/some_file_3.csv'
• ‘https://storage.googleapis.com/my-test-bucket-768/another_prefix/some_file_4.csv'

احسب عدد الصفوف في الملفات التي تنتهي أسماؤها بأرقام من 1 إلى 3:

SELECT count(*)
FROM gcs('https://storage.googleapis.com/clickhouse_public_datasets/my-test-bucket-768/{some,another}_prefix/some_file_{1..3}.csv', 'CSV', 'column1 UInt32, column2 UInt32, column3 UInt32')

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

احسب العدد الإجمالي للصفوف في جميع الملفات الموجودة ضمن هذين الدليلين:

SELECT count(*)
FROM gcs('https://storage.googleapis.com/clickhouse_public_datasets/my-test-bucket-768/{some,another}_prefix/*', 'CSV', 'column1 UInt32, column2 UInt32, column3 UInt32')

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

إذا كانت قائمة الملفات لديك تتضمن نطاقات رقمية بأصفار بادئة، فاستخدم صيغة الأقواس لكل رقم على حدة أو استخدم ?.

احسب العدد الإجمالي للصفوف في الملفات المسماة file-000.csv وfile-001.csv و… وfile-999.csv:

SELECT count(*)
FROM gcs('https://storage.googleapis.com/clickhouse_public_datasets/my-test-bucket-768/big_prefix/file-{000..999}.csv', 'CSV', 'name String, value UInt32');

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

أدخِل البيانات في الملف test-data.csv.gz:

INSERT INTO FUNCTION gcs('https://storage.googleapis.com/my-test-bucket-768/test-data.csv.gz', 'CSV', 'name String, value UInt32', 'gzip')
VALUES ('test-data', 1), ('test-data-2', 2);

أدرِج البيانات في الملف test-data.csv.gz من جدولٍ موجود:

INSERT INTO FUNCTION gcs('https://storage.googleapis.com/my-test-bucket-768/test-data.csv.gz', 'CSV', 'name String, value UInt32', 'gzip')
SELECT name, value FROM existing_table;

يمكن استخدام Glob ** لاجتياز الدليل بشكل متكرر. انظر إلى المثال أدناه، إذ سيجلب جميع الملفات من الدليل my-test-bucket-768 على نحو متكرر:

SELECT * FROM gcs('https://storage.googleapis.com/my-test-bucket-768/**', 'CSV', 'name String, value UInt32', 'gzip');

يسترجع ما يلي البيانات من جميع ملفات test-data.csv.gz الموجودة في أي مجلد داخل الدليل my-test-bucket، بشكلٍ تكراري:

SELECT * FROM gcs('https://storage.googleapis.com/my-test-bucket-768/**/test-data.csv.gz', 'CSV', 'name String, value UInt32', 'gzip');

في حالات الاستخدام في بيئة الإنتاج، يُوصى باستخدام المجموعات المسماة. وفيما يلي مثال على ذلك:

CREATE NAMED COLLECTION creds AS
        access_key_id = '***',
        secret_access_key = '***';
SELECT count(*)
FROM gcs(creds, url='https://s3-object-url.csv')

​

الكتابة المقسّمة حسب التقسيمات

إذا حدّدت تعبير PARTITION BY عند إدراج البيانات في جدول GCS، فسيُنشأ ملف منفصل لكل قيمة تقسيم. ويساعد تقسيم البيانات إلى ملفات منفصلة على تحسين كفاءة عمليات القراءة.

يشير المسار الذي يحتوي على {_partition_id} إلى استراتيجية التقسيم wildcard، لذا فإن تحديد partition_strategy='wildcard' صراحةً في الأمثلة أدناه اختياري. أما بالنسبة إلى المسارات التي لا تحتوي على العنصر النائب، فتكون استراتيجية التقسيم الافتراضية هي hive عندما يكون compatibility مضبوطًا على 26.6 أو إصدار أحدث (بما في ذلك القيم الافتراضية الحالية)؛ راجع إعداد file_like_engine_default_partition_strategy.

أمثلة

1. يؤدي استخدام معرّف التقسيم في المفتاح إلى إنشاء ملفات منفصلة:

INSERT INTO TABLE FUNCTION
    gcs('http://bucket.amazonaws.com/my_bucket/file_{_partition_id}.csv', 'CSV', 'a String, b UInt32, c UInt32', partition_strategy='wildcard')
    PARTITION BY a VALUES ('x', 2, 3), ('x', 4, 5), ('y', 11, 12), ('y', 13, 14), ('z', 21, 22), ('z', 23, 24);

ونتيجةً لذلك، تُكتب البيانات في ثلاثة ملفات: file_x.csv وfile_y.csv وfile_z.csv.

2. يؤدي استخدام معرّف التقسيم في اسم الحاوية إلى إنشاء ملفات في حاويات مختلفة:

INSERT INTO TABLE FUNCTION
    gcs('http://bucket.amazonaws.com/my_bucket_{_partition_id}/file.csv', 'CSV', 'a UInt32, b UInt32, c UInt32', partition_strategy='wildcard')
    PARTITION BY a VALUES (1, 2, 3), (1, 4, 5), (10, 11, 12), (10, 13, 14), (20, 21, 22), (20, 23, 24);

ونتيجةً لذلك، تُكتب البيانات في ثلاثة ملفات ضمن ثلاث حاويات مختلفة: my_bucket_1/file.csv وmy_bucket_10/file.csv وmy_bucket_20/file.csv.

​

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

• دالة الجدول S3
• محرك S3