يحتوي 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 |
└─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┘
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 |
└─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┘
variant (ويكون Big-endian افتراضيًا)، ويُرجع سلسلة نصية تتكوّن من 36 حرفًا بتنسيق نصي.
البنية
UUIDNumToString(binary[, variant])
String
أمثلة
مثال على الاستخدام
SELECT
'a/<@];!~p{jTj={)' AS bytes,
UUIDNumToString(toFixedString(bytes, 16)) AS uuid
┌─bytes────────────┬─uuid─────────────────────────────────┐
│ a/<@];!~p{jTj={) │ 612f3c40-5d3b-217e-707b-6a546a3d7b29 │
└──────────────────┴──────────────────────────────────────┘
SELECT
'@</a;]~!p{jTj={)' AS bytes,
UUIDNumToString(toFixedString(bytes, 16), 2) AS uuid
┌─bytes────────────┬─uuid─────────────────────────────────┐
│ @</a;]~!p{jTj={) │ 612f3c40-5d3b-217e-707b-6a546a3d7b29 │
└──────────────────┴──────────────────────────────────────┘
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx، وتُرجع FixedString(16) كتمثيلها الثنائي، مع إمكانية تحديد التنسيق اختياريًا باستخدام variant (Big-endian افتراضيًا).
البنية
UUIDStringToNum(string[, variant = 1])
string. FixedString(16)
أمثلة
مثال على الاستخدام
SELECT
'612f3c40-5d3b-217e-707b-6a546a3d7b29' AS uuid,
UUIDStringToNum(uuid) AS bytes
┌─uuid─────────────────────────────────┬─bytes────────────┐
│ 612f3c40-5d3b-217e-707b-6a546a3d7b29 │ a/<@];!~p{jTj={) │
└──────────────────────────────────────┴──────────────────┘
SELECT
'612f3c40-5d3b-217e-707b-6a546a3d7b29' AS uuid,
UUIDStringToNum(uuid, 2) AS bytes
┌─uuid─────────────────────────────────┬─bytes────────────┐
│ 612f3c40-5d3b-217e-707b-6a546a3d7b29 │ @</a;]~!p{jTj={) │
└──────────────────────────────────────┴──────────────────┘
variant (ويكون Big-endian افتراضيًا).
تستبدل هذه الدالة استدعاءات دالتين منفصلتين هما UUIDStringToNum(toString(uuid))، لذلك لا حاجة إلى أي تحويل وسيط من UUID إلى سلسلة لاستخراج البايتات من UUID.
الصياغة
UUIDToNum(uuid[, variant = 1])
FixedString(16)
أمثلة
مثال على الاستخدام
SELECT
toUUID('612f3c40-5d3b-217e-707b-6a546a3d7b29') AS uuid,
UUIDToNum(uuid) AS bytes
┌─uuid─────────────────────────────────┬─bytes────────────┐
│ 612f3c40-5d3b-217e-707b-6a546a3d7b29 │ a/<@];!~p{jTj={) │
└──────────────────────────────────────┴──────────────────┘
SELECT
toUUID('612f3c40-5d3b-217e-707b-6a546a3d7b29') AS uuid,
UUIDToNum(uuid, 2) AS bytes
┌─uuid─────────────────────────────────┬─bytes────────────┐
│ 612f3c40-5d3b-217e-707b-6a546a3d7b29 │ @</a;]~!p{jTj={) │
└──────────────────────────────────────┴──────────────────┘
UUIDv7ToDateTime(uuid[, timezone])
1970-01-01 00:00:00.000. DateTime64(3)
أمثلة
مثال على الاستخدام
SELECT UUIDv7ToDateTime(toUUID('018f05c9-4ab8-7b86-b64e-c9f03fbd45d1'))
┌─UUIDv7ToDateTime(toUUID('018f05c9-4ab8-7b86-b64e-c9f03fbd45d1'))─┐
│ 2024-04-22 15:30:29.048 │
└──────────────────────────────────────────────────────────────────┘
SELECT UUIDv7ToDateTime(toUUID('018f05c9-4ab8-7b86-b64e-c9f03fbd45d1'), 'America/New_York')
┌─UUIDv7ToDateTime(toUUID('018f05c9-4ab8-7b86-b64e-c9f03fbd45d1'), 'America/New_York')─┐
│ 2024-04-22 11:30:29.048 │
└─────────────────────────────────────────────────────────────────────────────────────┘
dateTime64ToSnowflake(value)
Int64
أمثلة
مثال على الاستخدام
WITH toDateTime64('2021-08-15 18:57:56.492', 3, 'Asia/Shanghai') AS dt64 SELECT dateTime64ToSnowflake(dt64);
┌─dateTime64ToSnowflake(dt64)─┐
│ 1426860704886947840 │
└─────────────────────────────┘
dateTime64ToSnowflakeID(value[, epoch])
value — تاريخ ووقت. DateTime64epoch — حقبة معرّف Snowflake بالمللي ثانية منذ 1970-01-01. القيمة الافتراضية هي 0 (1970-01-01). وبالنسبة إلى حقبة Twitter/X (2015-01-01)، أدخِل 1288834974657. UInt*
القيمة المعادة
قيمة الإدخال بعد تحويلها إلى UInt64
أمثلة
بسيط
SELECT dateTime64ToSnowflakeID(toDateTime64('2021-08-15 18:57:56', 3, 'Asia/Shanghai'))
dateTimeToSnowflake(value)
Int64
أمثلة
مثال على الاستخدام
WITH toDateTime('2021-08-15 18:57:56', 'Asia/Shanghai') AS dt SELECT dateTimeToSnowflake(dt);
┌─dateTimeToSnowflake(dt)─┐
│ 1426860702823350272 │
└─────────────────────────┘
dateTimeToSnowflakeID(value[, epoch])
value — تاريخ ووقت. DateTimeepoch — حقبة لمعرّف Snowflake، بالمللي ثانية منذ 1970-01-01. القيمة الافتراضية هي 0 (1970-01-01). بالنسبة إلى حقبة Twitter/X (2015-01-01)، استخدم 1288834974657. UInt*
القيمة المُعادة
قيمة الإدخال بعد تحويلها إلى UInt64
أمثلة
بسيط
SELECT dateTimeToSnowflakeID(toDateTime('2021-08-15 18:57:56', 'Asia/Shanghai'))
اعتبارًا من سبتمبر 2025، لا تزال معرّفات UUID من الإصدار 7 في حالة مسودة، وقد تتغير بنيتها في المستقبل.
UUID
أمثلة
مثال على الاستخدام
SELECT dateTimeToUUIDv7(toDateTime('2021-08-15 18:57:56', 'Asia/Shanghai'));
┌─dateTimeToUUIDv7(toDateTime('2021-08-15 18:57:56', 'Asia/Shanghai'))─┐
│ 018f05af-f4a8-778f-beee-1bedbc95c93b │
└─────────────────────────────────────────────────────────────────────────┘
SELECT dateTimeToUUIDv7(toDateTime('2021-08-15 18:57:56'));
SELECT dateTimeToUUIDv7(toDateTime('2021-08-15 18:57:56'));
┌─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 أن يزداد حقل العداد داخل الطابع الزمني زيادةً رتيبة عبر جميع استدعاءات الدالة في الخيوط والاستعلامات التي تعمل بالتوازي.
راجع قسم “توليد معرّف Snowflake” للاطلاع على تفاصيل التنفيذ.
الصياغة
generateSnowflakeID([expr, [machine_id]])
expr — تعبير عشوائي يُستخدم لتجاوز حذف التعبيرات الفرعية المشتركة إذا جرى استدعاء الدالة عدة مرات ضمن استعلام. لا تؤثر قيمة التعبير على معرّف Snowflake المُعاد. اختياري. - machine_id — معرّف جهاز، وتُستخدم أقل 10 بتات منه. Int64. اختياري.
القيمة المعادة
يُرجع معرّف Snowflake. UInt64
أمثلة
مثال استخدام
CREATE TABLE tab (id UInt64)
ENGINE = MergeTree()
ORDER BY tuple();
INSERT INTO tab SELECT generateSnowflakeID();
SELECT * FROM tab;
┌──────────────────id─┐
│ 7199081390080409600 │
└─────────────────────┘
SELECT generateSnowflakeID(1), generateSnowflakeID(2);
┌─generateSnowflakeID(1)─┬─generateSnowflakeID(2)─┐
│ 7199081609652224000 │ 7199081609652224001 │
└────────────────────────┴────────────────────────┘
SELECT generateSnowflakeID('expr', 1);
┌─generateSnowflakeID('expr', 1)─┐
│ 7201148511606784002 │
└────────────────────────────────┘
expr — اختياري. أي تعبير يُستخدم لتجاوز حذف التعبيرات الفرعية المشتركة عند استدعاء الدالة عدة مرات في استعلام. لا تؤثر قيمة هذا التعبير في UUID المُعاد.
القيمة المُعادة
يعيد UUIDv4. UUID
أمثلة
مثال على الاستخدام
SELECT generateUUIDv4(number) FROM numbers(3);
┌─generateUUIDv4(number)───────────────┐
│ fcf19b77-a610-42c5-b3f5-a13c122f65b6 │
│ 07700d36-cb6b-4189-af1d-0972f23dc3bc │
│ 68838947-1583-48b0-b9b7-cf8268dd343d │
└──────────────────────────────────────┘
SELECT generateUUIDv4(1), generateUUIDv4(1);
┌─generateUUIDv4(1)────────────────────┬─generateUUIDv4(2)────────────────────┐
│ 2d49dc6e-ddce-4cd0-afb8-790956df54c1 │ 2d49dc6e-ddce-4cd0-afb8-790956df54c1 │
└──────────────────────────────────────┴──────────────────────────────────────┘
اعتبارًا من سبتمبر 2025، لا تزال معرّفات UUID من الإصدار 7 في حالة مسودة، وقد تتغير بنيتها في المستقبل.
expr — اختياري. تعبير اعتباطي يُستخدم لتجاوز حذف التعبيرات الفرعية المشتركة إذا جرى استدعاء الدالة عدة مرات في استعلام. لا تؤثر قيمة هذا التعبير في UUID المُعاد. Any
القيمة المُعادة
يعيد UUIDv7. UUID
أمثلة
مثال على الاستخدام
SELECT generateUUIDv7(number) FROM numbers(3);
┌─generateUUIDv7(number)───────────────┐
│ 019947fb-5766-7ed0-b021-d906f8f7cebb │
│ 019947fb-5766-7ed0-b021-d9072d0d1e07 │
│ 019947fb-5766-7ed0-b021-d908dca2cf63 │
└──────────────────────────────────────┘
SELECT generateUUIDv7(1), generateUUIDv7(1);
┌─generateUUIDv7(1)────────────────────┬─generateUUIDv7(1)────────────────────┐
│ 019947ff-0f87-7d88-ace0-8b5b3a66e0c1 │ 019947ff-0f87-7d88-ace0-8b5b3a66e0c1 │
└──────────────────────────────────────┴──────────────────────────────────────┘
snowflakeIDToDateTime(value[, epoch[, time_zone]])
value — معرّف Snowflake. UInt64epoch — اختياري. حقبة معرّف Snowflake بالمللي ثانية منذ 1970-01-01. القيمة الافتراضية هي 0 (1970-01-01). لحقبة Twitter/X (2015-01-01)، مرّر 1288834974657. UInt*time_zone — اختياري. المنطقة الزمنية. تحلّل الدالة time_string وفقًا للمنطقة الزمنية. String
القيمة المُعادة
تعيد مكوّن الطابع الزمني لـ value. DateTime
أمثلة
مثال على الاستخدام
SELECT snowflakeIDToDateTime(7204436857747984384) AS res
┌─────────────────res─┐
│ 2024-06-06 10:59:58 │
└─────────────────────┘
snowflakeIDToDateTime64(value[, epoch[, time_zone]])
value — معرّف Snowflake. UInt64epoch — اختياري. حقبة معرّف 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
أمثلة
مثال على الاستخدام
SELECT snowflakeIDToDateTime64(7204436857747984384) AS res
┌─────────────────res─┐
│ 2024-06-06 10:59:58 │
└─────────────────────┘
snowflakeToDateTime(value[, time_zone])
value. DateTime
أمثلة
مثال على الاستخدام
SELECT snowflakeToDateTime(CAST('1426860702823350272', 'Int64'), 'UTC');
┌─snowflakeToDateTime(CAST('1426860702823350272', 'Int64'), 'UTC')─┐
│ 2021-08-15 10:57:56 │
└──────────────────────────────────────────────────────────────────┘
snowflakeToDateTime64(value[, time_zone])
value. DateTime64(3)
أمثلة
مثال على الاستخدام
SELECT snowflakeToDateTime64(CAST('1426860802823350272', 'Int64'), 'UTC');
┌─snowflakeToDateTime64(CAST('1426860802823350272', 'Int64'), 'UTC')─┐
│ 2021-08-15 10:58:19.841 │
└────────────────────────────────────────────────────────────────────┘
toUUIDOrDefault(string, default)
string — سلسلة نصية مكوّنة من 36 حرفًا أو FixedString(36) لتحويلها إلى UUID. - default — قيمة UUID التي ستُعاد إذا تعذّر تحويل الوسيط الأول إلى النوع UUID.
القيمة المُعادة
يعيد قيمة UUID المحوَّلة عند نجاح العملية، أو قيمة UUID الافتراضية إذا فشل التحويل. UUID
أمثلة
يعيد التحويل الناجح قيمة UUID المُحلَّلة
SELECT toUUIDOrDefault('61f0c404-5cb3-11e7-907b-a6006ad3dba0', toUUID('59f0c404-5cb3-11e7-907b-a6006ad3dba0'));
┌─toUUIDOrDefault('61f0c404-5cb3-11e7-907b-a6006ad3dba0', toUUID('59f0c404-5cb3-11e7-907b-a6006ad3dba0'))─┐
│ 61f0c404-5cb3-11e7-907b-a6006ad3dba0 │
└──────────────────────────────────────────────────────────────────────────────────────────────────────────┘
SELECT toUUIDOrDefault('-----61f0c404-5cb3-11e7-907b-a6006ad3dba0', toUUID('59f0c404-5cb3-11e7-907b-a6006ad3dba0'));
┌─toUUIDOrDefault('-----61f0c404-5cb3-11e7-907b-a6006ad3dba0', toUUID('59f0c404-5cb3-11e7-907b-a6006ad3dba0'))─┐
│ 59f0c404-5cb3-11e7-907b-a6006ad3dba0 │
└───────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
UUID، لكنها تُرجع NULL في حال حدوث خطأ.
تشبه toUUID، لكنها تُرجع NULL بدلًا من إطلاق استثناء عند حدوث أخطاء في التحويل.
الوسيطات المدعومة:
- التمثيلات النصية لـ UUID بالتنسيق القياسي (8-4-4-4-12 رقمًا سداسيّ عشري).
- التمثيلات النصية لـ UUID من دون واصلات (32 رقمًا سداسيّ عشري).
الوسيطات غير المدعومة (تُرجع NULL):
- تنسيقات سلاسل غير صالحة.
- أنواع غير نصية.
- UUIDs غير مكتملة التكوين.
البنية
الوسيطات
x — تمثيل نصي لقيمة UUID. String
القيمة المُعادة
تُرجِع قيمة UUID عند النجاح، وإلا NULL. UUID أو NULL
أمثلة
أمثلة الاستخدام
SELECT
toUUIDOrNull('550e8400-e29b-41d4-a716-446655440000') AS valid_uuid,
toUUIDOrNull('invalid-uuid') AS invalid_uuid
┌─valid_uuid───────────────────────────┬─invalid_uuid─┐
│ 550e8400-e29b-41d4-a716-446655440000 │ ᴺᵁᴸᴸ │
└──────────────────────────────────────┴──────────────┘
