دوال للعمل مع فهارس H3

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

يُسمّى مستوى هذا التسلسل الهرمي resolution، ويمكن أن يأخذ قيمة من 0 إلى 15، حيث إن 0 هو مستوى base الذي يضم أكبر الخلايا وأقلها دقة.

يمكن تحويل زوج من خط العرض وخط الطول إلى فهرس H3 بطول 64 بت، يحدِّد خلية في الشبكة.

يُستخدم فهرس H3 أساسًا لتجميع المواقع الجغرافية وإجراء المعالجات المكانية الأخرى.

يتوفر الوصف الكامل لنظام H3 على موقع Uber Engineering.

يتحقق مما إذا كان الرقم يمثّل فهرس H3 صالحًا.

البنية

h3IsValid(h3index)

المعلمة

• h3index — رقم فهرس الخلية السداسية. UInt64.

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

• 1 — الرقم فهرس H3 صالح. UInt8.
• 0 — الرقم ليس فهرس H3 صالحًا. UInt8.

مثال

SELECT h3IsValid(630814730351855103) AS h3IsValid;

┌─h3IsValid─┐
│         1 │
└───────────┘

يحدّد مستوى الدقة لفهرس H3 المُعطى.

البنية

h3GetResolution(h3index)

المعلمة

• h3index — رقم فهرس الخلية السداسية. UInt64.

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

• دقة الفهرس. النطاق: [0, 15]. UInt8.
• إذا كان الفهرس غير صالح، فستُرجع الدالة قيمة عشوائية. استخدم h3IsValid للتحقق من صحة الفهرس. UInt8.

مثال

SELECT h3GetResolution(639821929606596015) AS resolution;

┌─resolution─┐
│         14 │
└────────────┘

يحسب متوسط طول ضلع السداسي في H3 بوحدة الغراد.

الصيغة

h3EdgeAngle(resolution)

المعلمة

• resolution — دقة الفهرس. UInt8. النطاق: [0, 15].

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

• متوسط طول ضلع الخلية السداسية H3 بوحدة الغراد. Float64.

مثال

SELECT h3EdgeAngle(10) AS edgeAngle;

┌───────h3EdgeAngle(10)─┐
│ 0.0005927224846720883 │
└───────────────────────┘

يحسب متوسط طول حافة السداسي H3 بالأمتار.

البنية

h3EdgeLengthM(resolution)

المعلمة

• resolution — دقة الفهرس. UInt8. النطاق: [0, 15].

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

• متوسط طول حافة سداسي H3 بالأمتار. Float64.

مثال

SELECT h3EdgeLengthM(15) AS edgeLengthM;

┌─edgeLengthM─┐
│ 0.509713273 │
└─────────────┘

يحسب متوسط طول ضلع الخلية السداسية H3 بالكيلومترات.

الصيغة

h3EdgeLengthKm(resolution)

المعامل

• resolution — دقة الفهرس. UInt8. النطاق: [0, 15].

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

• متوسط طول حافة خلية H3 السداسية بالكيلومترات. Float64.

مثال

SELECT h3EdgeLengthKm(15) AS edgeLengthKm;

┌─edgeLengthKm─┐
│  0.000509713 │
└──────────────┘

يعيد فهرس نقطة H3 للإحداثيات (lat, lon) عند مستوى الدقة المحدد.

الصياغة

geoToH3(lat, lon, resolution)

الوسائط

• lat — خط العرض. Float64.
• lon — خط الطول. Float64.
• resolution — دقة الفهرس. النطاق: [0, 15]. UInt8.

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

• رقم فهرس الخلية السداسية. UInt64.
• 0 في حال حدوث خطأ. UInt64.

ملاحظة: في ClickHouse v25.4 أو الإصدارات الأقدم، تستقبل geoToH3() القيم بالترتيب (lon, lat). واعتبارًا من ClickHouse v25.5، تصبح قيم الإدخال بالترتيب (lat, lon). ويمكن استعادة السلوك السابق باستخدام الإعداد geotoh3_argument_order = 'lon_lat'.

مثال

SELECT geoToH3(55.71290588, 37.79506683, 15) AS h3Index;

