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

> توثيق الإحداثيات

# دوال للتعامل مع الإحداثيات الجغرافية

<div id="greatcircledistance">
  ## greatCircleDistance
</div>

يحسب المسافة بين نقطتين على سطح الأرض باستخدام [معادلة الدائرة العظمى](https://en.wikipedia.org/wiki/Great-circle_distance).

```sql theme={null}
greatCircleDistance(lon1Deg, lat1Deg, lon2Deg, lat2Deg)
```

**معلمات الإدخال**

* `lon1Deg` — خط الطول النقطة الأولى بالدرجات. النطاق: `[-180°, 180°]`.
* `lat1Deg` — خط العرض النقطة الأولى بالدرجات. النطاق: `[-90°, 90°]`.
* `lon2Deg` — خط الطول النقطة الثانية بالدرجات. النطاق: `[-180°, 180°]`.
* `lat2Deg` — خط العرض النقطة الثانية بالدرجات. النطاق: `[-90°, 90°]`.

تشير القيم الموجبة إلى خط العرض شمالًا وخط الطول شرقًا، وتشير القيم السالبة إلى خط العرض جنوبًا وخط الطول غربًا.

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

المسافة بين نقطتين على سطح الأرض، بالمتر.

يُنشئ استثناءً عندما تقع قيم معلمات الإدخال خارج النطاق.

**مثال**

```sql theme={null}
SELECT greatCircleDistance(55.755831, 37.617673, -55.755831, -37.617673) AS greatCircleDistance
```

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

<div id="geodistance">
  ## geoDistance
</div>

مشابهة لـ `greatCircleDistance`، لكنها تحسب المسافة على إهليلج WGS-84 بدلًا من الكرة. ويوفّر ذلك تقريبًا أدق لجيود الأرض.
الأداء مماثل لأداء `greatCircleDistance` (من دون أي تراجع في الأداء). ويُوصى باستخدام `geoDistance` لحساب المسافات على الأرض.

ملاحظة تقنية: بالنسبة للنقاط المتقاربة بما يكفي، نحسب المسافة باستخدام تقريب مستوٍ وفق المترية على المستوى المماس عند منتصف الإحداثيات.

```sql theme={null}
geoDistance(lon1Deg, lat1Deg, lon2Deg, lat2Deg)
```

**معلمات الإدخال**

* `lon1Deg` — خط الطول النقطة الأولى بالدرجات. النطاق: `[-180°, 180°]`.
* `lat1Deg` — خط العرض النقطة الأولى بالدرجات. النطاق: `[-90°, 90°]`.
* `lon2Deg` — خط الطول النقطة الثانية بالدرجات. النطاق: `[-180°, 180°]`.
* `lat2Deg` — خط العرض النقطة الثانية بالدرجات. النطاق: `[-90°, 90°]`.

تشير القيم الموجبة إلى خطوط العرض الشمالية وخطوط الطول الشرقية، وتشير القيم السالبة إلى خطوط العرض الجنوبية وخطوط الطول الغربية.

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

المسافة بين نقطتين على سطح الأرض، بالمتر.

يتم إنشاء استثناء عندما تقع قيم معلمات الإدخال خارج هذا النطاق.

**مثال**

```sql theme={null}
SELECT geoDistance(38.8976, -77.0366, 39.9496, -75.1503) AS geoDistance
```

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

<div id="greatcircleangle">
  ## greatCircleAngle
</div>

تحسب الزاوية المركزية بين نقطتين على سطح الأرض باستخدام [معادلة الدائرة العظمى](https://en.wikipedia.org/wiki/Great-circle_distance).

```sql theme={null}
greatCircleAngle(lon1Deg, lat1Deg, lon2Deg, lat2Deg)
```

**معلمات الإدخال**

* `lon1Deg` — خط الطول للنقطة الأولى، بالدرجات.
* `lat1Deg` — خط العرض للنقطة الأولى، بالدرجات.
* `lon2Deg` — خط الطول للنقطة الثانية، بالدرجات.
* `lat2Deg` — خط العرض للنقطة الثانية، بالدرجات.

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

الزاوية المركزية بين نقطتين، بالدرجات.

**مثال**

```sql theme={null}
SELECT greatCircleAngle(0, 0, 45, 0) AS arc
```

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

<div id="pointinellipses">
  ## pointInEllipses
</div>

يتحقق مما إذا كانت النقطة تقع داخل شكل بيضاوي واحد على الأقل.
الإحداثيات هندسية ضمن نظام الإحداثيات الديكارتية.

```sql theme={null}
pointInEllipses(x, y, x₀, y₀, a₀, b₀,...,xₙ, yₙ, aₙ, bₙ)
```

**معلمات الإدخال**

* `x, y` — إحداثيات نقطة على المستوى.
* `xᵢ, yᵢ` — إحداثيات مركز القطع الناقص رقم `i`.
* `aᵢ, bᵢ` — محورا القطع الناقص رقم `i` بوحدات إحداثيي x وy.

يجب أن يكون عدد معلمات الإدخال `2+4⋅n`، حيث إن `n` هو عدد الأشكال البيضوية.

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

`1` إذا كانت النقطة داخل شكل بيضوي واحد على الأقل؛ `0` إذا لم تكن كذلك.

**مثال**

```sql theme={null}
SELECT pointInEllipses(10., 10., 10., 9.1, 1., 0.9999)
```

```text theme={null}
┌─pointInEllipses(10., 10., 10., 9.1, 1., 0.9999)─┐
│                                               1 │
└─────────────────────────────────────────────────┘
```

<div id="pointinpolygon">
  ## pointInPolygon
</div>

يتحقق مما إذا كانت النقطة تقع داخل المضلع على المستوى.

```sql theme={null}
pointInPolygon((x, y), [(a, b), (c, d) ...], ...)
```

**قيم الإدخال**

* `(x, y)` — إحداثيات نقطة على المستوى. نوع البيانات — [Tuple](/ar/reference/data-types/tuple) — قيمة Tuple مكوّنة من رقمين.
* `[(a, b), (c, d) ...]` — رؤوس المضلع. نوع البيانات — [Array](/ar/reference/data-types/array). تُمثَّل كل قمة بزوج من الإحداثيات `(a, b)`. يجب تحديد الرؤوس بترتيب مع عقارب الساعة أو عكس اتجاه عقارب الساعة. الحد الأدنى لعدد الرؤوس هو 3. يجب أن يكون المضلع ثابتًا.
* تدعم الدالة أيضًا المضلع ذي الفتحات (الأجزاء المقتطعة). نوع البيانات — [Polygon](/ar/reference/data-types/geo#polygon). مرِّر إما `Polygon` بالكامل باعتباره المُدخل الثاني، أو مرِّر الحلقة الخارجية أولًا ثم كل فتحة كمدخل إضافي منفصل.
* تدعم الدالة أيضًا MultiPolygon. نوع البيانات — [MultiPolygon](/ar/reference/data-types/geo#multipolygon). مرِّر إما `MultiPolygon` بالكامل باعتباره المُدخل الثاني، أو أدرج كل مضلع مكوّن باعتباره مُدخلًا مستقلًا.

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

`1` إذا كانت النقطة داخل المضلع، و`0` إذا لم تكن كذلك.
إذا كانت النقطة على حدود المضلع، فقد تُرجع الدالة 0 أو 1.

**مثال**

```sql theme={null}
SELECT pointInPolygon((3., 3.), [(6, 0), (8, 4), (5, 8), (0, 2)]) AS res
```

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

> **ملاحظة**
> • يمكنك تعيين `validate_polygons = 0` لتجاوز التحقق من صحة الأشكال الهندسية.
> • تفترض الدالة `pointInPolygon` أن كل مضلع مُشكَّل بصورة صحيحة. إذا كان الإدخال متقاطعًا مع نفسه، أو كانت حلقاته مرتبة على نحو غير صحيح، أو كانت حوافه متداخلة، تصبح النتائج غير موثوقة—خصوصًا للنقاط الواقعة تمامًا على حافة أو رأس، أو داخل تقاطع ذاتي حيث يكون مفهوم "الداخل" مقابل "الخارج" غير معرّف.
> • عندما تكون وسيطة المضلع ثابتة وتُعبَّر النقطة باستخدام أعمدة المفتاح المفهرسة (على سبيل المثال، `pointInPolygon((x, y), constant_polygon)` على جدول تكون فيه `x, y` جزءًا من `PRIMARY KEY` أو مشمولة بفهرس `minmax`)، يمكن لـ ClickHouse استخدام كلٍّ من المفتاح الأساسي وفهارس تخطي البيانات `minmax` لاستبعاد الحبيبات غير ذات الصلة.