> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# كيفية الاستعلام عن البيانات في حاوية S3

> تعرّف على كيفية الاستعلام عن البيانات في حاوية S3 باستخدام chDB.

يُخزَّن الكثير من بيانات العالم في حاويات Amazon S3.
في هذا الدليل، سنتعلّم كيفية الاستعلام عن هذه البيانات باستخدام chDB.

<div id="setup">
  ## الإعداد
</div>

لنبدأ أولاً بإنشاء بيئة افتراضية:

```bash theme={null}
python -m venv .venv
source .venv/bin/activate
```

والآن سنثبّت chDB.
تأكّد من أن الإصدار لديك هو 2.0.2 أو أحدث:

```bash theme={null}
pip install "chdb>=2.0.2"
```

والآن سنثبّت IPython:

```bash theme={null}
pip install ipython
```

سنستخدم `ipython` لتشغيل الأوامر في بقية هذا الدليل، ويمكنك تشغيله بتنفيذ:

```bash theme={null}
ipython
```

يمكنك أيضًا استخدام الكود في برنامج نصي بلغة Python أو في دفتر Jupyter المفضل لديك.

<div id="listing-files-in-an-s3-bucket">
  ## سرد الملفات في حاوية S3
</div>

لنبدأ بسرد جميع الملفات في [حاوية S3 التي تحتوي على مراجعات Amazon](/docs/ar/get-started/sample-datasets/amazon-reviews).
للقيام بذلك، يمكننا استخدام [دالة الجدول `s3`](/docs/ar/reference/functions/table-functions/s3) وتمرير path إلى ملف أو محرف بدل لمجموعة من الملفات.

<Tip>
  إذا مرّرت اسم الحاوية فقط، فسيؤدي ذلك إلى ظهور استثناء.
</Tip>

سنستخدم أيضًا تنسيق الإدخال [`One`](/docs/ar/reference/formats/One) حتى لا يُحلَّل الملف؛ وبدلًا من ذلك، يُعاد صف واحد لكل ملف، ويمكننا الوصول إلى الملف عبر العمود الافتراضي `_file` وإلى المسار عبر العمود الافتراضي `_path`.

```python theme={null}
import chdb

chdb.query("""
SELECT
    _file,
    _path
FROM s3('s3://datasets-documentation/amazon_reviews/*.parquet', One)
SETTINGS output_format_pretty_row_numbers=0
""", 'PrettyCompact')
```

```text theme={null}
┌─_file───────────────────────────────┬─_path─────────────────────────────────────────────────────────────────────┐
│ amazon_reviews_2010.snappy.parquet  │ datasets-documentation/amazon_reviews/amazon_reviews_2010.snappy.parquet  │
│ amazon_reviews_1990s.snappy.parquet │ datasets-documentation/amazon_reviews/amazon_reviews_1990s.snappy.parquet │
│ amazon_reviews_2013.snappy.parquet  │ datasets-documentation/amazon_reviews/amazon_reviews_2013.snappy.parquet  │
│ amazon_reviews_2015.snappy.parquet  │ datasets-documentation/amazon_reviews/amazon_reviews_2015.snappy.parquet  │
│ amazon_reviews_2014.snappy.parquet  │ datasets-documentation/amazon_reviews/amazon_reviews_2014.snappy.parquet  │
│ amazon_reviews_2012.snappy.parquet  │ datasets-documentation/amazon_reviews/amazon_reviews_2012.snappy.parquet  │
│ amazon_reviews_2000s.snappy.parquet │ datasets-documentation/amazon_reviews/amazon_reviews_2000s.snappy.parquet │
│ amazon_reviews_2011.snappy.parquet  │ datasets-documentation/amazon_reviews/amazon_reviews_2011.snappy.parquet  │
└─────────────────────────────────────┴───────────────────────────────────────────────────────────────────────────┘
```

لا تحتوي هذه الحاوية إلا على ملفات Parquet.

<div id="querying-files-in-an-s3-bucket">
  ## الاستعلام عن الملفات في حاوية S3
</div>

بعد ذلك، لنتعلّم كيفية الاستعلام عن هذه الملفات.
إذا أردنا حساب عدد الصفوف في كل ملف من هذه الملفات، يمكننا تشغيل الاستعلام التالي:

```python theme={null}
chdb.query("""
SELECT
    _file,
    count() AS count,
    formatReadableQuantity(count) AS readableCount    
FROM s3('s3://datasets-documentation/amazon_reviews/*.parquet')
GROUP BY ALL
SETTINGS output_format_pretty_row_numbers=0
""", 'PrettyCompact')
```