┌────────────h3Index─┐
│ 644325524701193974 │
└────────────────────┘

يعيد خطَّي العرض والطول للمركز الهندسي المقابلَين لفهرس H3 المُقدَّم.

الصيغة

h3ToGeo(h3Index)

المعاملات

• h3Index — فهرس H3. UInt64.

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

• Tuple يتكوّن من قيمتين: tuple(lat,lon). ‏lat — خط العرض. Float64. ‏lon — خط الطول. Float64.

ملاحظة: في ClickHouse v24.12 أو الإصدارات الأقدم، تُرجع h3ToGeo() القيم بالترتيب (lon, lat). واعتبارًا من ClickHouse v25.1، تصبح القيم المُعادة بالترتيب (lat, lon). ويمكن استعادة السلوك السابق باستخدام الإعداد h3togeo_lon_lat_result_order = true.

مثال

SELECT h3ToGeo(644325524701193974) AS coordinates;

┌─coordinates───────────────────────────┐
│ (55.71290243145668,37.79506616830252) │
└───────────────────────────────────────┘

يعيد مصفوفة من الأزواج (lat, lon) تمثل حدود فهرس H3 المُدخل.

البنية

h3ToGeoBoundary(h3Index)

الوسائط

• h3Index — H3 Index. UInt64.

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

• Array من الأزواج '(lat, lon)'. (Float64, Float64).

مثال

SELECT h3ToGeoBoundary(644325524701193974) AS coordinates;

┌─h3ToGeoBoundary(599686042433355775)────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ [(37.2713558667319,-121.91508032705622),(37.353926450852256,-121.8622232890249),(37.42834118609435,-121.92354999630156),(37.42012867767779,-122.03773496427027),(37.33755608435299,-122.090428929044),(37.26319797461824,-122.02910130919001)] │
└────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

يسرد جميع سداسيات H3 الواقعة ضمن نطاق نصف القطر k انطلاقًا من السداسي المحدد، بترتيب عشوائي.

الصيغة

h3kRing(h3index, k)

الوسائط

• h3index — رقم فهرس الخلية السداسية. UInt64.
• k — نصف القطر. عدد صحيح

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

• مصفوفة من فهارس H3. مصفوفة(UInt64).

مثال

SELECT arrayJoin(h3kRing(644325529233966508, 1)) AS h3index;

┌────────────h3index─┐
│ 644325529233966508 │
│ 644325529233966497 │
│ 644325529233966510 │
│ 644325529233966504 │
│ 644325529233966509 │
│ 644325529233966355 │
│ 644325529233966354 │
└────────────────────┘

يُرجع السداسيات (عند مستوى الدقة المحدد) الواقعة ضمن الشكل الهندسي المُقدَّم، سواء كان حلقة أو مضلعًا (أو متعدد المضلعات).

البنية

h3PolygonToCells(geometry, resolution)

الوسائط

• يمكن أن تكون geometry أحد أنواع البيانات الجغرافية التالية أو أنواعها الأولية الأساسية:
  • Ring
  • Polygon
  • MultiPolygon
• resolution — دقة الفهرس. النطاق: [0, 15]. UInt8.

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

• مصفوفة من فهارس H3 التي تحتويها. Array(UInt64).

مثال

SELECT h3PolygonToCells([(-122.4089866999972145,37.813318999983238),(-122.3544736999993603,37.7198061999978478),(-122.4798767000009008,37.8151571999998453)], 7) AS h3index;

┌────────────h3index─┐
│ 608692970769612799 │
│ 608692971927240703 │
│ 608692970585063423 │
│ 608692970819944447 │
│ 608692970719281151 │
│ 608692970752835583 │
│ 608692972027903999 │
└────────────────────┘

يعيد الخلايا السداسية (عند مستوى الدقة المحدد) التي تغطي الشكل الهندسي المُدخل، سواء كان حلقة أو مضلعًا (أو متعدد المضلعات)، باستخدام أوضاع الاحتواء التجريبية في H3.

تربط هذه الدالة flags بأوضاع الاحتواء في H3:

