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

> يتيح لك هذا المحرك استخدام عنقود Keeper/ZooKeeper كمخزن مفتاح-قيمة متسق مع عمليات كتابة خطية وعمليات قراءة متسقة تسلسليًا.

# محرك جدول KeeperMap

يتيح لك هذا المحرك استخدام عنقود Keeper/ZooKeeper كمخزن مفتاح-قيمة متسق مع عمليات كتابة خطية وعمليات قراءة متسقة تسلسليًا.

لتمكين محرك التخزين KeeperMap، تحتاج إلى تحديد مسار ZooKeeper الذي ستُخزَّن فيه الجداول باستخدام الإعداد `<keeper_map_path_prefix>`.

على سبيل المثال:

```xml theme={null}
<clickhouse>
    <keeper_map_path_prefix>/keeper_map_tables</keeper_map_path_prefix>
</clickhouse>
```

حيث يمكن أن يكون المسار أي مسار صالح آخر في ZooKeeper.

<div id="creating-a-table">
  ## إنشاء جدول
</div>

```sql theme={null}
CREATE TABLE [IF NOT EXISTS] [db.]table_name [ON CLUSTER cluster]
(
    name1 [type1] [DEFAULT|MATERIALIZED|ALIAS expr1],
    name2 [type2] [DEFAULT|MATERIALIZED|ALIAS expr2],
    ...
) ENGINE = KeeperMap(root_path, [keys_limit]) PRIMARY KEY(primary_key_name)
```

معلمات المحرك:

* `root_path` - مسار ZooKeeper الذي سيُخزَّن فيه `table_name`.
  يجب ألا يحتوي هذا المسار على البادئة المعرّفة في الإعداد `<keeper_map_path_prefix>`، لأن هذه البادئة ستُضاف تلقائيًا إلى `root_path`.
  بالإضافة إلى ذلك، تكون الصيغة `auxiliary_zookeeper_cluster_name:/some/path` مدعومة أيضًا، حيث إن `auxiliary_zookeeper_cluster` عبارة عن عنقود ZooKeeper معرّف داخل الإعداد `<auxiliary_zookeepers>`.
  وبشكل افتراضي، يُستخدم عنقود ZooKeeper المعرّف داخل الإعداد `<zookeeper>`.
* `keys_limit` - عدد المفاتيح المسموح به داخل الجدول.
  هذا حدّ مرن، وقد ينتهي الأمر في بعض الحالات الطرفية بوجود عدد أكبر من المفاتيح داخل الجدول.
* `primary_key_name` – أي اسم عمود ضمن قائمة الأعمدة.
* يجب تحديد `primary key`، وهو يدعم عمودًا واحدًا فقط في المفتاح الأساسي. سيُسلسَل المفتاح الأساسي بصيغة ثنائية باعتباره `node name` داخل ZooKeeper.
* ستُسلسَل الأعمدة الأخرى غير المفتاح الأساسي بصيغة ثنائية وفق الترتيب المقابل، وتُخزَّن كقيمة للعقدة الناتجة التي يحددها المفتاح المُسلسَل.
* ستُحسَّن الاستعلامات التي تستخدم التصفية بالمفتاح `equals` أو `in` إلى عمليات بحث عن عدة مفاتيح من `Keeper`، وإلا فستُجلَب جميع القيم.

مثال:

```sql theme={null}
CREATE TABLE keeper_map_table
(
    `key` String,
    `v1` UInt32,
    `v2` String,
    `v3` Float32
)
ENGINE = KeeperMap('/keeper_map_table', 4)
PRIMARY KEY key
```

مع

```xml theme={null}
<clickhouse>
    <keeper_map_path_prefix>/keeper_map_tables</keeper_map_path_prefix>
</clickhouse>
```

سيُخزَّن كل Value، وهو تسلسل ثنائي لـ `(v1, v2, v3)`، داخل `/keeper_map_tables/keeper_map_table/data/serialized_key` في `Keeper`.
بالإضافة إلى ذلك، سيكون لعدد المفاتيح حد مرن قدره 4.

إذا أُنشئت عدة جداول على مسار ZooKeeper نفسه، فستظل القيم محفوظة ما دام هناك جدول واحد على الأقل يستخدمه.
ونتيجة لذلك، يمكن استخدام عبارة `ON CLUSTER` عند إنشاء الجدول ومشاركة البيانات بين عدة مثيلات ClickHouse.
وبالطبع، من الممكن تشغيل `CREATE TABLE` يدويًا باستخدام المسار نفسه على مثيلات ClickHouse غير مرتبطة للحصول على التأثير نفسه لمشاركة البيانات.

<div id="supported-operations">
  ## العمليات المدعومة
</div>

<div id="inserts">
  ### عمليات الإدراج
</div>

عند إدراج صفوف جديدة في `KeeperMap`، إذا لم يكن المفتاح موجودًا، فسيُنشأ إدخال جديد لهذا المفتاح.
إذا كان المفتاح موجودًا وكان الإعداد `keeper_map_strict_mode` مضبوطًا على `true`، فسيُطلق استثناء، وإلا فستُستبدل القيمة الخاصة بالمفتاح.

مثال:

```sql theme={null}
INSERT INTO keeper_map_table VALUES ('some key', 1, 'value', 3.2);
```

<div id="deletes">
  ### الحذف
</div>

يمكن حذف الصفوف باستخدام الاستعلام `DELETE` أو `TRUNCATE`.
إذا كان المفتاح موجودًا، وكان الإعداد `keeper_map_strict_mode` مضبوطًا على `true`، فلن تنجح عمليتا جلب البيانات وحذفها إلا إذا أمكن تنفيذهما بصورة ذرية.

```sql theme={null}
DELETE FROM keeper_map_table WHERE key LIKE 'some%' AND v1 > 1;
```

```sql theme={null}
ALTER TABLE keeper_map_table DELETE WHERE key LIKE 'some%' AND v1 > 1;
```

```sql theme={null}
TRUNCATE TABLE keeper_map_table;
```

<div id="updates">
  ### التحديثات
</div>

يمكن تحديث القيم باستخدام استعلام `ALTER TABLE`. ولا يمكن تحديث المفتاح الأساسي.
إذا كان الإعداد `keeper_map_strict_mode` مضبوطًا على `true`، فلن تنجح عمليتا جلب البيانات وتحديثها إلا إذا نُفِّذتا بصورة ذرّية.

```sql theme={null}
ALTER TABLE keeper_map_table UPDATE v1 = v1 * 10 + 2 WHERE key LIKE 'some%' AND v3 > 3.1;
```

<div id="related-content">
  ## محتوى مرتبط
</div>

* مدونة: [إنشاء تطبيقات للتحليلات في الوقت الفعلي باستخدام ClickHouse وHex](https://clickhouse.com/blog/building-real-time-applications-with-clickhouse-and-hex-notebook-keeper-engine)