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

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

​

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

​

توليد UUIDv7

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

 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                             |
└─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┘

​

إنشاء Snowflake ID

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

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

 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    |
└─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┘

​

UUIDNumToString

ظهر في: v1.1.0

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

البنية

UUIDNumToString(binary[, variant])

الوسائط

• binary — التمثيل الثنائي لـ UUID. FixedString(16)
• variant — المتغيّر كما هو محدد في RFC4122. 1 = Big-endian (الافتراضي)، 2 = Microsoft. (U)Int*

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

يُرجع UUID على هيئة سلسلة نصية. String

أمثلة

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

Query

SELECT
    'a/<@];!~p{jTj={)' AS bytes,
    UUIDNumToString(toFixedString(bytes, 16)) AS uuid

Response

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

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

Query

SELECT
    '@</a;]~!p{jTj={)' AS bytes,
    UUIDNumToString(toFixedString(bytes, 16), 2) AS uuid

Response

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

​

UUIDStringToNum

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

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

البنية

UUIDStringToNum(string[, variant = 1])

الوسائط

• string — سلسلة نصية أو سلسلة ثابتة بطول 36 حرفًا String أو FixedString(36)
• variant — قيمة المتغيّر كما هي محددة في RFC4122. 1 = Big-endian (الافتراضي)، 2 = Microsoft. (U)Int*

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

تعيد التمثيل الثنائي لـ string. FixedString(16)

أمثلة

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

Query

SELECT
    '612f3c40-5d3b-217e-707b-6a546a3d7b29' AS uuid,
    UUIDStringToNum(uuid) AS bytes

Response

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

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

Query

SELECT
    '612f3c40-5d3b-217e-707b-6a546a3d7b29' AS uuid,
    UUIDStringToNum(uuid, 2) AS bytes

Response

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

​

UUIDToNum

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

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

الصياغة

UUIDToNum(uuid[, variant = 1])

المعاملات

• uuid — UUID. String أو FixedString
• variant — قيمة المتغيّر كما هي محددة في RFC4122. 1 = Big-endian (الافتراضي)، 2 = Microsoft. (U)Int*

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

يعيد تمثيلاً ثنائياً لـ UUID. FixedString(16)

أمثلة

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

Query

SELECT
    toUUID('612f3c40-5d3b-217e-707b-6a546a3d7b29') AS uuid,
    UUIDToNum(uuid) AS bytes

Response

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

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

Query

SELECT
    toUUID('612f3c40-5d3b-217e-707b-6a546a3d7b29') AS uuid,
    UUIDToNum(uuid, 2) AS bytes

Response

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

​

UUIDv7ToDateTime

أُضيف في: v24.5.0

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

البنية

UUIDv7ToDateTime(uuid[, timezone])

الوسائط

• uuid — UUID الإصدار 7. String
• timezone — اختياري. اسم المنطقة الزمنية للقيمة المُعادة. String

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

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

أمثلة

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

Query

SELECT UUIDv7ToDateTime(toUUID('018f05c9-4ab8-7b86-b64e-c9f03fbd45d1'))

Response

┌─UUIDv7ToDateTime(toUUID('018f05c9-4ab8-7b86-b64e-c9f03fbd45d1'))─┐
│                                          2024-04-22 15:30:29.048 │
└──────────────────────────────────────────────────────────────────┘

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

Query

SELECT UUIDv7ToDateTime(toUUID('018f05c9-4ab8-7b86-b64e-c9f03fbd45d1'), 'America/New_York')

Response

┌─UUIDv7ToDateTime(toUUID('018f05c9-4ab8-7b86-b64e-c9f03fbd45d1'), 'America/New_York')─┐
│                                                             2024-04-22 11:30:29.048 │
└─────────────────────────────────────────────────────────────────────────────────────┘

​

dateTime64ToSnowflake

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

هذه الدالة مُهملة، ولا يمكن استخدامها إلا إذا كان الإعداد allow_deprecated_snowflake_conversion_functions مُمكّنًا. ستُزال هذه الدالة في وقت ما مستقبلًا.

يُرجى استخدام الدالة dateTime64ToSnowflakeID بدلًا منها.

تحوّل DateTime64 إلى أول Snowflake ID عند الوقت المحدد.

البنية

dateTime64ToSnowflake(value)

المعاملات

• value — تاريخ يتضمن وقتًا. DateTime64

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

تعيد قيمة الإدخال بعد تحويلها إلى أول Snowflake ID عند ذلك الوقت. Int64

أمثلة

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

Query

WITH toDateTime64('2021-08-15 18:57:56.492', 3, 'Asia/Shanghai') AS dt64 SELECT dateTime64ToSnowflake(dt64);

Response

┌─dateTime64ToSnowflake(dt64)─┐
│         1426860704886947840 │
└─────────────────────────────┘

​