• 0 — CONTAINMENT_CENTER
• 1 — CONTAINMENT_FULL
• 2 — CONTAINMENT_OVERLAPPING
• 3 — CONTAINMENT_OVERLAPPING_BBOX

الصيغة

h3PolygonToCellsWithContainment(geometry, resolution, flags)

المعاملات

• يمكن أن تكون geometry أحد أنواع البيانات الجغرافية التالية أو أنواعها الأولية المقابلة:
  • Ring
  • Polygon
  • MultiPolygon
• resolution — دقة الفهرس. النطاق: [0, 15]. ‏UInt8.
• flags — وضع الاحتواء. النطاق: [0, 3]. استخدم ثوابت عددية صحيحة مثل 0 و1 و2 و3، أو قيم UInt32 (على سبيل المثال، toUInt32(2)). تُمرَّر القيم إلى واجهة برمجة تطبيقات H3 بصيغة UInt32. وتُحوَّل أنواع الأعداد الصحيحة الأصلية الأخرى بتحويل دقيق.

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

• مصفوفة من فهارس H3 وفقًا لوضع الاحتواء المحدد. ‏Array(UInt64).

مثال

SELECT
    h3PolygonToCellsWithContainment([(-122.4089866999972145, 37.813318999983238), (-122.3544736999993603, 37.7198061999978478), (-122.4798767000009008, 37.8151571999998453)], 7, 0) AS center_cells,
    h3PolygonToCellsWithContainment([(-122.4089866999972145, 37.813318999983238), (-122.3544736999993603, 37.7198061999978478), (-122.4798767000009008, 37.8151571999998453)], 7, 2) AS overlap_cells;

   ┌─center_cells───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┬─overlap_cells──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
1. │ [608692970585063423,608692970719281151,608692970752835583,608692970769612799,608692970819944447,608692971927240703,608692972027903999] │ [608692970249519103,608692970266296319,608692970585063423,608692970601840639,608692970635395071,608692970685726719,608692970719281151,608692970736058367,608692970752835583,608692970769612799,608692970786390015,608692970819944447,608692971927240703,608692971994349567,608692972027903999] │
   └────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┴────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

يعيد رقم الخلية الأساسية لفهرس H3.

الصياغة

h3GetBaseCell(index)

المعامِل

• index — رقم فهرس الخلية السداسية. UInt64.

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

• رقم الخلية الأساسية للسداسي. UInt8.

مثال

SELECT h3GetBaseCell(612916788725809151) AS basecell;

┌─basecell─┐
│       12 │
└──────────┘

يُرجع متوسط مساحة الخلية السداسية بالمتر المربع عند مستوى الدقة المحدد.

الصيغة

h3HexAreaM2(resolution)

المعامل

• resolution — دقة الفهرس. النطاق: [0, 15]. UInt8.

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

• المساحة بالمتر المربع. Float64.

مثال

SELECT h3HexAreaM2(13) AS area;

┌─area─┐
│ 43.9 │
└──────┘

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

الصيغة

h3HexAreaKm2(resolution)

المعامل

• resolution — دقة الفهرس. النطاق: [0, 15]. UInt8.

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

• المساحة بالكيلومترات المربعة. Float64.

مثال

SELECT h3HexAreaKm2(13) AS area;

┌──────area─┐
│ 0.0000439 │
└───────────┘

يُعيد ما إذا كانت فهارس H3 المعطاة متجاورة أم لا.

البنية

h3IndexesAreNeighbors(index1, index2)

الوسيطات

• index1 — رقم فهرس الخلية السداسية. UInt64.
• index2 — رقم فهرس الخلية السداسية. UInt64.

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

• 1 — الفهرسان متجاوران. UInt8.
• 0 — الفهرسان غير متجاورين. UInt8.

مثال

SELECT h3IndexesAreNeighbors(617420388351344639, 617420388352655359) AS n;

┌─n─┐
│ 1 │
└───┘

تُرجِع مصفوفة من الفهارس الفرعية للفهرس H3 المحدَّد.

الصيغة

h3ToChildren(index, resolution)

الوسيطات

