دوال تحويل الأنواع

يستخدم ClickHouse عمومًا السلوك نفسه المستخدم في برامج C++.

تختلف دوال to<type> وcast في سلوكهما في بعض الحالات، مثل حالة LowCardinality: إذ يزيل cast السمة LowCardinality، بينما لا تفعل دوال to<type> ذلك. وينطبق الأمر نفسه على Nullable. هذا السلوك غير متوافق مع معيار SQL، ويمكن تغييره باستخدام الإعداد cast_keep_nullable.

مثال:

SELECT
    toTypeName(toLowCardinality('') AS val) AS source_type,
    toTypeName(toString(val)) AS to_type_result_type,
    toTypeName(CAST(val, 'String')) AS cast_result_type

┌

تتيح عائلة الدوال toString التحويل بين الأرقام، والسلاسل النصية (لكن ليس السلاسل ذات الطول الثابت)، والتواريخ، والتواريخ المقترنة بوقت. تقبل جميع هذه الدوال وسيطة واحدة.

• عند التحويل من سلسلة نصية أو إليها، تُنسَّق القيمة أو تُحلَّل وفق القواعد نفسها المستخدمة في تنسيق TabSeparated (وفي معظم تنسيقات النص الأخرى أيضًا). وإذا تعذّر تحليل السلسلة النصية، يُطرَح استثناء ويُلغى الطلب.
• عند تحويل التواريخ إلى أرقام أو العكس، يمثّل التاريخ عدد الأيام منذ بداية حقبة Unix.
• عند تحويل التواريخ المقترنة بوقت إلى أرقام أو العكس، يمثّل التاريخ مع الوقت عدد الثواني منذ بداية حقبة Unix.
• يمكن لدالة toString الخاصة بوسيطة DateTime أن تأخذ وسيطة String ثانية تتضمن اسم المنطقة الزمنية، على سبيل المثال: Europe/Amsterdam. وفي هذه الحالة، يُنسَّق الوقت وفقًا للمنطقة الزمنية المحددة.

تُعرَّف تنسيقات التاريخ والتاريخ المقترن بالوقت للدالتين toDate/toDateTime كما يلي:

YYYY-MM-DD
YYYY-MM-DD hh:mm:ss

كاستثناء، عند التحويل من الأنواع الرقمية UInt32 أو Int32 أو UInt64 أو Int64 إلى Date، إذا كان الرقم أكبر من أو يساوي 65536، فسيُفسَّر على أنه Unix timestamp (وليس عدد الأيام)، ويُقرَّب إلى التاريخ. ويتيح ذلك دعم الحالة الشائعة المتمثلة في كتابة toDate(unix_timestamp)، التي كانت ستؤدي بخلاف ذلك إلى حدوث خطأ، وستستلزم كتابة الصيغة الأكثر تعقيدًا toDate(toDateTime(unix_timestamp)).

يُجرى التحويل بين التاريخ وتاريخ مع وقت بالطريقة الطبيعية: بإضافة وقت صفري أو بحذف الوقت.

يستخدم التحويل بين الأنواع الرقمية القواعد نفسها المستخدمة في الإسناد بين الأنواع الرقمية المختلفة في C++.

مثال

SELECT
    now() AS ts,
    time_zone,
    toString(ts, time_zone) AS str_tz_datetime
FROM system.time_zones
WHERE time_zone LIKE 'Europe%'
LIMIT 10

┌──────────────────ts─┬─time_zone─────────┬─str_tz_datetime─────┐
│ 2023-09-08 19:14:59 │ Europe/Amsterdam  │ 2023-09-08 21:14:59 │
│ 2023-09-08 19:14:59 │ Europe/Andorra    │ 2023-09-08 21:14:59 │
│ 2023-09-08 19:14:59 │ Europe/Astrakhan  │ 2023-09-08 23:14:59 │
│ 2023-09-08 19:14:59 │ Europe/Athens     │ 2023-09-08 22:14:59 │
│ 2023-09-08 19:14:59 │ Europe/Belfast    │ 2023-09-08 20:14:59 │
│ 2023-09-08 19:14:59 │ Europe/Belgrade   │ 2023-09-08 21:14:59 │
│ 2023-09-08 19:14:59 │ Europe/Berlin     │ 2023-09-08 21:14:59 │
│ 2023-09-08 19:14:59 │ Europe/Bratislava │ 2023-09-08 21:14:59 │
│ 2023-09-08 19:14:59 │ Europe/Brussels   │ 2023-09-08 21:14:59 │
│ 2023-09-08 19:14:59 │ Europe/Bucharest  │ 2023-09-08 22:14:59 │
└─────────────────────┴───────────────────┴─────────────────────┘

راجع أيضًا الدالة toUnixTimestamp.

أُضيف في: v1.1.0

يحوّل قيمة إلى نوع البيانات المحدد. وعلى خلاف الدالة reinterpret، تحاول CAST إنتاج القيمة نفسها في النوع الهدف. إذا لم يكن ذلك ممكنًا، يُرفَع استثناء.

البنية

CAST(x, T)
or CAST(x AS T)
or x::T

الوسائط

• x — قيمة من أي نوع. Any
• T — نوع البيانات الهدف. String

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

تُرجِع القيمة بعد تحويلها إلى نوع البيانات الهدف. Any

أمثلة

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

SELECT CAST(42, 'String')

┌─CAST(42, 'String')─┐
│ 42                 │
└────────────────────┘

استخدام صيغة AS

SELECT CAST('2025-01-01' AS Date)

┌─CAST('2025-01-01', 'Date')─┐
│                 2025-01-01 │
└────────────────────────────┘

استخدام صياغة ::

SELECT '123'::UInt32

┌─CAST('123', 'UInt32')─┐
│                   123 │
└───────────────────────┘

أُضيف في: v21.2.0

يحوّل الوسيط إلى نوع البيانات Date. هذا اسم مستعار للتوافق مع MySQL للدالة toDate، ويتصرف بالطريقة نفسها التي تتصرف بها toDate.

الصيغة

DATE(expr)

الوسيطات

• expr — القيمة المراد تحويلها. String أو UInt32 أو Date أو DateTime

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

تُرجع قيمة من نوع Date. Date

أمثلة

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

SELECT DATE('2023-01-01')

2023-01-01

أُضيف في: v1.1.0

يحوّل قيمة إلى نوع بيانات محدد. بخلاف CAST، يُجري accurateCast تحقّقًا أكثر صرامة من الأنواع ويطرح استثناءً إذا كان التحويل سيؤدي إلى فقدان الدقة أو إذا لم يكن التحويل ممكنًا.

هذه الدالة أكثر أمانًا من CAST العادي لأنها تمنع فقدان الدقة وعمليات التحويل غير الصالحة.

البنية

accurateCast(x, T)

الوسيطات

• x — قيمة المراد تحويلها. Any
• T — اسم نوع البيانات الهدف. String

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

ترجع القيمة بعد تحويلها إلى نوع البيانات الهدف. Any

أمثلة

تحويل ناجح

SELECT accurateCast(42, 'UInt16')

┌─accurateCast(42, 'UInt16')─┐
│                         42 │
└────────────────────────────┘

من نص إلى رقم

SELECT accurateCast('123.45', 'Float64')

┌─accurateCast('123.45', 'Float64')─┐
│                            123.45 │
└───────────────────────────────────┘

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

تُحوِّل قيمة إلى نوع البيانات المحدد. تشبه accurateCast، لكنها تُرجع قيمة افتراضية بدلًا من إثارة استثناء إذا تعذّر إجراء التحويل بدقة.

إذا جرى توفير قيمة افتراضية باعتبارها الوسيط الثاني، فيجب أن تكون من النوع الهدف. إذا لم تُوفَّر قيمة افتراضية، تُستخدم القيمة الافتراضية للنوع الهدف.

الصياغة

accurateCastOrDefault(x, T[, default_value])

المعاملات

• x — قيمة لتحويلها. Any
• T — اسم نوع البيانات الهدف. const String
• default_value — اختياري. القيمة الافتراضية التي تُعاد إذا فشل التحويل. Any

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

تُعاد القيمة المحوَّلة إلى نوع البيانات الهدف، أو القيمة الافتراضية إذا لم يكن التحويل ممكنًا. Any

أمثلة

تحويل ناجح

SELECT accurateCastOrDefault(42, 'String')

┌─accurateCastOrDefault(42, 'String')─┐
│ 42                                  │
└─────────────────────────────────────┘

فشل التحويل مع قيمة افتراضية محددة صراحةً

SELECT accurateCastOrDefault('abc', 'UInt32', 999::UInt32)

┌─accurateCastOrDefault('abc', 'UInt32', CAST('999', 'UInt32'))─┐
│                                                           999 │
└───────────────────────────────────────────────────────────────┘

تعذّر التحويل مع قيمة افتراضية ضمنية

SELECT accurateCastOrDefault('abc', 'UInt32')

┌─accurateCastOrDefault('abc', 'UInt32')─┐
│                                      0 │
└────────────────────────────────────────┘

قُدِّمت في: v1.1.0

تحوّل قيمة إلى نوع البيانات المحدد. وهي تشبه accurateCast، لكنها تُرجع NULL بدلًا من طرح استثناء إذا تعذّر إجراء التحويل بدقة.

تجمع هذه الدالة بين أمان accurateCast والمعالجة السلسة للأخطاء.

الصياغة

accurateCastOrNull(x, T)

المعاملات

• x — قيمة مطلوب تحويلها. Any
• T — اسم نوع البيانات الهدف. String

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

ترجع القيمة بعد تحويلها إلى نوع البيانات الهدف، أو NULL إذا تعذر التحويل. Any

أمثلة

تحويل ناجح

SELECT accurateCastOrNull(42, 'String')

┌─accurateCastOrNull(42, 'String')─┐
│ 42                               │
└──────────────────────────────────┘

عند فشل التحويل، تُرجَع القيمة NULL

SELECT accurateCastOrNull('abc', 'UInt32')

┌─accurateCastOrNull('abc', 'UInt32')─┐
│                                ᴺᵁᴸᴸ │
└─────────────────────────────────────┘

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

يحوّل أي تعبيرات إلى سلسلة نصية باستخدام التنسيق المحدد.

الصيغة

formatRow(format, x, y, ...)

الوسائط

• format — تنسيق نصي. على سبيل المثال: CSV وTSV. String
• x, y, ... — تعبيرات. Any

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

سلسلة منسّقة. (في التنسيقات النصية، تنتهي عادةً بمحرف سطر جديد). String

أمثلة

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

SELECT formatRow('CSV', number, 'good')
FROM numbers(3)

┌─formatRow('CSV', number, 'good')─┐
│ 0,"good"                        ↴│
│ 1,"good"                        ↴│
│ 2,"good"                        ↴│
└──────────────────────────────────┘

بتنسيق مخصص

SELECT formatRow('CustomSeparated', number, 'good')
FROM numbers(3)
SETTINGS format_custom_result_before_delimiter='<prefix>\n', format_custom_result_after_delimiter='<suffix>'

┌─formatRow('CustomSeparated', number, 'good')─┐
│ <prefix>                                    ↴│
│↳0	good                                     ↴│
│↳<suffix>                                     │
│ <prefix>                                    ↴│
│↳1	good                                     ↴│
│↳<suffix>                                     │
│ <prefix>                                    ↴│
│↳2	good                                     ↴│
│↳<suffix>                                     │
└──────────────────────────────────────────────┘

أُضيف في: v20.7.0

مماثل لـ formatRow، لكنه يزيل محرف السطر الجديد من كل صف.

يحوّل تعبيرات عشوائية إلى سلسلة نصية باستخدام التنسيق المحدد، لكنه يزيل أي محارف سطر جديد لاحقة من النتيجة.

الصيغة

formatRowNoNewline(format, x, y, ...)

الوسائط

• format — تنسيق نصي. على سبيل المثال: CSV وTSV. String
• x, y, ... — تعبيرات. Any

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

تعيد سلسلة منسقة أزيلت منها فواصل الأسطر. String

أمثلة

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

SELECT formatRowNoNewline('CSV', number, 'good')
FROM numbers(3)

┌─formatRowNoNewline('CSV', number, 'good')─┐
│ 0,"good"                                  │
│ 1,"good"                                  │
│ 2,"good"                                  │
└───────────────────────────────────────────┘

استُحدث في: v20.5.0

يحوّل طابعًا زمنيًا لـ Unix بالميكروثانية إلى قيمة DateTime64 بدقة الميكروثانية.

تُعامَل قيمة الإدخال على أنها طابع زمني لـ Unix بدقة الميكروثانية (عدد الميكروثواني منذ 1970-01-01 00:00:00 UTC).

الصياغة

fromUnixTimestamp64Micro(value[, timezone])

الوسائط

• value — طابع زمني لـ Unix بالميكروثانية. Int64
• timezone — اختياري. المنطقة الزمنية للقيمة المُعادة. String

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

يعيد قيمة DateTime64 بدقة ميكروثانية. DateTime64(6)

أمثلة

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

SELECT fromUnixTimestamp64Micro(1640995200123456)

┌─fromUnixTimestamp64Micro(1640995200123456)─┐
│                 2022-01-01 00:00:00.123456 │
└────────────────────────────────────────────┘

أُضيف في: v20.5.0

يحوّل طابعًا زمنيًا لـ Unix بالملّي ثانية إلى قيمة DateTime64 بدقة الملّي ثانية.

تُعامَل قيمة الإدخال على أنها طابع زمني لـ Unix بدقة الملّي ثانية (عدد الملّي ثواني منذ 1970-01-01 00:00:00 UTC).

الصياغة

fromUnixTimestamp64Milli(value[, timezone])

الوسيطات

• value — طابع زمني بنظام Unix بالمللي ثانية. Int64
• timezone — اختياري. المنطقة الزمنية للقيمة المعادة. String

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

قيمة DateTime64 بدقة المللي ثانية. DateTime64(3)

أمثلة

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

SELECT fromUnixTimestamp64Milli(1640995200123)

┌─fromUnixTimestamp64Milli(1640995200123)─┐
│                 2022-01-01 00:00:00.123 │
└─────────────────────────────────────────┘

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

تُحوِّل طابعًا زمنيًا من Unix بالنانوثانية إلى قيمة DateTime64 بدقة النانوثانية.

تُعامَل قيمة الإدخال على أنها طابع زمني من Unix بدقة النانوثانية (أي عدد النانوثواني منذ 1970-01-01 00:00:00 UTC).

البنية

fromUnixTimestamp64Nano(value[, timezone])

المعاملات

• value — طابع زمني لـ Unix بالنانوثانية. Int64
• timezone — اختياري. المنطقة الزمنية للقيمة المُعادة. String

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

تُرجِع قيمة من النوع DateTime64 بدقة نانوثانية. DateTime64(9)

أمثلة

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

SELECT fromUnixTimestamp64Nano(1640995200123456789)

┌─fromUnixTimestamp64Nano(1640995200123456789)─┐
│                2022-01-01 00:00:00.123456789 │
└──────────────────────────────────────────────┘

أُضيف في: v24.12.0

يحوّل طابعًا زمنيًا من Unix بالثواني إلى قيمة DateTime64 بدقة الثواني.

تُعامَل قيمة الإدخال على أنها طابع زمني من Unix بدقة الثواني (أي عدد الثواني منذ 1970-01-01 00:00:00 UTC).

الصيغة

fromUnixTimestamp64Second(value[, timezone])

الوسيطات

• value — طابع زمني بنظام Unix بالثواني. Int64
• timezone — اختياري. المنطقة الزمنية للقيمة المُعادة. String

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

تُرجِع قيمة DateTime64 بدقة الثواني. DateTime64(0)

أمثلة

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

SELECT fromUnixTimestamp64Second(1640995200)

┌─fromUnixTimestamp64Second(1640995200)─┐
│                   2022-01-01 00:00:00 │
└───────────────────────────────────────┘

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

يُحلّل سلسلة تاريخ ووقت وفقًا لسلسلة تنسيق تاريخ خاصة بـ MySQL.

هذه الدالة هي عكس formatDateTime. وهي تُحلّل وسيطًا من النوع String باستخدام سلسلة تنسيق من النوع String. وتُرجِع قيمة من النوع DateTime.

البنية

parseDateTime(time_string, format[, timezone])

الأسماء البديلة: TO_UNIXTIME

الوسيطات

• time_string — سلسلة نصية تُحلَّل إلى DateTime. String
• format — سلسلة تنسيق تحدد كيفية تحليل time_string. String
• timezone — اختياري. المنطقة الزمنية. String

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

يعيد قيمة من النوع DateTime مُحلَّلة من السلسلة النصية المُدخلة وفقًا لسلسلة تنسيق بأسلوب MySQL. DateTime