dateTime64ToSnowflakeID

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

يحوّل قيمة DateTime64 إلى أول Snowflake ID في الوقت المحدد.

الصيغة

dateTime64ToSnowflakeID(value[, epoch])

الوسيطات

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

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

قيمة الإدخال بعد تحويلها إلى UInt64

أمثلة

بسيط

Query

SELECT dateTime64ToSnowflakeID(toDateTime64('2021-08-15 18:57:56', 3, 'Asia/Shanghai'))

Response

6832626394434895872

​

dateTimeToSnowflake

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

هذه الدالة مهملة، ولا يمكن استخدامها إلا إذا كان الإعداد allow_deprecated_snowflake_conversion_functions مُمكّنًا. ستُزال هذه الدالة في وقت ما مستقبلًا.

يُرجى استخدام الدالة dateTimeToSnowflakeID بدلًا منها.

تحوّل قيمة DateTime إلى أول Snowflake ID عند الوقت المحدد.

الصيغة

dateTimeToSnowflake(value)

المعاملات

• value — تاريخ ووقت. DateTime

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

تعيد قيمة الإدخال على شكل أول Snowflake ID عند ذلك الوقت. Int64

أمثلة

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

Query

WITH toDateTime('2021-08-15 18:57:56', 'Asia/Shanghai') AS dt SELECT dateTimeToSnowflake(dt);

Response

┌─dateTimeToSnowflake(dt)─┐
│     1426860702823350272 │
└─────────────────────────┘

​

dateTimeToSnowflakeID

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

تُحوِّل قيمة DateTime إلى أول معرّف Snowflake عند الوقت المحدد.

الصيغة

dateTimeToSnowflakeID(value[, epoch])

الوسيطات

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

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

قيمة الإدخال بعد تحويلها إلى UInt64

أمثلة

بسيط

Query

SELECT dateTimeToSnowflakeID(toDateTime('2021-08-15 18:57:56', 'Asia/Shanghai'))

Response

6832626392367104000

​

dateTimeToUUIDv7

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

تحوِّل قيمة DateTime إلى UUIDv7 عند الوقت المحدد.

راجع قسم “توليد UUIDv7” للاطلاع على تفاصيل بنية UUID، وإدارة العداد، وضمانات التزامن.

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

الصيغة

dateTimeToUUIDv7(value)

المعاملات

• value — تاريخ ووقت. DateTime

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

يُرجع UUIDv7. UUID

أمثلة

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

Query

SELECT dateTimeToUUIDv7(toDateTime('2021-08-15 18:57:56', 'Asia/Shanghai'));

Response

┌─dateTimeToUUIDv7(toDateTime('2021-08-15 18:57:56', 'Asia/Shanghai'))─┐
│ 018f05af-f4a8-778f-beee-1bedbc95c93b                                   │
└─────────────────────────────────────────────────────────────────────────┘

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

Query

SELECT dateTimeToUUIDv7(toDateTime('2021-08-15 18:57:56'));
SELECT dateTimeToUUIDv7(toDateTime('2021-08-15 18:57:56'));

Response

