> ## 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.

> توثيق دوال Tuple وMap

# دوال Map

{/*AUTOGENERATED_START*/}

<div id="extractKeyValuePairs">
  ## extractKeyValuePairs
</div>

مُتاح منذ: v23.4.0

تستخرج أزواج المفاتيح والقيم من أي سلسلة نصية. لا يشترط أن تكون السلسلة النصية منظمةً بالكامل وفق تنسيق أزواج المفاتيح والقيم؛

يمكن أن تحتوي على ضوضاء (مثل ملفات السجل). يجب تحديد تنسيق زوج المفتاح-القيمة المراد تفسيره من خلال وسيطات الدالة.

يتكوّن زوج المفتاح والقيمة من مفتاح يعقبه `key_value_delimiter` ثم قيمة. كما تُدعم المفاتيح والقيم المحاطة بعلامات اقتباس. ويجب الفصل بين أزواج المفتاح والقيمة بمحددات الأزواج.

**البنية**

```sql theme={null}
            extractKeyValuePairs(data, [key_value_delimiter], [pair_delimiter], [quoting_character])
```

**الوسيطات**

* `data` - السلسلة النصية المُراد استخراج أزواج المفتاح-القيمة منها. [String](/ar/reference/data-types/string) أو [FixedString](/ar/reference/data-types/fixedstring).
  * `key_value_delimiter` - الحرف المستخدَم كفاصل بين المفتاح والقيمة. القيمة الافتراضية هي `:`. [String](/ar/reference/data-types/string) أو [FixedString](/ar/reference/data-types/fixedstring).
  * `pair_delimiters` - مجموعة الأحرف المستخدَمة كفواصل بين الأزواج. القيمة الافتراضية هي `\space` و `,` و `;`. [String](/ar/reference/data-types/string) أو [FixedString](/ar/reference/data-types/fixedstring).
  * `quoting_character` - الحرف المستخدَم كحرف اقتباس. القيمة الافتراضية هي `"`. [String](/ar/reference/data-types/string) أو [FixedString](/ar/reference/data-types/fixedstring).
  * `unexpected_quoting_character_strategy` - الاستراتيجية المستخدَمة للتعامل مع أحرف الاقتباس في مواضع غير متوقعة أثناء مرحلتي `read_key` و `read_value`. القيم الممكنة: `invalid` و `accept` و `promote`. تؤدي القيمة `invalid` إلى تجاهل المفتاح/القيمة والعودة إلى حالة `WAITING_KEY`. وتتعامل القيمة `accept` معه بوصفه حرفًا عاديًا. أما القيمة `promote` فتنقل الحالة إلى `READ_QUOTED_{KEY/VALUE}` وتبدأ من الحرف التالي. القيمة الافتراضية هي `INVALID`

**القيم المُعادة**

* أزواج المفتاح والقيمة المستخرَجة ضمن Map(String, String).

**أمثلة**

الاستعلام:

**حالة بسيطة**

```sql theme={null}
            arthur :) select extractKeyValuePairs('name:neymar, age:31 team:psg,nationality:brazil') as kv

            SELECT extractKeyValuePairs('name:neymar, age:31 team:psg,nationality:brazil') as kv

            Query id: f9e0ca6f-3178-4ee2-aa2c-a5517abb9cee

            ┌─kv──────────────────────────────────────────────────────────────────────┐
            │ {'name':'neymar','age':'31','team':'psg','nationality':'brazil'}        │
            └─────────────────────────────────────────────────────────────────────────┘
```

**علامة الاقتباس المفردة كمحرف اقتباس**

```sql theme={null}
            arthur :) select extractKeyValuePairs('name:\'neymar\';\'age\':31;team:psg;nationality:brazil,last_key:last_value', ':', ';,', '\'') as kv

            SELECT extractKeyValuePairs('name:\'neymar\';\'age\':31;team:psg;nationality:brazil,last_key:last_value', ':', ';,', '\'') as kv

            Query id: 0e22bf6b-9844-414a-99dc-32bf647abd5e

            ┌─kv───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
            │ {'name':'neymar','age':'31','team':'psg','nationality':'brazil','last_key':'last_value'}                                 │
            └──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
```

أمثلة على unexpected\_quoting\_character\_strategy:

unexpected\_quoting\_character\_strategy=invalid

```sql theme={null}
            SELECT extractKeyValuePairs('name"abc:5', ':', ' ,;', '\"', 'INVALID') as kv;
```

```text theme={null}
            ┌─kv────────────────┐
            │ {'abc':'5'}  │
            └───────────────────┘
```

```sql theme={null}
            SELECT extractKeyValuePairs('name"abc":5', ':', ' ,;', '\"', 'INVALID') as kv;
```

```text theme={null}
            ┌─kv──┐
            │ {}  │
            └─────┘
```

unexpected\_quoting\_character\_strategy=accept