أمثلة

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

SELECT parseDateTime('2025-01-04+23:00:00', '%Y-%m-%d+%H:%i:%s')

┌─parseDateTime('2025-01-04+23:00:00', '%Y-%m-%d+%H:%i:%s')─┐
│                                       2025-01-04 23:00:00 │
└───────────────────────────────────────────────────────────┘

أُضيف في: v20.9.0

يحوّل التمثيل النصي للتاريخ والوقت إلى نوع البيانات DateTime.

تحلّل الدالة تنسيقات ISO 8601 وRFC 1123 - 5.2.14 RFC-822 Date and Time Specification وتنسيقات التاريخ والوقت الخاصة بـ ClickHouse، بالإضافة إلى بعض التنسيقات الأخرى.

الصيغة

parseDateTime32BestEffort(time_string[, time_zone])

الوسائط

• time_string — قيمة من نوع String تحتوي على تاريخ ووقت لتحويلهما. String
• time_zone — اختياري. المنطقة الزمنية التي يُحلَّل time_string وفقًا لها. String

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

تعيد time_string كقيمة من نوع DateTime. DateTime

أمثلة

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

SELECT parseDateTime32BestEffort('23/10/2025 12:12:57')
AS parseDateTime32BestEffort

┌─parseDateTime32BestEffort─┐
│       2025-10-23 12:12:57 │
└───────────────────────────┘

مع تحديد المنطقة الزمنية

SELECT parseDateTime32BestEffort('Sat, 18 Aug 2025 07:22:16 GMT', 'Asia/Istanbul')
AS parseDateTime32BestEffort

┌─parseDateTime32BestEffort─┐
│       2025-08-18 10:22:16 │
└───────────────────────────┘

الطابع الزمني ليونكس

SELECT parseDateTime32BestEffort('1284101485')
AS parseDateTime32BestEffort

┌─parseDateTime32BestEffort─┐
│       2010-09-10 06:51:25 │
└───────────────────────────┘

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

مماثلة لـ parseDateTime32BestEffort، باستثناء أنها تُرجِع NULL عند مواجهة تنسيق تاريخ يتعذّر معالجته.

الصياغة

parseDateTime32BestEffortOrNull(time_string[, time_zone])

الوسائط

• time_string — قيمة من النوع String تحتوي على تاريخ ووقت لتحويلهما. String
• time_zone — اختياري. المنطقة الزمنية التي يُفسَّر وفقًا لها time_string. String

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

يعيد كائن DateTime مُفسَّرًا من السلسلة، أو NULL إذا فشل التفسير. DateTime

أمثلة

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

SELECT
    parseDateTime32BestEffortOrNull('23/10/2025 12:12:57') AS valid,
    parseDateTime32BestEffortOrNull('invalid date') AS invalid

┌───────────────valid─┬─invalid─┐
│ 2025-10-23 12:12:57 │    ᴺᵁᴸᴸ │
└─────────────────────┴─────────┘

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

مطابقة لـ parseDateTime32BestEffort، باستثناء أنها تُرجِع تاريخًا صفريًا أو قيمة تاريخ ووقت صفرية عند مصادفة تنسيق تاريخ يتعذر معالجته.

البنية

parseDateTime32BestEffortOrZero(time_string[, time_zone])

الوسائط

• time_string — سلسلة نصية تحتوي على تاريخ ووقت لتحويلهما. String
• time_zone — اختياري. المنطقة الزمنية التي يُفسَّر وفقًا لها time_string. String

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

يعيد كائن DateTime ناتجًا عن تحليل السلسلة، أو التاريخ الصفري (1970-01-01 00:00:00) إذا فشلت عملية التحليل. DateTime

أمثلة

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

SELECT
    parseDateTime32BestEffortOrZero('23/10/2025 12:12:57') AS valid,
    parseDateTime32BestEffortOrZero('invalid date') AS invalid

┌───────────────valid─┬─────────────invalid─┐
│ 2025-10-23 12:12:57 │ 1970-01-01 00:00:00 │
└─────────────────────┴─────────────────────┘

أُضيف في: v24.11.0

يُحلِّل سلسلة تاريخ ووقت بدقة أجزاء من الثانية وفقًا لسلسلة تنسيق تاريخ MySQL.

هذه الدالة هي المعكوس لـ formatDateTime لـ DateTime64. وهي تُحلِّل وسيطة من النوع String باستخدام String للتنسيق. وتُرجع نوع DateTime64 يمكنه تمثيل التواريخ من 0000 إلى 9999 بدقة أجزاء من الثانية (تغطي درجات الدقة العالية نطاقًا أضيق لأن القيمة تُخزَّن في Int64 كعدد من tick: تصل الدقة 8 إلى نحو 4892، وتمتد الدقة 9 من 1677 إلى 2262).

الصيغة

parseDateTime64(time_string, format[, timezone])

الوسيطات

• time_string — سلسلة نصية يُراد تحليلها إلى DateTime64. String
• format — سلسلة تنسيق تحدد كيفية تحليل time_string. String
• timezone — اختياري. المنطقة الزمنية. String

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

يعيد قيمة DateTime64 مُحلَّلة من سلسلة الإدخال وفق سلسلة تنسيق بأسلوب MySQL. DateTime64

أمثلة

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

SELECT parseDateTime64('2025-01-04 23:00:00.123', '%Y-%m-%d %H:%i:%s.%f')

┌─parseDateTime64('2025-01-04 23:00:00.123', '%Y-%m-%d %H:%i:%s.%f')─┐
│                                         2025-01-04 23:00:00.123000 │
└────────────────────────────────────────────────────────────────────┘

أُضيف في: v20.1.0

تماثل الدالة parseDateTimeBestEffort، لكنها تُحلِّل أيضًا المللي ثانية والميكروثانية وتُرجع نوع البيانات DateTime64.

البنية

parseDateTime64BestEffort(time_string[, precision[, time_zone]])

المعاملات

• time_string — قيمة من نوع String تحتوي على تاريخ أو تاريخ ووقت لتحويله. String
• precision — اختياري. الدقة المطلوبة. 3 للملّي ثانية، و6 للميكروثانية. القيمة الافتراضية: 3. UInt8
• time_zone — اختياري. المنطقة الزمنية. تحلّل الدالة time_string وفقًا للمنطقة الزمنية. String

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

تعيد time_string بعد تحويله إلى نوع البيانات DateTime64. DateTime64

أمثلة

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

SELECT parseDateTime64BestEffort('2025-01-01') AS a, toTypeName(a) AS t
UNION ALL
SELECT parseDateTime64BestEffort('2025-01-01 01:01:00.12346') AS a, toTypeName(a) AS t
UNION ALL
SELECT parseDateTime64BestEffort('2025-01-01 01:01:00.12346',6) AS a, toTypeName(a) AS t
UNION ALL
SELECT parseDateTime64BestEffort('2025-01-01 01:01:00.12346',3,'Asia/Istanbul') AS a, toTypeName(a) AS t
FORMAT PrettyCompactMonoBlock

┌──────────────────────────a─┬─t──────────────────────────────┐
│ 2025-01-01 01:01:00.123000 │ DateTime64(3)                  │
│ 2025-01-01 00:00:00.000000 │ DateTime64(3)                  │
│ 2025-01-01 01:01:00.123460 │ DateTime64(6)                  │
│ 2025-12-31 22:01:00.123000 │ DateTime64(3, 'Asia/Istanbul') │
└────────────────────────────┴────────────────────────────────┘

مُتاحة منذ: v20.1.0

مطابقة للدالة parseDateTime64BestEffort، إلا أنها تُرجع NULL عند مواجهة تنسيق تاريخ يتعذر معالجته.

الصياغة

parseDateTime64BestEffortOrNull(time_string[, precision[, time_zone]])

الوسيطات

• time_string — قيمة String تحتوي على تاريخ أو تاريخ مع وقت لتحويله. String
• precision — اختياري. الدقة المطلوبة. 3 للملّي ثانية و6 للميكروثانية. القيمة الافتراضية: 3. UInt8
• time_zone — اختياري. المنطقة الزمنية. تُحلِّل الدالة time_string وفقًا للمنطقة الزمنية. String

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

تُعيد time_string بعد تحويله إلى DateTime64، أو NULL إذا تعذّر تحليل الإدخال. DateTime64 أو NULL

أمثلة

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

SELECT parseDateTime64BestEffortOrNull('2025-01-01 01:01:00.123') AS valid,
       parseDateTime64BestEffortOrNull('invalid') AS invalid

┌───────────────────valid─┬─invalid─┐
│ 2025-01-01 01:01:00.123 │    ᴺᵁᴸᴸ │
└─────────────────────────┴─────────┘

قُدِّم في: v20.1.0

مماثلة لـ parseDateTime64BestEffort، إلا أنها تُرجع تاريخًا صفريًا أو تاريخًا ووقتًا صفريين عند مصادفة تنسيق تاريخ يتعذر معالجته.

الصياغة

parseDateTime64BestEffortOrZero(time_string[, precision[, time_zone]])

الوسيطات

• time_string — قيمة من نوع String تحتوي على تاريخ أو تاريخ مع وقت لتحويله. String
• precision — اختياري. الدقة المطلوبة. 3 للمللي ثانية، و6 للميكروثانية. القيمة الافتراضية: 3. UInt8
• time_zone — اختياري. المنطقة الزمنية. تحلّل الدالة time_string وفقًا للمنطقة الزمنية. String

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

تعيد time_string بعد تحويله إلى DateTime64، أو التاريخ/التاريخ والوقت الصفري (1970-01-01 00:00:00.000) إذا تعذّر تحليل الإدخال. DateTime64

أمثلة

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

SELECT parseDateTime64BestEffortOrZero('2025-01-01 01:01:00.123') AS valid,
       parseDateTime64BestEffortOrZero('invalid') AS invalid

┌───────────────────valid─┬─────────────────invalid─┐
│ 2025-01-01 01:01:00.123 │ 1970-01-01 00:00:00.000 │
└─────────────────────────┴─────────────────────────┘

تم تقديمها في: v22.8.0

مماثلة لـ parseDateTime64BestEffort، باستثناء أن هذه الدالة تُفضّل تنسيق التاريخ الأمريكي (MM/DD/YYYY وما إلى ذلك) عند وجود التباس.

البنية

parseDateTime64BestEffortUS(time_string [, precision [, time_zone]])

الوسيطات

• time_string — String يحتوي على تاريخ أو تاريخ يتضمن وقتًا لتحويله. String
• precision — اختياري. الدقة المطلوبة. 3 للملّي ثانية، و6 للميكروثانية. الافتراضي: 3. UInt8
• time_zone — اختياري. المنطقة الزمنية. تحلّل الدالة time_string وفقًا للمنطقة الزمنية. String

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

تعيد time_string بعد تحويله إلى DateTime64 مع تفضيل تنسيق التاريخ الأمريكي في الحالات الملتبسة. DateTime64

أمثلة

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

SELECT parseDateTime64BestEffortUS('02/10/2025 12:30:45.123') AS us_format,
       parseDateTime64BestEffortUS('15/08/2025 10:15:30.456') AS fallback_to_standard

┌───────────────us_format─┬────fallback_to_standard─┐
│ 2025-02-10 12:30:45.123 │ 2025-08-15 10:15:30.456 │
└─────────────────────────┴─────────────────────────┘

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

مماثلة لـ parseDateTime64BestEffort، باستثناء أن هذه الدالة تفضّل تنسيق التاريخ الأمريكي (MM/DD/YYYY وما إلى ذلك) عند وجود التباس، وتُرجع NULL إذا صادفت تنسيق تاريخ لا يمكن معالجته.

البنية

parseDateTime64BestEffortUSOrNull(time_string[, precision[, time_zone]])

الوسيطات

• time_string — قيمة String تحتوي على تاريخ أو تاريخًا مع وقت لتحويله. String
• precision — اختياري. الدقة المطلوبة. 3 للميلي ثانية، و6 للميكروثانية. القيمة الافتراضية: 3. UInt8
• time_zone — اختياري. المنطقة الزمنية. تُحلِّل الدالة time_string وفقًا للمنطقة الزمنية. String

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

تعيد time_string بعد تحويله إلى DateTime64 مع تفضيل التنسيق الأمريكي، أو NULL إذا تعذر تحليل الإدخال. DateTime64 أو NULL

أمثلة

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

SELECT parseDateTime64BestEffortUSOrNull('02/10/2025 12:30:45.123') AS valid_us,
       parseDateTime64BestEffortUSOrNull('invalid') AS invalid

┌────────────────valid_us─┬─invalid─┐
│ 2025-02-10 12:30:45.123 │    ᴺᵁᴸᴸ │
└─────────────────────────┴─────────┘

أُضيف في: v22.8.0

مماثلة لـ parseDateTime64BestEffort، باستثناء أن هذه الدالة تفضّل تنسيق التاريخ الأمريكي (MM/DD/YYYY وما إلى ذلك) عند وجود التباس، وتُرجع التاريخ الصفري أو التاريخ والوقت الصفري إذا صادفت تنسيق تاريخ يتعذّر معالجته.

الصياغة

parseDateTime64BestEffortUSOrZero(time_string [, precision [, time_zone]])

الوسيطات

• time_string — قيمة String تحتوي على تاريخ أو تاريخ مع وقت لتحويله. String
• precision — اختياري. الدقة المطلوبة. 3 للميلي ثانية، و6 للميكروثانية. القيمة الافتراضية: 3. UInt8
• time_zone — اختياري. المنطقة الزمنية. تُحلِّل الدالة time_string وفقًا للمنطقة الزمنية. String

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

تعيد time_string بعد تحويله إلى DateTime64 باستخدام تفضيل التنسيق الأمريكي، أو قيمة التاريخ/التاريخ والوقت الصفرية (1970-01-01 00:00:00.000) إذا تعذّر تحليل الإدخال. DateTime64

أمثلة

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

SELECT parseDateTime64BestEffortUSOrZero('02/10/2025 12:30:45.123') AS valid_us,
       parseDateTime64BestEffortUSOrZero('invalid') AS invalid

┌────────────────valid_us─┬─────────────────invalid─┐
│ 2025-02-10 12:30:45.123 │ 1970-01-01 00:00:00.000 │
└─────────────────────────┴─────────────────────────┘

أُضيف في: v24.10.0

يُحلِّل سلسلة تاريخ ووقت بدقة أجزاء من الثانية وفقًا لسلسلة تنسيق تاريخ Joda.

هذه الدالة هي معكوس formatDateTimeInJodaSyntax لـ DateTime64. تُحلِّل وسيطًا من النوع String باستخدام سلسلة تنسيق بأسلوب Joda. وتُرجع نوع DateTime64، الذي يمكنه تمثيل التواريخ من 0000 إلى 9999 بدقة أجزاء من الثانية (تغطي درجات الدقة الأعلى نطاقًا أضيق لأن القيمة تُخزَّن في عدد Int64 من وحدات tick: تصل الدقة 8 إلى نحو 4892، وتمتد الدقة 9 من 1677 إلى 2262).

راجِع توثيق Joda Time للاطلاع على أنماط التنسيق.

البنية

parseDateTime64InJodaSyntax(time_string, format[, timezone])

الوسيطات

• time_string — قيمة String المراد تحليلها إلى DateTime64. String
• format — سلسلة تنسيق بصياغة Joda تحدد كيفية تحليل time_string. String
• timezone — اختياري. المنطقة الزمنية. String

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

يعيد قيمة من النوع DateTime64 جرى تحليلها من سلسلة الإدخال وفقًا لسلسلة التنسيق بأسلوب Joda. DateTime64

أمثلة

مثال استخدام

SELECT parseDateTime64InJodaSyntax('2025-01-04 23:00:00.123', 'yyyy-MM-dd HH:mm:ss.SSS')

┌─parseDateTime64InJodaSyntax('2025-01-04 23:00:00.123', 'yyyy-MM-dd HH:mm:ss.SSS')─┐
│                                                           2025-01-04 23:00:00.123 │
└───────────────────────────────────────────────────────────────────────────────────┘

أُضيف في: v24.10.0

مماثلة لـ parseDateTime64InJodaSyntax، لكنها تُرجع NULL عند مواجهة تنسيق تاريخ يتعذّر تحليله.

البنية

parseDateTime64InJodaSyntaxOrNull(time_string, format[, timezone])

الوسيطات

• time_string — سلسلة نصية لتحليلها إلى DateTime64. String
• format — سلسلة تنسيق بصيغة Joda تحدد كيفية تحليل time_string. String
• timezone — اختياري. المنطقة الزمنية. String

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

يعيد قيمة DateTime64 مُحلَّلة من سلسلة الإدخال، أو NULL إذا فشل التحليل. Nullable(DateTime64)

أمثلة

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

