مشاركة عبر

h3_try_distance وظيفه

  • مقالة

ينطبق على:وضع علامة Databricks SQL وضع علامة Databricks Runtime 13.3 LTS وما فوق

تتصرف هذه الدالة بشكل مشابه h3_distance، باستثناء أنه يتم إرجاع NULL بدلا من خطأ إذا كانت مسافة الشبكة بين معرفي خلية الإدخال H3 لنفس الدقة غير معرفة. على وجه التحديد، فإنه يرجع مسافة الشبكة لمعرفي الخلية H3 الإدخال، والتي من المتوقع أن تكون بنفس الدقة، أو NULL إذا كانت المسافة غير معرفة.

بناء الجملة

h3_try_distance ( h3CellId1Expr, h3CellId2Expr )

الوسيطات

  • h3CellId1Expr: تعبير BIGINT أو تعبير سلسلة سداسي عشري يمثل معرف خلية H3.
  • h3CellId2Expr: تعبير BIGINT أو تعبير سلسلة سداسي عشري يمثل معرف خلية H3.

المرتجعات

قيمة BIGINT وهي مسافة الشبكة لخلايا الإدخال H3، المتوقع أن يكون لها نفس الدقة، أو NULL إذا كانت المسافة غير معرفة.

ترجع الدالة NULL إذا كان أي من تعبيرات الإدخال NULL. يتحقق جزئيا من صحة وسيطات الإدخال لتحديد ما إذا كانت تمثل معرفات خلايا H3 صالحة. الشرط الضروري، ولكن غير الكافي، لمعرف H3 صالح هو أن قيمته بين 0x08001fffffffffff و 0x08ff3b6db6db6db6. سلوك الدالة غير معرف إذا كان أي من معرفي خلية الإدخال ليس معرف خلية صالحا.

حالات الخطأ

  • إذا كان h3CellId1Expr أو h3CellId2Expr عبارة عن سلسلة لا يمكن تحويلها إلى BIGINT أو تتوافق مع قيمة BIGINT أصغر من 0x08001fffffffffff أو أكبر من 0x08ff3b6db6db6db6، ترجع الدالة H3_INVALID_CELL_ID.
  • إذا كانت خلية الإدخال H3 ذات دقة مختلفة، ترجع الدالة H3_UNDEFINED_GRID_DISTANCE.
  • إذا كانت مسافة الشبكة بين خليتين H3 بنفس الدقة غير معرفة، ترجع الدالة NULL. يمكن أن تكون مسافة الشبكة غير معرفة لأي من الأسباب التالية:
    • أي واحدة من اثنتين من خلايا الإدخال H3 هي خلية البنتاغون.
    • يتم فصل الخليتين H3 بخلية البنتاغون.
    • الخليتان H3 بعيدتان جدا عن بعضهما البعض.

الأمثلة

-- Example where the two arguments are BIGINTs representing H3 cells.
> SELECT h3_distance(599686030622195711, 599686015589810175);
 2

-- Example where the two arguments are hexadecimal STRINGs representing H3 cells.
> SELECT h3_distance('85283447fffffff', '8528340ffffffff')
 2

-- Example of two cells that too far apart from each other.
> SELECT h3_distance(h3_longlatash3(-120, 45, 13), h3_longlatash3(120, 45, 13))
 NULL

-- Example of two cells with different resolutions.
> SELECT h3_distance(h3_longlatash3(120, 45, 13), h3_longlatash3(120, 45, 12));
  [H3_UNDEFINED_GRID_DISTANCE] H3 grid distance between 635869868887430591 and 631366269260060159 is undefined

-- First cell ID is a pentagon.
> SELECT h3_distance(590112357393367039, 590678880759578623)
 NULL

-- Distance between two hexagons separated by a pentagon.
> SELECT h3_distance(590112494832320511, 590112632271273983)
 NULL