```sql theme={null}
            SELECT extractKeyValuePairs('name"abc:5', ':', ' ,;', '\"', 'ACCEPT') as kv;
```

```text theme={null}
            ┌─kv────────────────┐
            │ {'name"abc':'5'}  │
            └───────────────────┘
```

```sql theme={null}
            SELECT extractKeyValuePairs('name"abc":5', ':', ' ,;', '\"', 'ACCEPT') as kv;
```

```text theme={null}
            ┌─kv─────────────────┐
            │ {'name"abc"':'5'}  │
            └────────────────────┘
```

unexpected\_quoting\_character\_strategy=promote

```sql theme={null}
            SELECT extractKeyValuePairs('name"abc:5', ':', ' ,;', '\"', 'PROMOTE') as kv;
```

```text theme={null}
            ┌─kv──┐
            │ {}  │
            └─────┘
```

```sql theme={null}
            SELECT extractKeyValuePairs('name"abc":5', ':', ' ,;', '\"', 'PROMOTE') as kv;
```

```text theme={null}
            ┌─kv───────────┐
            │ {'abc':'5'}  │
            └──────────────┘
```

**تسلسلات الإفلات عند عدم دعمها**

```sql theme={null}
            arthur :) select extractKeyValuePairs('age:a\\x0A\\n\\0') as kv

            SELECT extractKeyValuePairs('age:a\\x0A\\n\\0') AS kv

            Query id: e9fd26ee-b41f-4a11-b17f-25af6fd5d356

            ┌─kv────────────────────┐
            │ {'age':'a\\x0A\\n\\0'} │
            └───────────────────────┘
```

**الصيغة**

```sql theme={null}
extractKeyValuePairs(input)
```

**الأسماء المستعارة**: `str_to_map`, `mapFromString`

**الوسائط**

* لا شيء.

**القيمة المُعادة**

**أمثلة**

<div id="extractKeyValuePairsWithEscaping">
  ## extractKeyValuePairsWithEscaping
</div>

أُضيف في: v23.4.0

مماثلة لـ `extractKeyValuePairs` ولكن مع دعم تسلسلات الهروب.

تسلسلات الهروب المدعومة: `\x`، `\N`، `\a`، `\b`، `\e`، `\f`، `\n`، `\r`، `\t`، `\v` و `\0`.
تُعاد تسلسلات الهروب غير القياسية كما هي (بما في ذلك الشرطة المائلة العكسية) ما لم تكن إحدى القيم التالية:
`\\`، `'`، `"`، `backtick`، `/`، `=` أو محارف تحكم ASCII (`c <= 31`).

تلبي هذه الدالة حالة الاستخدام التي لا يكون فيها تطبيق الهروب مسبقًا أو لاحقًا مناسبًا. على سبيل المثال، تأمل
سلسلة الإدخال التالية: `a: "aaaa\"bbb"`. والمخرَج المتوقع هو: `a: aaaa\"bbbb`.

* الهروب المسبق: سيؤدي تطبيق الهروب المسبق عليها إلى إخراج: `a: "aaaa"bbb"`، ثم ستُخرج `extractKeyValuePairs` بعد ذلك: `a: aaaa`
  * الهروب اللاحق: ستُخرج `extractKeyValuePairs` القيمة `a: aaaa\`، وسيُبقيها الهروب اللاحق كما هي.

سيتم تجاهل تسلسلات الهروب البادئة في المفاتيح، وستُعد غير صالحة في القيم.

**تسلسلات الهروب عند تفعيل دعمها**

```sql theme={null}
            arthur :) select extractKeyValuePairsWithEscaping('age:a\\x0A\\n\\0') as kv

            SELECT extractKeyValuePairsWithEscaping('age:a\\x0A\\n\\0') AS kv

            Query id: 44c114f0-5658-4c75-ab87-4574de3a1645

            ┌─kv───────────────┐
            │ {'age':'a\n\n\0'} │
            └──────────────────┘