┌─dateTimeToUUIDv7(t⋯08-15 18:57:56'))─┐
│ 017b4b2d-7720-76ed-ae44-bbcc23a8c550 │
└──────────────────────────────────────┘
┌─dateTimeToUUIDv7(t⋯08-15 18:57:56'))─┐
│ 017b4b2d-7720-76ed-ae44-bbcf71ed0fd3 │
└──────────────────────────────────────┘

​

generateSnowflakeID

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

تُنشئ معرّف Snowflake.

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

راجع قسم “توليد معرّف Snowflake” للاطلاع على تفاصيل التنفيذ.

الصياغة

generateSnowflakeID([expr, [machine_id]])

الوسائط

• expr — تعبير عشوائي يُستخدم لتجاوز حذف التعبيرات الفرعية المشتركة إذا جرى استدعاء الدالة عدة مرات ضمن استعلام. لا تؤثر قيمة التعبير على معرّف Snowflake المُعاد. اختياري. - machine_id — معرّف جهاز، وتُستخدم أقل 10 بتات منه. Int64. اختياري.

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

يُرجع معرّف Snowflake. UInt64

أمثلة

مثال استخدام

Query

CREATE TABLE tab (id UInt64)
ENGINE = MergeTree()
ORDER BY tuple();

INSERT INTO tab SELECT generateSnowflakeID();

SELECT * FROM tab;

Response

┌──────────────────id─┐
│ 7199081390080409600 │
└─────────────────────┘

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

Query

SELECT generateSnowflakeID(1), generateSnowflakeID(2);

Response

┌─generateSnowflakeID(1)─┬─generateSnowflakeID(2)─┐
│    7199081609652224000 │    7199081609652224001 │
└────────────────────────┴────────────────────────┘

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

Query

SELECT generateSnowflakeID('expr', 1);

Response

┌─generateSnowflakeID('expr', 1)─┐
│            7201148511606784002 │
└────────────────────────────────┘

​

generateUUIDv4

أُضيف في: v1.1.0

يُنشئ UUID من الإصدار الرابع.

الصيغة

generateUUIDv4([expr])

الوسيطات

• expr — اختياري. أي تعبير يُستخدم لتجاوز حذف التعبيرات الفرعية المشتركة عند استدعاء الدالة عدة مرات في استعلام. لا تؤثر قيمة هذا التعبير في UUID المُعاد.

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

يعيد UUIDv4. UUID

أمثلة

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

Query

SELECT generateUUIDv4(number) FROM numbers(3);

Response

┌─generateUUIDv4(number)───────────────┐
│ fcf19b77-a610-42c5-b3f5-a13c122f65b6 │
│ 07700d36-cb6b-4189-af1d-0972f23dc3bc │
│ 68838947-1583-48b0-b9b7-cf8268dd343d │
└──────────────────────────────────────┘

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

Query

SELECT generateUUIDv4(1), generateUUIDv4(1);

Response

┌─generateUUIDv4(1)────────────────────┬─generateUUIDv4(2)────────────────────┐
│ 2d49dc6e-ddce-4cd0-afb8-790956df54c1 │ 2d49dc6e-ddce-4cd0-afb8-790956df54c1 │
└──────────────────────────────────────┴──────────────────────────────────────┘

​

generateUUIDv7

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

يُنشئ الإصدار 7 من UUID.

راجع قسم “توليد UUIDv7” للاطلاع على تفاصيل بنية UUID، وإدارة العداد، وضمانات التزامن.

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

الصياغة

generateUUIDv7([expr])

الوسيطات

• expr — اختياري. تعبير اعتباطي يُستخدم لتجاوز حذف التعبيرات الفرعية المشتركة إذا جرى استدعاء الدالة عدة مرات في استعلام. لا تؤثر قيمة هذا التعبير في UUID المُعاد. Any

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

يعيد UUIDv7. UUID

أمثلة

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

Query

SELECT generateUUIDv7(number) FROM numbers(3);

Response

┌─generateUUIDv7(number)───────────────┐
│ 019947fb-5766-7ed0-b021-d906f8f7cebb │
│ 019947fb-5766-7ed0-b021-d9072d0d1e07 │
│ 019947fb-5766-7ed0-b021-d908dca2cf63 │
└──────────────────────────────────────┘

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

Query

SELECT generateUUIDv7(1), generateUUIDv7(1);

Response

┌─generateUUIDv7(1)────────────────────┬─generateUUIDv7(1)────────────────────┐
│ 019947ff-0f87-7d88-ace0-8b5b3a66e0c1 │ 019947ff-0f87-7d88-ace0-8b5b3a66e0c1 │
└──────────────────────────────────────┴──────────────────────────────────────┘

​

snowflakeIDToDateTime

أُضيف في: v24.6.0

يعيد مكوّن الطابع الزمني من معرّف Snowflake كقيمة من النوع DateTime.

البنية

snowflakeIDToDateTime(value[, epoch[, time_zone]])

الوسائط

• value — معرّف Snowflake. UInt64
• epoch — اختياري. حقبة معرّف Snowflake بالمللي ثانية منذ 1970-01-01. القيمة الافتراضية هي 0 ‏(1970-01-01). لحقبة Twitter/X ‏(2015-01-01)، مرّر 1288834974657. UInt*
• time_zone — اختياري. المنطقة الزمنية. تحلّل الدالة time_string وفقًا للمنطقة الزمنية. String

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

تعيد مكوّن الطابع الزمني لـ value. DateTime

أمثلة

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

Query

SELECT snowflakeIDToDateTime(7204436857747984384) AS res

Response

┌─────────────────res─┐
│ 2024-06-06 10:59:58 │
└─────────────────────┘

​

snowflakeIDToDateTime64

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

تعيد مكوّن الطابع الزمني في معرّف Snowflake كقيمة من النوع DateTime64.

الصيغة

snowflakeIDToDateTime64(value[, epoch[, time_zone]])

الوسائط

• value — معرّف Snowflake. UInt64
• epoch — اختياري. حقبة معرّف Snowflake، بالمللي ثانية منذ 1970-01-01. القيمة الافتراضية هي 0 ‏(1970-01-01). بالنسبة إلى حقبة Twitter/X ‏(2015-01-01)، أدخِل 1288834974657. UInt*
• time_zone — اختياري. المنطقة الزمنية. تُحلِّل الدالة time_string وفقًا للمنطقة الزمنية. String

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

تعيد مكوّن الطابع الزمني لـ value على هيئة DateTime64 مع scale = 3، أي بدقة المللي ثانية. DateTime64

أمثلة

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

Query

SELECT snowflakeIDToDateTime64(7204436857747984384) AS res

Response

┌─────────────────res─┐
│ 2024-06-06 10:59:58 │
└─────────────────────┘

​

snowflakeToDateTime

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

هذه الدالة مهملة، ولا يمكن استخدامها إلا إذا كان الإعداد allow_deprecated_snowflake_conversion_functions مفعّلًا. ستُزال الدالة في مرحلة ما مستقبلًا.

يُرجى استخدام الدالة snowflakeIDToDateTime بدلًا منها.

تستخرج مكوّن الطابع الزمني من معرّف Snowflake بتنسيق DateTime.

الصيغة

snowflakeToDateTime(value[, time_zone])

الوسائط

• value — معرّف Snowflake. Int64
• time_zone — اختياري. المنطقة الزمنية. تفسّر الدالة time_string وفقًا للمنطقة الزمنية. String

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

تعيد مكوّن الطابع الزمني لـ value. DateTime

أمثلة

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

Query

SELECT snowflakeToDateTime(CAST('1426860702823350272', 'Int64'), 'UTC');

Response

┌─snowflakeToDateTime(CAST('1426860702823350272', 'Int64'), 'UTC')─┐
│                                              2021-08-15 10:57:56 │
└──────────────────────────────────────────────────────────────────┘

​

snowflakeToDateTime64

طُرحت في: v21.10.0

هذه الدالة متقادمة ولا يمكن استخدامها إلا إذا كان الإعداد allow_deprecated_snowflake_conversion_functions مفعّلًا. ستُزال هذه الدالة في وقت ما مستقبلًا.

يُرجى استخدام الدالة snowflakeIDToDateTime64 بدلًا منها.

تستخرج مكوّن الطابع الزمني من معرّف Snowflake بتنسيق DateTime64.

البنية

snowflakeToDateTime64(value[, time_zone])

الوسيطات

• value — معرّف Snowflake. Int64
• time_zone — اختياري. المنطقة الزمنية. تُحلِّل الدالة time_string وفقًا للمنطقة الزمنية. String

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

تعيد الدالة مكوّن الطابع الزمني في value. DateTime64(3)

أمثلة

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

Query

SELECT snowflakeToDateTime64(CAST('1426860802823350272', 'Int64'), 'UTC');

Response

┌─snowflakeToDateTime64(CAST('1426860802823350272', 'Int64'), 'UTC')─┐
│                                            2021-08-15 10:58:19.841 │
└────────────────────────────────────────────────────────────────────┘

​

toUUIDOrDefault

أُضيف في: v21.1.0

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

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

البنية

toUUIDOrDefault(string, default)

الوسائط

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

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

يعيد قيمة UUID المحوَّلة عند نجاح العملية، أو قيمة UUID الافتراضية إذا فشل التحويل. UUID

أمثلة

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

Query

SELECT toUUIDOrDefault('61f0c404-5cb3-11e7-907b-a6006ad3dba0', toUUID('59f0c404-5cb3-11e7-907b-a6006ad3dba0'));

Response

┌─toUUIDOrDefault('61f0c404-5cb3-11e7-907b-a6006ad3dba0', toUUID('59f0c404-5cb3-11e7-907b-a6006ad3dba0'))─┐
│ 61f0c404-5cb3-11e7-907b-a6006ad3dba0                                                                     │
└──────────────────────────────────────────────────────────────────────────────────────────────────────────┘

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

Query

SELECT toUUIDOrDefault('-----61f0c404-5cb3-11e7-907b-a6006ad3dba0', toUUID('59f0c404-5cb3-11e7-907b-a6006ad3dba0'));

Response

┌─toUUIDOrDefault('-----61f0c404-5cb3-11e7-907b-a6006ad3dba0', toUUID('59f0c404-5cb3-11e7-907b-a6006ad3dba0'))─┐
│ 59f0c404-5cb3-11e7-907b-a6006ad3dba0                                                                          │
└───────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

​

toUUIDOrNull

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

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

تشبه toUUID، لكنها تُرجع NULL بدلًا من إطلاق استثناء عند حدوث أخطاء في التحويل.

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

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

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

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

البنية

toUUIDOrNull(x)

الوسيطات

• x — تمثيل نصي لقيمة UUID. String

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

تُرجِع قيمة UUID عند النجاح، وإلا NULL. UUID أو NULL

أمثلة

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

Query

SELECT
    toUUIDOrNull('550e8400-e29b-41d4-a716-446655440000') AS valid_uuid,
    toUUIDOrNull('invalid-uuid') AS invalid_uuid

Response

┌─valid_uuid───────────────────────────┬─invalid_uuid─┐
│ 550e8400-e29b-41d4-a716-446655440000 │         ᴺᵁᴸᴸ │
└──────────────────────────────────────┴──────────────┘