SELECT parseDateTime64InJodaSyntaxOrNull('2025-01-04 23:00:00.123', 'yyyy-MM-dd HH:mm:ss.SSS')

┌─parseDateTime64InJodaSyntaxOrNull('2025-01-04 23:00:00.123', 'yyyy-MM-dd HH:mm:ss.SSS')─┐
│                                                                 2025-01-04 23:00:00.123 │
└─────────────────────────────────────────────────────────────────────────────────────────┘

أُضيف في: v24.10.0

مثل parseDateTime64InJodaSyntax، لكنها تُرجع التاريخ الصفري عند مواجهة تنسيق تاريخ غير قابل للتحليل.

البنية

parseDateTime64InJodaSyntaxOrZero(time_string, format[, timezone])

الوسيطات

• time_string — سلسلة نصية لتحليلها إلى DateTime64. String
• format — سلسلة تنسيق بصياغة Joda تحدد كيفية تحليل time_string. String
• timezone — اختياري. المنطقة الزمنية. String

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

يعيد قيمة DateTime64 جرى تحليلها من سلسلة الإدخال، أو قيمة DateTime64 صفرية إذا فشل التحليل. DateTime64

أمثلة

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

SELECT parseDateTime64InJodaSyntaxOrZero('2025-01-04 23:00:00.123', 'yyyy-MM-dd HH:mm:ss.SSS')

┌─parseDateTime64InJodaSyntaxOrZero('2025-01-04 23:00:00.123', 'yyyy-MM-dd HH:mm:ss.SSS')─┐
│                                                                 2025-01-04 23:00:00.123 │
└─────────────────────────────────────────────────────────────────────────────────────────┘

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

مماثلة لـ parseDateTime64، ولكنها تُرجع NULL عند مصادفة تنسيق تاريخ يتعذّر تحليله.

البنية

parseDateTime64OrNull(time_string, format[, timezone])

الوسيطات

• time_string — سلسلة نصية تُحلَّل إلى DateTime64. String
• format — سلسلة تنسيق تحدد كيفية تحليل time_string. String
• timezone — اختياري. المنطقة الزمنية. String

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

يعيد قيمة DateTime64 مُحلَّلة من سلسلة الإدخال، أو NULL إذا تعذّر التحليل. Nullable(DateTime64)

أمثلة

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

SELECT parseDateTime64OrNull('2025-01-04 23:00:00.123', '%Y-%m-%d %H:%i:%s.%f')

┌─parseDateTime64OrNull('2025-01-04 23:00:00.123', '%Y-%m-%d %H:%i:%s.%f')─┐
│                                               2025-01-04 23:00:00.123000 │
└──────────────────────────────────────────────────────────────────────────┘

أُضيف في: v24.11.0

مماثلة لـ parseDateTime64، لكنها تُرجع التاريخ الصفري عند مواجهة تنسيق تاريخ يتعذر تحليله.

البنية

parseDateTime64OrZero(time_string, format[, timezone])

الوسيطات

• time_string — سلسلة نصية تُحلَّل إلى DateTime64. String
• format — سلسلة تنسيق تحدد كيفية تحليل time_string. String
• timezone — اختياري. المنطقة الزمنية. String

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

تُرجِع قيمة DateTime64 مُحلَّلة من السلسلة النصية المُدخلة، أو قيمة DateTime64 صفرية إذا فشل التحليل. DateTime64

أمثلة

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

SELECT parseDateTime64OrZero('2025-01-04 23:00:00.123', '%Y-%m-%d %H:%i:%s.%f')

┌─parseDateTime64OrZero('2025-01-04 23:00:00.123', '%Y-%m-%d %H:%i:%s.%f')─┐
│                                               2025-01-04 23:00:00.123000 │
└──────────────────────────────────────────────────────────────────────────┘

أُضيف في: v1.1.0

يحوِّل قيمة تاريخ ووقت بصيغة String إلى نوع البيانات DateTime. تُحلِّل الدالة مواصفة التاريخ والوقت ISO 8601، وRFC 1123 - 5.2.14 RFC-822، وتنسيقات التاريخ والوقت الخاصة بـ ClickHouse، وبعض التنسيقات الأخرى.

التنسيقات غير القياسية المدعومة:

• سلسلة تحتوي على طابع زمني Unix مكوَّن من 9 إلى 10 أرقام.
• سلسلة تتضمن مكوّن تاريخ ومكوّن وقت: YYYYMMDDhhmmss, DD/MM/YYYY hh:mm:ss, DD-MM-YY hh:mm, YYYY-MM-DD hh:mm:ss، إلخ.
• سلسلة تتضمن تاريخًا، ولكن من دون مكوّن وقت: YYYY, YYYYMM, YYYY*MM, DD/MM/YYYY, DD-MM-YY، إلخ.
• سلسلة تتضمن يومًا ووقتًا: DD, DD hh, DD hh:mm. في هذه الحالة، يُستبدل MM بـ 01.
• سلسلة تتضمن التاريخ والوقت مع معلومات إزاحة المنطقة الزمنية: YYYY-MM-DD hh:mm:ss ±h:mm، إلخ.
• طابع زمني بتنسيق syslog: Mmm dd hh:mm:ss. على سبيل المثال: Jun 9 14:20:32.

بالنسبة إلى جميع التنسيقات التي تحتوي على فاصل، تُحلِّل الدالة أسماء الأشهر المكتوبة باسمها الكامل أو بأول ثلاثة أحرف من اسم الشهر. إذا لم تُحدَّد السنة، فتُعتبر مساوية للسنة الحالية.

البنية

parseDateTimeBestEffort(time_string[, time_zone])

الوسائط

• time_string — سلسلة نصية تحتوي على تاريخ ووقت لتحويلهما. String
• time_zone — اختياري. المنطقة الزمنية التي يُحلَّل time_string وفقًا لها. String

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

يعيد time_string على هيئة DateTime. DateTime

أمثلة

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

SELECT parseDateTimeBestEffort('23/10/2025 12:12:57') AS parseDateTimeBestEffort

┌─parseDateTimeBestEffort─┐
│     2025-10-23 12:12:57 │
└─────────────────────────┘

مع تحديد المنطقة الزمنية

SELECT parseDateTimeBestEffort('Sat, 18 Aug 2025 07:22:16 GMT', 'Asia/Istanbul') AS parseDateTimeBestEffort

┌─parseDateTimeBestEffort─┐
│     2025-08-18 10:22:16 │
└─────────────────────────┘

الطابع الزمني في Unix

SELECT parseDateTimeBestEffort('1735689600') AS parseDateTimeBestEffort

┌─parseDateTimeBestEffort─┐
│     2025-01-01 00:00:00 │
└─────────────────────────┘

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

هي مثل parseDateTimeBestEffort تمامًا، باستثناء أنها تُرجع NULL عندما تصادف تنسيق تاريخ يتعذر معالجته. تحلّل الدالة ISO 8601 وRFC 1123 - 5.2.14 RFC-822 Date and Time Specification وتنسيقات التاريخ والوقت الخاصة بـ ClickHouse وبعض التنسيقات الأخرى.

التنسيقات غير القياسية المدعومة:

• سلسلة تحتوي على Unix timestamp مكوّن من 9 إلى 10 أرقام.
• سلسلة تحتوي على مكوّن تاريخ ومكوّن وقت: YYYYMMDDhhmmss, DD/MM/YYYY hh:mm:ss, DD-MM-YY hh:mm, YYYY-MM-DD hh:mm:ss، إلخ.
• سلسلة تحتوي على تاريخ، ولكن من دون مكوّن وقت: YYYY, YYYYMM, YYYY*MM, DD/MM/YYYY, DD-MM-YY، إلخ.
• سلسلة تحتوي على يوم ووقت: DD, DD hh, DD hh:mm. في هذه الحالة، يُستبدل MM بـ 01.
• سلسلة تتضمن التاريخ والوقت إلى جانب معلومات إزاحة المنطقة الزمنية: YYYY-MM-DD hh:mm:ss ±h:mm، إلخ.
• syslog timestamp: Mmm dd hh:mm:ss. على سبيل المثال: Jun 9 14:20:32.

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

البنية

parseDateTimeBestEffortOrNull(time_string[, time_zone])

الوسيطات

• time_string — سلسلة نصية تحتوي على تاريخ ووقت لتحويلهما. String
• time_zone — اختياري. المنطقة الزمنية التي يُفسَّر time_string وفقًا لها. String

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

يعيد time_string كقيمة من النوع DateTime، أو NULL إذا تعذر تفسير المُدخل. DateTime أو NULL

أمثلة

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

SELECT parseDateTimeBestEffortOrNull('23/10/2025 12:12:57') AS valid,
       parseDateTimeBestEffortOrNull('invalid') AS invalid

┌───────────────valid─┬─invalid─┐
│ 2025-10-23 12:12:57 │    ᴺᵁᴸᴸ │
└─────────────────────┴─────────┘

قُدِّمت في: v1.1.0

مماثلة لـ parseDateTimeBestEffort، باستثناء أنها تُرجع zero date أو zero date time عند مصادفة تنسيق تاريخ يتعذر معالجته. تحلّل الدالة ISO 8601 وRFC 1123 - 5.2.14 RFC-822 Date and Time Specification وتنسيقات التاريخ والوقت الخاصة بـ ClickHouse، بالإضافة إلى بعض التنسيقات الأخرى.

التنسيقات غير القياسية المدعومة:

• سلسلة تحتوي على Unix timestamp مكوّن من 9 إلى 10 أرقام.
• سلسلة تتضمن مكوّن تاريخ ومكوّن وقت: YYYYMMDDhhmmss, DD/MM/YYYY hh:mm:ss, DD-MM-YY hh:mm, YYYY-MM-DD hh:mm:ss، إلخ.
• سلسلة تتضمن تاريخًا، ولكن من دون مكوّن وقت: YYYY, YYYYMM, YYYY*MM, DD/MM/YYYY, DD-MM-YY، إلخ.
• سلسلة تتضمن يومًا ووقتًا: DD, DD hh, DD hh:mm. في هذه الحالة، يُستبدل MM بـ 01.
• سلسلة تتضمن التاريخ والوقت إلى جانب معلومات إزاحة المنطقة الزمنية: YYYY-MM-DD hh:mm:ss ±h:mm، إلخ.
• syslog timestamp: Mmm dd hh:mm:ss. على سبيل المثال: Jun 9 14:20:32.

بالنسبة إلى جميع التنسيقات التي تتضمن فاصلًا، تحلّل الدالة أسماء الأشهر المكتوبة إما بصيغتها الكاملة أو بأول ثلاثة أحرف منها. إذا لم تُحدَّد السنة، فتُعتبر السنة الحالية.

الصيغة

parseDateTimeBestEffortOrZero(time_string[, time_zone])

المعاملات

• time_string — سلسلة نصية تحتوي على تاريخ ووقت لتحويلهما. String
• time_zone — اختياري. المنطقة الزمنية التي يُحلَّل time_string وفقًا لها. String

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

يُرجع time_string كـ DateTime، أو تاريخًا/تاريخًا ووقتًا صفريًا (1970-01-01 أو 1970-01-01 00:00:00) إذا تعذّر تحليل المُدخل. DateTime

أمثلة

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

SELECT parseDateTimeBestEffortOrZero('23/10/2025 12:12:57') AS valid,
       parseDateTimeBestEffortOrZero('invalid') AS invalid

┌───────────────valid─┬─────────────invalid─┐
│ 2025-10-23 12:12:57 │ 1970-01-01 00:00:00 │
└─────────────────────┴─────────────────────┘

تم تقديمه في: v1.1.0

تعمل هذه الدالة مثل parseDateTimeBestEffort مع تنسيقات التاريخ وفق ISO، مثل YYYY-MM-DD hh:mm:ss، ومع تنسيقات التاريخ الأخرى التي يمكن فيها استخراج مكوِّنَي الشهر واليوم بوضوح ومن دون التباس، مثل YYYYMMDDhhmmss وYYYY-MM وDD hh وYYYY-MM-DD hh:mm:ss ±h:mm. إذا تعذّر استخراج مكوِّنَي الشهر واليوم بوضوح ومن دون التباس، مثل MM/DD/YYYY أو MM-DD-YYYY أو MM-DD-YY، فإنها تفضّل تنسيق التاريخ الأمريكي بدلًا من DD/MM/YYYY أو DD-MM-YYYY أو DD-MM-YY. واستثناءً مما سبق، إذا كانت قيمة الشهر أكبر من 12 وأقل من أو تساوي 31، فستعود هذه الدالة إلى سلوك parseDateTimeBestEffort. فعلى سبيل المثال، يُفسَّر 15/08/2020 على أنه 2020-08-15.

البنية

parseDateTimeBestEffortUS(time_string[, time_zone])

الوسيطات

• time_string — قيمة String تحتوي على تاريخ ووقت لتحويله. String
• time_zone — اختياري. المنطقة الزمنية التي يُحلَّل time_string على أساسها. String

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

يعيد time_string كقيمة DateTime مع تفضيل تنسيق التاريخ الأمريكي في الحالات الملتبسة. DateTime

أمثلة

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

SELECT parseDateTimeBestEffortUS('02/10/2025') AS us_format,
       parseDateTimeBestEffortUS('15/08/2025') AS fallback_to_standard

┌───────────us_format─┬─fallback_to_standard─┐
│ 2025-02-10 00:00:00 │  2025-08-15 00:00:00 │
└─────────────────────┴──────────────────────┘

تم تقديمها في: v1.1.0

مماثلة للدالة parseDateTimeBestEffortUS، باستثناء أنها تُرجع NULL عندما تصادف تنسيق تاريخ يتعذر معالجته.

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

البنية

parseDateTimeBestEffortUSOrNull(time_string[, time_zone])

الوسيطات

• time_string — سلسلة نصية تحتوي على تاريخ ووقت لتحويلهما. String
• time_zone — اختياري. المنطقة الزمنية التي يُحلَّل time_string وفقًا لها. String

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

يعيد time_string كقيمة من نوع DateTime باستخدام تفضيل التنسيق الأمريكي، أو NULL إذا تعذّر تحليل الإدخال. DateTime أو NULL

أمثلة

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

SELECT parseDateTimeBestEffortUSOrNull('02/10/2025') AS valid_us,
       parseDateTimeBestEffortUSOrNull('invalid') AS invalid

┌────────────valid_us─┬─invalid─┐
│ 2025-02-10 00:00:00 │    ᴺᵁᴸᴸ │
└─────────────────────┴─────────┘

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

هي مماثلة للدالة parseDateTimeBestEffortUS، باستثناء أنها تُرجِع تاريخًا صفريًا (1970-01-01) أو تاريخًا صفريًا مع وقت (1970-01-01 00:00:00) عند مواجهة تنسيق تاريخ يتعذر معالجته.

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

البنية

parseDateTimeBestEffortUSOrZero(time_string[, time_zone])

الوسيطات

• time_string — قيمة من النوع String تحتوي على تاريخ ووقت لتحويلهما. String
• time_zone — اختياري. المنطقة الزمنية التي يُفسَّر وفقًا لها time_string. String

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

تُعيد time_string على هيئة DateTime مع تفضيل التنسيق الأمريكي، أو التاريخ/التاريخ والوقت الصفري (1970-01-01 أو 1970-01-01 00:00:00) إذا تعذّر تفسير الإدخال. DateTime

أمثلة

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

SELECT parseDateTimeBestEffortUSOrZero('02/10/2025') AS valid_us,
       parseDateTimeBestEffortUSOrZero('invalid') AS invalid

┌────────────valid_us─┬─────────────invalid─┐
│ 2025-02-10 00:00:00 │ 1970-01-01 00:00:00 │
└─────────────────────┴─────────────────────┘

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

تحلّل سلسلة تاريخ ووقت وفقًا لـ date format string بنمط Joda.

هذه الدالة هي معكوس formatDateTimeInJodaSyntax. وهي تحلّل String argument باستخدام format String بنمط Joda. وتُرجِع نوع DateTime.

ارجع إلى توثيق Joda Time للاطلاع على أنماط التنسيق.

البنية

parseDateTimeInJodaSyntax(time_string, format[, timezone])

المعاملات

• time_string — سلسلة نصية تُحلَّل إلى DateTime. String
• format — سلسلة تنسيق ببنية Joda تحدد كيفية تحليل time_string. String
• timezone — اختياري. المنطقة الزمنية. String

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

تعيد قيمة DateTime بعد تحليل سلسلة الإدخال النصية وفق سلسلة التنسيق بنمط Joda. DateTime

أمثلة

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

SELECT parseDateTimeInJodaSyntax('2025-01-04 23:00:00', 'yyyy-MM-dd HH:mm:ss')

