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

> توثيق دوال العمل مع القواميس المضمنة

# دوال العمل مع القواميس المضمنة

<Note>
  لكي تعمل الدوال أدناه، يجب أن تحدد إعدادات الخادم المسارات والعناوين اللازمة للوصول إلى جميع القواميس المضمنة. تُحمَّل القواميس عند أول استدعاء لأيٍ من هذه الدوال. وإذا تعذر تحميل القوائم المرجعية، فسيُطلق استثناء.

  لذلك، فإن الأمثلة الواردة في هذا القسم ستُطلق استثناءً في [ClickHouse Fiddle](https://fiddle.clickhouse.com/) وفي عمليات النشر السريعة وبيئات الإنتاج افتراضيًا، ما لم يتم إعدادها مسبقًا.
</Note>

للحصول على معلومات حول إنشاء القوائم المرجعية، راجع قسم ["القواميس"](/ar/reference/statements/create/dictionary/embedded).

<div id="multiple-geobases">
  ## قواعد جغرافية متعددة
</div>

يدعم ClickHouse العمل مع عدة قواعد جغرافية بديلة (تسلسلات هرمية إقليمية) في الوقت نفسه، لدعم وجهات نظر مختلفة بشأن البلدان التي تنتمي إليها مناطق معيّنة.

يحدّد config الخاص بـ 'clickhouse-server' الملف الذي يحتوي على التسلسل الهرمي للمناطق:

`<path_to_regions_hierarchy_file>/opt/geo/regions_hierarchy.txt</path_to_regions_hierarchy_file>`

وبالإضافة إلى هذا الملف، يبحث أيضًا عن ملفات مجاورة تحتوي على الرمز `_` وأي لاحقة مضافة إلى الاسم (قبل امتداد الملف).
فعلى سبيل المثال، سيعثر أيضًا على الملف `/opt/geo/regions_hierarchy_ua.txt` إذا كان موجودًا. وهنا يُسمّى `ua` مفتاح القاموس. أما القاموس الذي لا يحتوي على لاحقة، فيكون مفتاحه سلسلة فارغة.

تُعاد تحميل جميع القواميس أثناء وقت التشغيل (مرة كل عدد معيّن من الثواني، كما هو محدد في parameter إعدادات [`builtin_dictionaries_reload_interval`](/ar/reference/settings/server-settings/settings#builtin_dictionaries_reload_interval)، أو مرة واحدة كل ساعة افتراضيًا). ومع ذلك، لا تُحدَّد قائمة القواميس المتاحة إلا مرة واحدة عند بدء تشغيل الخادم.

تحتوي جميع الدوال الخاصة بالعمل مع المناطق على argument اختياري في النهاية — وهو مفتاح القاموس. ويُشار إليه باسم القاعدة الجغرافية.

مثال:

```sql theme={null}
regionToCountry(RegionID) – Uses the default dictionary: /opt/geo/regions_hierarchy.txt
regionToCountry(RegionID, '') – Uses the default dictionary: /opt/geo/regions_hierarchy.txt
regionToCountry(RegionID, 'ua') – Uses the dictionary for the 'ua' key: /opt/geo/regions_hierarchy_ua.txt
```

### regionToName

يقبل معرّف المنطقة وgeobase ويُرجع سلسلة نصية تحتوي على اسم المنطقة باللغة المقابلة. وإذا لم تكن المنطقة ذات المعرّف المحدد موجودة، فستُرجع سلسلة نصية فارغة.

**البنية**

```sql theme={null}
regionToName(id\[, lang\])
```

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

* `id` — معرّف المنطقة من `geobase`. [UInt32](/ar/reference/data-types/int-uint).
* `geobase` — مفتاح القاموس. راجع [قواعد geobase متعددة](#multiple-geobases). [String](/ar/reference/data-types/string). اختياري.

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

* اسم المنطقة باللغة المقابلة التي يحددها `geobase`. [String](/ar/reference/data-types/string).
* وإلا، سلسلة فارغة.

**مثال**

```sql title="Query" theme={null}
SELECT regionToName(number::UInt32,'en') FROM numbers(0,5);
```

```text title="Response" theme={null}
┌─regionToName(CAST(number, 'UInt32'), 'en')─┐
│                                            │
│ World                                      │
│ USA                                        │
│ Colorado                                   │
│ Boulder County                             │
└────────────────────────────────────────────┘
```

### regionToCity

يقبل معرّف منطقة من `geobase`. إذا كانت هذه المنطقة مدينةً أو جزءًا من مدينة، فإنه يعيد معرّف المنطقة للمدينة المعنية. وإلا، فإنه يعيد 0.

**الصيغة**

```sql theme={null}
regionToCity(id [, geobase])
```

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

* `id` — معرّف المنطقة من geobase. [UInt32](/ar/reference/data-types/int-uint).
* `geobase` — مفتاح القاموس. راجع [قواعد geobase متعددة](#multiple-geobases). [String](/ar/reference/data-types/string). اختياري.

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

* معرّف المنطقة للمدينة المناسبة، إن وُجدت. [UInt32](/ar/reference/data-types/int-uint).
* 0، إذا لم توجد أيّ مدينة.

**مثال**

```sql title="Query" theme={null}
SELECT regionToName(number::UInt32, 'en'), regionToCity(number::UInt32) AS id, regionToName(id, 'en') FROM numbers(13);
```

```response title="Response" theme={null}
┌─regionToName(CAST(number, 'UInt32'), 'en')─┬─id─┬─regionToName(regionToCity(CAST(number, 'UInt32')), 'en')─┐
│                                            │  0 │                                                          │
│ World                                      │  0 │                                                          │
│ USA                                        │  0 │                                                          │
│ Colorado                                   │  0 │                                                          │
│ Boulder County                             │  0 │                                                          │
│ Boulder                                    │  5 │ Boulder                                                  │
│ China                                      │  0 │                                                          │
│ Sichuan                                    │  0 │                                                          │
│ Chengdu                                    │  8 │ Chengdu                                                  │
│ America                                    │  0 │                                                          │
│ North America                              │  0 │                                                          │
│ Eurasia                                    │  0 │                                                          │
│ Asia                                       │  0 │                                                          │
└────────────────────────────────────────────┴────┴──────────────────────────────────────────────────────────┘
```

### regionToArea

يحوّل إقليمًا إلى منطقة (النوع 5 في geobase). وفي جميع الجوانب الأخرى، تكون هذه الدالة مماثلة للدالة ['regionToCity'](#regiontocity).

**البنية**

```sql theme={null}
regionToArea(id [, geobase])
```

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

* `id` — معرّف المنطقة من geobase. [UInt32](/ar/reference/data-types/int-uint).
* `geobase` — مفتاح القاموس. راجع [عدة geobases](#multiple-geobases). [String](/ar/reference/data-types/string). اختياري.

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

* معرّف المنطقة الخاص بالمنطقة المناسبة، إن وُجدت. [UInt32](/ar/reference/data-types/int-uint).
* 0 إذا لم توجد.

**مثال**

```sql title="Query" theme={null}
SELECT DISTINCT regionToName(regionToArea(toUInt32(number), 'ua'))
FROM system.numbers
LIMIT 15
```

```text title="Response" theme={null}
┌─regionToName(regionToArea(toUInt32(number), \'ua\'))─┐
│                                                      │
│ Moscow and Moscow region                             │
│ St. Petersburg and Leningrad region                  │
│ Belgorod region                                      │
│ Ivanovsk region                                      │
│ Kaluga region                                        │
│ Kostroma region                                      │
│ Kursk region                                         │
│ Lipetsk region                                       │
│ Orlov region                                         │
│ Ryazan region                                        │
│ Smolensk region                                      │
│ Tambov region                                        │
│ Tver region                                          │
│ Tula region                                          │
└──────────────────────────────────────────────────────┘
```

### regionToDistrict

يحوّل إقليمًا إلى دائرة اتحادية (النوع 4 في geobase). وفيما عدا ذلك، فهذه الدالة مطابقة للدالة 'regionToCity'.

**الصيغة**

```sql theme={null}
regionToDistrict(id [, geobase])
```

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

* `id` — معرّف المنطقة من geobase. [UInt32](/ar/reference/data-types/int-uint).
* `geobase` — مفتاح القاموس. راجع [geobase متعددة](#multiple-geobases). [String](/ar/reference/data-types/string). اختياري.

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

* معرّف المنطقة للمدينة المقابلة، إن وُجدت. [UInt32](/ar/reference/data-types/int-uint).
* 0، إذا لم توجد.

**مثال**

```sql title="Query" theme={null}
SELECT DISTINCT regionToName(regionToDistrict(toUInt32(number), 'ua'))
FROM system.numbers
LIMIT 15
```

```text title="Response" theme={null}
┌─regionToName(regionToDistrict(toUInt32(number), \'ua\'))─┐
│                                                          │
│ Central federal district                                 │
│ Northwest federal district                               │
│ South federal district                                   │
│ North Caucases federal district                          │
│ Privolga federal district                                │
│ Ural federal district                                    │
│ Siberian federal district                                │
│ Far East federal district                                │
│ Scotland                                                 │
│ Faroe Islands                                            │
│ Flemish region                                           │
│ Brussels capital region                                  │
│ Wallonia                                                 │
│ Federation of Bosnia and Herzegovina                     │
└──────────────────────────────────────────────────────────┘
```

### regionToCountry

يحوّل منطقة إلى بلد (النوع 3 في geobase). وفي جميع الجوانب الأخرى، تكون هذه الدالة مماثلة للدالة 'regionToCity'.

**الصيغة**

```sql theme={null}
regionToCountry(id [, geobase])
```

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

* `id` — معرّف المنطقة من geobase. [UInt32](/ar/reference/data-types/int-uint).
* `geobase` — مفتاح القاموس. راجع [قواعد geobase المتعددة](#multiple-geobases). [String](/ar/reference/data-types/string). اختياري.

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

* معرّف المنطقة للبلد المقابل، إذا وُجد. [UInt32](/ar/reference/data-types/int-uint).
* 0 إذا لم توجد قيمة.

**مثال**

```sql title="Query" theme={null}
SELECT regionToName(number::UInt32, 'en'), regionToCountry(number::UInt32) AS id, regionToName(id, 'en') FROM numbers(13);
```

```text title="Response" theme={null}
┌─regionToName(CAST(number, 'UInt32'), 'en')─┬─id─┬─regionToName(regionToCountry(CAST(number, 'UInt32')), 'en')─┐
│                                            │  0 │                                                             │
│ World                                      │  0 │                                                             │
│ USA                                        │  2 │ USA                                                         │
│ Colorado                                   │  2 │ USA                                                         │
│ Boulder County                             │  2 │ USA                                                         │
│ Boulder                                    │  2 │ USA                                                         │
│ China                                      │  6 │ China                                                       │
│ Sichuan                                    │  6 │ China                                                       │
│ Chengdu                                    │  6 │ China                                                       │
│ America                                    │  0 │                                                             │
│ North America                              │  0 │                                                             │
│ Eurasia                                    │  0 │                                                             │
│ Asia                                       │  0 │                                                             │
└────────────────────────────────────────────┴────┴─────────────────────────────────────────────────────────────┘
```

### regionToContinent

يحوّل منطقة إلى قارة (النوع 1 في geobase). وفيما عدا ذلك، فهذه الدالة مماثلة للدالة 'regionToCity'.

**الصيغة**

```sql theme={null}
regionToContinent(id [, geobase])
```

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

* `id` — معرّف المنطقة من geobase. [UInt32](/ar/reference/data-types/int-uint).
* `geobase` — مفتاح القاموس. راجع [قواعد geobase المتعددة](#multiple-geobases). [String](/ar/reference/data-types/string). اختياري.

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

* معرّف المنطقة للقارة المقابلة، إن وُجد. [UInt32](/ar/reference/data-types/int-uint).
* 0 إذا لم يوجد.

**مثال**

```sql title="Query" theme={null}
SELECT regionToName(number::UInt32, 'en'), regionToContinent(number::UInt32) AS id, regionToName(id, 'en') FROM numbers(13);
```

```text title="Response" theme={null}
┌─regionToName(CAST(number, 'UInt32'), 'en')─┬─id─┬─regionToName(regionToContinent(CAST(number, 'UInt32')), 'en')─┐
│                                            │  0 │                                                               │
│ World                                      │  0 │                                                               │
│ USA                                        │ 10 │ North America                                                 │
│ Colorado                                   │ 10 │ North America                                                 │
│ Boulder County                             │ 10 │ North America                                                 │
│ Boulder                                    │ 10 │ North America                                                 │
│ China                                      │ 12 │ Asia                                                          │
│ Sichuan                                    │ 12 │ Asia                                                          │
│ Chengdu                                    │ 12 │ Asia                                                          │
│ America                                    │  9 │ America                                                       │
│ North America                              │ 10 │ North America                                                 │
│ Eurasia                                    │ 11 │ Eurasia                                                       │
│ Asia                                       │ 12 │ Asia                                                          │
└────────────────────────────────────────────┴────┴───────────────────────────────────────────────────────────────┘
```

### regionToTopContinent

تُرجِع أعلى قارة في التسلسل الهرمي للمنطقة.

**الصيغة**

```sql theme={null}
regionToTopContinent(id[, geobase])
```

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

* `id` — معرّف المنطقة من geobase. [UInt32](/ar/reference/data-types/int-uint).
* `geobase` — مفتاح القاموس. راجع [قواعد geobase المتعددة](#multiple-geobases). [String](/ar/reference/data-types/string). اختياري.

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

* معرّف القارة في أعلى مستوى (أي الأخيرة عند الصعود في التسلسل الهرمي للمناطق). [UInt32](/ar/reference/data-types/int-uint).
* 0 إذا لم تكن موجودة.

**مثال**

```sql title="Query" theme={null}
SELECT regionToName(number::UInt32, 'en'), regionToTopContinent(number::UInt32) AS id, regionToName(id, 'en') FROM numbers(13);
```

```text title="Response" theme={null}
┌─regionToName(CAST(number, 'UInt32'), 'en')─┬─id─┬─regionToName(regionToTopContinent(CAST(number, 'UInt32')), 'en')─┐
│                                            │  0 │                                                                  │
│ World                                      │  0 │                                                                  │
│ USA                                        │  9 │ America                                                          │
│ Colorado                                   │  9 │ America                                                          │
│ Boulder County                             │  9 │ America                                                          │
│ Boulder                                    │  9 │ America                                                          │
│ China                                      │ 11 │ Eurasia                                                          │
│ Sichuan                                    │ 11 │ Eurasia                                                          │
│ Chengdu                                    │ 11 │ Eurasia                                                          │
│ America                                    │  9 │ America                                                          │
│ North America                              │  9 │ America                                                          │
│ Eurasia                                    │ 11 │ Eurasia                                                          │
│ Asia                                       │ 11 │ Eurasia                                                          │
└────────────────────────────────────────────┴────┴──────────────────────────────────────────────────────────────────┘
```

### regionToPopulation

يجلب عدد سكان منطقة ما. يمكن أن يكون عدد السكان مسجّلًا في الملفات ضمن geobase. راجع قسم ["القواميس"](/ar/reference/statements/create/dictionary/embedded). إذا لم يكن عدد السكان مسجّلًا للمنطقة، فستُرجِع 0. في geobase، قد يكون عدد السكان مسجّلًا للمناطق الفرعية، ولكن ليس للمناطق الأم.

**الصياغة**

```sql theme={null}
regionToPopulation(id[, geobase])
```

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

* `id` — معرّف المنطقة من geobase. [UInt32](/ar/reference/data-types/int-uint).
* `geobase` — مفتاح القاموس. راجع [Multiple Geobases](#multiple-geobases). [String](/ar/reference/data-types/string). اختياري.

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

* عدد سكان المنطقة. [UInt32](/ar/reference/data-types/int-uint).
* 0 إذا لم تكن هناك قيمة.

**مثال**

```sql title="Query" theme={null}
SELECT regionToName(number::UInt32, 'en'), regionToPopulation(number::UInt32) AS id, regionToName(id, 'en') FROM numbers(13);
```

```text title="Response" theme={null}
┌─regionToName(CAST(number, 'UInt32'), 'en')─┬─population─┐
│                                            │          0 │
│ World                                      │ 4294967295 │
│ USA                                        │  330000000 │
│ Colorado                                   │    5700000 │
│ Boulder County                             │     330000 │
│ Boulder                                    │     100000 │
│ China                                      │ 1500000000 │
│ Sichuan                                    │   83000000 │
│ Chengdu                                    │   20000000 │
│ America                                    │ 1000000000 │
│ North America                              │  600000000 │
│ Eurasia                                    │ 4294967295 │
│ Asia                                       │ 4294967295 │
└────────────────────────────────────────────┴────────────┘
```

### regionIn

يتحقق مما إذا كانت المنطقة `lhs` تندرج ضمن المنطقة `rhs`. ويُرجع قيمة من نوع UInt8 تساوي 1 إذا كانت كذلك، أو 0 إذا لم تكن كذلك.

**الصيغة**

```sql theme={null}
regionIn(lhs, rhs\[, geobase\])
```

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

* `lhs` — معرّف المنطقة Lhs من geobase. [UInt32](/ar/reference/data-types/int-uint).
* `rhs` — معرّف المنطقة Rhs من geobase. [UInt32](/ar/reference/data-types/int-uint).
* `geobase` — مفتاح القاموس. راجع [قواعد جغرافية متعددة](#multiple-geobases). [String](/ar/reference/data-types/string). اختياري.

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

* 1، إذا كانت تابعة لها. [UInt8](/ar/reference/data-types/int-uint).
* 0، إذا لم تكن تابعة لها.

**تفاصيل التنفيذ**

العلاقة انعكاسية — أي منطقة تنتمي أيضًا إلى نفسها.

**مثال**

```sql title="Query" theme={null}
SELECT regionToName(n1.number::UInt32, 'en') || (regionIn(n1.number::UInt32, n2.number::UInt32) ? ' is in ' : ' is not in ') || regionToName(n2.number::UInt32, 'en') FROM numbers(1,2) AS n1 CROSS JOIN numbers(1,5) AS n2;
```

```text title="Response" theme={null}
World is in World
World is not in USA
World is not in Colorado
World is not in Boulder County
World is not in Boulder
USA is in World
USA is in USA
USA is not in Colorado
USA is not in Boulder County
USA is not in Boulder    
```

### regionHierarchy

يقبل رقمًا من نوع UInt32، وهو معرّف المنطقة من geobase. ويُرجع مصفوفة من معرّفات المناطق تضمّ المنطقة المُمرَّرة وجميع المناطق الأعلى منها في التسلسل الهرمي.

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

```sql theme={null}
regionHierarchy(id\[, geobase\])
```

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

* `id` — معرّف المنطقة من geobase. [UInt32](/ar/reference/data-types/int-uint).
* `geobase` — مفتاح القاموس. راجع [Multiple Geobases](#multiple-geobases). [String](/ar/reference/data-types/string). اختياري.

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

* مصفوفة من معرّفات المناطق تضم المنطقة المُمرَّرة وجميع المناطق الأصلية في السلسلة. [Array](/ar/reference/data-types/array)([UInt32](/ar/reference/data-types/int-uint)).

**مثال**

```sql title="Query" theme={null}
SELECT regionHierarchy(number::UInt32) AS arr, arrayMap(id -> regionToName(id, 'en'), arr) FROM numbers(5);
```

```text title="Response" theme={null}
┌─arr────────────┬─arrayMap(lambda(tuple(id), regionToName(id, 'en')), regionHierarchy(CAST(number, 'UInt32')))─┐
│ []             │ []                                                                                           │
│ [1]            │ ['World']                                                                                    │
│ [2,10,9,1]     │ ['USA','North America','America','World']                                                    │
│ [3,2,10,9,1]   │ ['Colorado','USA','North America','America','World']                                         │
│ [4,3,2,10,9,1] │ ['Boulder County','Colorado','USA','North America','America','World']                        │
└────────────────┴──────────────────────────────────────────────────────────────────────────────────────────────┘
```

{/*AUTOGENERATED_START*/}