Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

gcs

View as MarkdownEdit this pageReport an issueSet up docs MCP

يوفّر واجهة شبيهة بالجدول لـ 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 [,..]])

الوسيطات

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؛ وإلا فلا يستخدم أي استراتيجية تقسيم.

يمكن أيضًا تمرير الوسيطات باستخدام المجموعات المسماة. في هذه الحالة، تعمل 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؛ وإلا فلن يستخدم أي استراتيجية تقسيم.

أمثلة

  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.

  1. يؤدي استخدام معرّف التقسيم في اسم الحاوية إلى إنشاء ملفات في حاويات مختلفة:
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.

Navigation