• index — رقم فهرس الخلية السداسية. UInt64.
• resolution — دقة المعرّف. النطاق: [0, 15]. UInt8.

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

• مصفوفة من معرّفات H3 الفرعية. مصفوفة(UInt64).

مثال

SELECT h3ToChildren(599405990164561919, 6) AS children;

┌─children───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ [603909588852408319,603909588986626047,603909589120843775,603909589255061503,603909589389279231,603909589523496959,603909589657714687] │
└────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

يعيد الفهرس الأب (الأقل دقة) الذي يحتوي على فهرس H3 المحدد.

البنية

h3ToParent(index, resolution)

الوسائط

• index — رقم فهرس الخلية السداسية. UInt64.
• resolution — دقة الفهرس. النطاق: [0, 15]. UInt8.

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

• فهرس H3 الأب. UInt64.

مثال

SELECT h3ToParent(599405990164561919, 3) AS parent;

┌─────────────parent─┐
│ 590398848891879423 │
└────────────────────┘

يحوّل تمثيل H3Index الخاص بالفهرس إلى تمثيله النصي.

h3ToString(index)

المعامل

• index — رقم فهرس الخلية السداسية. UInt64.

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

• التمثيل النصي لفهرس H3. String.

مثال

SELECT h3ToString(617420388352917503) AS h3_string;

┌─h3_string───────┐
│ 89184926cdbffff │
└─────────────────┘

يحوّل التمثيل النصي إلى تمثيل H3Index ‏(UInt64).

البنية

stringToH3(index_str)

المعامل

• index_str — التمثيل النصي لفهرس H3. سلسلة.

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

• رقم فهرس الخلية السداسية. تُرجع القيمة 0 عند حدوث خطأ. UInt64.

مثال

SELECT stringToH3('89184926cc3ffff') AS index;

┌──────────────index─┐
│ 617420388351344639 │
└────────────────────┘

يعيد مستوى الدقة لفهرس H3.

الصيغة

h3GetResolution(index)

المعامل

• index — رقم فهرس الخلية السداسية. UInt64.

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

• مستوى دقة الفهرس. النطاق: [0, 15]. UInt8.

مثال

SELECT h3GetResolution(617420388352917503) AS res;

┌─res─┐
│   9 │
└─────┘

تُرجِع ما إذا كان لفهرس H3 درجة دقة ذات اتجاه من الفئة III.

البنية

h3IsResClassIII(index)

المعامل

• index — رقم فهرس الخلية السداسية. UInt64.

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

• 1 — للفهرس مستوى دقة ذو اتجاه من الفئة III. UInt8.
• 0 — ليس للفهرس مستوى دقة ذو اتجاه من الفئة III. UInt8.

مثال

SELECT h3IsResClassIII(617420388352917503) AS res;

┌─res─┐
│   1 │
└─────┘

يُرجع ما إذا كان فهرس H3 هذا يمثّل خلية خماسية الأضلاع.

الصياغة

h3IsPentagon(index)

المعلمة

• index — رقم فهرس الخلية السداسية. UInt64.

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

• 1 — يمثّل الفهرس خلية خماسية الأضلاع. UInt8.
• 0 — لا يمثّل الفهرس خلية خماسية الأضلاع. UInt8.

مثال

SELECT h3IsPentagon(644721767722457330) AS pentagon;

┌─pentagon─┐
│        0 │
└──────────┘

يعيد أوجه عشروني السطوح التي يتقاطع معها مؤشر H3 معيّن.

الصيغة

h3GetFaces(index)

المعلمة

• index — رقم فهرس الخلية السداسية. UInt64.

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

• مصفوفة تحتوي على أوجه المجسّم عشرونيّ الوجوه التي يتقاطع معها فهرس H3 معيّن. Array(UInt64).

مثال

SELECT h3GetFaces(599686042433355775) AS faces;

┌─faces─┐
│ [7]   │
└───────┘

تُرجِع المساحة الدقيقة، بالمتر المربع، لخلية محددة تقابل قيمة H3 index المُدخلة.

الصيغة

h3CellAreaM2(index)

المعامل