```

**الصيغة**

```sql theme={null}
extractKeyValuePairsWithEscaping(input)
```

**المعاملات**

* لا يوجد.

**القيمة المُعادة**

**أمثلة**

<div id="map">
  ## map
</div>

أُضيف في: v21.1.0

ينشئ قيمة من النوع `Map(key, value)` من أزواج المفاتيح والقيم.

**البنية**

```sql theme={null}
map(key1, value1[, key2, value2, ...])
```

**المعاملات**

* `key_n` — مفاتيح عناصر الخريطة. [`Any`](/ar/reference/data-types/index)
* `value_n` — قيم عناصر الخريطة. [`Any`](/ar/reference/data-types/index)

**القيمة المُعادة**

تعيد خريطة تحتوي على أزواج مفتاح:قيمة. [`Map(Any, Any)`](/ar/reference/data-types/map)

**أمثلة**

**مثال على الاستخدام**

```sql title=Query theme={null}
SELECT map('key1', number, 'key2', number * 2) FROM numbers(3)
```

```response title=Response theme={null}
{'key1':0,'key2':0}
{'key1':1,'key2':2}
{'key1':2,'key2':4}
```

<div id="mapAdd">
  ## mapAdd
</div>

أُضيف في: v20.7.0

يجمع جميع المفاتيح ويحسب مجموع القيم المقابلة.

**البنية**

```sql theme={null}
mapAdd(arg1[, arg2, ...])
```

**الوسائط**

* `arg1[, arg2, ...]` — قيم من نوع Map أو Tuple تتكوّن من مصفوفتين، حيث تمثّل عناصر المصفوفة الأولى المفاتيح، بينما تحتوي المصفوفة الثانية على القيم المقابلة لكل مفتاح. [`Map(K, V)`](/ar/reference/data-types/map) أو [`Tuple(Array(T), Array(T))`](/ar/reference/data-types/tuple)

**القيمة المُعادة**

يعيد Map أو Tuple، بحيث تحتوي المصفوفة الأولى على المفاتيح المرتبة، وتحتوي المصفوفة الثانية على القيم. [`Map(K, V)`](/ar/reference/data-types/map) أو [`Tuple(Array(T), Array(T))`](/ar/reference/data-types/tuple)

**أمثلة**

**باستخدام نوع Map**

```sql title=Query theme={null}
SELECT mapAdd(map(1, 1), map(1, 1))
```

```response title=Response theme={null}
{1:2}
```

**باستخدام tuple**

```sql title=Query theme={null}
SELECT mapAdd(([toUInt8(1), 2], [1, 1]), ([toUInt8(1), 2], [1, 1]))
```

```response title=Response theme={null}
([1, 2], [2, 2])
```

<div id="mapAll">
  ## mapAll
</div>

أُضيفت في: v23.4.0

تتحقق مما إذا كان شرطٌ ما ينطبق على جميع أزواج المفتاح والقيمة في map.
تُعد `mapAll` دالة من الرتبة العليا.
يمكنك تمرير دالة lambda إليها بوصفها الوسيطة الأولى.

**البنية**

```sql theme={null}
mapAll([func,] map)
```

**الوسائط**

* `func` — دالة لامدا. [`Lambda function`](/ar/reference/functions/regular-functions/overview#arrow-operator-and-lambda)
* `map` — قيمة Map المراد التحقق منها. [`Map(K, V)`](/ar/reference/data-types/map)

**القيمة المُعادة**

تُرجع `1` إذا كانت جميع أزواج المفتاح والقيمة تستوفي الشرط، وإلا فتُرجع `0`. [`UInt8`](/ar/reference/data-types/int-uint)

**أمثلة**

**مثال على الاستخدام**

```sql title=Query theme={null}
SELECT mapAll((k, v) -> v = 1, map('k1', 1, 'k2', 2))
```

```response title=Response theme={null}
0
```

<div id="mapApply">
  ## mapApply
</div>

طُرح في: v22.3.0

يطبّق دالة على كل عنصر في Map.

**الصيغة**

```sql theme={null}
mapApply(func, map)
```

**الوسائط**

* `func` — دالة لامدا. [`دالة لامدا`](/ar/reference/functions/regular-functions/overview#arrow-operator-and-lambda)
* `map` — الخريطة المراد تطبيق الدالة عليها. [`Map(K, V)`](/ar/reference/data-types/map)

**القيمة المعادة**

تعيد خريطة جديدة ناتجة من الخريطة الأصلية عبر تطبيق `func` على كل عنصر. [`Map(K, V)`](/ar/reference/data-types/map)

**أمثلة**

**مثال على الاستخدام**

```sql title=Query theme={null}
SELECT mapApply((k, v) -> (k, v * 2), map('k1', 1, 'k2', 2))
```

```response title=Response theme={null}
{'k1':2,'k2':4}
```

<div id="mapConcat">
  ## mapConcat
</div>

أُضيفت في: v23.4.0

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

**الصيغة**

```sql theme={null}
mapConcat(maps)
```

**الوسيطات**

* `maps` — أي عدد من الخرائط. [`Map`](/ar/reference/data-types/map)

**القيمة المعادة**

تعيد خريطة ناتجة عن دمج الخرائط المُمرَّرة كوسيطات. [`Map`](/ar/reference/data-types/map)

**أمثلة**

**مثال على الاستخدام**

```sql title=Query theme={null}
SELECT mapConcat(map('k1', 'v1'), map('k2', 'v2'))
```

```response title=Response theme={null}
{'k1':'v1','k2':'v2'}
```

<div id="mapContainsKey">
  ## mapContainsKey
</div>

أُضيفت في: v21.2.0

يحدِّد ما إذا كان المفتاح موجودًا في خريطة.

**الصيغة**

```sql theme={null}
mapContainsKey(map, key)
```

**الأسماء البديلة**: `mapContains`

**المعاملات**

* `map` — الخريطة المراد البحث فيها. [`Map(K, V)`](/ar/reference/data-types/map)
* `key` — المفتاح المراد البحث عنه. يجب أن يطابق نوعه نوع المفتاح في الخريطة. [`Any`](/ar/reference/data-types/index)

**القيمة المعادة**

تعيد 1 إذا كانت الخريطة تحتوي على المفتاح، و0 إذا لم تكن تحتوي عليه. [`UInt8`](/ar/reference/data-types/int-uint)

**أمثلة**

**مثال على الاستخدام**

```sql title=Query theme={null}
SELECT mapContainsKey(map('k1', 'v1', 'k2', 'v2'), 'k1')
```

```response title=Response theme={null}
1
```

<div id="mapContainsKeyLike">
  ## mapContainsKeyLike
</div>

أُضيف في: v23.4.0

يتحقق مما إذا كانت الخريطة تحتوي على مفتاح يطابق النمط المحدد باستخدام `LIKE`.

**الصياغة**

```sql theme={null}
mapContainsKeyLike(map, pattern)
```

**الوسائط**

* `map` — الخريطة المراد البحث فيها. [`Map(K, V)`](/ar/reference/data-types/map)
* `pattern` — النمط المراد مطابقة المفاتيح وفقًا له. [`const String`](/ar/reference/data-types/string)

**القيمة المُعادة**

يعيد `1` إذا كانت `map` تحتوي على مفتاح يطابق `pattern`، وإلا فيعيد `0`. [`UInt8`](/ar/reference/data-types/int-uint)

**أمثلة**

**مثال على الاستخدام**

```sql title=Query theme={null}
CREATE TABLE tab (a Map(String, String))
ENGINE = MergeTree
ORDER BY tuple();