┌─parseDateTimeInJodaSyntax('2025-01-04 23:00:00', 'yyyy-MM-dd HH:mm:ss')─┐
│                                                     2025-01-04 23:00:00 │
└─────────────────────────────────────────────────────────────────────────┘

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

مماثلة لـ parseDateTimeInJodaSyntax، لكنها تُرجِع NULL عند مصادفة تنسيق تاريخ يتعذر تحليله.

البنية

parseDateTimeInJodaSyntaxOrNull(time_string, format[, timezone])

الوسيطات

• time_string — قيمة String المطلوب تحليلها إلى DateTime. String
• format — سلسلة تنسيق ببناء جملة Joda تحدد كيفية تحليل time_string. String
• timezone — اختياري. المنطقة الزمنية. String

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

يُرجع قيمة DateTime مُحلَّلة من سلسلة الإدخال، أو NULL إذا فشل التحليل. Nullable(DateTime)

أمثلة

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

SELECT parseDateTimeInJodaSyntaxOrNull('2025-01-04 23:00:00', 'yyyy-MM-dd HH:mm:ss')

┌─parseDateTimeInJodaSyntaxOrNull('2025-01-04 23:00:00', 'yyyy-MM-dd HH:mm:ss')─┐
│                                                           2025-01-04 23:00:00 │
└───────────────────────────────────────────────────────────────────────────────┘

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

مماثلة لـ parseDateTimeInJodaSyntax، لكنها تُرجع التاريخ الصفري عند مواجهة تنسيق تاريخ يتعذر تحليله.

الصياغة

parseDateTimeInJodaSyntaxOrZero(time_string, format[, timezone])

الوسيطات

• time_string — سلسلة نصية المطلوب تحليلها إلى DateTime. String
• format — سلسلة تنسيق ببناء جملة Joda تحدد كيفية تحليل time_string. String
• timezone — اختياري. المنطقة الزمنية. String

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

يعيد قيمة DateTime ناتجة عن تحليل سلسلة الإدخال، أو قيمة DateTime صفرية إذا فشل التحليل. DateTime

أمثلة

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

SELECT parseDateTimeInJodaSyntaxOrZero('2025-01-04 23:00:00', 'yyyy-MM-dd HH:mm:ss')

┌─parseDateTimeInJodaSyntaxOrZero('2025-01-04 23:00:00', 'yyyy-MM-dd HH:mm:ss')─┐
│                                                           2025-01-04 23:00:00 │
└───────────────────────────────────────────────────────────────────────────────┘

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

مثل parseDateTime، لكنها تُرجع NULL عند مواجهة تنسيق تاريخ يتعذر تحليله.

البنية

parseDateTimeOrNull(time_string, format[, timezone])

الأسماء البديلة: str_to_date

المعاملات

• time_string — سلسلة نصية يُراد تحليلها إلى DateTime. String
• format — سلسلة تنسيق تحدد كيفية تحليل time_string. String
• timezone — اختياري. المنطقة الزمنية. String

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

يعيد قيمة DateTime مُحلَّلة من سلسلة الإدخال، أو NULL إذا تعذّر التحليل. Nullable(DateTime)

أمثلة

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

SELECT parseDateTimeOrNull('2025-01-04+23:00:00', '%Y-%m-%d+%H:%i:%s')

┌─parseDateTimeOrNull('2025-01-04+23:00:00', '%Y-%m-%d+%H:%i:%s')─┐
│                                             2025-01-04 23:00:00 │
└─────────────────────────────────────────────────────────────────┘

استُحدث في: v23.3.0

مماثلة لـ parseDateTime، لكنها تُرجع التاريخ الصفري عند مصادفة تنسيق تاريخ غير قابل للتحليل.

الصياغة

parseDateTimeOrZero(time_string, format[, timezone])

الوسيطات

• time_string — سلسلة نصية مطلوب تحليلها إلى DateTime. String
• format — سلسلة تنسيق تحدد كيفية تحليل time_string. String
• timezone — اختياري. المنطقة الزمنية. String

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

يعيد قيمة DateTime ناتجة عن تحليل سلسلة الإدخال، أو zero DateTime إذا فشل التحليل. DateTime

أمثلة

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

SELECT parseDateTimeOrZero('2025-01-04+23:00:00', '%Y-%m-%d+%H:%i:%s')

┌─parseDateTimeOrZero('2025-01-04+23:00:00', '%Y-%m-%d+%H:%i:%s')─┐
│                                             2025-01-04 23:00:00 │
└─────────────────────────────────────────────────────────────────┘

قُدِّمت في: v1.1.0

تستخدم نفس تسلسل بايتات المصدر في الذاكرة للقيمة المعطاة x، وتُعيد تفسيره كنوع الوجهة. عندما يكون نوع الوجهة هو String، لا تكون المصفوفة المصدر Array مدعومة إلا إذا كان نوع عناصرها ثابت الحجم ومتجاورًا في الذاكرة (على سبيل المثال، Array(UInt8) أو Array(FixedString(2)))؛ وتُنسخ بايتات عناصرها حرفيًا بترتيبها الأصلي في الذاكرة، بحيث يمكن إعادة تفسير النتيجة مرة أخرى إلى النوع الأصلي Array على أي معمارية. أما المصفوفات التي تكون عناصرها متغيرة الطول (على سبيل المثال، Array(String)) أو قابلة لأن تكون NULL (على سبيل المثال، Array(Nullable(Int32))) فهي غير مدعومة.

البنية

reinterpret(x, type)

الوسائط

• x — القيمة المطلوب إعادة تفسيرها. عند إعادة التفسير إلى String، يجب أن يحتوي المصدر Array على عناصر متجاورة ثابتة الحجم. Any
• type — النوع الهدف. إذا كان مصفوفة، فيجب أن يكون نوع عناصر المصفوفة من الأنواع ذات الطول الثابت. String

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

قيمة من النوع الهدف. Any

أمثلة

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

SELECT reinterpret(toInt8(-1), 'UInt8') AS int_to_uint,
    reinterpret(toInt8(1), 'Float32') AS int_to_float,
    reinterpret('1', 'UInt32') AS string_to_int

┌─int_to_uint─┬─int_to_float─┬─string_to_int─┐
│         255 │        1e-45 │            49 │
└─────────────┴──────────────┴───────────────┘

مثال على النوع Array

SELECT reinterpret(x'3108b4403108d4403108b4403108d440', 'Array(Float32)') AS string_to_array_of_Float32

┌─string_to_array_of_Float32─┐
│ [5.626,6.626,5.626,6.626]  │
└────────────────────────────┘

مثال لتحويل Array إلى String

SELECT hex(reinterpret([toUInt8(1), toUInt8(2), toUInt8(255)]::Array(UInt8), 'String')) AS array_of_UInt8_to_string

┌─array_of_UInt8_to_string─┐
│ 0102FF                   │
└──────────────────────────┘

قُدِّم في: v1.1.0

يعيد تفسير قيمة الإدخال على أنها قيمة من النوع Date (بافتراض ترتيب البايتات little endian)، وهي عدد الأيام منذ بداية Unix epoch ‏1970-01-01

البنية

reinterpretAsDate(x)

الوسيطات

• x — عدد الأيام منذ بداية حقبة Unix. (U)Int* أو Float* أو Date أو DateTime أو UUID أو String أو FixedString

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

Date. Date

أمثلة

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

SELECT reinterpretAsDate(65), reinterpretAsDate('A')

┌─reinterpretAsDate(65)─┬─reinterpretAsDate('A')─┐
│            1970-03-07 │             1970-03-07 │
└───────────────────────┴────────────────────────┘

أُضيف في: v1.1.0

يعيد تفسير قيمة الإدخال على أنها قيمة من نوع DateTime (على افتراض ترتيب little endian)، وهي عدد الأيام منذ بداية حقبة Unix ‏1970-01-01

الصياغة

reinterpretAsDateTime(x)

الوسائط

• x — عدد الثواني منذ بداية حقبة يونكس. (U)Int* أو Float* أو Date أو DateTime أو UUID أو String أو FixedString

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

التاريخ والوقت. DateTime

أمثلة

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

SELECT reinterpretAsDateTime(65), reinterpretAsDateTime('A')

┌─reinterpretAsDateTime(65)─┬─reinterpretAsDateTime('A')─┐
│       1970-01-01 00:01:05 │        1970-01-01 00:01:05 │
└───────────────────────────┴────────────────────────────┘

تم تقديمه في: v1.1.0

يعيد تفسير قيمة الإدخال على أنها سلسلة ثابتة الطول (بافتراض ترتيب البايتات little endian). يُتجاهَل بايت NULL في النهاية، فعلى سبيل المثال، تُرجِع الدالة للقيمة 255 من النوع UInt32 سلسلةً تحتوي على محرف واحد.

البنية

reinterpretAsFixedString(x)

الوسائط

• x — القيمة المطلوب إعادة تفسيرها كسلسلة نصية. (U)Int* أو Float* أو Date أو DateTime

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

سلسلة ثابتة تحتوي على البايتات التي تمثل x. FixedString

أمثلة

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

-- The result is a sequence of bytes, so it is shown with `hex`.
SELECT
    hex(reinterpretAsFixedString(toDateTime('1970-01-01 01:01:05'))),
    hex(reinterpretAsFixedString(toDate('1970-03-07')))

┌─hex(reinterpretAsFixedString(toDateTime('1970-01-01 01:01:05')))─┬─hex(reinterpretAsFixedString(toDate('1970-03-07')))─┐
│ 510E0000                                                         │ 4100                                                │
└──────────────────────────────────────────────────────────────────┴─────────────────────────────────────────────────────┘

أُضيف في: v1.1.0

يعيد تفسير قيمة الإدخال على أنها قيمة من النوع Float32. وعلى خلاف CAST، لا تحاول الدالة الحفاظ على القيمة الأصلية؛ فإذا لم يكن النوع الهدف قادرًا على تمثيل نوع الإدخال، تكون قيمة الإخراج غير معرّفة.

البنية

reinterpretAsFloat32(x)

الوسائط

• x — القيمة المراد إعادة تفسيرها كـ Float32. (U)Int* أو Float* أو Date أو DateTime أو UUID أو String أو FixedString

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

تُرجع القيمة x بعد إعادة تفسيرها. Float32

أمثلة

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

SELECT reinterpretAsUInt32(toFloat32(0.2)) AS x, reinterpretAsFloat32(x)

┌──────────x─┬─reinterpretAsFloat32(x)─┐
│ 1045220557 │                     0.2 │
└────────────┴─────────────────────────┘

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

تعيد تفسير قيمة الإدخال باعتبارها قيمة من النوع Float64. وعلى خلاف CAST، لا تحاول الدالة الحفاظ على القيمة الأصلية؛ وإذا كان النوع الهدف غير قادر على تمثيل نوع الإدخال، تكون قيمة الإخراج غير معرّفة.

البنية

reinterpretAsFloat64(x)

الوسيطات

• x — قيمة يُعاد تفسيرها كـ Float64. (U)Int* أو Float* أو Date أو DateTime أو UUID أو String أو FixedString

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

تعيد القيمة x بعد إعادة تفسيرها. Float64

أمثلة

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

SELECT reinterpretAsUInt64(toFloat64(0.2)) AS x, reinterpretAsFloat64(x)

┌───────────────────x─┬─reinterpretAsFloat64(x)─┐
│ 4596373779694328218 │                     0.2 │
└─────────────────────┴─────────────────────────┘

أُضيف في: v1.1.0

يُعيد تفسير قيمة الإدخال باعتبارها قيمة من النوع Int128. وبخلاف CAST، لا تحاول هذه الدالة الحفاظ على القيمة الأصلية؛ فإذا كان النوع الهدف غير قادر على تمثيل نوع الإدخال، تكون قيمة الإخراج غير معرّفة.

البنية

reinterpretAsInt128(x)

المعاملات

• x — القيمة المراد إعادة تفسيرها كـ Int128. (U)Int* أو Float* أو Date أو DateTime أو UUID أو String أو FixedString

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

يعيد القيمة x بعد إعادة تفسيرها. Int128

أمثلة

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

SELECT
    toInt64(257) AS x,
    toTypeName(x),
    reinterpretAsInt128(x) AS res,
    toTypeName(res)

┌───x─┬─toTypeName(x)─┬─res─┬─toTypeName(res)─┐
│ 257 │ Int64         │ 257 │ Int128          │
└─────┴───────────────┴─────┴─────────────────┘

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

تعيد تفسير قيمة الإدخال باعتبارها قيمة من النوع Int16. وعلى خلاف CAST، لا تحاول الدالة الحفاظ على القيمة الأصلية؛ فإذا لم يكن النوع المستهدف قادرًا على تمثيل نوع الإدخال، تكون قيمة الإخراج غير معرّفة.

الصياغة

reinterpretAsInt16(x)

المعاملات

• x — القيمة المراد إعادة تفسيرها كـ Int16. (U)Int* أو Float* أو Date أو DateTime أو UUID أو String أو FixedString

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

تُعيد القيمة x بعد إعادة تفسيرها. Int16

أمثلة

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

SELECT
    toInt8(257) AS x,
    toTypeName(x),
    reinterpretAsInt16(x) AS res,
    toTypeName(res)

┌─x─┬─toTypeName(x)─┬─res─┬─toTypeName(res)─┐
│ 1 │ Int8          │   1 │ Int16           │
└───┴───────────────┴─────┴─────────────────┘

قُدِّمت في: v1.1.0

يعيد تفسير قيمة الإدخال على أنها قيمة من النوع Int256. وعلى خلاف CAST، لا تحاول هذه الدالة الحفاظ على القيمة الأصلية؛ وإذا كان النوع الهدف غير قادر على تمثيل نوع الإدخال، تكون النتيجة غير معرّفة.

البنية

reinterpretAsInt256(x)

الوسيطات

• x — القيمة المراد إعادة تفسيرها كـ Int256. (U)Int* أو Float* أو Date أو DateTime أو UUID أو String أو FixedString

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

تُرجِع القيمة x بعد إعادة تفسيرها. Int256

أمثلة

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

SELECT
    toInt128(257) AS x,
    toTypeName(x),
    reinterpretAsInt256(x) AS res,
    toTypeName(res)

┌───x─┬─toTypeName(x)─┬─res─┬─toTypeName(res)─┐
│ 257 │ Int128        │ 257 │ Int256          │
└─────┴───────────────┴─────┴─────────────────┘

قُدِّمت في: v1.1.0

تعيد تفسير قيمة الإدخال باعتبارها قيمة من النوع Int32. وعلى خلاف CAST، لا تحاول الدالة الحفاظ على القيمة الأصلية؛ فإذا لم يكن النوع الهدف قادرًا على تمثيل نوع الإدخال، تكون قيمة الإخراج غير معرّفة.

البنية

reinterpretAsInt32(x)

الوسيطات

• x — القيمة المراد إعادة تفسيرها إلى Int32. (U)Int* أو Float* أو Date أو DateTime أو UUID أو String أو FixedString

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

تُرجع القيمة x بعد إعادة تفسيرها. Int32

أمثلة

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

SELECT
    toInt16(257) AS x,
    toTypeName(x),
    reinterpretAsInt32(x) AS res,
    toTypeName(res)

┌───x─┬─toTypeName(x)─┬─res─┬─toTypeName(res)─┐
│ 257 │ Int16         │ 257 │ Int32           │
└─────┴───────────────┴─────┴─────────────────┘

تم تقديمه في: v1.1.0

يعيد تفسير قيمة الإدخال باعتبارها قيمة من النوع Int64. وخلافًا لـ CAST، لا تحاول الدالة الحفاظ على القيمة الأصلية؛ فإذا لم يكن النوع الهدف قادرًا على تمثيل نوع الإدخال، تكون قيمة الإخراج غير معرّفة.

البنية

reinterpretAsInt64(x)

المعاملات

• x — القيمة المراد إعادة تفسيرها كـ Int64. (U)Int* أو Float* أو Date أو DateTime أو UUID أو String أو FixedString

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

تُرجِع القيمة x بعد إعادة تفسيرها. Int64

أمثلة

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

SELECT
    toInt32(257) AS x,
    toTypeName(x),
    reinterpretAsInt64(x) AS res,
    toTypeName(res)

┌───x─┬─toTypeName(x)─┬─res─┬─toTypeName(res)─┐
│ 257 │ Int32         │ 257 │ Int64           │
└─────┴───────────────┴─────┴─────────────────┘

أُضيف في: v1.1.0

يعيد تفسير قيمة الإدخال على أنها قيمة من النوع Int8. وعلى خلاف CAST، لا تحاول هذه الدالة الحفاظ على القيمة الأصلية؛ وإذا كان النوع الهدف غير قادر على تمثيل نوع الإدخال، تكون قيمة الإخراج غير معرّفة.