• index — رقم فهرس الخلية السداسية. UInt64.

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

• مساحة الخلية بالأمتار المربعة. Float64.

مثال

SELECT h3CellAreaM2(579205133326352383) AS area;

┌───────────────area─┐
│ 4106166334463.9233 │
└────────────────────┘

يعيد المساحة الدقيقة لخلية محددة، مقاسةً بالراديان المربع، والمطابقة لفهرس H3 المُدخل.

البنية

h3CellAreaRads2(index)

المعامل

• index — رقم فهرس الخلية السداسية. UInt64.

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

• مساحة الخلية بوحدة الراديان المربّع. Float64.

مثال

SELECT h3CellAreaRads2(579205133326352383) AS area;

┌────────────────area─┐
│ 0.10116268528089567 │
└─────────────────────┘

تُرجِع فهرس H3 الابن المركزي (الأدق) الواقع ضمن فهرس H3 المُعطى عند درجة الدقة المحددة.

الصياغة

h3ToCenterChild(index, resolution)

المعامل

• index — رقم فهرس الخلية السداسية. UInt64.
• resolution — دقة الفهرس. النطاق: [0, 15]. UInt8.

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

• فهرس H3 للخلية الفرعية المركزية الواقعة ضمن فهرس H3 المحدد عند درجة الدقة المعطاة. UInt64.

مثال

SELECT h3ToCenterChild(577023702256844799,1) AS centerToChild;

┌──────centerToChild─┐
│ 581496515558637567 │
└────────────────────┘

يعيد الطول الدقيق للحافة أحادية الاتجاه التي يمثّلها فهرس H3 المُدخل، بالأمتار.

الصيغة

h3ExactEdgeLengthM(index)

معلمة

• index — رقم فهرس الخلية السداسية. UInt64.

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

• الطول الدقيق للحافة بالأمتار. Float64.

مثال

SELECT round(h3ExactEdgeLengthM(1310277011704381439), 6) AS exactEdgeLengthM;

┌─exactEdgeLengthM─┐
│    195449.631634 │
└──────────────────┘

يُرجِع الطول الدقيق للحافة أحادية الاتجاه التي يمثّلها فهرس H3 المُدخَل، بالكيلومترات.

صيغة

h3ExactEdgeLengthKm(index)

معلمة

• index — رقم فهرس الخلية السداسية. UInt64.

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

• الطول الدقيق للحافة بالكيلومترات. Float64.

مثال

SELECT round(h3ExactEdgeLengthKm(1310277011704381439), 8) AS exactEdgeLengthKm;

┌─exactEdgeLengthKm─┐
│      195.44963163 │
└───────────────────┘

تعيد الطول الدقيق للحافة أحادية الاتجاه التي يمثّلها فهرس h3 المُدخل، بالراديان.

الصيغة

h3ExactEdgeLengthRads(index)

معلمة

• index — رقم فهرس الخلية السداسية. UInt64.

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

• الطول الدقيق للحافة بالراديان. Float64.

مثال

SELECT round(h3ExactEdgeLengthRads(1310277011704381439), 12) AS exactEdgeLengthRads;

┌─exactEdgeLengthRads─┐
│      0.030677980119 │
└─────────────────────┘

يعيد عدد فهارس H3 الفريدة عند مستوى الدقة المحدد.

الصياغة

h3NumHexagons(resolution)

المعامل

• resolution — دقة الفهرس. النطاق: [0, 15]. UInt8.

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

• عدد فهارس H3. Int64.

مثال

SELECT h3NumHexagons(3) AS numHexagons;

┌─numHexagons─┐
│       41162 │
└─────────────┘

تعيد مسافة "الدائرة العظمى" أو "هافرسين" بين كل زوج من نقاط GeoCoord ‏(خط العرض/خط الطول)، بالمتر.

صيغة

h3PointDistM(lat1, lon1, lat2, lon2)

الوسائط

• lat1, lon1 — خط العرض وخط الطول للنقطة 1 بالدرجات. Float64.
• lat2, lon2 — خط العرض وخط الطول للنقطة 2 بالدرجات. Float64.

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