INSERT INTO tab VALUES ({'abc':'abc','def':'def'}), ({'hij':'hij','klm':'klm'});

SELECT mapContainsKeyLike(a, 'a%') FROM tab;
```

```response title=Response theme={null}
┌─mapContainsKeyLike(a, 'a%')─┐
│                           1 │
│                           0 │
└─────────────────────────────┘
```

<div id="mapContainsValue">
  ## mapContainsValue
</div>

تم تقديمه في: v25.6.0

يحدّد ما إذا كانت قيمة ما موجودة في map.

**الصياغة**

```sql theme={null}
mapContainsValue(map, value)
```

**الوسيطات**

* `map` — كائن Map المراد البحث فيه. [`Map(K, V)`](/ar/reference/data-types/map)
* `value` — القيمة المراد البحث عنها. يجب أن يتطابق النوع مع نوع القيم في `map`. [`Any`](/ar/reference/data-types/index)

**القيمة المعادة**

يُرجع `1` إذا كانت `map` تحتوي على القيمة، و`0` إذا لم تكن كذلك. [`UInt8`](/ar/reference/data-types/int-uint)

**أمثلة**

**مثال على الاستخدام**

```sql title=Query theme={null}
SELECT mapContainsValue(map('k1', 'v1', 'k2', 'v2'), 'v1')
```

```response title=Response theme={null}
1
```

<div id="mapContainsValueLike">
  ## mapContainsValueLike
</div>

أُضيفت في: v25.5.0

يتحقق مما إذا كان ‎map‎ يحتوي على قيمة تطابق النمط المحدد باستخدام `LIKE`.

**الصياغة**

```sql theme={null}
mapContainsValueLike(map, pattern)
```

**المعاملات**

* `map` — الـ Map المطلوب البحث فيه. [`Map(K, V)`](/ar/reference/data-types/map)
* `pattern` — النمط المطلوب مطابقة القيم معه. [`const String`](/ar/reference/data-types/string)

**القيمة المعادة**

تعيد `1` إذا كان `map` يحتوي على قيمة تطابق `pattern`، وإلا فتعيد `0`. [`UInt8`](/ar/reference/data-types/int-uint)

**أمثلة**

**مثال على الاستخدام**

```sql title=Query theme={null}
CREATE TABLE tab (a Map(String, String))
ENGINE = MergeTree
ORDER BY tuple();

INSERT INTO tab VALUES ({'abc':'abc','def':'def'}), ({'hij':'hij','klm':'klm'});

