> ## Documentation Index > Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-8c05c8a2.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. > يوفّر واجهة شبيهة بالجدول لـ `SELECT` و`INSERT` البيانات من Google Cloud Storage. ويتطلب دور IAM `Storage Object User`. # gcs يوفّر واجهة شبيهة بالجدول لـ `SELECT` و`INSERT` البيانات من [Google Cloud Storage](https://cloud.google.com/storage/). ويتطلب [دور IAM `Storage Object User`](https://cloud.google.com/storage/docs/access-control/iam-roles). هذا اسم مستعار لـ [دالة الجدول s3](/ar/reference/functions/table-functions/s3). إذا كان لديك عدة نُسخ متماثلة في العنقود، فيمكنك استخدام [الدالة s3Cluster](/ar/reference/functions/table-functions/s3Cluster) (التي تعمل مع GCS) بدلًا من ذلك لتنفيذ عمليات `INSERT` بشكل متوازٍ.
## البنية
```sql theme={null} gcs(url [, NOSIGN | hmac_key, hmac_secret] [,format] [,structure] [,compression_method]) gcs(named_collection[, option=value [,..]]) ``` **GCS** تتكامل دالة الجدول GCS مع Google Cloud Storage باستخدام واجهة برمجة تطبيقات GCS XML ومفاتيح HMAC. راجع [وثائق التشغيل البيني من Google](https://cloud.google.com/storage/docs/interoperability) لمزيد من التفاصيل حول نقطة النهاية وHMAC.
## الوسيطات
| Argument | Description | | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `url` | مسار الـ حاوية إلى الملف. يدعم أحرف البدل التالية في وضع `readonly`: `*`, `**`, `?`, `{abc,def}` و `{N..M}`، حيث إن `N` و `M` — أرقام، و `'abc'` و `'def'` — سلاسل نصية. | | `NOSIGN` | إذا استُخدمت هذه الكلمة المفتاحية بدلًا من بيانات الاعتماد، فلن تُوقَّع أي من الطلبات. | | `hmac_key` and `hmac_secret` | مفاتيح تحدد بيانات الاعتماد المطلوب استخدامها مع نقطة النهاية المحددة. اختيارية. | | `format` | [تنسيق](/ar/reference/formats/index) الملف. | | `structure` | بنية الجدول. التنسيق هو `'column1_name column1_type, column2_name column2_type, ...'`. | | `compression_method` | هذه المعلمة اختيارية. القيم المدعومة: `none` و `gzip` أو `gz` و `brotli` أو `br` و `xz` أو `LZMA` و `zstd` أو `zst`. افتراضيًا، سيُكتشف أسلوب الضغط تلقائيًا من امتداد الملف. | **GCS** يأتي مسار GCS بهذا التنسيق لأن نقطة النهاية الخاصة بـ Google XML API تختلف عن JSON API: ```text theme={null} https://storage.googleapis.com/// ``` وليس ~~[https://storage.cloud.google.com](https://storage.cloud.google.com)~~. يمكن أيضًا تمرير الوسيطات باستخدام [المجموعات المسماة](/ar/concepts/features/configuration/server-config/named-collections). في هذه الحالة، تعمل `url` و `format` و `structure` و `compression_method` بالطريقة نفسها، مع دعم بعض المعلمات الإضافية: | 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/my-test-bucket-768/data.csv`: ```sql theme={null} 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; ``` ```text theme={null} ┌─column1─┬─column2─┬─column3─┐ │ 1 │ 2 │ 3 │ │ 3 │ 2 │ 1 │ └─────────┴─────────┴─────────┘ ``` مثال مشابه، ولكن من ملف باستخدام طريقة ضغط `gzip`: ```sql theme={null} 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; ``` ```text theme={null} ┌─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\_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\_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\_3.csv\'); * '[https://storage.googleapis.com/my-test-bucket-768/some\_prefix/some\_file\_4.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\_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\_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\_3.csv\'); * '[https://storage.googleapis.com/my-test-bucket-768/another\_prefix/some\_file\_4.csv\'](https://storage.googleapis.com/my-test-bucket-768/another\_prefix/some\_file\_4.csv\'); احسب عدد الصفوف في الملفات التي تنتهي أسماؤها بأرقام من 1 إلى 3: ```sql theme={null} 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') ``` ```text theme={null} ┌─count()─┐ │ 18 │ └─────────┘ ``` احسب العدد الإجمالي للصفوف في جميع الملفات الموجودة ضمن هذين الدليلين: ```sql theme={null} 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') ``` ```text theme={null} ┌─count()─┐ │ 24 │ └─────────┘ ``` إذا كانت قائمة الملفات لديك تتضمن نطاقات رقمية بأصفار بادئة، فاستخدم صيغة الأقواس لكل رقم على حدة أو استخدم `?`. احسب العدد الإجمالي للصفوف في الملفات المسماة `file-000.csv` و`file-001.csv` و... و`file-999.csv`: ```sql theme={null} 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'); ``` ```text theme={null} ┌─count()─┐ │ 12 │ └─────────┘ ``` أدخِل البيانات في الملف `test-data.csv.gz`: ```sql theme={null} 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` من جدولٍ موجود: ```sql theme={null} 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` على نحو متكرر: ```sql theme={null} SELECT * FROM gcs('https://storage.googleapis.com/my-test-bucket-768/**', 'CSV', 'name String, value UInt32', 'gzip'); ``` يسترجع ما يلي البيانات من جميع ملفات `test-data.csv.gz` الموجودة في أي مجلد داخل الدليل `my-test-bucket`، بشكلٍ تكراري: ```sql theme={null} SELECT * FROM gcs('https://storage.googleapis.com/my-test-bucket-768/**/test-data.csv.gz', 'CSV', 'name String, value UInt32', 'gzip'); ``` في حالات الاستخدام في بيئة الإنتاج، يُوصى باستخدام [المجموعات المسماة](/ar/concepts/features/configuration/server-config/named-collections). وفيما يلي مثال على ذلك: ```sql theme={null} 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`، فسيُنشأ ملف منفصل لكل قيمة تقسيم. ويساعد تقسيم البيانات إلى ملفات منفصلة على تحسين كفاءة عمليات القراءة. **أمثلة** 1. يؤدي استخدام معرّف التقسيم في المفتاح إلى إنشاء ملفات منفصلة: ```sql theme={null} INSERT INTO TABLE FUNCTION gcs('http://bucket.amazonaws.com/my_bucket/file_{_partition_id}.csv', 'CSV', 'a String, b UInt32, c UInt32') 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. يؤدي استخدام معرّف التقسيم في اسم الحاوية إلى إنشاء ملفات في حاويات مختلفة: ```sql theme={null} INSERT INTO TABLE FUNCTION gcs('http://bucket.amazonaws.com/my_bucket_{_partition_id}/file.csv', 'CSV', 'a UInt32, b UInt32, c UInt32') 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](/ar/reference/functions/table-functions/s3) * [محرك S3](/ar/reference/engines/table-engines/integrations/s3)