> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-revert-104359-revert-104251-parquet-single.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# بدء الاستخدام مع بحيرات البيانات

> مقدمة عملية حول الاستعلام عن البيانات وتسريعها وإعادة كتابتها ضمن تنسيقات الجداول المفتوحة باستخدام ClickHouse.

export const Image = ({img, alt, size = "lg"}) => {
  const normalizedSize = ["sm", "md", "lg"].includes(size) ? size : "lg";
  return <div className={`ch-image-${normalizedSize}`}>
      <Frame>
        <img src={img} alt={alt} />
      </Frame>
    </div>;
};

<Info>
  **باختصار**

  دليل عملي للاستعلام عن جداول بحيرة البيانات، وتسريع أدائها باستخدام MergeTree، ثم كتابة النتائج مجددًا إلى Iceberg. تستخدم جميع الخطوات مجموعات بيانات عامة، وتعمل على كلٍّ من Cloud وOSS.
</Info>

لقطات الشاشة في هذا الدليل مأخوذة من [ClickHouse Cloud](https://console.clickhouse.cloud) وحدة تحكم SQL. تعمل جميع الاستعلامات على كلٍّ من Cloud وعمليات النشر المُدارة ذاتيًا.

يوفّر ClickHouse ثلاث طرق لقراءة تنسيقات الجداول المفتوحة: دوال الجداول، ومحركات الجداول، ومحرك قاعدة البيانات [`DataLakeCatalog`](/ar/reference/engines/database-engines/datalake). **إذا كانت جداولك موجودة في Data Catalog** ‏(Glue وUnity Catalog وREST وغيرها)، فاتصل عبر `DataLakeCatalog` لتتمكن من الوصول إلى جميع جداول Iceberg/Delta لديك من خلال دالة واحدة. أمّا قسمَا دالة الجدول ومحرك الجدول أدناه فهما الأنسب للاستعلامات المخصّصة أو عندما تعرف `path` تخزينًا محددًا ولا تستخدم كتالوجًا.

<Steps>
  <Step title="استعلم عن بيانات Iceberg مباشرة" id="query-directly">
    أسرع طريقة للبدء — خاصةً للاستعلامات المخصّصة أو عندما لا تستخدم كتالوجًا — هي استخدام دالة الجدول [`icebergS3()`](/ar/reference/functions/table-functions/iceberg). وجّهها إلى جدول Iceberg في S3 ونفّذ استعلامًا فورًا، من دون أي إعداد.

    افحص المخطط:

    ```sql theme={null}
    DESCRIBE icebergS3('https://datasets-documentation.s3.amazonaws.com/lake_formats/iceberg/')
    ```

    نفّذ استعلامًا:

    ```sql theme={null}
    SELECT
        url,
        count() AS cnt
    FROM icebergS3('https://datasets-documentation.s3.amazonaws.com/lake_formats/iceberg/')
    GROUP BY url
    ORDER BY cnt DESC
    LIMIT 5
    ```

    <Image img="https://mintcdn.com/private-7c7dfe99-revert-104359-revert-104251-parquet-single/ZdmxDtIw7E15PlXi/images/datalake/iceberg-query-direct.webp?fit=max&auto=format&n=ZdmxDtIw7E15PlXi&q=85&s=e4e9d501f09f8c0817aa05f2c854a6c6" alt="استعلام Iceberg" width="3836" height="1744" data-path="images/datalake/iceberg-query-direct.webp" />

    يقرأ ClickHouse البيانات الوصفية لـ Iceberg مباشرةً من S3 ويستنتج المخطط تلقائيًا. وينطبق النهج نفسه على [`deltaLake()`](/ar/reference/functions/table-functions/deltalake) و[`hudi()`](/ar/reference/functions/table-functions/hudi) و[`paimon()`](/ar/reference/functions/table-functions/paimon).

    **تعرّف على المزيد:** يتناول [الاستعلام عن تنسيقات الجداول المفتوحة مباشرةً](/ar/guides/use-cases/data-warehousing/getting-started/querying-directly) التنسيقات الأربعة، ومتغيرات cluster للقراءة الموزعة، وخيارات الواجهة الخلفية للتخزين (S3 وAzure وHDFS وlocal).
  </Step>

  <Step title="أنشئ جدولًا دائمًا باستخدام محرك جدول Iceberg" id="table-engine">
    عندما لا تستخدم كتالوجًا ولكنك ستنفّذ استعلامات على المسار نفسه بشكل متكرر، أنشئ جدولًا باستخدام محرك جدول Iceberg حتى لا تحتاج إلى تمرير المسار في كل مرة. تبقى البيانات في S3 — ولا تُنسخ أي بيانات:

    ```sql theme={null}
    CREATE TABLE hits_iceberg
        ENGINE = IcebergS3('https://datasets-documentation.s3.amazonaws.com/lake_formats/iceberg/')
    ```

    يمكنك الآن الاستعلام عنه كما تفعل مع أي جدول في ClickHouse:

    ```sql theme={null}
    SELECT
        url,
        count() AS cnt
    FROM hits_iceberg
    GROUP BY url
    ORDER BY cnt DESC
    LIMIT 5
    ```

    <Image img="https://mintcdn.com/private-7c7dfe99-revert-104359-revert-104251-parquet-single/ZdmxDtIw7E15PlXi/images/datalake/iceberg-query-engine.webp?fit=max&auto=format&n=ZdmxDtIw7E15PlXi&q=85&s=4eef063182e72a232994083e3b31d015" alt="استعلام Iceberg" width="3836" height="1744" data-path="images/datalake/iceberg-query-engine.webp" />

    يدعم محرك الجدول التخزين المؤقت للبيانات، والتخزين المؤقت للبيانات الوصفية، وتطوّر المخطط، والسفر عبر الزمن. راجع دليل [الاستعلام مباشرةً](/ar/guides/use-cases/data-warehousing/getting-started/querying-directly) للحصول على تفاصيل حول ميزات محرك الجدول، و[مصفوفة الدعم](/ar/guides/use-cases/data-warehousing/support-matrix) للاطلاع على مقارنة شاملة للميزات.
  </Step>

  <Step title="الاتصال بكتالوج" id="connect-catalog">
    إذا كانت مؤسستك تستخدم كتالوج بيانات، فهذا هو مسار التكامل الذي نوصي به. تعمل الكتالوجات على تجميع البيانات الوصفية للجداول واكتشافها في مكان مركزي — وبدلًا من إدارة تعريف جدول لكل مسار تخزين، اتصل مرة واحدة باستخدام محرك قاعدة البيانات [`DataLakeCatalog`](/ar/reference/engines/database-engines/datalake). يظهر كل جدول في الكتالوج كجدول ClickHouse، بما في ذلك الجداول التي أُضيفت upstream بعد إنشاء الاتصال.

    <Warning>
      **موصى به عند استخدام كتالوج**

      استخدم `DataLakeCatalog` لأعباء العمل في production مع Glue وUnity Catalog وREST و[الكتالوجات المدعومة](/ar/guides/use-cases/data-warehousing/reference/index) الأخرى. تعمل دوال الجداول ومحركات الجداول عندما تعرف مسارًا محددًا، لكنها لا تظل متزامنة مع نمو الكتالوج لديك وتتطلب بيانات اعتماد أو مسارات منفصلة لكل جدول.
    </Warning>

    إليك مثالاً على الاتصال بـ [AWS Glue](/ar/guides/use-cases/data-warehousing/glue-catalog):

    ```sql theme={null}
    CREATE DATABASE my_lake
    ENGINE = DataLakeCatalog
    SETTINGS
        catalog_type = 'glue',
        region = '<your-region>',
        aws_access_key_id = '<your-access-key>',
        aws_secret_access_key = '<your-secret-key>'
    ```

    يتطلب كل نوع من أنواع الكتالوجات إعدادات اتصال خاصة به — راجع [أدلة الكتالوجات](/ar/guides/use-cases/data-warehousing/reference/index) للاطّلاع على القائمة الكاملة بالكتالوجات المدعومة وخيارات تهيئتها.

    تصفّح الجداول ونفّذ استعلامًا:

    ```sql theme={null}
    SHOW TABLES FROM my_lake;
    ```

    ```sql theme={null}
    SELECT count(*) FROM my_lake.`<database>.<table>`
    ```

    <Note>
      علامات الاقتباس المعكوسة مطلوبة حول `<database>.<table>` لأن ClickHouse لا يدعم بشكل أصلي أكثر من نطاق أسماء واحد.
    </Note>

    **تعرّف على المزيد:** يشرح [الاتصال بـ Data Catalog](/ar/guides/use-cases/data-warehousing/getting-started/connecting-catalogs) إعداد Unity Catalog كاملًا مع أمثلة على Delta وIceberg.
  </Step>

  <Step title="نفِّذ استعلامًا" id="issue-query">
    بصرف النظر عن الطريقة التي استخدمتها أعلاه — دالة الجدول أو محرك الجدول أو `DataLakeCatalog` — فإن ClickHouse SQL نفسه يعمل في جميعها. وفي بيئة الإنتاج عند استخدام كتالوج، نفِّذ الاستعلام عبر قاعدة البيانات `DataLakeCatalog`؛ وتظل الأمثلة الأخرى مفيدة للاختبارات السريعة والوصول المستند إلى path:

    ```sql theme={null}
    -- Table function
    SELECT url, count() AS cnt
    FROM icebergS3('https://datasets-documentation.s3.amazonaws.com/lake_formats/iceberg/')
    GROUP BY url ORDER BY cnt DESC LIMIT 5

    -- Table engine
    SELECT url, count() AS cnt
    FROM hits_iceberg
    GROUP BY url ORDER BY cnt DESC LIMIT 5

    -- Catalog
    SELECT url, count() AS cnt
    FROM my_lake.`<database>.<table>`
    GROUP BY url ORDER BY cnt DESC LIMIT 5
    ```

    صياغة الاستعلام متطابقة — والتغيير الوحيد يكون في عبارة `FROM`. تعمل جميع الدوال وعمليات JOIN وعمليات التجميع في ClickHouse SQL بالطريقة نفسها بغضّ النظر عن مصدر البيانات.
  </Step>

  <Step title="حمّل مجموعة فرعية إلى ClickHouse" id="load-data">
    يُعد الاستعلام عن Iceberg مباشرةً أمرًا مناسبًا، لكن الأداء يظل محدودًا بمعدل نقل الشبكة وتخطيط الملفات. بالنسبة إلى أعباء العمل التحليلية، حمّل البيانات إلى جدول MergeTree أصلي.

    أولًا، شغّل استعلامًا مُرشَّحًا على جدول Iceberg للحصول على خط أساس:

    ```sql theme={null}
    SELECT
        url,
        count() AS cnt
    FROM hits_iceberg
    WHERE counterid = 38
    GROUP BY url
    ORDER BY cnt DESC
    LIMIT 5
    ```

    يفحص هذا الاستعلام مجموعة البيانات بالكامل في S3 لأن Iceberg لا يراعي عامل التصفية `counterid` — لذا توقّع أن يستغرق ذلك عدة ثوانٍ.

    <Image img="https://mintcdn.com/private-7c7dfe99-revert-104359-revert-104251-parquet-single/ZdmxDtIw7E15PlXi/images/datalake/iceberg-query.webp?fit=max&auto=format&n=ZdmxDtIw7E15PlXi&q=85&s=07b01c7ccf1cabb33367a7409ac0c5c1" alt="استعلام Iceberg" width="3836" height="1744" data-path="images/datalake/iceberg-query.webp" />

    الآن أنشئ جدول MergeTree وحمّل البيانات:

    ```sql theme={null}
    CREATE TABLE hits_clickhouse
    (
        url String,
        eventtime DateTime,
        counterid UInt32
    )
    ENGINE = MergeTree()
    ORDER BY (counterid, eventtime);
    ```

    ```sql theme={null}
    INSERT INTO hits_clickhouse
    SELECT url, eventtime, counterid
    FROM hits_iceberg
    ```

    أعِد تنفيذ الاستعلام نفسه على جدول MergeTree:

    ```sql theme={null}
    SELECT
        url,
        count() AS cnt
    FROM hits_clickhouse
    WHERE counterid = 38
    GROUP BY url
    ORDER BY cnt DESC
    LIMIT 5
    ```

    <Image img="https://mintcdn.com/private-7c7dfe99-revert-104359-revert-104251-parquet-single/ZdmxDtIw7E15PlXi/images/datalake/clickhouse-query.webp?fit=max&auto=format&n=ZdmxDtIw7E15PlXi&q=85&s=1ad2f995e266a45e382df9a1d3cc3917" alt="استعلام ClickHouse" width="3836" height="1744" data-path="images/datalake/clickhouse-query.webp" />

    نظرًا لأن `counterid` هو العمود الأول في مفتاح `ORDER BY`، فإن الفهرس الأساسي المتناثر في ClickHouse يتخطّى مباشرةً إلى وحدات granule ذات الصلة، فلا يقرأ إلا الصفوف الخاصة بـ `counterid = 38` بدلًا من فحص جميع الصفوف المئة مليون. والنتيجة هي تسارع كبير جدًا.

    يمضي دليل [تسريع التحليلات](/ar/guides/use-cases/data-warehousing/getting-started/accelerating-analytics) إلى ما هو أبعد من ذلك باستخدام الأنواع `LowCardinality`، وفهارس النص الكامل، ومفاتيح ترتيب محسّنة، مع عرض **تحسّن بنحو \~40x** على مجموعة بيانات تضم 283 مليون صف.

    **اعرف المزيد:** يغطّي [تسريع التحليلات باستخدام MergeTree](/ar/guides/use-cases/data-warehousing/getting-started/accelerating-analytics) تحسين المخطط، وفهرسة النص الكامل، ومقارنة كاملة للأداء قبل وبعد.
  </Step>

  <Step title="الكتابة مرة أخرى إلى Iceberg" id="write-back">
    يمكن لـ ClickHouse أيضًا كتابة البيانات مرة أخرى إلى جداول Iceberg، مما يتيح سير عمل ETL العكسي — من خلال نشر النتائج المُجمَّعة أو مجموعات فرعية لتستخدمها أدوات أخرى (Spark وTrino وDuckDB وغيرها).

    أنشئ جدول Iceberg للمخرجات:

    ```sql theme={null}
    CREATE TABLE output_iceberg
    (
        url String,
        cnt UInt64
    )
    ENGINE = IcebergS3('https://your-bucket.s3.amazonaws.com/output/', 'access_key', 'secret_key')
    ```

    اكتب النتائج المجمَّعة:

    ```sql theme={null}
    SET allow_experimental_insert_into_iceberg = 1;

    INSERT INTO output_iceberg
    SELECT
        url,
        count() AS cnt
    FROM hits_clickhouse
    GROUP BY url
    ORDER BY cnt DESC
    ```

    يمكن لأي محرّك متوافق مع Iceberg قراءة جدول Iceberg الناتج.

    **تعرّف على المزيد:** يشرح [كتابة البيانات إلى تنسيقات الجداول المفتوحة](/ar/guides/use-cases/data-warehousing/getting-started/writing-data) كيفية كتابة البيانات الخام والنتائج المجمّعة باستخدام مجموعة بيانات UK Price Paid، بما في ذلك اعتبارات المخطط عند مواءمة أنواع ClickHouse مع Iceberg.
  </Step>
</Steps>

<div id="next-steps">
  ## الخطوات التالية
</div>

بعد أن اطّلعت الآن على سير العمل الكامل، تعمّق أكثر في كل جانب:

* [الاتصال بالكتالوجات](/ar/guides/use-cases/data-warehousing/getting-started/connecting-catalogs) — موصى به لأعباء العمل المعتمدة على الكتالوج؛ جولة كاملة في Unity Catalog مع Delta وIceberg
* [الاستعلام عن البيانات مباشرةً](/ar/guides/use-cases/data-warehousing/getting-started/querying-directly) — التنسيقات الأربعة جميعها، خيارات العناقيد، محركات الجداول، التخزين المؤقت
* [تسريع التحليلات](/ar/guides/use-cases/data-warehousing/getting-started/accelerating-analytics) — تحسين المخطط، الفهرسة، عرض توضيحي لزيادة السرعة بنحو 40x
* [الكتابة إلى بحيرات البيانات](/ar/guides/use-cases/data-warehousing/getting-started/writing-data) — كتابة خام، كتابة مُجمّعة، مواءمة الأنواع
* [مصفوفة الدعم](/ar/guides/use-cases/data-warehousing/support-matrix) — مقارنة الميزات عبر التنسيقات وأنظمة التخزين الخلفية
* [أفضل الممارسات](/ar/guides/use-cases/data-warehousing/getting-started/best-practices) — اختيار أسلوب الوصول، وإعدادات الأداء، وأنماط أعباء العمل