SELECT mapContainsValueLike(a, 'a%') FROM tab;
```

```response title=Response theme={null}
┌─mapContainsV⋯ke(a, 'a%')─┐
│                        1 │
│                        0 │
└──────────────────────────┘
```

<div id="mapExists">
  ## mapExists
</div>

قُدِّمت في: v23.4.0

تتحقّق مما إذا كان شرطٌ ما ينطبق على زوج مفتاح-قيمة واحد على الأقل في map.
`mapExists` هي دالة عالية الرتبة.
يمكنك تمرير دالة لامبدا إليها باعتبارها الوسيط الأول.

**الصيغة**

```sql theme={null}
mapExists([func,] map)
```

**الوسائط**

* `func` — اختياري. دالة لامدا. [`Lambda function`](/ar/reference/functions/regular-functions/overview#arrow-operator-and-lambda)
* `map` — قيمة Map المراد التحقق منها. [`Map(K, V)`](/ar/reference/data-types/map)

**القيمة المُعادة**

تُرجع `1` إذا كان هناك زوج مفتاح-قيمة واحد على الأقل يستوفي الشرط، و`0` خلاف ذلك. [`UInt8`](/ar/reference/data-types/int-uint)

**أمثلة**

**مثال على الاستخدام**

```sql title=Query theme={null}
SELECT mapExists((k, v) -> v = 1, map('k1', 1, 'k2', 2))
```

```response title=Response theme={null}
1
```

<div id="mapExtractKeyLike">
  ## mapExtractKeyLike
</div>

أُضيفت في: v23.4.0

عند تزويد هذه الدالة بخريطة ذات مفاتيح نصية ونمط `LIKE`، فإنها تُرجع خريطةً تحتوي على العناصر التي يطابق مفتاحها النمط.

**البنية**

```sql theme={null}
mapExtractKeyLike(map, pattern)
```

**الوسيطات**

* `map` — الخريطة المراد الاستخراج منها. [`Map(K, V)`](/ar/reference/data-types/map)
* `pattern` — النمط المطلوب مطابقة المفاتيح عليه. [`const String`](/ar/reference/data-types/string)

**القيمة المُعادة**

تعيد خريطة تحتوي على العناصر التي يطابق مفتاحها النمط المحدد. وإذا لم يطابق أي عنصر هذا النمط، فستُعاد خريطة فارغة. [`Map(K, V)`](/ar/reference/data-types/map)

**أمثلة**

**مثال على الاستخدام**

```sql title=Query theme={null}
CREATE TABLE tab (a Map(String, String))
ENGINE = MergeTree
ORDER BY tuple();

INSERT INTO tab VALUES ({'abc':'abc','def':'def'}), ({'hij':'hij','klm':'klm'});

SELECT mapExtractKeyLike(a, 'a%') FROM tab;
```

```response title=Response theme={null}
┌─mapExtractKeyLike(a, 'a%')─┐
│ {'abc':'abc'}              │
│ {}                         │
└────────────────────────────┘
```

<div id="mapExtractValueLike">
  ## mapExtractValueLike
</div>

أُضيف في: v25.5.0

إذا كانت لديك `map` تحتوي على قيم من النوع String ونمط `LIKE`، فستُرجع هذه الدالة `map` بالعناصر التي تطابق قيمتها النمط.

**الصيغة**

```sql theme={null}
mapExtractValueLike(map, pattern)
```

**الوسيطات**

* `map` — قيمة الـ Map المراد الاستخراج منها. [`Map(K, V)`](/ar/reference/data-types/map)
* `pattern` — النمط المطلوب مطابقة القيم معه. [`const String`](/ar/reference/data-types/string)

**القيمة المعادة**

يعيد قيمة Map تحتوي على العناصر التي تطابق قيمتها النمط المحدد. وإذا لم يطابق أي عنصر هذا النمط، فستُعاد قيمة Map فارغة. [`Map(K, V)`](/ar/reference/data-types/map)

**أمثلة**

**مثال على الاستخدام**

```sql title=Query theme={null}
CREATE TABLE tab (a Map(String, String))
ENGINE = MergeTree
ORDER BY tuple();

INSERT INTO tab VALUES ({'abc':'abc','def':'def'}), ({'hij':'hij','klm':'klm'});