البنية

reinterpretAsInt8(x)

الوسائط

• x — القيمة المراد إعادة تفسيرها إلى Int8. (U)Int* أو Float* أو Date أو DateTime أو UUID أو String أو FixedString

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

تُرجع القيمة x بعد إعادة تفسيرها. Int8

أمثلة

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

SELECT
    toUInt8(257) AS x,
    toTypeName(x),
    reinterpretAsInt8(x) AS res,
    toTypeName(res)

┌─x─┬─toTypeName(x)─┬─res─┬─toTypeName(res)─┐
│ 1 │ UInt8         │   1 │ Int8            │
└───┴───────────────┴─────┴─────────────────┘

ظهر في: v1.1.0

تعيد تفسير قيمة الإدخال كسلسلة نصية. بالنسبة إلى القيم scalar، يُطبَّع ترتيب البايتات إلى little endian، ويتم تجاهل وحدات null byte الموجودة في النهاية. على سبيل المثال، تُرجِع الدالة للقيمة 255 من النوع UInt32 سلسلة نصية تحتوي على محرف واحد. أما في حالة Array من عناصر ثابتة الحجم، فتُنسخ بايتات العناصر حرفيًا بترتيبها الأصلي داخل الذاكرة، من دون إزالة بايتات الصفر اللاحقة ومن دون التطبيع إلى little endian، بحيث يمكن إعادة تفسير النتيجة إلى نوع Array الأصلي على أي معمارية.

البنية

reinterpretAsString(x)

الوسائط

• x — القيمة المطلوب إعادة تفسيرها كسلسلة نصية. (U)Int* أو Float* أو Date أو DateTime أو Array

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

سلسلة String تحتوي على بايتات تمثل x. String

أمثلة

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

-- The result is a sequence of bytes, so it is shown with `hex`.
SELECT
    hex(reinterpretAsString(toDateTime('1970-01-01 01:01:05'))),
    hex(reinterpretAsString(toDate('1970-03-07')))

┌─hex(reinterpretAsString(toDateTime('1970-01-01 01:01:05')))─┬─hex(reinterpretAsString(toDate('1970-03-07')))─┐
│ 510E                                                        │ 41                                             │
└─────────────────────────────────────────────────────────────┴────────────────────────────────────────────────┘

مثال على تحويل Array إلى String

SELECT hex(reinterpretAsString([toUInt8(1), toUInt8(2), toUInt8(255)]::Array(UInt8))) AS array_of_UInt8_to_string

┌─array_of_UInt8_to_string─┐
│ 0102FF                   │
└──────────────────────────┘

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

تعيد تفسير قيمة الإدخال على أنها قيمة من النوع UInt128. وعلى خلاف CAST، لا تحاول الدالة الحفاظ على القيمة الأصلية؛ فإذا لم يكن النوع الهدف قادرًا على تمثيل نوع الإدخال، تكون قيمة الإخراج غير معرّفة.

البنية

reinterpretAsUInt128(x)

الوسائط

• x — القيمة المراد إعادة تفسيرها كـ UInt128. (U)Int* أو Float* أو Date أو DateTime أو UUID أو String أو FixedString

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

تُرجع القيمة x بعد إعادة تفسيرها. UInt128

أمثلة

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

SELECT
    toUInt64(257) AS x,
    toTypeName(x),
    reinterpretAsUInt128(x) AS res,
    toTypeName(res)

┌───x─┬─toTypeName(x)─┬─res─┬─toTypeName(res)─┐
│ 257 │ UInt64        │ 257 │ UInt128         │
└─────┴───────────────┴─────┴─────────────────┘

أُضيف في: v1.1.0

يعيد تفسير قيمة الإدخال باعتبارها قيمة من النوع UInt16. وعلى خلاف CAST، لا تحاول هذه الدالة الحفاظ على القيمة الأصلية؛ فإذا لم يكن النوع الهدف قادرًا على تمثيل نوع الإدخال، تكون قيمة الإخراج غير معرّفة.

البنية

reinterpretAsUInt16(x)

المعاملات

• x — القيمة المطلوب إعادة تفسيرها كـ UInt16. (U)Int* أو Float* أو Date أو DateTime أو UUID أو String أو FixedString

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

تُرجِع القيمة x بعد إعادة تفسيرها. UInt16

أمثلة

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

SELECT
    toUInt8(257) AS x,
    toTypeName(x),
    reinterpretAsUInt16(x) AS res,
    toTypeName(res)

┌─x─┬─toTypeName(x)─┬─res─┬─toTypeName(res)─┐
│ 1 │ UInt8         │   1 │ UInt16          │
└───┴───────────────┴─────┴─────────────────┘

قُدِّم في: v1.1.0

يعيد تفسير قيمة الإدخال باعتبارها قيمة من النوع UInt256. وعلى خلاف CAST، لا تحاول الدالة الحفاظ على القيمة الأصلية؛ فإذا لم يكن النوع الهدف قادرًا على تمثيل نوع الإدخال، تكون قيمة الإخراج غير معرّفة.

الصياغة

reinterpretAsUInt256(x)

الوسيطات

• x — القيمة المراد إعادة تفسيرها بصفتها UInt256. (U)Int* أو Float* أو Date أو DateTime أو UUID أو String أو FixedString

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

القيمة x بعد إعادة تفسيرها. UInt256

أمثلة

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

SELECT
    toUInt128(257) AS x,
    toTypeName(x),
    reinterpretAsUInt256(x) AS res,
    toTypeName(res)

┌───x─┬─toTypeName(x)─┬─res─┬─toTypeName(res)─┐
│ 257 │ UInt128       │ 257 │ UInt256         │
└─────┴───────────────┴─────┴─────────────────┘

قُدِّمت في: v1.1.0

يعيد تفسير قيمة الإدخال باعتبارها قيمة من النوع UInt32. وعلى خلاف CAST، لا تحاول الدالة الحفاظ على القيمة الأصلية؛ وإذا لم يكن النوع الهدف قادرًا على تمثيل نوع الإدخال، فستكون قيمة الإخراج غير معرّفة.

الصيغة

reinterpretAsUInt32(x)

المعاملات

• x — القيمة المراد إعادة تفسيرها على أنها UInt32. (U)Int* أو Float* أو Date أو DateTime أو UUID أو String أو FixedString

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

تعيد القيمة x بعد إعادة تفسيرها. UInt32

أمثلة

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

SELECT
    toUInt16(257) AS x,
    toTypeName(x),
    reinterpretAsUInt32(x) AS res,
    toTypeName(res)

┌───x─┬─toTypeName(x)─┬─res─┬─toTypeName(res)─┐
│ 257 │ UInt16        │ 257 │ UInt32          │
└─────┴───────────────┴─────┴─────────────────┘

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

تعيد هذه الدالة تفسير قيمة الإدخال على أنها قيمة من النوع UInt64. وخلافًا لـ CAST، لا تحاول الدالة الحفاظ على القيمة الأصلية؛ وإذا كان النوع الهدف غير قادر على تمثيل نوع الإدخال، تكون قيمة الإخراج غير معرّفة.

الصيغة

reinterpretAsUInt64(x)

الوسيطات

• x — القيمة المراد إعادة تفسيرها كـ UInt64. Int* أو UInt* أو Float* أو Date أو DateTime أو UUID أو String أو FixedString

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

القيمة المُعاد تفسيرها لـ x. UInt64

أمثلة

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

SELECT
    toUInt32(257) AS x,
    toTypeName(x),
    reinterpretAsUInt64(x) AS res,
    toTypeName(res)

┌───x─┬─toTypeName(x)─┬─res─┬─toTypeName(res)─┐
│ 257 │ UInt32        │ 257 │ UInt64          │
└─────┴───────────────┴─────┴─────────────────┘

أُضيف في: v1.1.0

يعيد تفسير قيمة الإدخال على أنها قيمة من النوع UInt8. وعلى خلاف CAST، لا تحاول الدالة الحفاظ على القيمة الأصلية؛ فإذا لم يكن النوع الهدف قادرًا على تمثيل نوع الإدخال، تكون النتيجة غير معرّفة.

البنية

reinterpretAsUInt8(x)

الوسائط

• x — القيمة المطلوب إعادة تفسيرها باعتبارها UInt8. (U)Int* أو Float* أو Date أو DateTime أو UUID أو String أو FixedString

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

تُرجع القيمة x بعد إعادة تفسيرها. UInt8

أمثلة

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

SELECT
    toInt8(-1) AS val,
    toTypeName(val),
    reinterpretAsUInt8(val) AS res,
    toTypeName(res);

┌─val─┬─toTypeName(val)─┬─res─┬─toTypeName(res)─┐
│  -1 │ Int8            │ 255 │ UInt8           │
└─────┴─────────────────┴─────┴─────────────────┘

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

تقبل سلسلة بطول 16 بايت وتُرجع UUID عبر تفسير كل نصف مكوّن من 8 بايتات بترتيب البايتات little-endian. وإذا لم يكن طول السلسلة كافيًا، فستعمل الدالة كما لو أُضيف إليها العدد اللازم من البايتات الصفرية في النهاية. وإذا كانت السلسلة أطول من 16 بايتًا، فسيتم تجاهل البايتات الزائدة في النهاية.

البنية

reinterpretAsUUID(fixed_string)

الوسائط

• fixed_string — سلسلة بايتات بترتيب big-endian. FixedString

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

قيمة من النوع UUID. UUID

أمثلة

من String إلى UUID

SELECT reinterpretAsUUID(reverse(unhex('000102030405060708090a0b0c0d0e0f')))

┌─reinterpretAsUUID(reverse(unhex('000102030405060708090a0b0c0d0e0f')))─┐
│ 08090a0b-0c0d-0e0f-0001-020304050607                                  │
└───────────────────────────────────────────────────────────────────────┘

أُضيف في: v1.1.0

يحوّل قيمة الإدخال إلى قيمة من النوع BFloat16. ويُطلق استثناءً عند حدوث خطأ.

انظر أيضًا:

• toBFloat16OrZero.
• toBFloat16OrNull.

الصيغة

toBFloat16(expr)

الوسائط

• expr — تعبير يُرجع رقمًا أو تمثيلًا نصيًا لرقم. تعبير

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

تُرجِع قيمة brain-float‏ 16 بت. BFloat16

أمثلة

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

SELECT
toBFloat16(toFloat32(42.7)),
toBFloat16(toFloat32('42.7')),
toBFloat16('42.7')
FORMAT Vertical;

Row 1:
──────
toBFloat16(toFloat32(42.7)):   42.5
toBFloat16(toFloat32('42.7')): 42.5
toBFloat16('42.7'):            42.5

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

تحوِّل قيمة إدخال من نوع String إلى قيمة من النوع BFloat16. إذا كانت السلسلة النصية لا تمثِّل قيمة عددية بفاصلة عائمة، فتعيد الدالة NULL.

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

• التمثيلات النصية للقيم الرقمية.

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

• التمثيلات النصية للقيم الثنائية والسداسية العشرية.
• القيم الرقمية.

انظر أيضًا:

• toBFloat16.
• toBFloat16OrZero.

البنية

toBFloat16OrNull(x)

الوسيطات

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

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

تعيد قيمة brain-float‏ من 16 بت، وإلا NULL. BFloat16 أو NULL

أمثلة

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

SELECT toBFloat16OrNull('0x5E'), -- unsupported arguments
       toBFloat16OrNull('12.3'), -- typical use
       toBFloat16OrNull('12.3456789') -- silent loss of precision

\N	12.25	12.3125

طُرح في: v1.1.0

يحوّل قيمة إدخال من نوع String إلى قيمة من النوع BFloat16. إذا لم تكن السلسلة النصية تمثل قيمة بفاصلة عائمة، فستُرجع الدالة صفرًا.

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

• التمثيلات النصية للقيم الرقمية.

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

• التمثيلات النصية للقيم الثنائية والسداسية العشرية.
• القيم الرقمية.

انظر أيضًا:

• toBFloat16.
• toBFloat16OrNull.

الصياغة

toBFloat16OrZero(x)

الوسائط

• x — تمثيل نصي لعدد. String

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

تُرجع قيمة brain-float ذات 16 بت، وإلا فتُرجع 0. BFloat16

أمثلة

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

SELECT toBFloat16OrZero('0x5E'), -- unsupported arguments
       toBFloat16OrZero('12.3'), -- typical use
       toBFloat16OrZero('12.3456789') -- silent loss of precision

0	12.25	12.3125

أُضيف في: v22.2.0

يحوّل قيمة الإدخال إلى قيمة من النوع Bool.

الصيغة

toBool(expr)

الوسائط

• expr — تعبير يُرجع رقمًا أو سلسلة نصية. بالنسبة إلى السلاسل النصية، يقبل 'true' أو 'false' (غير حساس لحالة الأحرف). (U)Int* أو Float* أو String أو Expression

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

يُرجع true أو false بناءً على تقييم الوسيط. Bool

أمثلة

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

SELECT
    toBool(toUInt8(1)),
    toBool(toInt8(-1)),
    toBool(toFloat32(1.01)),
    toBool('true'),
    toBool('false'),
    toBool('FALSE')
FORMAT Vertical

Row 1:
──────
toBool(toUInt8(1)):      true
toBool(toInt8(-1)):      true
toBool(toFloat32(1.01)): true
toBool('true'):          true
toBool('false'):         false
toBool('FALSE'):         false

أُضيف في: v1.1.0

يحوّل قيمة مُدخلة إلى النوع Date. يدعم التحويل من الأنواع String وFixedString وDateTime أو من الأنواع الرقمية.

البنية

toDate(x)

المعاملات

• x — قيمة الإدخال المطلوب تحويلها. String أو FixedString أو DateTime أو (U)Int* أو Float*

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

يعيد قيمة الإدخال بعد تحويلها. Date

أمثلة

تحويل String إلى Date

SELECT toDate('2025-04-15')

2025-04-15

تحويل DateTime إلى Date

SELECT toDate(toDateTime('2025-04-15 10:30:00'))

2025-04-15

تحويل العدد الصحيح إلى Date

SELECT toDate(20297)

2025-07-28

أُضيف في: v21.9.0

يحوّل الوسيطة إلى نوع البيانات Date32. إذا كانت القيمة خارج النطاق [0000-01-01, 9999-12-31]، فإن toDate32 يعيد القيم الحدّية التي يدعمها Date32. إذا كانت الوسيطة من النوع Date، فتُؤخذ حدودها في الاعتبار.

البنية

toDate32(expr)

وسيط

• expr — القيمة المراد تحويلها. String أو UInt32 أو Date

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

يعيد تاريخًا تقويميًا. Date32

أمثلة

ضمن النطاق

SELECT toDate32('2025-01-01') AS value, toTypeName(value)
FORMAT Vertical

Row 1:
──────
value:             2025-01-01
toTypeName(value): Date32

قبل عام 1900

SELECT toDate32('1899-01-01') AS value, toTypeName(value)
FORMAT Vertical

Row 1:
──────
value:             1899-01-01
toTypeName(value): Date32

أُضيف في: v21.11.0

يحوِّل الوسيط إلى نوع البيانات Date32. إذا تعذّر تحويل الوسيط، بما في ذلك القيمة الرقمية الواقعة خارج نطاق Date32، فإن الدالة تُرجع قيمة افتراضية تكون إما الوسيط الثاني (إذا تم تحديده)، أو 1900-01-01 بخلاف ذلك، وهي القيمة الافتراضية التاريخية لـ Date32 (وليست حدها الأدنى، وهو 0000-01-01). وإذا كان الوسيط من النوع Date، فتُؤخذ حدوده في الاعتبار.

لاحظ أنه، بخلاف toDate32، لا تقيِّد هذه الدالة الوسيط الرقمي الواقع خارج النطاق ضمن حدود Date32؛ بل يُعامل هذا الوسيط على أنه غير قابل للتحويل.

البنية

toDate32OrDefault(expr[, default])

الوسيطات

• expr — تعبير يُرجع رقمًا أو تمثيلًا نصيًا لرقم. String أو (U)Int* أو Float*
• default — اختياري. القيمة الافتراضية التي ستُعاد إذا تعذّر التحليل. Date32

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

قيمة من النوع Date32 عند النجاح، وإلا فستُعاد القيمة الافتراضية إذا تم تمريرها، أو 1900-01-01 إذا لم يتم ذلك. Date32

أمثلة

تحويل ناجح

SELECT toDate32OrDefault('1930-01-01', toDate32('2020-01-01'))

1930-01-01

تعذّر التحويل

SELECT toDate32OrDefault('xx1930-01-01', toDate32('2020-01-01'))

2020-01-01

رقم خارج النطاق

SELECT toDate32OrDefault(toUInt64(18446744073709551615), toDate32('2020-01-01'))