• مسافة هافرسين أو مسافة الدائرة العظمى بالأمتار.Float64.

مثال

SELECT h3PointDistM(-10.0 ,0.0, 10.0, 0.0) AS h3PointDistM;

┌───────h3PointDistM─┐
│ 2223901.0395045886 │
└────────────────────┘

يعيد مسافة "الدائرة العظمى" أو مسافة "هافرسين" بين أزواج من نقاط GeoCoord (خط العرض/خط الطول) بالكيلومترات.

صيغة

h3PointDistKm(lat1, lon1, lat2, lon2)

وسيط

• lat1, lon1 — خط العرض وخط الطول للنقطة 1 بالدرجات. Float64.
• lat2, lon2 — خط العرض وخط الطول للنقطة 2 بالدرجات. Float64.

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

• مسافة هافرسين أو مسافة الدائرة العظمى بالكيلومترات. Float64.

مثال

SELECT h3PointDistKm(-10.0 ,0.0, 10.0, 0.0) AS h3PointDistKm;

┌──────h3PointDistKm─┐
│ 2223.9010395045884 │
└────────────────────┘

تعيد مسافة "الدائرة العظمى" أو مسافة "هافرسين" بين أزواج من نقاط GeoCoord ‏(خط العرض/خط الطول) بوحدة الراديان.

الصيغة

h3PointDistRads(lat1, lon1, lat2, lon2)

الوسائط

• lat1, lon1 — خط العرض وخط الطول للنقطة 1 بالدرجات. Float64.
• lat2, lon2 — خط العرض وخط الطول للنقطة 2 بالدرجات. Float64.

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

• مسافة هافرسين أو مسافة الدائرة العظمى بالراديان. Float64.

مثال

SELECT h3PointDistRads(-10.0 ,0.0, 10.0, 0.0) AS h3PointDistRads;

┌────h3PointDistRads─┐
│ 0.3490658503988659 │
└────────────────────┘

يعيد مصفوفة تضم جميع فهارس H3 عند مستوى الدقة 0.

الصيغة

h3GetRes0Indexes()

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

• مصفوفة تضم جميع فهارس H3 عند مستوى الدقة 0. مصفوفة(UInt64).

مثال

SELECT h3GetRes0Indexes AS indexes ;

┌─indexes─────────────────────────────────────┐
│ [576495936675512319,576531121047601151,....]│
└─────────────────────────────────────────────┘

يعيد جميع فهارس H3 الخماسية عند مستوى الوضوح المحدد.

الصياغة

h3GetPentagonIndexes(resolution)

المعلمة

• resolution — دقة الفهرس. النطاق: [0, 15]. UInt8.

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

• مصفوفة تضم جميع فهارس H3 الخماسية. مصفوفة(UInt64).

مثال

SELECT h3GetPentagonIndexes(3) AS indexes;

┌─indexes────────────────────────────────────────────────────────┐
│ [590112357393367039,590464201114255359,590816044835143679,...] │
└────────────────────────────────────────────────────────────────┘

يعيد الخط الواصل بين الفهرسين المُعطيين.

الصيغة

h3Line(start,end)

المعلمات

• start — رقم فهرس الخلية السداسية الذي يمثّل نقطة البداية. UInt64.
• end — رقم فهرس الخلية السداسية الذي يمثّل نقطة النهاية. UInt64.

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

مصفوفة من فهارس H3 تمثّل خط الفهارس بين الفهرسين المحددين. Array(UInt64).

مثال

 SELECT h3Line(590080540275638271,590103561300344831) AS indexes;

┌─indexes────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ [590080540275638271,590080471556161535,590080883873021951,590106516237844479,590104385934065663,590103630019821567,590103561300344831] │
└────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

تعيد المسافة، بوحدة خلايا الشبكة، بين الفهرسين المُقدَّمين.

الصيغة

h3Distance(start,end)

المعامل

• start — رقم فهرس الخلية السداسية الذي يمثّل نقطة البداية. UInt64.
• end — رقم فهرس الخلية السداسية الذي يمثّل نقطة النهاية. UInt64.

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

• عدد خلايا الشبكة. Int64.

