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

> توثيق الدوال الخاصة بالتعامل مع UUIDs

# دوال للتعامل مع UUIDs

export const DeprecatedBadge = () => {
  return <div className="deprecatedBadge">
            <div className="deprecatedIcon">
            <svg width="14" height="10" viewBox="0 0 14 10" fill="none" xmlns="http://www.w3.org/2000/svg">
                <path d="M13 0H1C0.734784 0 0.48043 0.105357 0.292893 0.292893C0.105357 0.48043 0 0.734784 0 1V2.5C0 2.76522 0.105357 3.01957 0.292893 3.20711C0.48043 3.39464 0.734784 3.5 1 3.5V9C1 9.26522 1.10536 9.51957 1.29289 9.70711C1.48043 9.89464 1.73478 10 2 10H12C12.2652 10 12.5196 9.89464 12.7071 9.70711C12.8946 9.51957 13 9.26522 13 9V3.5C13.2652 3.5 13.5196 3.39464 13.7071 3.20711C13.8946 3.01957 14 2.76522 14 2.5V1C14 0.734784 13.8946 0.48043 13.7071 0.292893C13.5196 0.105357 13.2652 0 13 0ZM12 9H2V3.5H12V9ZM13 2.5H1V1H13V2.5ZM5 5.5C5 5.36739 5.05268 5.24021 5.14645 5.14645C5.24021 5.05268 5.36739 5 5.5 5H8.5C8.63261 5 8.75979 5.05268 8.85355 5.14645C8.94732 5.24021 9 5.36739 9 5.5C9 5.63261 8.94732 5.75979 8.85355 5.85355C8.75979 5.94732 8.63261 6 8.5 6H5.5C5.36739 6 5.24021 5.94732 5.14645 5.85355C5.05268 5.75979 5 5.63261 5 5.5Z" fill="currentColor" />
            </svg>
        </div>
            ميزة متقادمة
        </div>;
};

<div id="functions-for-working-with-uuids">
  # دوال للتعامل مع UUIDs
</div>

<div id="uuidv7-generation">
  ## توليد UUIDv7
</div>

يحتوي UUID المُولَّد على طابع زمني من 48 بت بوحدة ميلي ثانية وفق Unix، يليه الإصدار "7" (4 بت)، وعدّاد (42 بت) لتمييز UUIDs ضمن الميلي ثانية الواحدة (بما في ذلك حقل المتغيّر "2"، 2 بت)، وحقل عشوائي (32 بت).
بالنسبة إلى أي طابع زمني معيّن (`unix_ts_ms`)، يبدأ العدّاد بقيمة عشوائية ويزداد بمقدار 1 لكل UUID جديد إلى أن يتغيّر الطابع الزمني. وفي حال تجاوز سعة العدّاد، يُزاد حقل الطابع الزمني بمقدار 1 ويُعاد ضبط العدّاد إلى قيمة بداية عشوائية جديدة.
تضمن دوال توليد UUID أن حقل العدّاد داخل الطابع الزمني يزداد اطرادًا عبر جميع استدعاءات الدوال في الخيوط والاستعلامات التي تعمل بالتوازي.

```text theme={null}
 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
├─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┤
|                           unix_ts_ms                          |
├─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┤
|          unix_ts_ms           |  ver  |   counter_high_bits   |
├─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┤
|var|                   counter_low_bits                        |
├─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┤
|                            rand_b                             |
└─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┘
```

<div id="snowflake-id-generation">
  ## إنشاء Snowflake ID
</div>

يحتوي Snowflake ID المُنشأ على طابع Unix زمني حالي بالمللي ثانية (41 + 1 من البتات العليا الصفرية)، يليه معرّف آلة (10 بتات)، ثم عدّاد (12 بتًا) لتمييز المعرّفات داخل المللي ثانية الواحدة. وبالنسبة إلى أي طابع زمني معيّن (`unix_ts_ms`)، يبدأ العدّاد من 0 ويزداد بمقدار 1 مع كل Snowflake ID جديد إلى أن يتغيّر الطابع الزمني. وفي حال تجاوز سعة العدّاد، تُزاد خانة الطابع الزمني بمقدار 1 ويُعاد ضبط العدّاد إلى 0.

<Note>
  تستند معرّفات Snowflake المُنشأة إلى حقبة UNIX التي تبدأ في 1970-01-01. ومع أنه لا يوجد معيار أو توصية تحدد حقبة معرّفات Snowflake، فقد تستخدم التطبيقات في أنظمة أخرى حقبة مختلفة، مثل Twitter/X ‏(2010-11-04) أو Mastodon ‏(2015-01-01).
</Note>

