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

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

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

لذلك، فإن الأمثلة الواردة في هذا القسم ستُطلق استثناءً في ClickHouse Fiddle وفي عمليات النشر السريعة وبيئات الإنتاج افتراضيًا، ما لم يتم إعدادها مسبقًا.

للحصول على معلومات حول إنشاء القوائم المرجعية، راجع قسم “القواميس”.

​

قواعد جغرافية متعددة

يدعم 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، أو مرة واحدة كل ساعة افتراضيًا). ومع ذلك، لا تُحدَّد قائمة القواميس المتاحة إلا مرة واحدة عند بدء تشغيل الخادم.

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

مثال:

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 ويُرجع سلسلة نصية تحتوي على اسم المنطقة باللغة المقابلة. وإذا لم تكن المنطقة ذات المعرّف المحدد موجودة، فستُرجع سلسلة نصية فارغة.

البنية

regionToName(id\[, lang\])

المعلمات

• id — معرّف المنطقة من geobase. UInt32.
• geobase — مفتاح القاموس. راجع قواعد geobase متعددة. String. اختياري.

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

• اسم المنطقة باللغة المقابلة التي يحددها geobase. String.
• وإلا، سلسلة فارغة.

مثال

Query

SELECT regionToName(number::UInt32,'en') FROM numbers(0,5);

Response

┌─regionToName(CAST(number, 'UInt32'), 'en')─┐
│                                            │
│ World                                      │
│ USA                                        │
│ Colorado                                   │
│ Boulder County                             │
└────────────────────────────────────────────┘

​

regionToCity

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

الصيغة

regionToCity(id [, geobase])

المعلمات

• id — معرّف المنطقة من geobase. UInt32.
• geobase — مفتاح القاموس. راجع قواعد geobase متعددة. String. اختياري.

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

• معرّف المنطقة للمدينة المناسبة، إن وُجدت. UInt32.
• 0، إذا لم توجد أيّ مدينة.

مثال

Query

SELECT regionToName(number::UInt32, 'en'), regionToCity(number::UInt32) AS id, regionToName(id, 'en') FROM numbers(13);

Response

┌─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’.

البنية

regionToArea(id [, geobase])

المعلمات

• id — معرّف المنطقة من geobase. UInt32.
• geobase — مفتاح القاموس. راجع عدة geobases. String. اختياري.

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

• معرّف المنطقة الخاص بالمنطقة المناسبة، إن وُجدت. UInt32.
• 0 إذا لم توجد.

مثال

Query

SELECT DISTINCT regionToName(regionToArea(toUInt32(number), 'ua'))
FROM system.numbers
LIMIT 15

Response

┌─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’.

الصيغة

regionToDistrict(id [, geobase])

المعلمات

• id — معرّف المنطقة من geobase. UInt32.
• geobase — مفتاح القاموس. راجع geobase متعددة. String. اختياري.

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

• معرّف المنطقة للمدينة المقابلة، إن وُجدت. UInt32.
• 0، إذا لم توجد.

مثال

Query

SELECT DISTINCT regionToName(regionToDistrict(toUInt32(number), 'ua'))
FROM system.numbers
LIMIT 15

Response

┌─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’.

الصيغة

regionToCountry(id [, geobase])

المعلمات

• id — معرّف المنطقة من geobase. UInt32.
• geobase — مفتاح القاموس. راجع قواعد geobase المتعددة. String. اختياري.

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

• معرّف المنطقة للبلد المقابل، إذا وُجد. UInt32.
• 0 إذا لم توجد قيمة.

مثال

Query

SELECT regionToName(number::UInt32, 'en'), regionToCountry(number::UInt32) AS id, regionToName(id, 'en') FROM numbers(13);

Response

┌─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’.

الصيغة

regionToContinent(id [, geobase])

المعاملات

• id — معرّف المنطقة من geobase. UInt32.
• geobase — مفتاح القاموس. راجع قواعد geobase المتعددة. String. اختياري.

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

• معرّف المنطقة للقارة المقابلة، إن وُجد. UInt32.
• 0 إذا لم يوجد.

مثال

Query

SELECT regionToName(number::UInt32, 'en'), regionToContinent(number::UInt32) AS id, regionToName(id, 'en') FROM numbers(13);

Response

┌─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

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

الصيغة

regionToTopContinent(id[, geobase])

المعلمات

• id — معرّف المنطقة من geobase. UInt32.
• geobase — مفتاح القاموس. راجع قواعد geobase المتعددة. String. اختياري.

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

• معرّف القارة في أعلى مستوى (أي الأخيرة عند الصعود في التسلسل الهرمي للمناطق). UInt32.
• 0 إذا لم تكن موجودة.

مثال

Query

SELECT regionToName(number::UInt32, 'en'), regionToTopContinent(number::UInt32) AS id, regionToName(id, 'en') FROM numbers(13);

Response

┌─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. راجع قسم “القواميس”. إذا لم يكن عدد السكان مسجّلًا للمنطقة، فستُرجِع 0. في geobase، قد يكون عدد السكان مسجّلًا للمناطق الفرعية، ولكن ليس للمناطق الأم.

الصياغة

regionToPopulation(id[, geobase])

المعاملات

• id — معرّف المنطقة من geobase. UInt32.
• geobase — مفتاح القاموس. راجع Multiple Geobases. String. اختياري.

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

• عدد سكان المنطقة. UInt32.
• 0 إذا لم تكن هناك قيمة.

مثال

Query

SELECT regionToName(number::UInt32, 'en'), regionToPopulation(number::UInt32) AS id, regionToName(id, 'en') FROM numbers(13);

Response

┌─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 إذا لم تكن كذلك.

الصيغة

regionIn(lhs, rhs\[, geobase\])

المعلمات

• lhs — معرّف المنطقة Lhs من geobase. UInt32.
• rhs — معرّف المنطقة Rhs من geobase. UInt32.
• geobase — مفتاح القاموس. راجع قواعد جغرافية متعددة. String. اختياري.

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

• 1، إذا كانت تابعة لها. UInt8.
• 0، إذا لم تكن تابعة لها.

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

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

مثال

Query

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;

Response

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. ويُرجع مصفوفة من معرّفات المناطق تضمّ المنطقة المُمرَّرة وجميع المناطق الأعلى منها في التسلسل الهرمي.

بناء الجملة

regionHierarchy(id\[, geobase\])

المعلمات

• id — معرّف المنطقة من geobase. UInt32.
• geobase — مفتاح القاموس. راجع Multiple Geobases. String. اختياري.

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

• مصفوفة من معرّفات المناطق تضم المنطقة المُمرَّرة وجميع المناطق الأصلية في السلسلة. Array(UInt32).

مثال

Query

SELECT regionHierarchy(number::UInt32) AS arr, arrayMap(id -> regionToName(id, 'en'), arr) FROM numbers(5);

Response

┌─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']                        │
└────────────────┴──────────────────────────────────────────────────────────────────────────────────────────────┘