2020-01-01

أُضيف في: v21.9.0

يحوّل قيمة الإدخال إلى قيمة من النوع Date32، لكنه يعيد NULL إذا كانت الوسيطة غير صالحة. وهو مماثل لـ toDate32، لكنه يعيد NULL إذا كانت الوسيطة غير صالحة.

البنية

toDate32OrNull(x)

الوسائط

• x — تمثيل نصي لتاريخ. String

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

تعيد قيمة من النوع Date32 عند النجاح، وإلا NULL. Date32 أو NULL

أمثلة

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

SELECT toDate32OrNull('2025-01-01'), toDate32OrNull('invalid')

┌─toDate32OrNull('2025-01-01')─┬─toDate32OrNull('invalid')─┐
│                   2025-01-01 │                      ᴺᵁᴸᴸ │
└──────────────────────────────┴───────────────────────────┘

أُضيف في: v21.9.0

يحوّل قيمة الإدخال إلى قيمة من النوع Date32، لكنه يعيد القيمة الافتراضية 1900-01-01 إذا كانت الوسيطة غير صالحة. وهو مماثل لـ toDate32، لكنه يعيد 1900-01-01 إذا كانت الوسيطة غير صالحة. لاحظ أن 1900-01-01 قيمة افتراضية تاريخية للإدخال غير الصالح، وليست الحد الأدنى لـ Date32، وهو 0000-01-01.

انظر أيضًا:

• toDate32
• toDate32OrNull
• toDate32OrDefault

الصيغة

toDate32OrZero(x)

الوسيطات

• x — تمثيل نصي لتاريخ. String

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

تُعيد قيمة Date32 عند النجاح، وإلا تُعيد القيمة الافتراضية التاريخية للإدخال غير الصالح (1900-01-01). Date32

أمثلة

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

SELECT toDate32OrZero('2025-01-01'), toDate32OrZero('')

┌─toDate32OrZero('2025-01-01')─┬─toDate32OrZero('')─┐
│                   2025-01-01 │         1900-01-01 │
└──────────────────────────────┴────────────────────┘

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

مثل toDate، ولكن إذا تعذّر ذلك، فتعيد قيمة افتراضية تكون إما الوسيطة الثانية (إذا كانت محددة)، أو الحد الأدنى لنوع Date بخلاف ذلك.

الصياغة

toDateOrDefault(expr[, default])

الوسيطات

• expr — تعبير يُرجع عددًا أو تمثيلًا نصيًا لعدد. String أو (U)Int* أو Float*
• default — اختياري. القيمة الافتراضية التي تُعاد إذا تعذّر التحليل. Date

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

قيمة من النوع Date عند النجاح، وإلا فتُعاد القيمة الافتراضية إذا مُرِّرت، أو 1970-01-01 إذا لم تُمرَّر. Date

أمثلة

تحويل ناجح

SELECT toDateOrDefault('2022-12-30')

2022-12-30

فشل التحويل

SELECT toDateOrDefault('', CAST('2023-01-01', 'Date'))

2023-01-01

استُحدث في: v1.1.0

يحوّل قيمة الإدخال إلى قيمة من النوع Date، لكنه يعيد NULL إذا تلقّى وسيطة غير صالحة. وهو مثل toDate، لكنه يعيد NULL إذا تلقّى وسيطة غير صالحة. تُفسَّر الوسيطة الصحيحة بالطريقة نفسها المتّبعة في toDate (على أنها عدد الأيام منذ 1970-01-01 إذا لم تتجاوز 65535، وإلا فتُعد Unix timestamp)، وتُرجع NULL إذا كانت خارج نطاق النوع Date.

الصياغة

toDateOrNull(x)

الوسائط

• x — تمثيل نصي لتاريخ، أو عدد صحيح من الأيام، أو Unix timestamp. String أو (U)Int8/16/32/64

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

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

أمثلة

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

SELECT toDateOrNull('2025-12-30'), toDateOrNull('invalid')

┌─toDateOrNull('2025-12-30')─┬─toDateOrNull('invalid')─┐
│                 2025-12-30 │                    ᴺᵁᴸᴸ │
└────────────────────────────┴─────────────────────────┘

أُضيف في: v1.1.0

يحوّل قيمة الإدخال إلى قيمة من النوع Date، لكنه يعيد الحد الأدنى لـ Date عند تمرير وسيطة غير صالحة. وهو مماثل لـ toDate، لكنه يعيد الحد الأدنى لـ Date عند تمرير وسيطة غير صالحة.

انظر أيضًا:

• toDate
• toDateOrNull
• toDateOrDefault

البنية

toDateOrZero(x)

الوسائط

• x — تمثيل نصي لتاريخ. String

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

يعيد قيمة من النوع Date عند النجاح، وإلا فيُعيد الحد الأدنى لـ Date (1970-01-01). Date

أمثلة

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

SELECT toDateOrZero('2025-12-30'), toDateOrZero('')

┌─toDateOrZero('2025-12-30')─┬─toDateOrZero('')─┐
│                 2025-12-30 │       1970-01-01 │
└────────────────────────────┴──────────────────┘

أُضيف في: v1.1.0

يحوّل قيمة مُدخلة إلى النوع DateTime.

الصياغة

toDateTime(expr[, time_zone])

الوسيطات

• expr — القيمة. String أو Int أو Date أو DateTime
• time_zone — المنطقة الزمنية. String

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

يُرجع قيمة من نوع التاريخ والوقت. DateTime

أمثلة

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

SELECT toDateTime('2025-01-01 00:00:00'), toDateTime(1735689600, 'UTC')
FORMAT Vertical

Row 1:
──────
toDateTime('2025-01-01 00:00:00'): 2025-01-01 00:00:00
toDateTime(1735689600, 'UTC'):     2025-01-01 00:00:00

مُتاح منذ: v20.9.0

يحوّل قيمة الإدخال إلى النوع DateTime. يدعم التحويل من String أو FixedString أو Date أو Date32 أو Time أو DateTime أو DateTime64 أو الأنواع الرقمية ((U)Int8 أو (U)Int16 أو (U)Int32 أو (U)Int64 أو BFloat16 أو Float32 أو Float64). لا تُدعم قيم Decimal وTime64 وتؤدي إلى استثناء؛ أما النوع Time وأنواع الأعداد الصحيحة العريضة، مثل (U)Int128/(U)Int256، فتلتف قيمها بدلاً من إشباعها. DateTime32 اسم مستعار لـ DateTime ويدعم التواريخ من 1970-01-01 00:00:00 إلى 2106-02-07 06:28:15. عند التحويل من سلسلة أو من أحد الأنواع الرقمية القابلة للإشباع المذكورة أعلاه، تُقيَّد القيم الواقعة خارج هذا النطاق بحدوده. لا يمكن تحويل قيم الفاصلة العائمة غير المنتهية (NaN وinf و-inf) وتؤدي إلى استثناء. تتبع التحويلات من أنواع التاريخ والوقت الأخرى، مثل Date32 أو DateTime64، الإعداد date_time_overflow_behavior: فقد ينتج عن وضع ignore الافتراضي قيم ملتفة، بينما يقيّد saturate القيم بحدود النطاق، ويطرح throw استثناءً.

الصيغة

toDateTime32(x[, timezone])

الوسيطات

• x — قيمة الإدخال المراد تحويلها. String أو FixedString أو (U)Int* أو Float* أو BFloat16 أو Date أو Date32 أو Time أو DateTime أو DateTime64
• timezone — اختياري. المنطقة الزمنية لقيمة DateTime المُعادة. String

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

تعيد قيمة الإدخال بعد تحويلها. DateTime

أمثلة

من سلسلة نصية

SELECT toDateTime32('2025-01-01 00:00:00') AS value, toTypeName(value);

┌───────────────value─┬─toTypeName(value)─┐
│ 2025-01-01 00:00:00 │ DateTime          │
└─────────────────────┴───────────────────┘

من Unix timestamp

SELECT toDateTime32(1735689600, 'UTC') AS value, toTypeName(value);

┌───────────────value─┬─toTypeName(value)─┐
│ 2025-01-01 00:00:00 │ DateTime('UTC')   │
└─────────────────────┴───────────────────┘

باستخدام منطقة زمنية

SELECT toDateTime32('2025-01-01 00:00:00', 'Asia/Istanbul') AS value, toTypeName(value);

┌───────────────value─┬─toTypeName(value)─────────┐
│ 2025-01-01 00:00:00 │ DateTime('Asia/Istanbul') │
└─────────────────────┴───────────────────────────┘

أُضيف في: v20.1.0

يحوّل قيمة إدخال إلى قيمة من النوع DateTime64.

الصيغة

toDateTime64(expr, scale[, timezone])

الوسيطات

• expr — تعبير يُرجع رقمًا أو تمثيلًا نصيًا لرقم. تعبير
• scale — مقدار النبضة (الدقة): 10^(-scale) ثانية. UInt8
• timezone — اختياري. المنطقة الزمنية لكائن DateTime64 المحدد. String

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

يُرجع تاريخًا تقويميًا ووقتًا من اليوم، بدقة أجزاء من الثانية. DateTime64

أمثلة

القيمة ضمن النطاق

SELECT toDateTime64('2025-01-01 00:00:00.000', 3) AS value, toTypeName(value);

┌───────────────────value─┬─toTypeName(value)─┐
│ 2025-01-01 00:00:00.000 │ DateTime64(3)     │
└─────────────────────────┴───────────────────┘

بصيغة Decimal بدقة

SELECT toDateTime64(1546300800.000, 3) AS value, toTypeName(value);
-- Without the decimal point the value is still treated as Unix Timestamp in seconds
SELECT toDateTime64(1546300800000, 3) AS value, toTypeName(value);

┌───────────────────value─┬─toTypeName(value)─┐
│ 2019-01-01 00:00:00.000 │ DateTime64(3)     │
└─────────────────────────┴───────────────────┘
┌───────────────────value─┬─toTypeName(value)─┐
│ 9999-12-31 23:59:59.000 │ DateTime64(3)     │
└─────────────────────────┴───────────────────┘

باستخدام المنطقة الزمنية

SELECT toDateTime64('2025-01-01 00:00:00', 3, 'Asia/Istanbul') AS value, toTypeName(value);

┌───────────────────value─┬─toTypeName(value)──────────────┐
│ 2025-01-01 00:00:00.000 │ DateTime64(3, 'Asia/Istanbul') │
└─────────────────────────┴────────────────────────────────┘

أُضيف في: v21.11.0

مثل toDateTime64، تُحوِّل هذه الدالة قيمة إدخال إلى قيمة من النوع DateTime64، لكنها تُرجع إما القيمة الافتراضية من DateTime64 أو القيمة الافتراضية المُعطاة إذا تم تمرير مُعامل غير صالح.

الصيغة

toDateTime64OrDefault(expr, scale[, timezone, default])

الوسيطات

• expr — تعبير يُرجع رقمًا أو تمثيلًا نصيًا لرقم. String أو (U)Int* أو Float*
• scale — حجم الـ tick (الدقة): ‏10^-precision ثانية. UInt8
• timezone — اختياري. المنطقة الزمنية. String
• default — اختياري. القيمة الافتراضية التي ستُعاد إذا لم تنجح عملية التحليل. DateTime64

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

قيمة من النوع DateTime64 عند النجاح، وإلا فستُعاد القيمة الافتراضية إذا تم تمريرها، أو 1970-01-01 00:00:00.000 إذا لم يتم ذلك. DateTime64

أمثلة

تحويل ناجح

SELECT toDateTime64OrDefault('1976-10-18 00:00:00.30', 3)

1976-10-18 00:00:00.300

تعذّر التحويل

SELECT toDateTime64OrDefault('1976-10-18 00:00:00 30', 3, 'UTC', toDateTime64('2001-01-01 00:00:00.00',3))

2001-01-01 00:00:00.000

استُحدثت في: v20.1.0

يحوّل قيمة إدخال إلى قيمة من النوع DateTime64، لكنه يعيد NULL إذا كانت الوسيطة غير صالحة. وهو مماثل لـ toDateTime64، لكنه يعيد NULL إذا كانت الوسيطة غير صالحة. تُفسَّر الوسيطة الصحيحة على أنها Unix timestamp بالثواني الكاملة، وتنتج NULL إذا كانت خارج نطاق النوع DateTime64.

البنية

toDateTime64OrNull(x[, precision[, timezone]])

الوسيطات

• x — تمثيل نصي لتاريخ ووقت بدقة أجزاء الثانية، أو طابع زمني Unix صحيح. String أو (U)Int8/16/32/64
• precision — اختياري. دقة أجزاء الثانية للقيمة المُعادة. UInt8
• timezone — اختياري. المنطقة الزمنية للقيمة المُعادة. String

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

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

أمثلة

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

SELECT toDateTime64OrNull('2025-12-30 13:44:17.123'), toDateTime64OrNull('invalid')

┌─toDateTime64OrNull('2025-12-30 13:44:17.123')─┬─toDateTime64OrNull('invalid')─┐
│                       2025-12-30 13:44:17.123 │                          ᴺᵁᴸᴸ │
└───────────────────────────────────────────────┴───────────────────────────────┘

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

يحوِّل قيمة الإدخال إلى قيمة من النوع DateTime64، لكنه يعيد الحد الأدنى لـ DateTime64 إذا استلم وسيطة غير صالحة. وهو مماثل لـ toDateTime64، لكنه يعيد الحد الأدنى لـ DateTime64 إذا استلم وسيطة غير صالحة.

راجع أيضًا:

• toDateTime64.
• toDateTime64OrNull.
• toDateTime64OrDefault.

البنية

toDateTime64OrZero(x)

الوسيطات

• x — تمثيل نصي لتاريخ ووقت بدقة أجزاء من الثانية. String

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

تعيد قيمة من النوع DateTime64 عند النجاح، وإلا فتعيد الحد الأدنى لـ DateTime64 (1970-01-01 00:00:00.000). DateTime64

أمثلة

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

SELECT toDateTime64OrZero('2025-12-30 13:44:17.123'), toDateTime64OrZero('invalid')

┌─toDateTime64OrZero('2025-12-30 13:44:17.123')─┬─toDateTime64OrZero('invalid')─┐
│                       2025-12-30 13:44:17.123 │       1970-01-01 00:00:00.000 │
└───────────────────────────────────────────────┴───────────────────────────────┘

تم تقديمه في: v21.11.0

مثل toDateTime، ولكن إذا تعذّر التحويل، فإنه يعيد قيمة افتراضية تكون إما الوسيطة الثالثة (إذا كانت محددة)، أو الحد الأدنى لنوع DateTime بخلاف ذلك.

البنية

toDateTimeOrDefault(expr[, timezone, default])

الوسائط

• expr — تعبير يُرجع رقمًا أو تمثيلًا نصيًا لرقم. String أو (U)Int* أو Float*
• timezone — اختياري. المنطقة الزمنية. String
• default — اختياري. القيمة الافتراضية التي تُعاد إذا تعذّر التحليل. DateTime

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

قيمة من النوع DateTime عند النجاح، وإلا فتُعاد القيمة الافتراضية إذا تم تمريرها، أو 1970-01-01 00:00:00 إذا لم يتم تمريرها. DateTime

أمثلة

تحويل ناجح

SELECT toDateTimeOrDefault('2022-12-30 13:44:17')

2022-12-30 13:44:17

فشل التحويل

SELECT toDateTimeOrDefault('', 'UTC', CAST('2023-01-01', 'DateTime(\'UTC\')'))

2023-01-01 00:00:00

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

يحوّل قيمة الإدخال إلى قيمة من النوع DateTime، لكنه يُرجع NULL إذا تلقّى وسيطًا غير صالح. وهو مماثل لـ toDateTime، لكنه يُرجع NULL إذا تلقّى وسيطًا غير صالح. ويُفسَّر الوسيط الصحيح على أنه طابع زمني Unix، ويُنتج NULL إذا كان خارج نطاق النوع DateTime.

البنية

toDateTimeOrNull(x[, timezone])

الوسيطات

• x — تمثيل نصي لتاريخ ووقت، أو طابع زمني Unix صحيح. String أو (U)Int8/16/32/64
• timezone — اختياري. المنطقة الزمنية للقيمة المُعادة. String

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

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

أمثلة

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

SELECT toDateTimeOrNull('2025-12-30 13:44:17'), toDateTimeOrNull('invalid')

┌─toDateTimeOrNull('2025-12-30 13:44:17')─┬─toDateTimeOrNull('invalid')─┐
│                     2025-12-30 13:44:17 │                        ᴺᵁᴸᴸ │
└─────────────────────────────────────────┴─────────────────────────────┘

وسيط عدد صحيح مع منطقة زمنية

