> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-fbfa8bee.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> توثيق دوال Tuple

# دوال Tuple

<Note>
  تم إنشاء الوثائق أدناه استنادًا إلى جدول النظام `system.functions`.
</Note>

{/*AUTOGENERATED_START*/}

<div id="dotProduct">
  ## dotProduct
</div>

مُستحدثة في: v21.11.0

تحسب [الضرب النقطي](https://en.wikipedia.org/wiki/Dot_product) (الجداء القياسي) لمتجهين (tupleين أو مصفوفتين متساويتين في الحجم).
وتُرجِع مجموع نواتج ضرب العناصر المناظرة.

**الصيغة**

```sql theme={null}
dotProduct(vector1, vector2)
```

**الأسماء المستعارة**: `scalarProduct`

**الوسائط**

* `vector1` — المتجه الأول. [`Array(T)`](/ar/reference/data-types/array) أو [`Tuple(T)`](/ar/reference/data-types/tuple)
* `vector2` — المتجه الثاني. يجب أن يكون بالحجم نفسه للمتجه الأول. [`Array(T)`](/ar/reference/data-types/array) أو [`Tuple(T)`](/ar/reference/data-types/tuple)

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

تعيد حاصل الضرب النقطي للمتجهين. [`(U)Int*`](/ar/reference/data-types/int-uint) أو [`Float*`](/ar/reference/data-types/float) أو [`Decimal`](/ar/reference/data-types/decimal)

**أمثلة**

**الاستخدام الأساسي**

```sql title=Query theme={null}
SELECT dotProduct((1, 2), (3, 4))
```

```response title=Response theme={null}
11
```

<div id="flattenTuple">
  ## flattenTuple
</div>

أُضيفت في: v22.6.0

تُسطِّح Tuple مُسمّى ومتداخلاً.
تكون عناصر الـ Tuple المُعادة هي مسارات الـ Tuple المُدخلة.

**البنية**

```sql theme={null}
flattenTuple(input)
```

**الوسائط**

* `input` — Tuple مُسمّى ومتداخل يُراد تسطيحه. [`Tuple(n1 T1[, n2 T2, ... ])`](/ar/reference/data-types/tuple)

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

يُرجع Tuple ناتجًا تكون عناصره مسارات من الإدخال الأصلي. [`Tuple(T)`](/ar/reference/data-types/tuple)

**أمثلة**

**مثال على الاستخدام**

```sql title=Query theme={null}
CREATE TABLE tab(t Tuple(a UInt32, b Tuple(c String, d UInt32))) ENGINE = MergeTree ORDER BY tuple();
INSERT INTO tab VALUES ((3, ('c', 4)));

SELECT flattenTuple(t) FROM tab;
```

```response title=Response theme={null}
┌─flattenTuple(t)┐
│ (3, 'c', 4)    │
└────────────────┘
```

<div id="tuple">
  ## tuple
</div>

ظهر في: v1.1.0

يعيد tuple من خلال تجميع معاملات الإدخال.

بالنسبة إلى الأعمدة C1 وC2 و... ذات الأنواع T1 وT2 و...، فإنه يعيد tuple من النوع المسمى Tuple(C1 T1, C2 T2, ...) يحتوي على هذه الأعمدة إذا كانت أسماؤها فريدة ويمكن التعامل معها كمُعرِّفات غير مقتبسة، وإلا فسيُعاد Tuple(T1, T2, ...). لا توجد أي تكلفة لتنفيذ هذه الدالة.
تُستخدم Tuples عادةً كقيم وسيطة لوسيط من معاملات IN، أو لإنشاء قائمة بالمعاملات الصورية لدوال lambda. ولا يمكن كتابة Tuples في جدول.

تُنفِّذ الدالة العامل `(x, y, ...)`.

**البنية**

```sql theme={null}
tuple([t1[, t2[ ...]])
```

**الوسائط**

* لا يوجد.

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

**أمثلة**

**اعتيادي**

```sql title=Query theme={null}
SELECT tuple(1, 2)
```

```response title=Response theme={null}
(1,2)
```

<div id="tupleConcat">
  ## tupleConcat
</div>

قُدِّمت في: v23.8.0

تدمج قيم Tuple الممرَّرة كوسائط.

**البنية**

```sql theme={null}
tupleConcat(tuple1[, tuple2, [...]])
```

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

* `tupleN` — عدد غير محدد من المعاملات من النوع Tuple. [`Tuple(T)`](/ar/reference/data-types/tuple)

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

يُرجِع قيمة Tuple تحتوي على جميع العناصر من قيم Tuple المُدخلة. [`Tuple(T)`](/ar/reference/data-types/tuple)

**أمثلة**

**مثال على الاستخدام**

```sql title=Query theme={null}
SELECT tupleConcat((1, 2), ('a',), (true, false))
```

```response title=Response theme={null}
(1, 2, 'a', true, false)
```

<div id="tupleDivide">
  ## tupleDivide
</div>

قُدِّمت في: v21.11.0

تحسب القسمة عنصرًا بعنصر لـ tupleين أو أكثر من الحجم نفسه، وتُطبَّق من اليسار إلى اليمين.

<Note>
  ستُرجع القسمة على صفر القيمة `inf`.
</Note>

**البنية**

```sql theme={null}
tupleDivide(t1, t2[, tN, ...])
```

**الوسيطات**

* `t1` — قيمة Tuple الأولى للإدخال. [`Tuple((U)Int*)`](/ar/reference/data-types/tuple) أو [`Tuple(Float*)`](/ar/reference/data-types/tuple) أو [`Tuple(Decimal)`](/ar/reference/data-types/tuple)
* `t2, ..., tN` — قيمة Tuple إضافية واحدة أو أكثر للإدخال. يجب أن تكون جميع قيم Tuple بالحجم نفسه. [`Tuple((U)Int*)`](/ar/reference/data-types/tuple) أو [`Tuple(Float*)`](/ar/reference/data-types/tuple) أو [`Tuple(Decimal)`](/ar/reference/data-types/tuple)

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

تعيد قيمة Tuple تحتوي على نواتج القسمة عنصرًا بعنصر. [`Tuple((U)Int*)`](/ar/reference/data-types/tuple) أو [`Tuple(Float*)`](/ar/reference/data-types/tuple) أو [`Tuple(Decimal)`](/ar/reference/data-types/tuple)

**أمثلة**

**قيمتا Tuple**

```sql title=Query theme={null}
SELECT tupleDivide((1, 2), (2, 3))
```

```response title=Response theme={null}
(0.5, 0.6666666666666666)
```

**ثلاثة tuples**

```sql title=Query theme={null}
SELECT tupleDivide((100.0, 60.0), (5.0, 3.0), (2.0, 4.0))
```

```response title=Response theme={null}
(10, 5)
```

<div id="tupleDivideByNumber">
  ## tupleDivideByNumber
</div>

أُضيف في: v21.11.0

يُرجع قيمة Tuple تكون جميع عناصرها مقسومة على عدد.

<Note>
  ستُرجع القسمة على صفر القيمة `inf`.
</Note>

**البنية**

```sql theme={null}
tupleDivideByNumber(tuple, number)
```

**الوسيطات**

* `tuple` — قيمة Tuple المطلوب قسمتها. [`Tuple((U)Int*)`](/ar/reference/data-types/tuple) أو [`Tuple(Float*)`](/ar/reference/data-types/tuple) أو [`Tuple(Decimal)`](/ar/reference/data-types/tuple)
* `number` — القاسم. [`(U)Int*`](/ar/reference/data-types/int-uint) أو [`Float*`](/ar/reference/data-types/float) أو [`Decimal`](/ar/reference/data-types/decimal)

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

تعيد قيمة Tuple تحتوي على عناصر مقسومة. [`Tuple((U)Int*)`](/ar/reference/data-types/tuple) أو [`Tuple(Float*)`](/ar/reference/data-types/tuple) أو [`Tuple(Decimal)`](/ar/reference/data-types/tuple)

**أمثلة**

**الاستخدام الأساسي**

```sql title=Query theme={null}
SELECT tupleDivideByNumber((1, 2), 0.5)
```

```response title=Response theme={null}
(2, 4)
```

<div id="tupleElement">
  ## tupleElement
</div>

أُضيفت في: v1.1.0

تستخرج عنصرًا من Tuple باستخدام الفهرس أو الاسم.

للوصول باستخدام الفهرس، يُتوقع فهرس رقمي يبدأ العد فيه من 1.
وللوصول باستخدام الاسم، يمكن تمرير اسم العنصر كسلسلة نصية (يعمل هذا فقط مع Tuple المُسمّاة).

الفهارس السالبة مدعومة. في هذه الحالة، يُحدَّد العنصر المقابل مع ترقيم يبدأ من النهاية. على سبيل المثال، `tuple.-1` هو العنصر الأخير في Tuple.

تحدّد وسيطة ثالثة اختيارية قيمة افتراضية تُعاد بدلًا من إطلاق استثناء عندما لا يكون العنصر المطلوب الوصول إليه موجودًا.
يجب أن تكون جميع الوسيطات ثوابت.

هذه الدالة لا تترتب عليها أي كلفة وقت تشغيل، وتنفّذ المعاملين `x.index` و `x.name`.

**البنية**

```sql theme={null}
tupleElement(tuple, index|name[, default_value])
```

**الوسائط**

* `tuple` — قيمة من النوع Tuple أو مصفوفة من قيم Tuple. [`Tuple(T)`](/ar/reference/data-types/tuple) أو [`Array(Tuple(T))`](/ar/reference/data-types/array)
* `index` — فهرس العمود، بدءًا من 1. [`const UInt8/16/32/64`](/ar/reference/data-types/int-uint)
* `name` — اسم العنصر. [`const String`](/ar/reference/data-types/string)
* `default_value` — القيمة الافتراضية التي تُعاد عندما يكون الفهرس خارج النطاق أو عندما لا يكون العنصر موجودًا. [`Any`](/ar/reference/data-types/index)

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

يُعاد العنصر عند الفهرس أو الاسم المحدد. [`Any`](/ar/reference/data-types/index)

**أمثلة**

**الوصول بالفهرس**

```sql title=Query theme={null}
SELECT tupleElement((1, 'hello'), 2)
```

```response title=Response theme={null}
hello
```

**الفهرسة بالمؤشرات السالبة**

```sql title=Query theme={null}
SELECT tupleElement((1, 'hello'), -1)
```

```response title=Response theme={null}
hello
```

**Tuple مُسمّاة مع جدول**

```sql title=Query theme={null}
CREATE TABLE example (values Tuple(name String, age UInt32)) ENGINE = Memory;
INSERT INTO example VALUES (('Alice', 30));
SELECT tupleElement(values, 'name') FROM example;
```

```response title=Response theme={null}
Alice
```

**مع القيمة الافتراضية**

```sql title=Query theme={null}
SELECT tupleElement((1, 2), 5, 'not_found')
```

```response title=Response theme={null}
not_found
```

**صيغة المعامل**

```sql title=Query theme={null}
SELECT (1, 'hello').2
```

```response title=Response theme={null}
hello
```

<div id="tupleHammingDistance">
  ## tupleHammingDistance
</div>

أُضيفت في: v21.1.0

تعيد [مسافة هامينغ](https://en.wikipedia.org/wiki/Hamming_distance) بين قيمتَي Tuple لهما العدد نفسه من العناصر.

<Note>
  يُحدَّد نوع النتيجة بالطريقة نفسها المتبعة في [الدوال الحسابية](/ar/reference/functions/regular-functions/arithmetic-functions)، وذلك بناءً على عدد العناصر في قيمتَي Tuple المُدخلتَين.

  ```sql theme={null}
  SELECT
      toTypeName(tupleHammingDistance(tuple(0), tuple(0))) AS t1,
      toTypeName(tupleHammingDistance((0, 0), (0, 0))) AS t2,
      toTypeName(tupleHammingDistance((0, 0, 0), (0, 0, 0))) AS t3,
      toTypeName(tupleHammingDistance((0, 0, 0, 0), (0, 0, 0, 0))) AS t4,
      toTypeName(tupleHammingDistance((0, 0, 0, 0, 0), (0, 0, 0, 0, 0))) AS t5
  ```

  ```text theme={null}
  ┌─t1────┬─t2─────┬─t3─────┬─t4─────┬─t5─────┐
  │ UInt8 │ UInt16 │ UInt32 │ UInt64 │ UInt64 │
  └───────┴────────┴────────┴────────┴────────┘
  ```
</Note>

**الصيغة**

```sql theme={null}
tupleHammingDistance(t1, t2)
```

**الوسائط**

* `t1` — أول `Tuple`. [`Tuple(*)`](/ar/reference/data-types/tuple)
* `t2` — ثاني `Tuple`. [`Tuple(*)`](/ar/reference/data-types/tuple)

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

تعيد مسافة هامينغ. [`UInt8/16/32/64`](/ar/reference/data-types/int-uint)

**أمثلة**

**مثال على الاستخدام**

```sql title=Query theme={null}
SELECT tupleHammingDistance((1, 2, 3), (3, 2, 1))
```

```response title=Response theme={null}
2
```

**باستخدام MinHash لاكتشاف السلاسل النصية شبه المتطابقة**

```sql title=Query theme={null}
SELECT tupleHammingDistance(wordShingleMinHash(string), wordShingleMinHashCaseInsensitive(string)) FROM (SELECT 'ClickHouse is a column-oriented database management system for online analytical processing of queries.' AS string)
```

```response title=Response theme={null}
2
```

<div id="tupleIntDiv">
  ## tupleIntDiv
</div>

تم تقديمه في: v23.8.0

يجري قسمة صحيحة على مستوى كل عنصر لاثنين أو أكثر من عناصر Tuple ذات الحجم نفسه، مع التطبيق من اليسار إلى اليمين. ويُرجع Tuple من نواتج القسمة.
إذا كان أي Tuple يحتوي على عناصر غير صحيحة، فتُحسب النتيجة بتقريب كل بسط أو مقسوم عليه غير صحيح إلى أقرب عدد صحيح.
تؤدي القسمة على 0 إلى طرح استثناء.

**البنية**

```sql theme={null}
tupleIntDiv(t1, t2[, tN, ...])
```

**الوسيطات**

* `t1` — أول Tuple مُدخل. [`Tuple((U)Int*)`](/ar/reference/data-types/tuple) أو [`Tuple(Float*)`](/ar/reference/data-types/tuple) أو [`Tuple(Decimal)`](/ar/reference/data-types/tuple)
* `t2, ..., tN` — واحد أو أكثر من قيم Tuple المُدخلة الإضافية. يجب أن يكون حجم جميع قيم Tuple متماثلًا. [`Tuple((U)Int*)`](/ar/reference/data-types/tuple) أو [`Tuple(Float*)`](/ar/reference/data-types/tuple) أو [`Tuple(Decimal)`](/ar/reference/data-types/tuple)

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

تعيد Tuple من نواتج القسمة الصحيحة. [`Tuple((U)Int*)`](/ar/reference/data-types/tuple) أو [`Tuple(Float*)`](/ar/reference/data-types/tuple) أو [`Tuple(Decimal)`](/ar/reference/data-types/tuple)

**أمثلة**

**Tupleان**

```sql title=Query theme={null}
SELECT tupleIntDiv((15, 10, 5), (5, 5, 5))
```

```response title=Response theme={null}
(3, 2, 1)
```

**مع القيم العشرية**

```sql title=Query theme={null}
SELECT tupleIntDiv((15, 10, 5), (5.5, 5.5, 5.5))
```

```response title=Response theme={null}
(2, 1, 0)
```

**ثلاثة Tuples**

```sql title=Query theme={null}
SELECT tupleIntDiv((120, 60), (4, 3), (2, 4))
```

```response title=Response theme={null}
(15, 5)
```

<div id="tupleIntDivByNumber">
  ## tupleIntDivByNumber
</div>

أُضيفت في: v23.8.0

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

**البنية**

```sql theme={null}
tupleIntDivByNumber(tuple_num, div)
```

**الوسائط**

* `tuple_num` — Tuple لقيم البسط. [`Tuple((U)Int*)`](/ar/reference/data-types/tuple) أو [`Tuple(Float*)`](/ar/reference/data-types/tuple) أو [`Tuple(Decimal)`](/ar/reference/data-types/tuple)
* `div` — قيمة المقسوم عليه. [`(U)Int*`](/ar/reference/data-types/int-uint) أو [`Float*`](/ar/reference/data-types/float) أو [`Decimal`](/ar/reference/data-types/decimal)

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

تعيد Tuple من نواتج القسمة. [`Tuple((U)Int*)`](/ar/reference/data-types/tuple) أو [`Tuple(Float*)`](/ar/reference/data-types/tuple) أو [`Tuple(Decimal)`](/ar/reference/data-types/tuple)

**أمثلة**

**الاستخدام الأساسي**

```sql title=Query theme={null}
SELECT tupleIntDivByNumber((15, 10, 5), 5)
```

```response title=Response theme={null}
(3, 2, 1)
```

**مع قيم Decimal**

```sql title=Query theme={null}
SELECT tupleIntDivByNumber((15.2, 10.7, 5.5), 5.8)
```

```response title=Response theme={null}
(2, 1, 0)
```

<div id="tupleIntDivOrZero">
  ## tupleIntDivOrZero
</div>

أُضيف في: v23.8.0

مثل [`tupleIntDiv`](#tupleIntDiv)، يُجري قسمة صحيحة على مستوى كل عنصر لاثنين أو أكثر من قيم Tuple ذات الحجم نفسه، مع التطبيق من اليسار إلى اليمين.
في حالة القسمة على 0، يُرجِع 0 لذلك العنصر بدلًا من إثارة استثناء.
إذا احتوى أي Tuple على عناصر غير صحيحة، فتُحتسب النتيجة عبر التقريب إلى أقرب عدد صحيح لكل بسط أو مقسوم عليه غير صحيح.

**الصياغة**

```sql theme={null}
tupleIntDivOrZero(t1, t2[, tN, ...])
```

**الوسائط**

* `t1` — قيمة Tuple الأولى للإدخال. [`Tuple((U)Int*)`](/ar/reference/data-types/tuple) أو [`Tuple(Float*)`](/ar/reference/data-types/tuple) أو [`Tuple(Decimal)`](/ar/reference/data-types/tuple)
* `t2, ..., tN` — قيمة Tuple إضافية واحدة أو أكثر للإدخال. يجب أن تكون جميع قيم Tuple بالحجم نفسه. [`Tuple((U)Int*)`](/ar/reference/data-types/tuple) أو [`Tuple(Float*)`](/ar/reference/data-types/tuple) أو [`Tuple(Decimal)`](/ar/reference/data-types/tuple)

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

تعيد قيمة Tuple من نواتج القسمة الصحيحة، مع 0 لأي عنصر يكون فيه المقسوم عليه 0. [`Tuple((U)Int*)`](/ar/reference/data-types/tuple) أو [`Tuple(Float*)`](/ar/reference/data-types/tuple) أو [`Tuple(Decimal)`](/ar/reference/data-types/tuple)

**أمثلة**

**مع مقسوم عليه يساوي صفرًا**

```sql title=Query theme={null}
SELECT tupleIntDivOrZero((5, 10, 15), (0, 0, 0))
```

```response title=Response theme={null}
(0, 0, 0)
```

**ثلاث قيم Tuple**

```sql title=Query theme={null}
SELECT tupleIntDivOrZero((120, 60), (4, 3), (2, 4))
```

```response title=Response theme={null}
(15, 5)
```

<div id="tupleIntDivOrZeroByNumber">
  ## tupleIntDivOrZeroByNumber
</div>

قُدِّم في: v23.8.0

مثل [`tupleIntDivByNumber`](#tupleIntDivByNumber)، يُجري هذا الدالّة قسمةً صحيحة لعناصر Tuple من البسوط على مقام معيّن، ويُرجع Tuple من نواتج القسمة.
ولا يُنتج خطأً إذا كان القاسم صفراً، بل يُرجع ناتج القسمة صفراً.
إذا احتوى Tuple أو القاسم على عناصر غير صحيحة، فتُحسب النتيجة بتقريب كل بسط أو قاسم غير صحيح إلى أقرب عدد صحيح.

**البنية**

```sql theme={null}
tupleIntDivOrZeroByNumber(tuple_num, div)
```

**الوسيطات**

* `tuple_num` — ‏Tuple لقيم البسط. [`Tuple((U)Int*)`](/ar/reference/data-types/tuple) or [`Tuple(Float*)`](/ar/reference/data-types/tuple) or [`Tuple(Decimal)`](/ar/reference/data-types/tuple)
* `div` — قيمة المقسوم عليه. [`(U)Int*`](/ar/reference/data-types/int-uint) or [`Float*`](/ar/reference/data-types/float) or [`Decimal`](/ar/reference/data-types/decimal)

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

تُرجِع Tuple من نواتج القسمة، مع `0` للنواتج التي يكون فيها المقسوم عليه `0`. [`Tuple((U)Int*)`](/ar/reference/data-types/tuple) or [`Tuple(Float*)`](/ar/reference/data-types/tuple) or [`Tuple(Decimal)`](/ar/reference/data-types/tuple)

**أمثلة**

**الاستخدام الأساسي**

```sql title=Query theme={null}
SELECT tupleIntDivOrZeroByNumber((15, 10, 5), 5)
```

```response title=Response theme={null}
(3, 2, 1)
```

**عند كون القاسم صفرًا**

```sql title=Query theme={null}
SELECT tupleIntDivOrZeroByNumber((15, 10, 5), 0)
```

```response title=Response theme={null}
(0, 0, 0)
```

<div id="tupleMinus">
  ## tupleMinus
</div>

قُدِّمت في: v21.11.0

يحسب الفرق عنصرًا بعنصر بين قيمتي Tuple أو أكثر من الحجم نفسه، ويُطبَّق من اليسار إلى اليمين.

**الصياغة**

```sql theme={null}
tupleMinus(t1, t2[, tN, ...])
```

**الأسماء البديلة**: `vectorDifference`

**الوسيطات**

* `t1` — قيمة الإدخال الأولى من النوع `Tuple`. [`Tuple((U)Int*)`](/ar/reference/data-types/tuple) أو [`Tuple(Float*)`](/ar/reference/data-types/tuple) أو [`Tuple(Decimal)`](/ar/reference/data-types/tuple)
* `t2, ..., tN` — قيمة إدخال إضافية واحدة أو أكثر من النوع `Tuple`. يجب أن تكون جميع قيم `Tuple` بالحجم نفسه. [`Tuple((U)Int*)`](/ar/reference/data-types/tuple) أو [`Tuple(Float*)`](/ar/reference/data-types/tuple) أو [`Tuple(Decimal)`](/ar/reference/data-types/tuple)

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

تعيد قيمة `Tuple` تحتوي على الفروق عنصرًا بعنصر. [`Tuple((U)Int*)`](/ar/reference/data-types/tuple) أو [`Tuple(Float*)`](/ar/reference/data-types/tuple) أو [`Tuple(Decimal)`](/ar/reference/data-types/tuple)

**أمثلة**

**زوج من قيم Tuple**

```sql title=Query theme={null}
SELECT tupleMinus((1, 2), (2, 3))
```

```response title=Response theme={null}
(-1, -1)
```

**ثلاثة Tuples**

```sql title=Query theme={null}
SELECT tupleMinus((10, 10), (3, 4), (2, 1))
```

```response title=Response theme={null}
(5, 5)
```

<div id="tupleModulo">
  ## tupleModulo
</div>

قُدِّمت في: v23.8.0

يعيد Tuple يحتوي على بواقي القسمة المحسوبة عنصرًا بعنصر من قسمة مجموعتي Tuple أو أكثر من الحجم نفسه، مع تطبيق العملية من اليسار إلى اليمين.

**البنية**

```sql theme={null}
tupleModulo(t1, t2[, tN, ...])
```

**الوسيطات**

* `t1` — أول Tuple مُدخل. [`Tuple((U)Int*)`](/ar/reference/data-types/tuple) أو [`Tuple(Float*)`](/ar/reference/data-types/tuple) أو [`Tuple(Decimal)`](/ar/reference/data-types/tuple)
* `t2, ..., tN` — قيمة Tuple مُدخلة إضافية واحدة أو أكثر. يجب أن تكون جميع قيم Tuple بالحجم نفسه. [`Tuple((U)Int*)`](/ar/reference/data-types/tuple) أو [`Tuple(Float*)`](/ar/reference/data-types/tuple) أو [`Tuple(Decimal)`](/ar/reference/data-types/tuple)

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

تُعيد Tuple يحتوي على بواقي القسمة محسوبةً عنصرًا بعنصر. يتم طرح استثناء عند القسمة على صفر. [`Tuple((U)Int*)`](/ar/reference/data-types/tuple) أو [`Tuple(Float*)`](/ar/reference/data-types/tuple) أو [`Tuple(Decimal)`](/ar/reference/data-types/tuple)

**أمثلة**

**قيمتا Tuple**

```sql title=Query theme={null}
SELECT tupleModulo((15, 10, 5), (5, 3, 2))
```

```response title=Response theme={null}
(0, 1, 1)
```

**ثلاثة Tuples**

```sql title=Query theme={null}
SELECT tupleModulo((10, 20), (7, 9), (3, 5))
```

```response title=Response theme={null}
(0, 2)
```

<div id="tupleModuloByNumber">
  ## tupleModuloByNumber
</div>

أُضيف في: v23.8.0

تُرجِع Tuple تحتوي على نواتج باقي القسمة (البواقي) لعمليات القسمة بين Tuple ومقسوم عليه معيّن.

**الصياغة**

```sql theme={null}
tupleModuloByNumber(tuple_num, div)
```

**الوسيطات**

* `tuple_num` — Tuple لعناصر البسط. [`Tuple((U)Int*)`](/ar/reference/data-types/tuple) أو [`Tuple(Float*)`](/ar/reference/data-types/tuple) أو [`Tuple(Decimal)`](/ar/reference/data-types/tuple)
* `div` — قيمة القاسم. [`(U)Int*`](/ar/reference/data-types/int-uint) أو [`Float*`](/ar/reference/data-types/float) أو [`Decimal`](/ar/reference/data-types/decimal)

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

تُرجِع Tuple من بواقي القسمة. ويتم طرح خطأ عند القسمة على صفر. [`Tuple((U)Int*)`](/ar/reference/data-types/tuple) أو [`Tuple(Float*)`](/ar/reference/data-types/tuple) أو [`Tuple(Decimal)`](/ar/reference/data-types/tuple)

**أمثلة**

**الاستخدام الأساسي**

```sql title=Query theme={null}
SELECT tupleModuloByNumber((15, 10, 5), 2)
```

```response title=Response theme={null}
(1, 0, 1)
```

<div id="tupleMultiply">
  ## tupleMultiply
</div>

أُضيف في: v21.11.0

يحسب حاصل الضرب عنصرًا بعنصر لاثنين أو أكثر من قيم Tuple ذات الحجم نفسه.

**البنية**

```sql theme={null}
tupleMultiply(t1, t2[, tN, ...])
```

**الوسيطات**

* `t1` — Tuple الإدخال الأول. [`Tuple((U)Int*)`](/ar/reference/data-types/tuple) أو [`Tuple(Float*)`](/ar/reference/data-types/tuple) أو [`Tuple(Decimal)`](/ar/reference/data-types/tuple)
* `t2, ..., tN` — قيمة Tuple إضافية واحدة أو أكثر للإدخال. يجب أن تكون جميع قيم Tuple بالحجم نفسه. [`Tuple((U)Int*)`](/ar/reference/data-types/tuple) أو [`Tuple(Float*)`](/ar/reference/data-types/tuple) أو [`Tuple(Decimal)`](/ar/reference/data-types/tuple)

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

تعيد قيمة Tuple تحتوي على نواتج الضرب على مستوى العناصر. [`Tuple((U)Int*)`](/ar/reference/data-types/tuple) أو [`Tuple(Float*)`](/ar/reference/data-types/tuple) أو [`Tuple(Decimal)`](/ar/reference/data-types/tuple)

**أمثلة**

**قيمتا Tuple**

```sql title=Query theme={null}
SELECT tupleMultiply((1, 2), (2, 3))
```

```response title=Response theme={null}
(2, 6)
```

**ثلاثة tuples**

```sql title=Query theme={null}
SELECT tupleMultiply((1, 2), (2, 3), (1, 2))
```

```response title=Response theme={null}
(2, 12)
```

<div id="tupleMultiplyByNumber">
  ## tupleMultiplyByNumber
</div>

أُضيف في: v21.11.0

يُرجع Tuple تكون جميع عناصرها مضروبة في عدد.

**البنية**

```sql theme={null}
tupleMultiplyByNumber(tuple, number)
```

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

* `tuple` — قيمة Tuple المراد ضربها. [`Tuple((U)Int*)`](/ar/reference/data-types/tuple) أو [`Tuple(Float*)`](/ar/reference/data-types/tuple) أو [`Tuple(Decimal)`](/ar/reference/data-types/tuple)
* `number` — المُضاعِف. [`(U)Int*`](/ar/reference/data-types/int-uint) أو [`Float*`](/ar/reference/data-types/float) أو [`Decimal`](/ar/reference/data-types/decimal)

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

يُرجع قيمة Tuple بعناصر مضروبة. [`Tuple((U)Int*)`](/ar/reference/data-types/tuple) أو [`Tuple(Float*)`](/ar/reference/data-types/tuple) أو [`Tuple(Decimal)`](/ar/reference/data-types/tuple)

**أمثلة**

**الاستخدام الأساسي**

```sql title=Query theme={null}
SELECT tupleMultiplyByNumber((1, 2), -2.1)
```

```response title=Response theme={null}
(-2.1, -4.2)
```

<div id="tupleNames">
  ## tupleNames
</div>

أُضيفت في: v24.8.0

يحوّل Tuple إلى مصفوفة من أسماء الأعمدة. وبالنسبة إلى Tuple بالصيغة `Tuple(a T, b T, ...)`، فإنه يعيد مصفوفة من السلاسل النصية التي تمثل الأعمدة المسمّاة في الـ Tuple. وإذا لم تكن لعناصر الـ Tuple أسماء صريحة، فستُستخدم فهارسها بدلًا منها كأسماء للأعمدة.

**البنية**

```sql theme={null}
tupleNames(tuple)
```

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

* لا شيء.

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

**أمثلة**

**نموذجي**

```sql title=Query theme={null}
SELECT tupleNames(tuple(1 as a, 2 as b))
```

```response title=Response theme={null}
['a','b']
```

<div id="tupleNegate">
  ## tupleNegate
</div>

أُضيفت في: v21.11.0

تحسب القيمة السالبة لعناصر الـ Tuple.

**الصيغة**

```sql theme={null}
tupleNegate(t)
```

**الوسيطات**

* `t` — قيمة Tuple المراد نفيها. [`Tuple((U)Int*)`](/ar/reference/data-types/tuple) أو [`Tuple(Float*)`](/ar/reference/data-types/tuple) أو [`Tuple(Decimal)`](/ar/reference/data-types/tuple)

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

تُرجِع قيمة Tuple تحتوي على نتيجة النفي. [`Tuple((U)Int*)`](/ar/reference/data-types/tuple) أو [`Tuple(Float*)`](/ar/reference/data-types/tuple) أو [`Tuple(Decimal)`](/ar/reference/data-types/tuple)

**أمثلة**

**الاستخدام الأساسي**

```sql title=Query theme={null}
SELECT tupleNegate((1, 2))
```

```response title=Response theme={null}
(-1, -2)
```

<div id="tuplePlus">
  ## tuplePlus
</div>

طُرح في: v21.11.0

يحسب مجموع العناصر المناظرة في tupleين أو أكثر من الحجم نفسه.

**الصيغة**

```sql theme={null}
tuplePlus(t1, t2[, tN, ...])
```

**الأسماء البديلة**: `vectorSum`

**الوسائط**

* `t1` — Tuple الإدخال الأول. [`Tuple((U)Int*)`](/ar/reference/data-types/tuple) أو [`Tuple(Float*)`](/ar/reference/data-types/tuple) أو [`Tuple(Decimal)`](/ar/reference/data-types/tuple)
* `t2, ..., tN` — Tuple إدخال إضافي واحد أو أكثر. يجب أن تكون جميع قيم Tuple بالحجم نفسه. [`Tuple((U)Int*)`](/ar/reference/data-types/tuple) أو [`Tuple(Float*)`](/ar/reference/data-types/tuple) أو [`Tuple(Decimal)`](/ar/reference/data-types/tuple)

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

تُرجِع قيمة Tuple تحتوي على المجاميع عنصرًا بعنصر. [`Tuple((U)Int*)`](/ar/reference/data-types/tuple) أو [`Tuple(Float*)`](/ar/reference/data-types/tuple) أو [`Tuple(Decimal)`](/ar/reference/data-types/tuple)

**أمثلة**

**Tupleان**

```sql title=Query theme={null}
SELECT tuplePlus((1, 2), (2, 3))
```

```response title=Response theme={null}
(3, 5)
```

**ثلاثة Tuples**

```sql title=Query theme={null}
SELECT tuplePlus((1, 2), (2, 3), (3, 4))
```

```response title=Response theme={null}
(6, 9)
```

<div id="tuplePositiveModuloByNumber">
  ## tuplePositiveModuloByNumber
</div>

أُضيف في: v26.4.0

يعيد Tuple يحتوي على البواقي الموجبة (remainders) لعمليات قسمة عناصر Tuple على مقسوم عليه معيّن.
وعلى خلاف tupleModuloByNumber، تكون النتيجة دائمًا غير سالبة.

**البنية**

```sql theme={null}
tuplePositiveModuloByNumber(tuple_num, div)
```

**الوسيطات**

* `tuple_num` — Tuple لقيم المقسوم. [`Tuple((U)Int*)`](/ar/reference/data-types/tuple) أو [`Tuple(Float*)`](/ar/reference/data-types/tuple) أو [`Tuple(Decimal)`](/ar/reference/data-types/tuple)
* `div` — قيمة المقسوم عليه. [`(U)Int*`](/ar/reference/data-types/int-uint) أو [`Float*`](/ar/reference/data-types/float) أو [`Decimal`](/ar/reference/data-types/decimal)

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

تُرجع Tuple من البواقي غير السالبة. [`Tuple((U)Int*)`](/ar/reference/data-types/tuple) أو [`Tuple(Float*)`](/ar/reference/data-types/tuple) أو [`Tuple(Decimal)`](/ar/reference/data-types/tuple)

**أمثلة**

**الاستخدام الأساسي**

```sql title=Query theme={null}
SELECT tuplePositiveModuloByNumber((15, 10, 5), 2)
```

```response title=Response theme={null}
(1, 0, 1)
```

<div id="tupleToNameValuePairs">
  ## tupleToNameValuePairs
</div>

تم تقديمها في: v21.9.0

تحوّل Tuple إلى Array من أزواج `(name, value)`.
على سبيل المثال، يُحوَّل الـ Tuple `Tuple(n1 T1, n2 T2, ...)` إلى `Array(Tuple('n1', T1), Tuple('n2', T2), ...)`.
يجب أن تكون جميع القيم في الـ Tuple من النوع نفسه.

**الصياغة**

```sql theme={null}
tupleToNameValuePairs(tuple)
```

**الوسيطات**

* `tuple` — Tuple مُسمّى يحتوي على قيم من أي أنواع. [`Tuple(n1 T1[, n2 T2, ...])`](/ar/reference/data-types/tuple)

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

تعيد مصفوفة من أزواج `(name, value)`. [`Array(Tuple(String, T))`](/ar/reference/data-types/array)

**أمثلة**

**Tuple مُسمّى**

```sql title=Query theme={null}
SELECT tupleToNameValuePairs(tuple(1593 AS user_ID, 2502 AS session_ID))
```

```response title=Response theme={null}
[('1', 1593), ('2', 2502)]
```

**Tuple غير مُسمّى**

```sql title=Query theme={null}
SELECT tupleToNameValuePairs(tuple(3, 2, 1))
```

```response title=Response theme={null}
[('1', 3), ('2', 2), ('3', 1)]
```

<div id="untuple">
  ## untuple
</div>

ينفّذ استبدالًا نحويًا لعناصر [tuple](/ar/reference/data-types/tuple) في موضع الاستدعاء.

تعتمد أسماء الأعمدة الناتجة على التنفيذ وقد تتغير. لا تفترض أسماء أعمدة محددة بعد `untuple`.

**الصيغة**

```sql theme={null}
untuple(x)
```

يمكنك استخدام التعبير `EXCEPT` لتخطي الأعمدة من نتيجة الاستعلام.

**الوسائط**

* `x` — دالة `tuple`، أو عمود، أو Tuple من العناصر. [Tuple](/ar/reference/data-types/tuple).

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

* لا شيء.

**أمثلة**

جدول الإدخال:

```text theme={null}
┌─key─┬─v1─┬─v2─┬─v3─┬─v4─┬─v5─┬─v6────────┐
│   1 │ 10 │ 20 │ 40 │ 30 │ 15 │ (33,'ab') │
│   2 │ 25 │ 65 │ 70 │ 40 │  6 │ (44,'cd') │
│   3 │ 57 │ 30 │ 20 │ 10 │  5 │ (55,'ef') │
│   4 │ 55 │ 12 │  7 │ 80 │ 90 │ (66,'gh') │
│   5 │ 30 │ 50 │ 70 │ 25 │ 55 │ (77,'kl') │
└─────┴────┴────┴────┴────┴────┴───────────┘
```

مثال على استخدام عمود من نوع `Tuple` بصفته معلمة للدالة `untuple`:

```sql title="Query" theme={null}
SELECT untuple(v6) FROM kv;
```

```text title="Response" theme={null}
┌─_ut_1─┬─_ut_2─┐
│    33 │ ab    │
│    44 │ cd    │
│    55 │ ef    │
│    66 │ gh    │
│    77 │ kl    │
└───────┴───────┘
```

مثال على استخدام تعبير `EXCEPT`:

```sql title="Query" theme={null}
SELECT untuple((* EXCEPT (v2, v3),)) FROM kv;
```

```text title="Response" theme={null}
┌─key─┬─v1─┬─v4─┬─v5─┬─v6────────┐
│   1 │ 10 │ 30 │ 15 │ (33,'ab') │
│   2 │ 25 │ 40 │  6 │ (44,'cd') │
│   3 │ 57 │ 10 │  5 │ (55,'ef') │
│   4 │ 55 │ 80 │ 90 │ (66,'gh') │
│   5 │ 30 │ 25 │ 55 │ (77,'kl') │
└─────┴────┴────┴────┴───────────┘
```

<div id="distance-functions">
  ## دوال المسافة
</div>

ترد جميع الدوال المدعومة في [وثائق دوال المسافة](/ar/reference/functions/regular-functions/distance-functions).