SELECT mapExtractValueLike(a, 'a%') FROM tab;
```

```response title=Response theme={null}
┌─mapExtractValueLike(a, 'a%')─┐
│ {'abc':'abc'}                │
│ {}                           │
└──────────────────────────────┘
```

<div id="mapFilter">
  ## mapFilter
</div>

أُضيف في: v22.3.0

يُرشّح قيمة من النوع Map عبر تطبيق دالة على كل عنصر فيها.

**البنية**

```sql theme={null}
mapFilter(func, map)
```

**الوسيطات**

* `func` — دالة لامبدا. [`دالة لامبدا`](/ar/reference/functions/regular-functions/overview#arrow-operator-and-lambda)
* `map` — الخريطة المطلوب تصفيتها. [`Map(K, V)`](/ar/reference/data-types/map)

**القيمة المعادة**

يعيد خريطة لا تحتوي إلا على العناصر التي تُرجع لها `func` قيمة غير `0`. [`Map(K, V)`](/ar/reference/data-types/map)

**أمثلة**

**مثال على الاستخدام**

```sql title=Query theme={null}
SELECT mapFilter((k, v) -> v > 1, map('k1', 1, 'k2', 2))
```

```response title=Response theme={null}
{'k2':2}
```

<div id="mapFromArrays">
  ## mapFromArrays
</div>

أُضيف في: v23.3.0

ينشئ خريطة من مصفوفة أو خريطة من المفاتيح، ومن مصفوفة أو خريطة من القيم.
تُعدّ هذه الدالة بديلاً مناسبًا للصياغة `CAST([...], 'Map(key_type, value_type)')`.

**الصيغة**

```sql theme={null}
mapFromArrays(keys, values)
```

**الأسماء المستعارة**: `MAP_FROM_ARRAYS`

**الوسيطات**

* `keys` — `Array` أو `Map` من المفاتيح لإنشاء الـ `Map` منه. [`Array`](/ar/reference/data-types/array) أو [`Map`](/ar/reference/data-types/map)
* `values` — `Array` أو `Map` من القيم لإنشاء الـ `Map` منه. [`Array`](/ar/reference/data-types/array) أو [`Map`](/ar/reference/data-types/map)

**القيمة المُعادة**

يُرجع `Map` بمفاتيح وقيم مُنشأة من مصفوفة المفاتيح ومصفوفة/‏`Map` القيم. [`Map`](/ar/reference/data-types/map)

**أمثلة**

**الاستخدام الأساسي**

```sql title=Query theme={null}
SELECT mapFromArrays(['a', 'b', 'c'], [1, 2, 3])
```

```response title=Response theme={null}
{'a':1,'b':2,'c':3}
```

**مع مُدخلات Map**

```sql title=Query theme={null}
SELECT mapFromArrays([1, 2, 3], map('a', 1, 'b', 2, 'c', 3))
```

```response title=Response theme={null}
{1:('a', 1), 2:('b', 2), 3:('c', 3)}
```

<div id="mapKeys">
  ## mapKeys
</div>

أُضيفت في: v21.2.0

تعيد مفاتيح قيمة Map معيّنة.
يمكن تحسين هذه الدالة عبر تمكين الإعداد [`optimize_functions_to_subcolumns`](/ar/reference/settings/session-settings#optimize_functions_to_subcolumns).
عند تمكين هذا الإعداد، لا تقرأ الدالة سوى العمود الفرعي `keys` بدلًا من قيمة Map بالكامل.
يُحوَّل الاستعلام `SELECT mapKeys(m) FROM table` إلى `SELECT m.keys FROM table`.

**الصيغة**

```sql theme={null}
mapKeys(map)
```

**الوسائط**

* `map` — كائن الـ Map المراد استخراج المفاتيح منه. [`Map(K, V)`](/ar/reference/data-types/map)

**القيمة المعادة**

تعيد مصفوفة تحتوي على جميع مفاتيح الـ Map. [`Array(T)`](/ar/reference/data-types/array)

**أمثلة**

**مثال على الاستخدام**

```sql title=Query theme={null}
SELECT mapKeys(map('k1', 'v1', 'k2', 'v2'))
```

```response title=Response theme={null}
['k1','k2']
```

<div id="mapPartialReverseSort">
  ## mapPartialReverseSort
</div>

أُضيف في: v23.4.0

يرتّب عناصر map ترتيبًا تنازليًا، مع وسيطة limit إضافية تتيح الفرز الجزئي.
إذا جرى تحديد الدالة func، فإن ترتيب الفرز يتحدد وفقًا لنتيجة الدالة func عند تطبيقها على مفاتيح map وقيمه.

**الصيغة**

```sql theme={null}
mapPartialReverseSort([func,] limit, map)
```

**الوسائط**

* `func` — اختياري. دالة لامبدا. [`Lambda function`](/ar/reference/functions/regular-functions/overview#arrow-operator-and-lambda)
* `limit` — تُرتَّب العناصر ضمن النطاق `[1..limit]`. [`(U)Int*`](/ar/reference/data-types/int-uint)
* `map` — الخريطة المطلوب فرزها. [`Map(K, V)`](/ar/reference/data-types/map)

**القيمة المُعادة**

يُرجع خريطةً مفروزةً جزئيًا بترتيب تنازلي. [`Map(K, V)`](/ar/reference/data-types/map)

**أمثلة**

**مثال للاستخدام**

```sql title=Query theme={null}
SELECT mapPartialReverseSort((k, v) -> v, 2, map('k1', 3, 'k2', 1, 'k3', 2))
```

```response title=Response theme={null}
{'k1':3,'k3':2,'k2':1}
```

<div id="mapPartialSort">
  ## mapPartialSort
</div>

قُدِّمت في: v23.4.0

ترتّب عناصر `Map` ترتيبًا تصاعديًا، مع وسيطة حدّ إضافية تتيح الفرز الجزئي.
إذا كانت الدالة `func` محددة، يُحدَّد ترتيب الفرز بناءً على ناتج الدالة `func` عند تطبيقها على مفاتيح `Map` وقيمها.

**البنية**

```sql theme={null}
mapPartialSort([func,] limit, map)
```

**الوسائط**

* `func` — اختياري. دالة لامبدا. [`Lambda function`](/ar/reference/functions/regular-functions/overview#arrow-operator-and-lambda)
* `limit` — تُفرَز العناصر ضمن النطاق `[1..limit]`. [`(U)Int*`](/ar/reference/data-types/int-uint)
* `map` — الخريطة المطلوب فرزها. [`Map(K, V)`](/ar/reference/data-types/map)

**القيمة المُعادة**

يعيد خريطة مفروزة جزئيًا. [`Map(K, V)`](/ar/reference/data-types/map)

**أمثلة**

**مثال على الاستخدام**

```sql title=Query theme={null}
SELECT mapPartialSort((k, v) -> v, 2, map('k1', 3, 'k2', 1, 'k3', 2))
```

```response title=Response theme={null}
{'k2':1,'k3':2,'k1':3}
```

<div id="mapPopulateSeries">
  ## mapPopulateSeries
</div>

أُضيفت في: v20.10.0

تملأ أزواج المفتاح-القيمة المفقودة في map ذات مفاتيح صحيحة.
ولدعم توسيع المفاتيح إلى ما بعد أكبر قيمة، يمكن تحديد مفتاح أقصى.
وبصورة أدق، تُرجع الدالة map تكون فيها المفاتيح سلسلة تمتد من أصغر مفتاح إلى أكبر مفتاح (أو الوسيطة max إذا جرى تحديدها) بخطوة مقدارها 1، مع القيم المقابلة.
إذا لم تُحدَّد قيمة لمفتاح ما، تُستخدَم قيمة افتراضية له.
في حال تكرار المفاتيح، لا تُربَط بالمفتاح إلا القيمة الأولى فقط (حسب ترتيب الظهور).

**البنية**

```sql theme={null}
mapPopulateSeries(map[, max]) | mapPopulateSeries(keys, values[, max])
```

**الوسائط**

* `map` — Map بمفاتيح صحيحة. [`Map((U)Int*, V)`](/ar/reference/data-types/map)
* `keys` — مصفوفة من المفاتيح. [`Array(T)`](/ar/reference/data-types/array)
* `values` — مصفوفة من القيم. [`Array(T)`](/ar/reference/data-types/array)
* `max` — اختياري. الحد الأقصى لقيمة المفتاح. [`Int8`](/ar/reference/data-types/int-uint) أو [`Int16`](/ar/reference/data-types/int-uint) أو [`Int32`](/ar/reference/data-types/int-uint) أو [`Int64`](/ar/reference/data-types/int-uint) أو [`Int128`](/ar/reference/data-types/int-uint) أو [`Int256`](/ar/reference/data-types/int-uint)

**القيمة المعادة**

يعيد Map أو Tuple من مصفوفتين، حيث تحتوي الأولى على المفاتيح بترتيب مرتب، وتحتوي الثانية على القيم المقابلة لهذه المفاتيح. [`Map(K, V)`](/ar/reference/data-types/map) أو [`Tuple(Array(UInt*), Array(Any))`](/ar/reference/data-types/tuple)

**أمثلة**

**باستخدام نوع Map**

```sql title=Query theme={null}
SELECT mapPopulateSeries(map(1, 10, 5, 20), 6)
```

```response title=Response theme={null}
{1:10, 2:0, 3:0, 4:0, 5:20, 6:0}
```

**مع المصفوفات المُحوَّلة**

```sql title=Query theme={null}
SELECT mapPopulateSeries([1, 2, 4], [11, 22, 44], 5)
```

```response title=Response theme={null}
([1, 2, 3, 4, 5], [11, 22, 0, 44, 0])
```

<div id="mapReverseSort">
  ## mapReverseSort
</div>

أُضيفت في: v23.4.0

ترتّب عناصر `map` ترتيبًا تنازليًا.
إذا جرى تحديد الدالة `func`، فيُحدَّد ترتيب الفرز وفقًا لنتيجة تطبيق الدالة `func` على مفاتيح `map` وقيمها.

**البنية**

```sql theme={null}
mapReverseSort([func,] map)
```

**الوسيطات**

* `func` — اختياري. دالة لامبدا. [`Lambda function`](/ar/reference/functions/regular-functions/overview#arrow-operator-and-lambda)
* `map` — قيمة `Map` المطلوب فرزها. [`Map(K, V)`](/ar/reference/data-types/map)

**القيمة المعادة**

تعيد قيمة `Map` مفروزة بترتيب تنازلي. [`Map(K, V)`](/ar/reference/data-types/map)

**أمثلة**

**مثال على الاستخدام**

```sql title=Query theme={null}
SELECT mapReverseSort((k, v) -> v, map('k1', 3, 'k2', 1, 'k3', 2))
```

```response title=Response theme={null}
{'k1':3,'k3':2,'k2':1}
```

<div id="mapSort">
  ## mapSort
</div>

أُضيف في: v23.4.0

يرتّب عناصر الـ Map بترتيب تصاعدي.
إذا جرى تحديد الدالة func، فيتحدد ترتيب الفرز وفقًا لنتيجة الدالة func المطبَّقة على مفاتيح الـ Map وقيمه.

**البنية**

```sql theme={null}
mapSort([func,] map)
```

**الوسائط**

* `func` — اختياري. دالة لامبدا. [`دالة لامبدا`](/ar/reference/functions/regular-functions/overview#arrow-operator-and-lambda)
* `map` — قيمة Map المراد فرزها. [`Map(K, V)`](/ar/reference/data-types/map)

**القيمة المُعادة**

يعيد قيمة Map مفروزة بترتيب تصاعدي. [`Map(K, V)`](/ar/reference/data-types/map)

**أمثلة**

**مثال على الاستخدام**

```sql title=Query theme={null}
SELECT mapSort((k, v) -> v, map('k1', 3, 'k2', 1, 'k3', 2))
```

```response title=Response theme={null}
{'k2':1,'k3':2,'k1':3}
```

<div id="mapSubtract">
  ## mapSubtract
</div>

قُدِّمت في: v20.7.0

اجمع كل المفاتيح واطرح القيم المقابلة.

**الصيغة**

```sql theme={null}
mapSubtract(arg1[, arg2, ...])
```

**الوسيطات**

* `arg1[, arg2, ...]` — خرائط أو قيم من نوع Tuple مكوّنة من مصفوفتين، حيث تمثل عناصر المصفوفة الأولى المفاتيح، بينما تحتوي المصفوفة الثانية على القيم المقابلة لكل مفتاح. [`Map(K, V)`](/ar/reference/data-types/map) أو [`Tuple(Array(T), Array(T))`](/ar/reference/data-types/tuple)

**القيمة المعادة**

تعيد خريطة واحدة أو قيمة من نوع Tuple، حيث تحتوي المصفوفة الأولى على المفاتيح المرتبة، وتحتوي المصفوفة الثانية على القيم. [`Map(K, V)`](/ar/reference/data-types/map) أو [`Tuple(Array(T), Array(T))`](/ar/reference/data-types/tuple)

**أمثلة**

**مع نوع Map**

```sql title=Query theme={null}
SELECT mapSubtract(map(1, 1), map(1, 1))
```

```response title=Response theme={null}
{1:0}
```

**باستخدام map من النوع Tuple**

```sql title=Query theme={null}
SELECT mapSubtract(([toUInt8(1), 2], [toInt32(1), 1]), ([toUInt8(1), 2], [toInt32(2), 1]))
```

```response title=Response theme={null}
([1, 2], [-1, 0])
```

<div id="mapUpdate">
  ## mapUpdate
</div>

أُضيفت في: v22.3.0

بالنسبة إلى قيمتَي Map، تُرجِع الدالة قيمة Map الأولى بعد تحديث قيمها بقيم المفاتيح المناظرة في قيمة Map الثانية.

**الصيغة**

```sql theme={null}
mapUpdate(map1, map2)
```

**الوسيطات**

* `map1` — الخريطة المراد تحديثها. [`Map(K, V)`](/ar/reference/data-types/map)
* `map2` — الخريطة المُستخدمة في التحديث. [`Map(K, V)`](/ar/reference/data-types/map)

**القيمة المُعادة**

يُرجع `map1` بعد تحديث قيمه بالقيم المرتبطة بالمفاتيح المناظرة في `map2`. [`Map(K, V)`](/ar/reference/data-types/map)

**أمثلة**

**الاستخدام الأساسي**

```sql title=Query theme={null}
SELECT mapUpdate(map('key1', 0, 'key3', 0), map('key1', 10, 'key2', 10))
```

```response title=Response theme={null}
{'key3':0,'key1':10,'key2':10}
```

<div id="mapValues">
  ## mapValues
</div>

قُدِّمت في: v21.2.0

تعيد هذه الدالة قيم Map معيّن.
يمكن تحسين هذه الدالة عبر تفعيل الإعداد [`optimize_functions_to_subcolumns`](/ar/reference/settings/session-settings#optimize_functions_to_subcolumns).
عند تفعيل هذا الإعداد، لا تقرأ الدالة سوى العمود الفرعي `values` بدلًا من قراءة الـ Map بالكامل.
يُحوَّل الاستعلام `SELECT mapValues(m) FROM table` إلى `SELECT m.values FROM table`.

**بناء الجملة**

```sql theme={null}
mapValues(map)
```

**الوسائط**

* `map` — كائن Map لاستخراج القيم منه. [`Map(K, V)`](/ar/reference/data-types/map)

**القيمة المُعادة**

يُعيد مصفوفة تحتوي على جميع القيم من الـ Map. [`Array(T)`](/ar/reference/data-types/array)

**أمثلة**

**مثال على الاستخدام**

```sql title=Query theme={null}
SELECT mapValues(map('k1', 'v1', 'k2', 'v2'))
```

```response title=Response theme={null}
['v1','v2']
```