gcs

يوفّر واجهة شبيهة بالجدول لـ 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}` استراتيجية `wildcard`. أما المسار الذي يحتوي على `glob` آخر فلا يستخدم أي استراتيجية تقسيم ويتجاهل `PARTITION BY`. ويستخدم المسار الذي لا يحتوي على `glob` استراتيجية `hive` عندما تكون `file_like_engine_default_partition_strategy` هي `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:

احسب عدد الصفوف في الملفات التي تنتهي أسماؤها بأرقام من 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' صراحةً في الأمثلة أدناه اختياري. لا يستخدم المسار الذي يحتوي على نمط glob آخر أي استراتيجية تقسيم ويتجاهل PARTITION BY. يستخدم المسار الذي لا يحتوي على نمط glob استراتيجية hive عندما تكون قيمة file_like_engine_default_partition_strategy هي hive؛ وإلا فلن يستخدم أي استراتيجية تقسيم. أمثلة

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

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.

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

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.

SQL Reference

Data Types

Engines

Functions

Formats

Interfaces

Settings

System Tables

Data Lakes

البنية

الوسيطات

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

أمثلة

الاستخدام

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

​البنية

​الوسيطات

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

​أمثلة

​الاستخدام

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

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

البنية

الوسيطات

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

أمثلة

الاستخدام

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

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