SELECT toDateTimeOrNull(1583851242, 'Asia/Shanghai'), toDateTimeOrNull(4294967296)

┌─toDateTimeOrNull(1583851242, 'Asia/Shanghai')─┬─toDateTimeOrNull(4294967296)─┐
│                           2020-03-10 22:40:42 │                         ᴺᵁᴸᴸ │
└───────────────────────────────────────────────┴──────────────────────────────┘

تم تقديمه في: v1.1.0

يحوّل قيمة مُدخلة إلى قيمة من النوع DateTime، لكنه يعيد الحد الأدنى لـ DateTime إذا كانت الوسيطة غير صالحة. وهو مماثل لـ toDateTime، لكنه يعيد الحد الأدنى لـ DateTime إذا كانت الوسيطة غير صالحة.

البنية

toDateTimeOrZero(x)

الوسيطات

• x — تمثيل نصي لتاريخ ووقت. String

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

يعيد قيمة من نوع DateTime عند النجاح، وإلا فيُعيد الحد الأدنى لنوع DateTime (1970-01-01 00:00:00). DateTime

أمثلة

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

SELECT toDateTimeOrZero('2025-12-30 13:44:17'), toDateTimeOrZero('invalid')

┌─toDateTimeOrZero('2025-12-30 13:44:17')─┬─toDateTimeOrZero('invalid')─┐
│                     2025-12-30 13:44:17 │         1970-01-01 00:00:00 │
└─────────────────────────────────────────┴─────────────────────────────┘

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

تحوّل قيمة إدخال إلى قيمة من النوع Decimal(38, S) بمقياس S. يرفع استثناءً عند حدوث خطأ.

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

• القيم أو تمثيلاتها النصية من النوع (U)Int*.
• القيم أو تمثيلاتها النصية من النوع Float*.

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

• القيم أو التمثيلات النصية لقيم Float* NaN و Inf (دون حساسية لحالة الأحرف).
• التمثيلات النصية للقيم الثنائية والسداسية العشرية، مثل SELECT toDecimal128('0xc0fe', 1);.

الصياغة

toDecimal128(expr, S)

الوسيطات

• expr — تعبير يُرجع عددًا أو تمثيلًا نصيًا لعدد. Expression
• S — معامل المقياس بين 0 و38، ويُحدِّد عدد الخانات التي يمكن أن يحتوي عليها الجزء الكسري من العدد. UInt8

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

تُرجع قيمة من النوع Decimal(38, S) Decimal128(S)

أمثلة

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

SELECT
    toDecimal128(99, 1) AS a, toTypeName(a) AS type_a,
    toDecimal128(99.67, 2) AS b, toTypeName(b) AS type_b,
    toDecimal128('99.67', 3) AS c, toTypeName(c) AS type_c
FORMAT Vertical

Row 1:
──────
a:      99
type_a: Decimal(38, 1)
b:      99.67
type_b: Decimal(38, 2)
c:      99.67
type_c: Decimal(38, 3)

تم تقديمه في: v21.11.0

مثل toDecimal128، تحوّل هذه الدالة قيمة الإدخال إلى قيمة من النوع Decimal(38, S)، لكنها تُرجع القيمة الافتراضية في حال حدوث خطأ.

البنية

toDecimal128OrDefault(expr, S[, default])

الوسيطات

• expr — تمثيل نصي لرقم. String
• S — معامل المقياس بين 0 و38، ويحدد عدد الخانات التي يمكن أن يحتوي عليها الجزء الكسري من الرقم. UInt8
• default — اختياري. القيمة الافتراضية التي تُعاد إذا تعذّر التحليل إلى النوع Decimal128(S). Decimal128(S)

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

قيمة من النوع Decimal(38, S) عند النجاح، وإلا فتُعاد القيمة الافتراضية إذا تم تمريرها، أو 0 إذا لم يتم ذلك. Decimal128(S)

أمثلة

تحويل ناجح

SELECT toDecimal128OrDefault(toString(1/42), 18)

0.023809523809523808

تعذّر التحويل

SELECT toDecimal128OrDefault('Inf', 0, CAST('-1', 'Decimal128(0)'))

-1

أُضيف في: v20.1.0

يحوّل قيمة إدخال إلى قيمة من النوع Decimal(38, S)، لكنه يعيد NULL في حال حدوث خطأ. وهو يشبه toDecimal128، لكنه يعيد NULL بدلًا من رفع استثناء عند حدوث أخطاء في التحويل.

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

• القيم أو التمثيلات النصية من النوع (U)Int*.
• القيم أو التمثيلات النصية من النوع Float*.

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

• القيم أو التمثيلات النصية لقيم Float* NaN وInf (غير حساسة لحالة الأحرف).
• التمثيلات النصية للقيم الثنائية والسداسية العشرية.
• القيم التي تتجاوز حدود Decimal128:(-1*10^(38 - S), 1*10^(38 - S)).

انظر أيضًا:

• toDecimal128.
• toDecimal128OrZero.
• toDecimal128OrDefault.

البنية

toDecimal128OrNull(expr, S)

الوسيطات

• expr — تعبير يُرجع رقمًا أو تمثيلًا نصيًا لرقم. تعبير
• S — معامل المقياس بين 0 و38، ويحدّد عدد الخانات التي يمكن أن يحتوي عليها الجزء الكسري من الرقم. UInt8

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

يُرجع قيمة Decimal(38, S) عند النجاح، وإلا يُرجع NULL. Decimal128(S) أو NULL

أمثلة

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

SELECT toDecimal128OrNull('42.7', 2), toDecimal128OrNull('invalid', 2)

┌─toDecimal128OrNull('42.7', 2)─┬─toDecimal128OrNull('invalid', 2)─┐
│                          42.7 │                             ᴺᵁᴸᴸ │
└───────────────────────────────┴──────────────────────────────────┘

تم تقديمه في: v20.1.0

يحوّل قيمة الإدخال إلى قيمة من النوع Decimal(38, S)، لكنه يعيد 0 في حال حدوث خطأ. يشبه toDecimal128، لكنه يعيد 0 بدلًا من إطلاق استثناء عند حدوث أخطاء في التحويل.

الوسائط المدعومة:

• القيم أو تمثيلاتها النصية من النوع (U)Int*.
• القيم أو تمثيلاتها النصية من النوع Float*.

الوسائط غير المدعومة (تعيد 0):

• القيم أو التمثيلات النصية لقيم Float* NaN وInf (دون حساسية لحالة الأحرف).
• التمثيلات النصية للقيم الثنائية والست عشرية.

البنية

toDecimal128OrZero(expr, S)

الوسيطات

• expr — تعبير يُرجع رقمًا أو تمثيلًا نصيًا لرقم. تعبير
• S — معامل المقياس بين 0 و38، ويحدّد عدد الخانات التي يمكن أن يحتوي عليها الجزء الكسري من الرقم. UInt8

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

يُرجع قيمة Decimal(38, S) عند النجاح، وإلا 0. Decimal128(S)

أمثلة

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

SELECT toDecimal128OrZero('42.7', 2), toDecimal128OrZero('invalid', 2)

┌─toDecimal128OrZero('42.7', 2)─┬─toDecimal128OrZero('invalid', 2)─┐
│                          42.7 │                                0 │
└───────────────────────────────┴──────────────────────────────────┘

طُرِحت في: v20.8.0

يحوّل قيمة الإدخال إلى قيمة من النوع Decimal(76, S) ذات مقياس S. يطلق استثناءً عند حدوث خطأ.

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

• القيم أو تمثيلاتها النصية من النوع (U)Int*.
• القيم أو تمثيلاتها النصية من النوع Float*.

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

• القيم أو تمثيلاتها النصية لقيم Float* ‏NaN وInf (من دون حساسية لحالة الأحرف).
• التمثيلات النصية للقيم الثنائية والسداسية العشرية، مثل SELECT toDecimal256('0xc0fe', 1);.

الصياغة

toDecimal256(expr, S)

الوسيطات

• expr — تعبير يُرجِع عددًا أو تمثيلًا نصيًا لعدد. تعبير
• S — معامل المقياس بين 0 و76، ويحدّد عدد الأرقام التي يمكن أن يحتوي عليها الجزء الكسري من العدد. UInt8

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

يُرجِع قيمة من النوع Decimal(76, S). Decimal256(S)

أمثلة

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

SELECT
    toDecimal256(99, 1) AS a, toTypeName(a) AS type_a,
    toDecimal256(99.67, 2) AS b, toTypeName(b) AS type_b,
    toDecimal256('99.67', 3) AS c, toTypeName(c) AS type_c
FORMAT Vertical

Row 1:
──────
a:      99
type_a: Decimal(76, 1)
b:      99.67
type_b: Decimal(76, 2)
c:      99.67
type_c: Decimal(76, 3)

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

مثل toDecimal256، تحوّل هذه الدالة قيمة الإدخال إلى قيمة من النوع Decimal(76, S)، لكنها تُرجع القيمة الافتراضية عند حدوث خطأ.

الصيغة

toDecimal256OrDefault(expr, S[, default])

الوسيطات

• expr — تمثيل نصي لرقم. String
• S — معامل المقياس بين 0 و76، ويحدد عدد الخانات التي يمكن أن يحتوي عليها الجزء الكسري من الرقم. UInt8
• default — اختياري. القيمة الافتراضية التي تُعاد إذا تعذّر التحليل إلى النوع Decimal256(S). Decimal256(S)

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

قيمة من النوع Decimal(76, S) عند النجاح، وإلا فتُعاد القيمة الافتراضية إذا تم تمريرها، أو 0 إذا لم يتم ذلك. Decimal256(S)

أمثلة

تحويل ناجح

SELECT toDecimal256OrDefault(toString(1/42), 76)

0.023809523809523808

فشل التحويل

SELECT toDecimal256OrDefault('Inf', 0, CAST('-1', 'Decimal256(0)'))

-1

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

تحوِّل قيمة الإدخال إلى قيمة من النوع Decimal(76, S)، لكنها تُرجع NULL في حال حدوث خطأ. تشبه toDecimal256، لكنها تُرجع NULL بدلًا من إطلاق استثناء عند حدوث أخطاء في التحويل.

الوسائط المدعومة:

• القيم أو التمثيلات النصية من النوع (U)Int*.
• القيم أو التمثيلات النصية من النوع Float*.

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

• القيم أو التمثيلات النصية لقيم Float* NaN وInf (بدون حساسية لحالة الأحرف).
• التمثيلات النصية للقيم الثنائية والسداسية العشرية.
• القيم التي تتجاوز حدود Decimal256: (-1 * 10^(76 - S), 1 * 10^(76 - S)).

انظر أيضًا:

• toDecimal256.
• toDecimal256OrZero.
• toDecimal256OrDefault.

البنية

toDecimal256OrNull(expr, S)

الوسيطات

• expr — تعبير يُرجع رقمًا أو تمثيلًا نصيًا لرقم. تعبير
• S — معلمة المقياس بين 0 و76، وتحدد عدد الخانات التي يمكن أن يتضمنها الجزء الكسري من الرقم. UInt8

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

يُرجع قيمة من النوع Decimal(76, S) عند النجاح، وإلا NULL. Decimal256(S) أو NULL

أمثلة

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

SELECT toDecimal256OrNull('42.7', 2), toDecimal256OrNull('invalid', 2)

┌─toDecimal256OrNull('42.7', 2)─┬─toDecimal256OrNull('invalid', 2)─┐
│                          42.7 │                             ᴺᵁᴸᴸ │
└───────────────────────────────┴──────────────────────────────────┘

أُضيف في: v20.8.0

يحوّل قيمة الإدخال إلى قيمة من النوع Decimal(76, S)، لكنه يعيد 0 في حال حدوث خطأ. يشبه toDecimal256، لكنه يعيد 0 بدلًا من رفع استثناء عند حدوث أخطاء في التحويل.

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

• القيم أو التمثيلات النصية من النوع (U)Int*.
• القيم أو التمثيلات النصية من النوع Float*.

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

• القيم أو التمثيلات النصية لقيم Float* NaN وInf (غير حساسة لحالة الأحرف).
• التمثيلات النصية للقيم الثنائية والسداسية عشرية.

انظر أيضًا:

• toDecimal256.
• toDecimal256OrNull.
• toDecimal256OrDefault.

البنية

toDecimal256OrZero(expr, S)

الوسيطات

• expr — تعبير يُرجع رقمًا أو تمثيلًا نصيًا لرقم. Expression
• S — معامل المقياس بين 0 و76، ويحدّد عدد الخانات التي يمكن أن يتكوّن منها الجزء الكسري من الرقم. UInt8

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

يُرجع قيمة Decimal(76, S) عند النجاح، وإلا يُرجع 0. Decimal256(S)

أمثلة

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

SELECT toDecimal256OrZero('42.7', 2), toDecimal256OrZero('invalid', 2)

┌─toDecimal256OrZero('42.7', 2)─┬─toDecimal256OrZero('invalid', 2)─┐
│                          42.7 │                                0 │
└───────────────────────────────┴──────────────────────────────────┘

أُضيف في: v18.12.0

يحوّل قيمة إدخال إلى قيمة من النوع Decimal(9, S) ذات مقياس S. ويطلق استثناءً عند حدوث خطأ.

الوسائط المدعومة:

• قيم أو تمثيلات نصية من النوع (U)Int*.
• قيم أو تمثيلات نصية من النوع Float*.

الوسائط غير المدعومة:

• قيم أو تمثيلات نصية لقيم Float* NaN وInf (من دون حساسية لحالة الأحرف).
• تمثيلات نصية للقيم الثنائية والسداسية العشرية، مثل SELECT toDecimal32('0xc0fe', 1);.

الصيغة

toDecimal32(expr, S)

الوسيطات

• expr — تعبير يُرجع رقمًا أو سلسلة نصية تمثل رقمًا. تعبير
• S — معامل المقياس بين 0 و9، ويحدّد عدد الخانات التي يمكن أن يتكوّن منها الجزء الكسري من الرقم. UInt8

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

يُرجع قيمة من النوع Decimal(9, S) Decimal32(S)

أمثلة

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

SELECT
    toDecimal32(2, 1) AS a, toTypeName(a) AS type_a,
    toDecimal32(4.2, 2) AS b, toTypeName(b) AS type_b,
    toDecimal32('4.2', 3) AS c, toTypeName(c) AS type_c
FORMAT Vertical

Row 1:
──────
a:      2
type_a: Decimal(9, 1)
b:      4.2
type_b: Decimal(9, 2)
c:      4.2
type_c: Decimal(9, 3)

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

مثل toDecimal32، تُحوِّل هذه الدالة قيمة الإدخال إلى قيمة من النوع Decimal(9, S)، لكنها تُرجِع القيمة الافتراضية في حال حدوث خطأ.

البنية

toDecimal32OrDefault(expr, S[, default])

الوسائط

• expr — تمثيل نصي لرقم. String
• S — معامل المقياس بين 0 و9، ويحدّد عدد الخانات التي يمكن أن يحتوي عليها الجزء الكسري من الرقم. UInt8
• default — اختياري. القيمة الافتراضية التي ستُعاد إذا تعذّر التحليل إلى النوع Decimal32(S). Decimal32(S)

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

قيمة من النوع Decimal(9, S) عند نجاح العملية، وإلا فتُعاد القيمة الافتراضية إذا تم تمريرها، أو 0 إذا لم يتم ذلك. Decimal32(S)

أمثلة

تحويل ناجح

SELECT toDecimal32OrDefault(toString(0.0001), 5)

0.0001

تعذّر التحويل

SELECT toDecimal32OrDefault('Inf', 0, CAST('-1', 'Decimal32(0)'))

-1

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

تحوِّل قيمة مُدخلة إلى قيمة من النوع Decimal(9, S)، لكنها تُرجع NULL في حال حدوث خطأ. تشبه toDecimal32، لكنها تُرجع NULL بدلًا من إطلاق استثناء عند حدوث أخطاء في التحويل.

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

• القيم أو تمثيلاتها النصية من النوع (U)Int*.
• القيم أو تمثيلاتها النصية من النوع Float*.

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

• القيم أو تمثيلاتها النصية من قيم Float* وهي NaN وInf (غير حساسة لحالة الأحرف).
• التمثيلات النصية للقيم الثنائية والسداسية العشرية.
• القيم التي تتجاوز حدود Decimal32:(-1*10^(9 - S), 1*10^(9 - S)).

انظر أيضًا:

• toDecimal32.
• toDecimal32OrZero.
• toDecimal32OrDefault.

البنية

toDecimal32OrNull(expr, S)

الوسائط

• expr — تعبير يُرجع رقمًا أو تمثيلًا نصيًا لرقم. تعبير
• S — معامل المقياس بين 0 و9، ويحدّد عدد الأرقام التي يمكن أن يحتويها الجزء الكسري من الرقم. UInt8

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