```text theme={null}
┌─_file───────────────────────────────┬────count─┬─readableCount───┐
│ amazon_reviews_2013.snappy.parquet  │ 28034255 │ 28.03 million   │
│ amazon_reviews_1990s.snappy.parquet │   639532 │ 639.53 thousand │
│ amazon_reviews_2011.snappy.parquet  │  6112495 │ 6.11 million    │
│ amazon_reviews_2015.snappy.parquet  │ 41905631 │ 41.91 million   │
│ amazon_reviews_2012.snappy.parquet  │ 11541011 │ 11.54 million   │
│ amazon_reviews_2000s.snappy.parquet │ 14728295 │ 14.73 million   │
│ amazon_reviews_2014.snappy.parquet  │ 44127569 │ 44.13 million   │
│ amazon_reviews_2010.snappy.parquet  │  3868472 │ 3.87 million    │
└─────────────────────────────────────┴──────────┴─────────────────┘
```

يمكننا أيضًا تمرير عنوان URI عبر HTTP لحاوية S3، وسنحصل على النتائج نفسها:

```python theme={null}
chdb.query("""
SELECT
    _file,
    count() AS count,
    formatReadableQuantity(count) AS readableCount    
FROM s3('https://datasets-documentation.s3.eu-west-3.amazonaws.com/amazon_reviews/*.parquet')
GROUP BY ALL
SETTINGS output_format_pretty_row_numbers=0
""", 'PrettyCompact')
```

دعنا نلقِ نظرة على بنية ملفات Parquet هذه باستخدام عبارة `DESCRIBE`:

```python theme={null}
chdb.query("""
DESCRIBE s3('s3://datasets-documentation/amazon_reviews/*.parquet')
SETTINGS describe_compact_output=1
""", 'PrettyCompact')
```

```text theme={null}
    ┌─name──────────────┬─type─────────────┐
 1. │ review_date       │ Nullable(UInt16) │
 2. │ marketplace       │ Nullable(String) │
 3. │ customer_id       │ Nullable(UInt64) │
 4. │ review_id         │ Nullable(String) │
 5. │ product_id        │ Nullable(String) │
 6. │ product_parent    │ Nullable(UInt64) │
 7. │ product_title     │ Nullable(String) │
 8. │ product_category  │ Nullable(String) │
 9. │ star_rating       │ Nullable(UInt8)  │
10. │ helpful_votes     │ Nullable(UInt32) │
11. │ total_votes       │ Nullable(UInt32) │
12. │ vine              │ Nullable(Bool)   │
13. │ verified_purchase │ Nullable(Bool)   │
14. │ review_headline   │ Nullable(String) │
15. │ review_body       │ Nullable(String) │
    └───────────────────┴──────────────────┘
```

لنحسب الآن أبرز فئات المنتجات بناءً على عدد المراجعات، وكذلك متوسط التقييم بالنجوم:

```python theme={null}
chdb.query("""
SELECT product_category, count() AS reviews, round(avg(star_rating), 2) as avg
FROM s3('s3://datasets-documentation/amazon_reviews/*.parquet')
GROUP BY ALL
LIMIT 10
""", 'PrettyCompact')
```

```text theme={null}
    ┌─product_category─┬──reviews─┬──avg─┐
 1. │ Toys             │  4864056 │ 4.21 │
 2. │ Apparel          │  5906085 │ 4.11 │
 3. │ Luggage          │   348644 │ 4.22 │
 4. │ Kitchen          │  4880297 │ 4.21 │
 5. │ Books            │ 19530930 │ 4.34 │
 6. │ Outdoors         │  2302327 │ 4.24 │
 7. │ Video            │   380596 │ 4.19 │
 8. │ Grocery          │  2402365 │ 4.31 │
 9. │ Shoes            │  4366757 │ 4.24 │
10. │ Jewelry          │  1767667 │ 4.14 │
    └──────────────────┴──────────┴──────┘
```

<div id="querying-files-in-a-private-s3-bucket">
  ## الاستعلام عن الملفات في حاوية S3 خاصة
</div>

إذا كنا نستعلم عن ملفات في حاوية S3 خاصة، فسنحتاج إلى تمرير مفتاح وصول ومفتاح سري.
يمكننا تمرير بيانات الاعتماد هذه إلى دالة الجدول ‏`s3`:

```python theme={null}
chdb.query("""
SELECT product_category, count() AS reviews, round(avg(star_rating), 2) as avg
FROM s3('s3://datasets-documentation/amazon_reviews/*.parquet', 'access-key', 'secret')
GROUP BY ALL
LIMIT 10
""", 'PrettyCompact')
```

<Note>
  لن يعمل هذا الاستعلام لأنها حاوية S3 عامة!
</Note>

ومن البدائل استخدام [المجموعات المُسمّاة](/docs/ar/concepts/features/configuration/server-config/named-collections)، لكن هذا النهج غير مدعوم بعد في chDB.