يعيد عددًا سالبًا إذا تعذّر حساب المسافة.

مثال

 SELECT h3Distance(590080540275638271,590103561300344831) AS distance;

┌─distance─┐
│        6 │
└──────────┘

تُرجع الفهارس الخاصة بالحلقة السداسية المتمركزة حول origin ‏h3Index المُعطى وبطول k.

تُرجع 0 إذا لم يُرصد أي تشوّه خماسي.

البنية

h3HexRing(index, k)

المعاملات

• index — رقم فهرس الخلية السداسية الذي يمثّل الخلية الأصل. UInt64.
• k — المسافة. UInt64.

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

• مصفوفة من فهارس H3. Array(UInt64).

مثال

 SELECT h3HexRing(590080540275638271, toUInt16(1)) AS hexRing;

┌─hexRing─────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ [590080815153545215,590080471556161535,590080677714591743,590077585338138623,590077447899185151,590079509483487231] │
└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

يعيد فهرس H3 لحافة أحادية الاتجاه لفهرسي خليتي H3 متجاورتين (الأصل والوجهة). يطرح استثناءً إذا لم يكن أيٌّ من الإدخالين خلية H3 صالحة (يتحكم في ذلك الإعداد functions_h3_default_if_invalid). بالنسبة إلى الخلايا الصالحة غير المتجاورة (بما في ذلك الخلية نفسها مرتين)، يعيد 0.

الصيغة

h3GetUnidirectionalEdge(originIndex, destinationIndex)

المعامل

• originIndex — رقم فهرس الخلية السداسية الأصلي. UInt64.
• destinationIndex — رقم فهرس الخلية السداسية للوجهة. UInt64.

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

• رقم فهرس الخلية السداسية للحافة أحادية الاتجاه. UInt64.

مثال

 SELECT h3GetUnidirectionalEdge(599686042433355775, 599686043507097599) AS edge;

┌────────────────edge─┐
│ 1248204388774707199 │
└─────────────────────┘

يحدِّد ما إذا كان H3Index المُقدَّم فهرس حافة أحادية الاتجاه صالحًا. يعيد القيمة 1 إذا كان حافة أحادية الاتجاه، و0 بخلاف ذلك.

البنية

h3UnidirectionalEdgeIsValid(index)

المعلمة

• index — رقم فهرس الخلية السداسية. UInt64.

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

• 1 — فهرس H3 هو حافة أحادية الاتجاه صالحة. UInt8.
• 0 — فهرس H3 ليس حافة أحادية الاتجاه صالحة. UInt8.

مثال

 SELECT h3UnidirectionalEdgeIsValid(1248204388774707199) AS validOrNot;

┌─validOrNot─┐
│          1 │
└────────────┘

يعيد مؤشر السداسي الأصلي من H3Index الخاص بالحافة أحادية الاتجاه. يطرح استثناءً إذا لم يكن الإدخال حافة موجهة صالحة (يتحكم في ذلك الإعداد functions_h3_default_if_invalid)؛ ولا يعيد 0 إلا عند تمكين هذا الإعداد.

الصياغة

h3GetOriginIndexFromUnidirectionalEdge(edge)

المعلمة

• edge — رقم فهرس الخلية السداسية الذي يمثّل حافة أحادية الاتجاه. UInt64.

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

• رقم فهرس الخلية السداسية للمنشأ. UInt64.
• يطرح INCORRECT_DATA للحواف الموجّهة غير الصالحة افتراضياً؛ ويعيد 0 عندما يكون functions_h3_default_if_invalid = 1.

مثال

 SELECT h3GetOriginIndexFromUnidirectionalEdge(1248204388774707199) AS origin;

┌─────────────origin─┐
│ 599686042433355775 │
└────────────────────┘

يعيد فهرس الخلية السداسية للوجهة من H3Index للحافة أحادية الاتجاه. يطرح استثناءً إذا لم يكن الإدخال حافة موجهة صالحة (يتحكم في ذلك الإعداد functions_h3_default_if_invalid)؛ ولا يعيد 0 إلا عند تمكين هذا الإعداد.

الصياغة