```text theme={null}
 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
├─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┤
|0|                         timestamp                           |
├─┼                 ┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┤
|                   |     machine_id    |    machine_seq_num    |
└─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┘
```

{/*AUTOGENERATED_START*/}

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

ظهر في: v1.1.0

يأخذ التمثيل الثنائي لـ UUID، مع إمكانية تحديد تنسيقه اختياريًا باستخدام `variant` (ويكون `Big-endian` افتراضيًا)، ويُرجع سلسلة نصية تتكوّن من 36 حرفًا بتنسيق نصي.

**البنية**

```sql theme={null}
UUIDNumToString(binary[, variant])
```

**الوسائط**

* `binary` — التمثيل الثنائي لـ UUID. [`FixedString(16)`](/ar/reference/data-types/fixedstring)
* `variant` — المتغيّر كما هو محدد في [RFC4122](https://datatracker.ietf.org/doc/html/rfc4122#section-4.1.1). 1 = `Big-endian` (الافتراضي)، 2 = `Microsoft`. [`(U)Int*`](/ar/reference/data-types/int-uint)

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

يُرجع UUID على هيئة سلسلة نصية. [`String`](/ar/reference/data-types/string)

**أمثلة**

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

```sql title=Query theme={null}
SELECT
    'a/<@];!~p{jTj={)' AS bytes,
    UUIDNumToString(toFixedString(bytes, 16)) AS uuid
```

```response title=Response theme={null}
┌─bytes────────────┬─uuid─────────────────────────────────┐
│ a/<@];!~p{jTj={) │ 612f3c40-5d3b-217e-707b-6a546a3d7b29 │
└──────────────────┴──────────────────────────────────────┘
```

**متغير مايكروسوفت**

```sql title=Query theme={null}
SELECT
    '@</a;]~!p{jTj={)' AS bytes,
    UUIDNumToString(toFixedString(bytes, 16), 2) AS uuid
```

```response title=Response theme={null}
┌─bytes────────────┬─uuid─────────────────────────────────┐
│ @</a;]~!p{jTj={) │ 612f3c40-5d3b-217e-707b-6a546a3d7b29 │
└──────────────────┴──────────────────────────────────────┘
```

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

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

تقبل سلسلة نصية تتكوّن من 36 حرفًا بالتنسيق `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`، وتُرجع [FixedString(16)](/ar/reference/data-types/fixedstring) كتمثيلها الثنائي، مع إمكانية تحديد التنسيق اختياريًا باستخدام `variant` (‏`Big-endian` افتراضيًا).

**البنية**

```sql theme={null}
UUIDStringToNum(string[, variant = 1])
```

**الوسائط**

* `string` — سلسلة نصية أو سلسلة ثابتة بطول 36 حرفًا [`String`](/ar/reference/data-types/string) أو [`FixedString(36)`](/ar/reference/data-types/fixedstring)
* `variant` — قيمة المتغيّر كما هي محددة في [RFC4122](https://datatracker.ietf.org/doc/html/rfc4122#section-4.1.1). 1 = `Big-endian` (الافتراضي)، 2 = `Microsoft`. [`(U)Int*`](/ar/reference/data-types/int-uint)

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

تعيد التمثيل الثنائي لـ `string`. [`FixedString(16)`](/ar/reference/data-types/fixedstring)

**أمثلة**

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

```sql title=Query theme={null}
SELECT
    '612f3c40-5d3b-217e-707b-6a546a3d7b29' AS uuid,
    UUIDStringToNum(uuid) AS bytes
```

```response title=Response theme={null}
┌─uuid─────────────────────────────────┬─bytes────────────┐
│ 612f3c40-5d3b-217e-707b-6a546a3d7b29 │ a/<@];!~p{jTj={) │
└──────────────────────────────────────┴──────────────────┘
```

**متغير مايكروسوفت**

```sql title=Query theme={null}
SELECT
    '612f3c40-5d3b-217e-707b-6a546a3d7b29' AS uuid,
    UUIDStringToNum(uuid, 2) AS bytes
```

```response title=Response theme={null}
┌─uuid─────────────────────────────────┬─bytes────────────┐
│ 612f3c40-5d3b-217e-707b-6a546a3d7b29 │ @</a;]~!p{jTj={) │
└──────────────────────────────────────┴──────────────────┘
```

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

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

تقبل [UUID](/ar/reference/data-types/uuid) وتُرجع تمثيله الثنائي كقيمة [FixedString(16)](/ar/reference/data-types/fixedstring)، مع إمكانية تحديد تنسيقه اختياريًا عبر `variant` (ويكون `Big-endian` افتراضيًا).
تستبدل هذه الدالة استدعاءات دالتين منفصلتين هما `UUIDStringToNum(toString(uuid))`، لذلك لا حاجة إلى أي تحويل وسيط من UUID إلى سلسلة لاستخراج البايتات من UUID.

**الصياغة**

```sql theme={null}
UUIDToNum(uuid[, variant = 1])
```

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

* `uuid` — UUID. [`String`](/ar/reference/data-types/string) أو [`FixedString`](/ar/reference/data-types/fixedstring)
* `variant` — قيمة المتغيّر كما هي محددة في [RFC4122](https://datatracker.ietf.org/doc/html/rfc4122#section-4.1.1). 1 = `Big-endian` (الافتراضي)، 2 = `Microsoft`. [`(U)Int*`](/ar/reference/data-types/int-uint)

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

يعيد تمثيلاً ثنائياً لـ UUID. [`FixedString(16)`](/ar/reference/data-types/fixedstring)

**أمثلة**

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

```sql title=Query theme={null}
SELECT
    toUUID('612f3c40-5d3b-217e-707b-6a546a3d7b29') AS uuid,
    UUIDToNum(uuid) AS bytes
```

```response title=Response theme={null}
┌─uuid─────────────────────────────────┬─bytes────────────┐
│ 612f3c40-5d3b-217e-707b-6a546a3d7b29 │ a/<@];!~p{jTj={) │
└──────────────────────────────────────┴──────────────────┘
```

**متغير مايكروسوفت**

```sql title=Query theme={null}
SELECT
    toUUID('612f3c40-5d3b-217e-707b-6a546a3d7b29') AS uuid,
    UUIDToNum(uuid, 2) AS bytes
```

```response title=Response theme={null}
┌─uuid─────────────────────────────────┬─bytes────────────┐
│ 612f3c40-5d3b-217e-707b-6a546a3d7b29 │ @</a;]~!p{jTj={) │
└──────────────────────────────────────┴──────────────────┘
```

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

أُضيف في: v24.5.0

يعيد مكوّن الطابع الزمني في UUID الإصدار 7.

**البنية**

```sql theme={null}
UUIDv7ToDateTime(uuid[, timezone])
```

**الوسائط**

* `uuid` — UUID الإصدار 7. [`String`](/ar/reference/data-types/string)
* `timezone` — اختياري. [اسم المنطقة الزمنية](/ar/reference/settings/server-settings/settings#timezone) للقيمة المُعادة. [`String`](/ar/reference/data-types/string)

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

يعيد طابعًا زمنيًا بدقة المللي ثانية. إذا لم يكن UUID صالحًا من الإصدار 7، فستكون القيمة المُعادة `1970-01-01 00:00:00.000`. [`DateTime64(3)`](/ar/reference/data-types/datetime64)

**أمثلة**

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

```sql title=Query theme={null}
SELECT UUIDv7ToDateTime(toUUID('018f05c9-4ab8-7b86-b64e-c9f03fbd45d1'))
```

```response title=Response theme={null}
┌─UUIDv7ToDateTime(toUUID('018f05c9-4ab8-7b86-b64e-c9f03fbd45d1'))─┐
│                                          2024-04-22 15:30:29.048 │
└──────────────────────────────────────────────────────────────────┘
```

**مع منطقة زمنية**

```sql title=Query theme={null}
SELECT UUIDv7ToDateTime(toUUID('018f05c9-4ab8-7b86-b64e-c9f03fbd45d1'), 'America/New_York')
```

```response title=Response theme={null}
┌─UUIDv7ToDateTime(toUUID('018f05c9-4ab8-7b86-b64e-c9f03fbd45d1'), 'America/New_York')─┐
│                                                             2024-04-22 11:30:29.048 │
└─────────────────────────────────────────────────────────────────────────────────────┘
```

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

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

<Warning>
  هذه الدالة مُهملة، ولا يمكن استخدامها إلا إذا كان الإعداد [`allow_deprecated_snowflake_conversion_functions`](/ar/reference/settings/session-settings#allow_deprecated_snowflake_conversion_functions) مُمكّنًا.
  ستُزال هذه الدالة في وقت ما مستقبلًا.

  يُرجى استخدام الدالة [dateTime64ToSnowflakeID](#dateTime64ToSnowflakeID) بدلًا منها.
</Warning>

تحوّل [DateTime64](/ar/reference/data-types/datetime64) إلى أول [Snowflake ID](https://en.wikipedia.org/wiki/Snowflake_ID) عند الوقت المحدد.

**البنية**

```sql theme={null}
dateTime64ToSnowflake(value)
```

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

* `value` — تاريخ يتضمن وقتًا. [`DateTime64`](/ar/reference/data-types/datetime64)

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

تعيد قيمة الإدخال بعد تحويلها إلى أول Snowflake ID عند ذلك الوقت. [`Int64`](/ar/reference/data-types/int-uint)

**أمثلة**

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

```sql title=Query theme={null}
WITH toDateTime64('2021-08-15 18:57:56.492', 3, 'Asia/Shanghai') AS dt64 SELECT dateTime64ToSnowflake(dt64);
```

```response title=Response theme={null}
┌─dateTime64ToSnowflake(dt64)─┐
│         1426860704886947840 │
└─────────────────────────────┘
```

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

قُدِّمت في: v24.6.0

يحوّل قيمة [DateTime64](/ar/reference/data-types/datetime64) إلى أول [Snowflake ID](https://en.wikipedia.org/wiki/Snowflake_ID) في الوقت المحدد.

**الصيغة**

```sql theme={null}
dateTime64ToSnowflakeID(value[, epoch])
```

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

* `value` — تاريخ ووقت. [`DateTime64`](/ar/reference/data-types/datetime64)
* `epoch` — حقبة معرّف Snowflake بالمللي ثانية منذ 1970-01-01. القيمة الافتراضية هي 0 ‏(1970-01-01). وبالنسبة إلى حقبة Twitter/X ‏(2015-01-01)، أدخِل 1288834974657. [`UInt*`](/ar/reference/data-types/int-uint)

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

قيمة الإدخال بعد تحويلها إلى [`UInt64`](/ar/reference/data-types/int-uint)

**أمثلة**

**بسيط**

```sql title=Query theme={null}
SELECT dateTime64ToSnowflakeID(toDateTime64('2021-08-15 18:57:56', 3, 'Asia/Shanghai'))
```

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

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

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

<Warning>
  هذه الدالة مهملة، ولا يمكن استخدامها إلا إذا كان الإعداد [`allow_deprecated_snowflake_conversion_functions`](/ar/reference/settings/session-settings#allow_deprecated_snowflake_conversion_functions) مُمكّنًا.
  ستُزال هذه الدالة في وقت ما مستقبلًا.

  يُرجى استخدام الدالة [dateTimeToSnowflakeID](#dateTimeToSnowflakeID) بدلًا منها.
</Warning>

تحوّل قيمة [DateTime](/ar/reference/data-types/datetime) إلى أول [Snowflake ID](https://en.wikipedia.org/wiki/Snowflake_ID) عند الوقت المحدد.

**الصيغة**

```sql theme={null}
dateTimeToSnowflake(value)
```

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

* `value` — تاريخ ووقت. [`DateTime`](/ar/reference/data-types/datetime)

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

تعيد قيمة الإدخال على شكل أول Snowflake ID عند ذلك الوقت. [`Int64`](/ar/reference/data-types/int-uint)

**أمثلة**

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

```sql title=Query theme={null}
WITH toDateTime('2021-08-15 18:57:56', 'Asia/Shanghai') AS dt SELECT dateTimeToSnowflake(dt);
```

```response title=Response theme={null}
┌─dateTimeToSnowflake(dt)─┐
│     1426860702823350272 │
└─────────────────────────┘
```

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

قُدِّمت في: v24.6.0

تُحوِّل قيمة [DateTime](/ar/reference/data-types/datetime) إلى أول [معرّف Snowflake](https://en.wikipedia.org/wiki/Snowflake_ID) عند الوقت المحدد.

**الصيغة**

```sql theme={null}
dateTimeToSnowflakeID(value[, epoch])
```

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

* `value` — تاريخ ووقت. [`DateTime`](/ar/reference/data-types/datetime)
* `epoch` — حقبة لمعرّف Snowflake، بالمللي ثانية منذ 1970-01-01. القيمة الافتراضية هي 0 ‏(1970-01-01). بالنسبة إلى حقبة Twitter/X ‏(2015-01-01)، استخدم 1288834974657. [`UInt*`](/ar/reference/data-types/int-uint)

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

قيمة الإدخال بعد تحويلها إلى [`UInt64`](/ar/reference/data-types/int-uint)

**أمثلة**

**بسيط**

```sql title=Query theme={null}
SELECT dateTimeToSnowflakeID(toDateTime('2021-08-15 18:57:56', 'Asia/Shanghai'))
```

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

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

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

تحوِّل قيمة [DateTime](/ar/reference/data-types/datetime) إلى [UUIDv7](https://en.wikipedia.org/wiki/UUID#Version_7) عند الوقت المحدد.

راجع قسم ["توليد UUIDv7"](#uuidv7-generation) للاطلاع على تفاصيل بنية UUID، وإدارة العداد، وضمانات التزامن.

<Note>
  اعتبارًا من سبتمبر 2025، لا تزال معرّفات UUID من الإصدار 7 في حالة مسودة، وقد تتغير بنيتها في المستقبل.
</Note>

**الصيغة**

```sql theme={null}
dateTimeToUUIDv7(value)
```

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

* `value` — تاريخ ووقت. [`DateTime`](/ar/reference/data-types/datetime)

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

يُرجع UUIDv7. [`UUID`](/ar/reference/data-types/uuid)

**أمثلة**

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

```sql title=Query theme={null}
SELECT dateTimeToUUIDv7(toDateTime('2021-08-15 18:57:56', 'Asia/Shanghai'));
```

```response title=Response theme={null}
┌─dateTimeToUUIDv7(toDateTime('2021-08-15 18:57:56', 'Asia/Shanghai'))─┐
│ 018f05af-f4a8-778f-beee-1bedbc95c93b                                   │
└─────────────────────────────────────────────────────────────────────────┘
```

**عدة معرّفات UUID للطابع الزمني نفسه**

```sql title=Query theme={null}
SELECT dateTimeToUUIDv7(toDateTime('2021-08-15 18:57:56'));
SELECT dateTimeToUUIDv7(toDateTime('2021-08-15 18:57:56'));
```

```response title=Response theme={null}
┌─dateTimeToUUIDv7(t⋯08-15 18:57:56'))─┐
│ 017b4b2d-7720-76ed-ae44-bbcc23a8c550 │
└──────────────────────────────────────┘
┌─dateTimeToUUIDv7(t⋯08-15 18:57:56'))─┐
│ 017b4b2d-7720-76ed-ae44-bbcf71ed0fd3 │
└──────────────────────────────────────┘
```

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

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

تُنشئ [معرّف Snowflake](https://en.wikipedia.org/wiki/Snowflake_ID).

تضمن الدالة `generateSnowflakeID` أن يزداد حقل العداد داخل الطابع الزمني زيادةً رتيبة عبر جميع استدعاءات الدالة في الخيوط والاستعلامات التي تعمل بالتوازي.

راجع قسم ["توليد معرّف Snowflake"](#snowflake-id-generation) للاطلاع على تفاصيل التنفيذ.

**الصياغة**

```sql theme={null}
generateSnowflakeID([expr, [machine_id]])
```

**الوسائط**

* `expr` — [تعبير](/ar/reference/syntax#expressions) عشوائي يُستخدم لتجاوز [حذف التعبيرات الفرعية المشتركة](/ar/reference/functions/regular-functions/overview#common-subexpression-elimination) إذا جرى استدعاء الدالة عدة مرات ضمن استعلام. لا تؤثر قيمة التعبير على معرّف Snowflake المُعاد. اختياري. - `machine_id` — معرّف جهاز، وتُستخدم أقل 10 بتات منه. [Int64](/ar/reference/data-types/int-uint). اختياري.

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

يُرجع معرّف Snowflake. [`UInt64`](/ar/reference/data-types/int-uint)

**أمثلة**

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

```sql title=Query theme={null}
CREATE TABLE tab (id UInt64)
ENGINE = MergeTree()
ORDER BY tuple();

INSERT INTO tab SELECT generateSnowflakeID();

SELECT * FROM tab;
```

```response title=Response theme={null}
┌──────────────────id─┐
│ 7199081390080409600 │
└─────────────────────┘
```

**إنشاء عدة معرّفات Snowflake لكل صف**

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

```response title=Response theme={null}
┌─generateSnowflakeID(1)─┬─generateSnowflakeID(2)─┐
│    7199081609652224000 │    7199081609652224001 │
└────────────────────────┴────────────────────────┘
```

**باستخدام expression ومعرّف جهاز**

```sql title=Query theme={null}
SELECT generateSnowflakeID('expr', 1);
```

```response title=Response theme={null}
┌─generateSnowflakeID('expr', 1)─┐
│            7201148511606784002 │
└────────────────────────────────┘
```

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

أُضيف في: v1.1.0

يُنشئ [UUID](/ar/reference/data-types/uuid) من [الإصدار الرابع](https://tools.ietf.org/html/rfc4122#section-4.4).

**الصيغة**

```sql theme={null}
generateUUIDv4([expr])
```

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

* `expr` — اختياري. أي تعبير يُستخدم لتجاوز [حذف التعبيرات الفرعية المشتركة](/ar/reference/functions/regular-functions/overview#common-subexpression-elimination) عند استدعاء الدالة عدة مرات في استعلام. لا تؤثر قيمة هذا التعبير في UUID المُعاد.

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

يعيد UUIDv4. [`UUID`](/ar/reference/data-types/uuid)

**أمثلة**

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

```sql title=Query theme={null}
SELECT generateUUIDv4(number) FROM numbers(3);
```

```response title=Response theme={null}
┌─generateUUIDv4(number)───────────────┐
│ fcf19b77-a610-42c5-b3f5-a13c122f65b6 │
│ 07700d36-cb6b-4189-af1d-0972f23dc3bc │
│ 68838947-1583-48b0-b9b7-cf8268dd343d │
└──────────────────────────────────────┘
```

**حذف التعبيرات الفرعية المشتركة**

```sql title=Query theme={null}
SELECT generateUUIDv4(1), generateUUIDv4(1);
```

```response title=Response theme={null}
┌─generateUUIDv4(1)────────────────────┬─generateUUIDv4(2)────────────────────┐
│ 2d49dc6e-ddce-4cd0-afb8-790956df54c1 │ 2d49dc6e-ddce-4cd0-afb8-790956df54c1 │
└──────────────────────────────────────┴──────────────────────────────────────┘
```

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

مُقدَّم في: v24.5.0

يُنشئ [الإصدار 7](https://datatracker.ietf.org/doc/html/draft-peabody-dispatch-new-uuid-format-04) من [UUID](/ar/reference/data-types/uuid).

راجع قسم ["توليد UUIDv7"](#uuidv7-generation) للاطلاع على تفاصيل بنية UUID، وإدارة العداد، وضمانات التزامن.

<Note>
  اعتبارًا من سبتمبر 2025، لا تزال معرّفات UUID من الإصدار 7 في حالة مسودة، وقد تتغير بنيتها في المستقبل.
</Note>

**الصياغة**

```sql theme={null}
generateUUIDv7([expr])
```

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

* `expr` — اختياري. تعبير اعتباطي يُستخدم لتجاوز [حذف التعبيرات الفرعية المشتركة](/ar/reference/functions/regular-functions/overview#common-subexpression-elimination) إذا جرى استدعاء الدالة عدة مرات في استعلام. لا تؤثر قيمة هذا التعبير في UUID المُعاد. [`Any`](/ar/reference/data-types/index)

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

يعيد UUIDv7. [`UUID`](/ar/reference/data-types/uuid)

**أمثلة**

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

```sql title=Query theme={null}
SELECT generateUUIDv7(number) FROM numbers(3);
```

```response title=Response theme={null}
┌─generateUUIDv7(number)───────────────┐
│ 019947fb-5766-7ed0-b021-d906f8f7cebb │
│ 019947fb-5766-7ed0-b021-d9072d0d1e07 │
│ 019947fb-5766-7ed0-b021-d908dca2cf63 │
└──────────────────────────────────────┘
```

**حذف التعبيرات الفرعية المشتركة**

```sql title=Query theme={null}
SELECT generateUUIDv7(1), generateUUIDv7(1);
```

```response title=Response theme={null}
┌─generateUUIDv7(1)────────────────────┬─generateUUIDv7(1)────────────────────┐
│ 019947ff-0f87-7d88-ace0-8b5b3a66e0c1 │ 019947ff-0f87-7d88-ace0-8b5b3a66e0c1 │
└──────────────────────────────────────┴──────────────────────────────────────┘
```

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

أُضيف في: v24.6.0

يعيد مكوّن الطابع الزمني من [معرّف Snowflake](https://en.wikipedia.org/wiki/Snowflake_ID) كقيمة من النوع [DateTime](/ar/reference/data-types/datetime).

**البنية**

```sql theme={null}
snowflakeIDToDateTime(value[, epoch[, time_zone]])
```

**الوسائط**

* `value` — معرّف Snowflake. [`UInt64`](/ar/reference/data-types/int-uint)
* `epoch` — اختياري. حقبة معرّف Snowflake بالمللي ثانية منذ 1970-01-01. القيمة الافتراضية هي 0 ‏(1970-01-01). لحقبة Twitter/X ‏(2015-01-01)، مرّر 1288834974657. [`UInt*`](/ar/reference/data-types/int-uint)
* `time_zone` — اختياري. [المنطقة الزمنية](/ar/reference/settings/server-settings/settings#timezone). تحلّل الدالة `time_string` وفقًا للمنطقة الزمنية. [`String`](/ar/reference/data-types/string)

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

تعيد مكوّن الطابع الزمني لـ `value`. [`DateTime`](/ar/reference/data-types/datetime)

**أمثلة**

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

```sql title=Query theme={null}
SELECT snowflakeIDToDateTime(7204436857747984384) AS res
```

```response title=Response theme={null}
┌─────────────────res─┐
│ 2024-06-06 10:59:58 │
└─────────────────────┘
```

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

قُدِّمت في: v24.6.0

تعيد مكوّن الطابع الزمني في [معرّف Snowflake](https://en.wikipedia.org/wiki/Snowflake_ID) كقيمة من النوع [DateTime64](/ar/reference/data-types/datetime64).

**الصيغة**

```sql theme={null}
snowflakeIDToDateTime64(value[, epoch[, time_zone]])
```

**الوسائط**

* `value` — معرّف Snowflake. [`UInt64`](/ar/reference/data-types/int-uint)
* `epoch` — اختياري. حقبة معرّف Snowflake، بالمللي ثانية منذ 1970-01-01. القيمة الافتراضية هي 0 ‏(1970-01-01). بالنسبة إلى حقبة Twitter/X ‏(2015-01-01)، أدخِل 1288834974657. [`UInt*`](/ar/reference/data-types/int-uint)
* `time_zone` — اختياري. [المنطقة الزمنية](/ar/reference/settings/server-settings/settings#timezone). تُحلِّل الدالة `time_string` وفقًا للمنطقة الزمنية. [`String`](/ar/reference/data-types/string)

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

تعيد مكوّن الطابع الزمني لـ `value` على هيئة `DateTime64` مع scale = 3، أي بدقة المللي ثانية. [`DateTime64`](/ar/reference/data-types/datetime64)

**أمثلة**

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

```sql title=Query theme={null}
SELECT snowflakeIDToDateTime64(7204436857747984384) AS res
```

```response title=Response theme={null}
┌─────────────────res─┐
│ 2024-06-06 10:59:58 │
└─────────────────────┘
```

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

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

<Warning>
  هذه الدالة مهملة، ولا يمكن استخدامها إلا إذا كان الإعداد [`allow_deprecated_snowflake_conversion_functions`](/ar/reference/settings/session-settings#allow_deprecated_snowflake_conversion_functions) مفعّلًا.
  ستُزال الدالة في مرحلة ما مستقبلًا.

  يُرجى استخدام الدالة [`snowflakeIDToDateTime`](#snowflakeIDToDateTime) بدلًا منها.
</Warning>

تستخرج مكوّن الطابع الزمني من [معرّف Snowflake](https://en.wikipedia.org/wiki/Snowflake_ID) بتنسيق [DateTime](/ar/reference/data-types/datetime).

**الصيغة**

```sql theme={null}
snowflakeToDateTime(value[, time_zone])
```

**الوسائط**

* `value` — معرّف Snowflake. [`Int64`](/ar/reference/data-types/int-uint)
* `time_zone` — اختياري. [المنطقة الزمنية](/ar/reference/settings/server-settings/settings#timezone). تفسّر الدالة `time_string` وفقًا للمنطقة الزمنية. [`String`](/ar/reference/data-types/string)

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

تعيد مكوّن الطابع الزمني لـ `value`. [`DateTime`](/ar/reference/data-types/datetime)

**أمثلة**

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

```sql title=Query theme={null}
SELECT snowflakeToDateTime(CAST('1426860702823350272', 'Int64'), 'UTC');
```

```response title=Response theme={null}
┌─snowflakeToDateTime(CAST('1426860702823350272', 'Int64'), 'UTC')─┐
│                                              2021-08-15 10:57:56 │
└──────────────────────────────────────────────────────────────────┘
```

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

طُرحت في: v21.10.0

<Warning>
  هذه الدالة متقادمة ولا يمكن استخدامها إلا إذا كان الإعداد [`allow_deprecated_snowflake_conversion_functions`](/ar/reference/settings/session-settings#allow_deprecated_snowflake_conversion_functions) مفعّلًا.
  ستُزال هذه الدالة في وقت ما مستقبلًا.

  يُرجى استخدام الدالة [`snowflakeIDToDateTime64`](#snowflakeIDToDateTime64) بدلًا منها.
</Warning>

تستخرج مكوّن الطابع الزمني من [معرّف Snowflake](https://en.wikipedia.org/wiki/Snowflake_ID) بتنسيق [DateTime64](/ar/reference/data-types/datetime64).

**البنية**

```sql theme={null}
snowflakeToDateTime64(value[, time_zone])
```

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

* `value` — معرّف Snowflake. [`Int64`](/ar/reference/data-types/int-uint)
* `time_zone` — اختياري. [المنطقة الزمنية](/ar/reference/settings/server-settings/settings#timezone). تُحلِّل الدالة `time_string` وفقًا للمنطقة الزمنية. [`String`](/ar/reference/data-types/string)

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

تعيد الدالة مكوّن الطابع الزمني في `value`. [`DateTime64(3)`](/ar/reference/data-types/datetime64)

**أمثلة**

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

```sql title=Query theme={null}
SELECT snowflakeToDateTime64(CAST('1426860802823350272', 'Int64'), 'UTC');
```

```response title=Response theme={null}
┌─snowflakeToDateTime64(CAST('1426860802823350272', 'Int64'), 'UTC')─┐
│                                            2021-08-15 10:58:19.841 │
└────────────────────────────────────────────────────────────────────┘
```

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

أُضيف في: v21.1.0

يحوّل قيمة من نوع String إلى نوع UUID. وإذا فشل التحويل، فسيُعيد قيمة UUID افتراضية بدلًا من إصدار error.

تحاول هذه الدالة تحليل سلسلة مكوّنة من 36 حرفًا بتنسيق UUID القياسي (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx).
إذا تعذّر تحويل السلسلة إلى UUID صالح، فستُعيد الدالة قيمة UUID الافتراضية المُقدَّمة.

**البنية**

```sql theme={null}
toUUIDOrDefault(string, default)
```

**الوسائط**

* `string` — سلسلة نصية مكوّنة من 36 حرفًا أو FixedString(36) لتحويلها إلى UUID. - `default` — قيمة UUID التي ستُعاد إذا تعذّر تحويل الوسيط الأول إلى النوع UUID.

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

يعيد قيمة UUID المحوَّلة عند نجاح العملية، أو قيمة UUID الافتراضية إذا فشل التحويل. [`UUID`](/ar/reference/data-types/uuid)

**أمثلة**

**يعيد التحويل الناجح قيمة UUID المُحلَّلة**

```sql title=Query theme={null}
SELECT toUUIDOrDefault('61f0c404-5cb3-11e7-907b-a6006ad3dba0', toUUID('59f0c404-5cb3-11e7-907b-a6006ad3dba0'));
```

```response title=Response theme={null}
┌─toUUIDOrDefault('61f0c404-5cb3-11e7-907b-a6006ad3dba0', toUUID('59f0c404-5cb3-11e7-907b-a6006ad3dba0'))─┐
│ 61f0c404-5cb3-11e7-907b-a6006ad3dba0                                                                     │
└──────────────────────────────────────────────────────────────────────────────────────────────────────────┘
```

**يُرجِع التحويل الفاشل قيمة UUID الافتراضية**

```sql title=Query theme={null}
SELECT toUUIDOrDefault('-----61f0c404-5cb3-11e7-907b-a6006ad3dba0', toUUID('59f0c404-5cb3-11e7-907b-a6006ad3dba0'));
```

```response title=Response theme={null}
┌─toUUIDOrDefault('-----61f0c404-5cb3-11e7-907b-a6006ad3dba0', toUUID('59f0c404-5cb3-11e7-907b-a6006ad3dba0'))─┐
│ 59f0c404-5cb3-11e7-907b-a6006ad3dba0                                                                          │
└───────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
```

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

أُضيفت في: v20.12.0

تحوِّل قيمة إدخال إلى قيمة من النوع `UUID`، لكنها تُرجع `NULL` في حال حدوث خطأ.

تشبه [`toUUID`](/ar/reference/functions/regular-functions/type-conversion-functions#toUUID)، لكنها تُرجع `NULL` بدلًا من إطلاق استثناء عند حدوث أخطاء في التحويل.

الوسيطات المدعومة:

* التمثيلات النصية لـ UUID بالتنسيق القياسي (8-4-4-4-12 رقمًا سداسيّ عشري).
* التمثيلات النصية لـ UUID من دون واصلات (32 رقمًا سداسيّ عشري).

الوسيطات غير المدعومة (تُرجع `NULL`):

* تنسيقات سلاسل غير صالحة.
* أنواع غير نصية.
* UUIDs غير مكتملة التكوين.

**البنية**

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

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

* `x` — تمثيل نصي لقيمة UUID. [`String`](/ar/reference/data-types/string)

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

تُرجِع قيمة UUID عند النجاح، وإلا `NULL`. [`UUID`](/ar/reference/data-types/uuid) أو [`NULL`](/ar/reference/syntax#null)

**أمثلة**

**أمثلة الاستخدام**

```sql title=Query theme={null}
SELECT
    toUUIDOrNull('550e8400-e29b-41d4-a716-446655440000') AS valid_uuid,
    toUUIDOrNull('invalid-uuid') AS invalid_uuid
```

```response title=Response theme={null}
┌─valid_uuid───────────────────────────┬─invalid_uuid─┐
│ 550e8400-e29b-41d4-a716-446655440000 │         ᴺᵁᴸᴸ │
└──────────────────────────────────────┴──────────────┘
```