يُرجع قيمة من النوع Decimal(9, S) عند النجاح، وإلا فيُرجع NULL. Decimal32(S) أو NULL

أمثلة

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

SELECT toDecimal32OrNull('42.7', 2), toDecimal32OrNull('invalid', 2)

┌─toDecimal32OrNull('42.7', 2)─┬─toDecimal32OrNull('invalid', 2)─┐
│                         42.7 │                            ᴺᵁᴸᴸ │
└──────────────────────────────┴─────────────────────────────────┘

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

تحوّل قيمة الإدخال إلى قيمة من النوع Decimal(9, S)، لكنها تُرجِع 0 في حال حدوث خطأ. تشبه toDecimal32، لكنها تُرجِع 0 بدلًا من إطلاق استثناء عند حدوث أخطاء في التحويل.

الوسائط المدعومة:

• القيم أو تمثيلاتها النصية من النوع (U)Int*.
• القيم أو تمثيلاتها النصية من النوع Float*.

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

• القيم أو التمثيلات النصية لقيم Float* NaN وInf (دون مراعاة حالة الأحرف).
• التمثيلات النصية للقيم الثنائية والسداسية عشرية.

البنية

toDecimal32OrZero(expr, S)

المعاملات

• expr — تعبير يُرجع رقمًا أو تمثيلًا نصيًا لرقم. Expression
• S — معامل المقياس بين 0 و9، ويحدّد عدد الخانات التي يمكن أن يحتويها الجزء الكسري من الرقم. UInt8

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

تُرجع قيمة Decimal(9, S) عند النجاح، وإلا تُرجع 0. Decimal32(S)

أمثلة

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

SELECT toDecimal32OrZero('42.7', 2), toDecimal32OrZero('invalid', 2)

┌─toDecimal32OrZero('42.7', 2)─┬─toDecimal32OrZero('invalid', 2)─┐
│                         42.7 │                               0 │
└──────────────────────────────┴─────────────────────────────────┘

أُضيف في: v18.12.0

يحوّل قيمة الإدخال إلى قيمة من النوع Decimal(18, S) وبمقياس S. يرفع استثناءً في حال حدوث خطأ.

الوسائط المدعومة:

• القيم أو التمثيلات النصية من النوع (U)Int*.
• القيم أو التمثيلات النصية من النوع Float*.

الوسائط غير المدعومة:

• القيم أو التمثيلات النصية لقيم Float* ‏NaN و Inf (غير حساسة لحالة الأحرف).
• التمثيلات النصية للقيم الثنائية والست عشرية، مثل SELECT toDecimal64('0xc0fe', 1);.

البنية

toDecimal64(expr, S)

الوسائط

• expr — تعبير يُرجِع رقمًا أو تمثيلًا نصيًا لرقم. Expression
• S — معامل المقياس بين 0 و18، ويحدّد عدد الخانات التي يمكن أن يحتوي عليها الجزء الكسري من الرقم. UInt8

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

يُرجِع قيمة عشرية. Decimal(18, S)

أمثلة

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

SELECT
    toDecimal64(2, 1) AS a, toTypeName(a) AS type_a,
    toDecimal64(4.2, 2) AS b, toTypeName(b) AS type_b,
    toDecimal64('4.2', 3) AS c, toTypeName(c) AS type_c
FORMAT Vertical

Row 1:
──────
a:      2
type_a: Decimal(18, 1)
b:      4.2
type_b: Decimal(18, 2)
c:      4.2
type_c: Decimal(18, 3)

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

مثل toDecimal64، تحوّل هذه الدالة قيمة الإدخال إلى قيمة من النوع Decimal(18, S)، لكنها تُرجع القيمة الافتراضية عند حدوث خطأ.

الصيغة

toDecimal64OrDefault(expr, S[, default])

المعاملات

• expr — تمثيل نصي لرقم. String
• S — معامل المقياس بين 0 و18، ويحدد عدد الخانات التي يمكن أن يحتوي عليها الجزء الكسري من الرقم. UInt8
• default — اختياري. القيمة الافتراضية التي تُعاد إذا تعذّر التحويل إلى النوع Decimal64(S). Decimal64(S)

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

قيمة من النوع Decimal(18, S) عند نجاح العملية، وإلا فتُعاد القيمة الافتراضية إذا تم تمريرها، أو 0 إذا لم يتم ذلك. Decimal64(S)

أمثلة

تحويل ناجح

SELECT toDecimal64OrDefault(toString(0.0001), 18)

0.0001

تعذّر التحويل

SELECT toDecimal64OrDefault('Inf', 0, CAST('-1', 'Decimal64(0)'))

-1

أُضيف في: v20.1.0

يحوّل قيمة الإدخال إلى قيمة من النوع Decimal(18, S)، لكنه يُرجع NULL عند حدوث خطأ. وهو يشبه toDecimal64، لكنه يُرجع NULL بدلًا من إطلاق استثناء عند حدوث أخطاء في التحويل.

الوسائط المدعومة:

• القيم أو التمثيلات النصية من النوع (U)Int*.
• القيم أو التمثيلات النصية من النوع Float*.

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

• القيم NaN وInf من النوع Float*، أو تمثيلاتها النصية (دون تمييز بين الأحرف الكبيرة والصغيرة).
• التمثيلات النصية للقيم الثنائية والست عشرية.
• القيم التي تتجاوز حدود Decimal64:(-1*10^(18 - S), 1*10^(18 - S)).

انظر أيضًا:

• toDecimal64.
• toDecimal64OrZero.
• toDecimal64OrDefault.

الصيغة

toDecimal64OrNull(expr, S)

الوسيطات

• expr — تعبير يُرجع رقمًا أو تمثيلًا نصيًا لرقم. تعبير
• S — معامل المقياس بين 0 و18، ويحدّد عدد الخانات التي يمكن أن يحتوي عليها الجزء الكسري من الرقم. UInt8

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

تُرجع قيمة Decimal(18, S) عند النجاح، وإلا NULL. Decimal64(S) أو NULL

أمثلة

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

SELECT toDecimal64OrNull('42.7', 2), toDecimal64OrNull('invalid', 2)

┌─toDecimal64OrNull('42.7', 2)─┬─toDecimal64OrNull('invalid', 2)─┐
│                         42.7 │                            ᴺᵁᴸᴸ │
└──────────────────────────────┴─────────────────────────────────┘

أُضيف في: v20.1.0

يحوّل قيمة الإدخال إلى قيمة من النوع Decimal(18, S)، لكنه يعيد 0 عند حدوث خطأ. وهو يشبه toDecimal64، لكنه يعيد 0 بدلًا من إطلاق استثناء عند حدوث أخطاء في التحويل.

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

• القيم أو التمثيلات النصية من النوع (U)Int*.
• القيم أو التمثيلات النصية من النوع Float*.

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

• القيم أو التمثيلات النصية لقيم Float* NaN وInf (دون تمييز بين الأحرف الكبيرة والصغيرة).
• التمثيلات النصية للقيم الثنائية والسداسية العشرية.

انظر أيضًا:

• toDecimal64.
• toDecimal64OrNull.
• toDecimal64OrDefault.

البنية

toDecimal64OrZero(expr, S)

الوسائط

• expr — تعبير يُرجع رقمًا أو تمثيلًا نصيًا لرقم. تعبير
• S — معامل المقياس بين 0 و18، ويحدّد عدد الأرقام التي يمكن أن يحتوي عليها الجزء الكسري من الرقم. UInt8

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

يُرجع قيمة من النوع Decimal(18, S) عند النجاح، وإلا 0. Decimal64(S)

أمثلة

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

SELECT toDecimal64OrZero('42.7', 2), toDecimal64OrZero('invalid', 2)

┌─toDecimal64OrZero('42.7', 2)─┬─toDecimal64OrZero('invalid', 2)─┐
│                         42.7 │                               0 │
└──────────────────────────────┴─────────────────────────────────┘

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

تحوّل قيمة رقمية إلى String بعدد محدد من الخانات الكسرية.

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

الصياغة

toDecimalString(number, scale)

الوسيطات

• number — القيمة العددية المراد تحويلها إلى سلسلة نصية. يمكن أن تكون من أي نوع عددي (Int أو UInt أو Float أو Decimal). Int8 أو Int16 أو Int32 أو Int64 أو UInt8 أو UInt16 أو UInt32 أو UInt64 أو Float32 أو Float64 أو Decimal
• scale — عدد الخانات التي ستُعرض في الجزء الكسري. ستُقرَّب النتيجة عند الحاجة. UInt8

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

تعرض تمثيلًا نصيًا للعدد بعدد الخانات الكسرية المحدد تمامًا. String

أمثلة

تقريب عدد وتنسيقه

SELECT toDecimalString(2.1456, 2)

┌─toDecimalString(2.1456, 2)─┐
│ 2.15                       │
└────────────────────────────┘

الحشو بالأصفار

SELECT toDecimalString(5, 3)

┌─toDecimalString(5, 3)─┐
│ 5.000                 │
└───────────────────────┘

أنواع عددية مختلفة

SELECT toDecimalString(CAST(123.456 AS Decimal(10,3)), 2) AS decimal_val,
       toDecimalString(CAST(42.7 AS Float32), 4) AS float_val

┌─decimal_val─┬─float_val─┐
│ 123.46      │ 42.7000   │
└─────────────┴───────────┘

قُدِّم في: v1.1.0

يحوّل وسيطًا من النوع String إلى النوع FixedString(N) (سلسلة نصية ذات طول ثابت مقداره N).

إذا كانت السلسلة النصية تحتوي على عدد بايتات أقل من N، فتُستكمل من اليمين ببايتات null. إذا كانت السلسلة النصية تحتوي على عدد بايتات أكبر من N، يُطرح استثناء.

البنية

toFixedString(s, N)

المعاملات

• s — السلسلة المطلوب تحويلها. String
• N — طول قيمة FixedString الناتجة. const UInt*

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

تُرجع قيمة FixedString بطول N. FixedString(N)

أمثلة

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

-- The padding is made of null bytes, so the result is shown with `hex`.
SELECT hex(toFixedString('foo', 8)) AS s;

┌─s────────────────┐
│ 666F6F0000000000 │
└──────────────────┘

أُضيف في: v1.1.0

يحوّل قيمة الإدخال إلى قيمة من النوع Float32. يطرح استثناءً في حال حدوث خطأ.

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

• قيم من النوع (U)Int*.
• التمثيلات النصية لـ (U)Int8/16/32/128/256.
• قيم من النوع Float*، بما في ذلك NaN وInf.
• التمثيلات النصية لـ Float*، بما في ذلك NaN وInf (غير حسّاسة لحالة الأحرف).

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

• التمثيلات النصية للقيم الثنائية والستّ عشرية، على سبيل المثال SELECT toFloat32('0xc0fe');.

انظر أيضًا:

• toFloat32OrZero.
• toFloat32OrNull.
• toFloat32OrDefault.

البنية

toFloat32(expr)

المعاملات

• expr — تعبير يُرجع رقمًا أو تمثيلًا نصيًا لرقم. تعبير

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

يُرجع قيمة عددية بفاصلة عائمة 32-بت. Float32

أمثلة

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

SELECT
    toFloat32(42.7),
    toFloat32('42.7'),
    toFloat32('NaN')
FORMAT Vertical

Row 1:
──────
toFloat32(42.7):   42.7
toFloat32('42.7'): 42.7
toFloat32('NaN'):  nan

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

على غرار toFloat32، تحوّل هذه الدالة قيمة الإدخال إلى قيمة من النوع Float32، لكنها تُرجع القيمة الافتراضية عند حدوث خطأ. إذا لم يتم تمرير قيمة default، فسيُرجع 0 عند حدوث خطأ.

الصيغة

toFloat32OrDefault(expr[, default])

المعاملات

• expr — تعبير يُرجع عددًا أو تمثيلًا نصيًا لعدد. String أو (U)Int* أو Float*
• default — اختياري. القيمة الافتراضية التي ستُعاد إذا لم ينجح التحليل. Float32

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

تُرجع قيمة من النوع Float32 عند النجاح، وإلا فتُرجع القيمة الافتراضية إذا تم تمريرها، أو 0 إذا لم يتم ذلك. Float32

أمثلة

تحويل ناجح

SELECT toFloat32OrDefault('8', CAST('0', 'Float32'))

8

فشل التحويل

SELECT toFloat32OrDefault('abc', CAST('0', 'Float32'))

0

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

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

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

• قيم من النوع (U)Int*.
• تمثيلات نصية لـ (U)Int8/16/32/128/256.
• قيم من النوع Float*، بما في ذلك NaN وInf.
• تمثيلات نصية لـ Float*، بما في ذلك NaN وInf (غير حساسة لحالة الأحرف).

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

• تمثيلات نصية للقيم الثنائية والسداسية العشرية، مثل SELECT toFloat32OrNull('0xc0fe');.
• تنسيقات سلاسل نصية غير صالحة.

انظر أيضًا:

• toFloat32.
• toFloat32OrZero.
• toFloat32OrDefault.

البنية

toFloat32OrNull(x)

الوسيطات

• x — تمثيل نصي لعدد. String

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

يعيد قيمة Float32 عند النجاح، وإلا NULL. Float32 أو NULL

أمثلة

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

SELECT
    toFloat32OrNull('42.7'),
    toFloat32OrNull('NaN'),
    toFloat32OrNull('abc')
FORMAT Vertical

Row 1:
──────
toFloat32OrNull('42.7'): 42.7
toFloat32OrNull('NaN'):  nan
toFloat32OrNull('abc'):  ᴺᵁᴸᴸ

أُضيف في: v1.1.0

يحوّل قيمة الإدخال إلى قيمة من النوع Float32، ويُرجع 0 في حال حدوث خطأ. يشبه toFloat32، لكنه يُرجع 0 بدلًا من إطلاق استثناء عند حدوث أخطاء في التحويل.

انظر أيضًا:

• toFloat32.
• toFloat32OrNull.
• toFloat32OrDefault.

الصيغة

toFloat32OrZero(x)

الوسيطات

• x — تمثيل نصي لعدد. String

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

يُرجع قيمة عائمة 32-بت عند النجاح، وإلا 0. Float32

أمثلة

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

SELECT
    toFloat32OrZero('42.7'),
    toFloat32OrZero('abc')
FORMAT Vertical

Row 1:
──────
toFloat32OrZero('42.7'): 42.7
toFloat32OrZero('abc'):  0

أُضيف في: v1.1.0

يحوِّل قيمة إدخال إلى قيمة من النوع Float64. يُطلق استثناءً في حال حدوث خطأ.

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

• قيم من النوع (U)Int*.
• التمثيلات النصية للقيم من النوع (U)Int8/16/32/128/256.
• قيم من النوع Float*، بما في ذلك NaN وInf.
• التمثيلات النصية للقيم من النوع Float*، بما في ذلك NaN وInf (من دون حساسية لحالة الأحرف).

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

• التمثيلات النصية للقيم الثنائية والسداسية العشرية، على سبيل المثال SELECT toFloat64('0xc0fe');.

انظر أيضًا:

• toFloat64OrZero.
• toFloat64OrNull.
• toFloat64OrDefault.

البنية

toFloat64(expr)

الوسيطات

• expr — تعبير يُرجع عددًا أو تمثيلًا نصيًا لعدد. تعبير

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

تُرجع قيمة عددية بفاصلة عائمة بدقة 64 بت. Float64

أمثلة

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

SELECT
    toFloat64(42.7),
    toFloat64('42.7'),
    toFloat64('NaN')
FORMAT Vertical

Row 1:
──────
toFloat64(42.7):   42.7
toFloat64('42.7'): 42.7
toFloat64('NaN'):  nan

أُضيف في: v21.11.0

مثل toFloat64، تحوّل هذه الدالة قيمة الإدخال إلى قيمة من النوع Float64، لكنها تُرجع القيمة الافتراضية في حال حدوث خطأ. إذا لم يتم تمرير قيمة default، فسيتم إرجاع 0 عند حدوث خطأ.

الصياغة

toFloat64OrDefault(expr[, default])

الوسيطات

• expr — تعبير يُرجع رقمًا أو تمثيلًا نصيًا لرقم. String أو (U)Int* أو Float*
• default — اختياري. القيمة الافتراضية التي تُعاد إذا لم تنجح عملية التحليل. Float64

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

يُرجع قيمة من النوع Float64 عند النجاح، وإلا فيُرجع القيمة الافتراضية إذا تم تمريرها، أو 0 إذا لم يتم تمريرها. Float64

أمثلة

تحويل ناجح

SELECT toFloat64OrDefault('8', CAST('0', 'Float64'))

8

تعذّر التحويل