h3GetDestinationIndexFromUnidirectionalEdge(edge)

المعامل

• edge — رقم فهرس الخلية السداسية الذي يمثّل حافة أحادية الاتجاه. UInt64.

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

• رقم فهرس الخلية السداسية للوجهة. UInt64.
• يُطلق INCORRECT_DATA عند وجود حواف موجّهة غير صالحة افتراضيًا؛ ويعيد 0 عندما يكون functions_h3_default_if_invalid = 1.

مثال

 SELECT h3GetDestinationIndexFromUnidirectionalEdge(1248204388774707199) AS destination;

┌────────destination─┐
│ 599686043507097599 │
└────────────────────┘

يعيد فهارس السداسيات عند نقطتَي المنشأ والوجهة من H3Index للحافة أحادية الاتجاه المحددة.

البنية

h3GetIndexesFromUnidirectionalEdge(edge)

المعلمة

• edge — رقم فهرس الخلية السداسية الذي يمثّل حافة أحادية الاتجاه. UInt64.

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

زوج مرتب يتكوّن من قيمتين tuple(origin,destination):

• origin — رقم فهرس الخلية السداسية للمنشأ. UInt64.
• destination — رقم فهرس الخلية السداسية للوجهة. UInt64.

يطرح استثناءً إذا كانت قيمة الإدخال المقدَّمة ليست حافة موجَّهة صالحة (يتحكم في ذلك الإعداد functions_h3_default_if_invalid)؛ ولا يُرجِع (0,0) إلا عند تمكين ذلك الإعداد.

مثال

 SELECT h3GetIndexesFromUnidirectionalEdge(1248204388774707199) AS indexes;

┌─indexes─────────────────────────────────┐
│ (599686042433355775,599686043507097599) │
└─────────────────────────────────────────┘

يوفّر جميع الحواف أحادية الاتجاه الخارجة من قيمة H3Index المقدَّمة. يُطلق استثناءً إذا لم يكن الإدخال خلية H3 صالحة (يتحكم في ذلك الإعداد functions_h3_default_if_invalid)؛ ولا يعيد مصفوفة فارغة إلا عند تفعيل هذا الإعداد.

الصيغة

h3GetUnidirectionalEdgesFromHexagon(index)

المعلمة

• index — رقم فهرس الخلية السداسية الذي يمثّل خلية. UInt64.

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

• مصفوفة من فهارس H3 تمثّل كل حافة أحادية الاتجاه. Array(UInt64).
• يُطلق الخطأ INCORRECT_DATA للخلايا غير الصالحة افتراضيًا؛ ويعيد [] عندما يكون functions_h3_default_if_invalid = 1.

مثال

 SELECT h3GetUnidirectionalEdgesFromHexagon(599686042433355775) AS edges;

┌─edges─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ [1248204388774707199,1320261982812635135,1392319576850563071,1464377170888491007,1536434764926418943,1608492358964346879] │
└───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

تُرجِع الإحداثيات التي تُعرِّف الحافة أحادية الاتجاه. تطرح استثناءً إذا لم يكن الإدخال حافة موجّهة صالحة (يتحكم في ذلك الإعداد functions_h3_default_if_invalid)؛ ولا تُرجِع مصفوفة فارغة إلا عندما يكون هذا الإعداد مُفعّلًا.

البنية

h3GetUnidirectionalEdgeBoundary(index)

المعامل

• index — رقم فهرس الخلية السداسية الذي يمثّل حافة أحادية الاتجاه. UInt64.

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

• مصفوفة من الأزواج '(lat, lon)'. (Float64, Float64).
• يُطلق INCORRECT_DATA للحواف الموجّهة غير الصالحة افتراضيًا؛ ويُرجع [] عندما يكون functions_h3_default_if_invalid = 1.

مثال

 SELECT h3GetUnidirectionalEdgeBoundary(1248204388774707199) AS boundary;

┌─boundary────────────────────────────────────────────────────────────────────────┐
│ [(37.42012867767779,-122.03773496427027),(37.33755608435299,-122.090428929044)] │
└─────────────────────────────────────────────────────────────────────────────────┘