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

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

​

المشكلات الشائعة في تحويل البيانات

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

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

انتبه إلى احتمال فقدان البيانات إذا جرى تحويل قيم من نوع بيانات إلى نوع أصغر (على سبيل المثال من Int64 إلى Int32) أو بين أنواع بيانات غير متوافقة (على سبيل المثال من String إلى Int). تأكد بعناية من أن النتيجة مطابقة لما هو متوقع.

مثال:

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

┌─source_type────────────┬─to_type_result_type────┬─cast_result_type─┐
│ LowCardinality(String) │ LowCardinality(String) │ String           │
└────────────────────────┴────────────────────────┴──────────────────┘

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

┌─source_type──────┬─to_type_result_type─┬─cast_result_type─┐
│ Nullable(String) │ Nullable(String)    │ String           │
└──────────────────┴─────────────────────┴──────────────────┘

SELECT
    toTypeName(toNullable('') AS val) AS source_type,
    toTypeName(toString(val)) AS to_type_result_type,
    toTypeName(CAST(val, 'String')) AS cast_result_type
SETTINGS cast_keep_nullable = 1

┌─source_type──────┬─to_type_result_type─┬─cast_result_type─┐
│ Nullable(String) │ Nullable(String)    │ Nullable(String) │
└──────────────────┴─────────────────────┴──────────────────┘

​

ملاحظات حول دوال toString

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

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

​

ملاحظات حول الدالتين toDate/toDateTime

تُعرَّف تنسيقات التاريخ والتاريخ المقترن بالوقت للدالتين 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++.

مثال

Query

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

Response

┌──────────────────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.

​

CAST

أُضيف في: v1.1.0

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

البنية

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

الوسائط

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

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

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

أمثلة

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

Query

SELECT CAST(42, 'String')

Response

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

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

Query

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

Response

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

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

Query

SELECT '123'::UInt32

Response

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

​

DATE

أُضيف في: v21.2.0

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

الصيغة

DATE(expr)

الوسيطات

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

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

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

أمثلة

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

Query

SELECT DATE('2023-01-01')

Response

2023-01-01

​

accurateCast

أُضيف في: v1.1.0

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

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

البنية

accurateCast(x, T)

الوسيطات

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

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

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

أمثلة

تحويل ناجح

Query

SELECT accurateCast(42, 'UInt16')

Response

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

من نص إلى رقم

Query

SELECT accurateCast('123.45', 'Float64')

Response

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

​

accurateCastOrDefault

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

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

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

الصياغة

accurateCastOrDefault(x, T[, default_value])

المعاملات

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

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

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

أمثلة

تحويل ناجح

Query

SELECT accurateCastOrDefault(42, 'String')

Response

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

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

Query

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

Response

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

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

Query

SELECT accurateCastOrDefault('abc', 'UInt32')

Response

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

​

accurateCastOrNull

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

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

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

الصياغة

accurateCastOrNull(x, T)

المعاملات

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

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

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

أمثلة

تحويل ناجح

Query

SELECT accurateCastOrNull(42, 'String')

Response

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

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

Query

SELECT accurateCastOrNull('abc', 'UInt32')

Response

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

​

formatRow

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

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

إذا كان التنسيق يحتوي على لاحقة/بادئة، فستُكتب في كل صف. لا تدعم هذه الدالة إلا التنسيقات المعتمدة على الصفوف.

الصيغة

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

الوسائط

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

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

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

أمثلة

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

Query

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

Response

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

بتنسيق مخصص

Query

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

Response

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

​

formatRowNoNewline

أُضيف في: v20.7.0

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

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

الصيغة

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

الوسائط

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

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

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

أمثلة

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

Query

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

Response

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

​

fromUnixTimestamp64Micro

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

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

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

الصياغة

fromUnixTimestamp64Micro(value[, timezone])

الوسائط

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

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

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

أمثلة

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

Query

SELECT fromUnixTimestamp64Micro(1640995200123456)

Response

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

​

fromUnixTimestamp64Milli

أُضيف في: v20.5.0

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

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

الصياغة

fromUnixTimestamp64Milli(value[, timezone])

الوسيطات

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

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

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

أمثلة

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

Query

SELECT fromUnixTimestamp64Milli(1640995200123)

Response

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

​

fromUnixTimestamp64Nano

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

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

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

يُرجى ملاحظة أن قيمة الإدخال تُعامَل على أنها طابع زمني بتوقيت UTC، وليس وفق المنطقة الزمنية لقيمة الإدخال.

البنية

fromUnixTimestamp64Nano(value[, timezone])

المعاملات

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

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

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

أمثلة

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

Query

SELECT fromUnixTimestamp64Nano(1640995200123456789)

Response

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

​

fromUnixTimestamp64Second

أُضيف في: v24.12.0

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

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

الصيغة

fromUnixTimestamp64Second(value[, timezone])

الوسيطات

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

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

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

أمثلة

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

Query

SELECT fromUnixTimestamp64Second(1640995200)

Response

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

​

kqlParameterCast

أُضيف في: v26.9.0

يتحقق من قيمة ما مقابل نوع Kusto Query Language مُصرَّح به ويحوّلها إلى الحامل المقابل لذلك النوع في ClickHouse: فأي argument لا ينتمي نوعه إلى نوع KQL المُصرَّح به يُرفض أثناء التحليل، أما القيمة التي لا تتسع (overflow في int مثلاً) فتُعدّ error على مستوى كل row. الوسيط الثاني هو اسم نوع KQL المُصرَّح به، والثالث يصف الـ parameter في رسالة الخطأ؛ ويجب أن يكون كلاهما سلاسل نصية ثابتة.

تدعم هذه الدالة معاملات الدوال ذات الأنواع المحددة عندما يكون dialect = 'kusto'، وهي ليست مخصصة للاستدعاء المباشر من SQL.

الصيغة

kqlParameterCast(value, type, parameter)

الوسيطات

• value — الوسيط الذي يمرره استدعاء دالة KQL. - type — اسم نوع KQL المُعلَن، وهو constant string. - parameter — وصف الـ parameter، وهو constant string يُستخدم في رسالة الـ error.

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

value على هيئة carrier الخاص بـ ClickHouse للنوع المُعلَن.

Examples

long

Query

SELECT kqlParameterCast(5, 'long', 'the parameter') AS x, toTypeName(x)

Response

5	Int64

real

Query

SELECT kqlParameterCast(5, 'real', 'the parameter') AS x, toTypeName(x)

Response

5	Float64

​

kqlToTimespan

أُضيف في: v26.8.0

يحوّل قيمةً إلى timespan (أي Interval بالنانو ثانية) تمامًا كما تفعل الدالة totimespan() في Kusto Query Language: فقيمة الـ timespan تمرّ كما هي، والرقم يُحتسب أيامًا، والسلسلة النصية تُقرأ بالصيغة [-][d.]hh:mm:ss[.fffffff] — وتُعاد NULL عند تعذّر تحليلها.

تستند totimespan() إلى هذه الدالة عندما يكون dialect = 'kusto'، وهي غير مخصّصة للاستدعاء مباشرةً من SQL.

الصيغة

kqlToTimespan(x)

الوسيطات

• x — قيمة timespan، أو عدد من الأيام، أو سلسلة نصية تمثّل قيمة timespan.

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

القيمة على هيئة interval بالنانوثانية؛ أو NULL إذا كانت السلسلة النصية لا تمثّل قيمة timespan.

Examples

string

Query

SELECT kqlToTimespan('0.00:01:00')

Response

60000000000

أيام

Query

SELECT kqlToTimespan(2)

Response

172800000000000

​

parseDateTime

تم تقديمه في: 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

أمثلة

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

Query

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

Response

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

​

parseDateTime32BestEffort

أُضيف في: 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

أمثلة

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

Query

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

Response

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

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

Query

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

Response

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

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

Query

SELECT parseDateTime32BestEffort('1284101485')
AS parseDateTime32BestEffort

Response

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

​

parseDateTime32BestEffortOrNull

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

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

الصياغة

parseDateTime32BestEffortOrNull(time_string[, time_zone])

الوسائط

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

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

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

أمثلة

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

Query

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

Response

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

​

parseDateTime32BestEffortOrZero

أُضيفت في: 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

أمثلة

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

Query

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

Response

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

​

parseDateTime64

أُضيف في: 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

أمثلة

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

Query

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

Response

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

​

parseDateTime64BestEffort

أُضيف في: 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

أمثلة

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

Query

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

Response

┌──────────────────────────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') │
└────────────────────────────┴────────────────────────────────┘

​

parseDateTime64BestEffortOrNull

مُتاحة منذ: 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

أمثلة

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

Query

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

Response

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

​

parseDateTime64BestEffortOrZero

قُدِّم في: 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

أمثلة

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

Query

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

Response

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

​

parseDateTime64BestEffortUS

تم تقديمها في: 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

أمثلة

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

Query

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

Response

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

​

parseDateTime64BestEffortUSOrNull

أُضيفت في: 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

أمثلة

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

Query

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

Response

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

​

parseDateTime64BestEffortUSOrZero

أُضيف في: 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

أمثلة

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

Query

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

Response

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

​

parseDateTime64InJodaSyntax

أُضيف في: 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

أمثلة

مثال استخدام

Query

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

Response

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

​

parseDateTime64InJodaSyntaxOrNull

أُضيف في: 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)

أمثلة

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

Query

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

Response

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

​

parseDateTime64InJodaSyntaxOrZero

أُضيف في: v24.10.0

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

البنية

parseDateTime64InJodaSyntaxOrZero(time_string, format[, timezone])

الوسيطات

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

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

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

أمثلة

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

Query

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

Response

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

​

parseDateTime64OrNull

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

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

البنية

parseDateTime64OrNull(time_string, format[, timezone])

الوسيطات

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

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

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

أمثلة

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

Query

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

Response

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

​

parseDateTime64OrZero

أُضيف في: v24.11.0

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

البنية

parseDateTime64OrZero(time_string, format[, timezone])

الوسيطات

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

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

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

أمثلة

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

Query

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

Response

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

​

parseDateTimeBestEffort

أُضيف في: 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

أمثلة

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

Query

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

Response

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

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

Query

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

Response

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

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

Query

SELECT parseDateTimeBestEffort('1735689600') AS parseDateTimeBestEffort

Response

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

​

parseDateTimeBestEffortOrNull

أُضيفت في: 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

أمثلة

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

Query

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

Response

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

​

parseDateTimeBestEffortOrZero

قُدِّمت في: 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

أمثلة

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

Query

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

Response

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

​

parseDateTimeBestEffortUS

تم تقديمه في: 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

أمثلة

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

Query

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

Response

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

​

parseDateTimeBestEffortUSOrNull

تم تقديمها في: 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

أمثلة

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

Query

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

Response

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

​

parseDateTimeBestEffortUSOrZero

أُضيفت في: 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

أمثلة

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

Query

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

Response

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

​

parseDateTimeInJodaSyntax

قُدِّمت في: 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

أمثلة

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

Query

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

Response

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

​

parseDateTimeInJodaSyntaxOrNull

أُضيفت في: 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)

أمثلة

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

Query

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

Response

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

​

parseDateTimeInJodaSyntaxOrZero

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

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

الصياغة

parseDateTimeInJodaSyntaxOrZero(time_string, format[, timezone])

الوسيطات

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

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

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

أمثلة

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

Query

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

Response

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

​

parseDateTimeOrNull

أُضيفت في: 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)

أمثلة

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

Query

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

Response

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

​

parseDateTimeOrZero

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

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

الصياغة

parseDateTimeOrZero(time_string, format[, timezone])

الوسيطات

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

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

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

أمثلة

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

Query

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

Response

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

​

reinterpret

قُدِّمت في: 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

أمثلة

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

Query

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

Response

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

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

Query

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

Response

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

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

Query

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

Response

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

​

reinterpretAsDate

قُدِّم في: 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

أمثلة

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

Query

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

Response

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

​

reinterpretAsDateTime

أُضيف في: v1.1.0

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

الصياغة

reinterpretAsDateTime(x)

الوسائط

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

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

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

أمثلة

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

Query

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

Response

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

​

reinterpretAsFixedString

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

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

البنية

reinterpretAsFixedString(x)

الوسائط

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

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

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

أمثلة

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

Query

-- 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')))

Response

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

​

reinterpretAsFloat32

أُضيف في: v1.1.0

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

البنية

reinterpretAsFloat32(x)

الوسائط

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

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

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

أمثلة

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

Query

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

Response

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

​

reinterpretAsFloat64

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

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

البنية

reinterpretAsFloat64(x)

الوسيطات

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

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

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

أمثلة

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

Query

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

Response

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

​

reinterpretAsInt128

أُضيف في: v1.1.0

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

البنية

reinterpretAsInt128(x)

المعاملات

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

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

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

أمثلة

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

Query

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

Response

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

​

reinterpretAsInt16

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

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

الصياغة

reinterpretAsInt16(x)

المعاملات

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

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

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

أمثلة

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

Query

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

Response

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

​

reinterpretAsInt256

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

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

البنية

reinterpretAsInt256(x)

الوسيطات

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

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

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

أمثلة

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

Query

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

Response

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

​

reinterpretAsInt32

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

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

البنية

reinterpretAsInt32(x)

الوسيطات

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

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

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

أمثلة

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

Query

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

Response

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

​

reinterpretAsInt64

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

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

البنية

reinterpretAsInt64(x)

المعاملات

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

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

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

أمثلة

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

Query

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

Response

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

​

reinterpretAsInt8

أُضيف في: v1.1.0

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

البنية

reinterpretAsInt8(x)

الوسائط

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

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

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

أمثلة

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

Query

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

Response

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

​

reinterpretAsString

ظهر في: 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

أمثلة

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

Query

-- 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')))

Response

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

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

Query

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

Response

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

​

reinterpretAsUInt128

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

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

البنية

reinterpretAsUInt128(x)

الوسائط

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

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

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

أمثلة

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

Query

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

Response

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

​

reinterpretAsUInt16

أُضيف في: v1.1.0

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

البنية

reinterpretAsUInt16(x)

المعاملات

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

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

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

أمثلة

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

Query

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

Response

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

​

reinterpretAsUInt256

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

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

الصياغة

reinterpretAsUInt256(x)

الوسيطات

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

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

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

أمثلة

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

Query

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

Response

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

​

reinterpretAsUInt32

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

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

الصيغة

reinterpretAsUInt32(x)

المعاملات

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

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

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

أمثلة

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

Query

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

Response

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

​

reinterpretAsUInt64

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

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

الصيغة

reinterpretAsUInt64(x)

الوسيطات

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

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

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

أمثلة

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

Query

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

Response

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

​

reinterpretAsUInt8

أُضيف في: v1.1.0

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

البنية

reinterpretAsUInt8(x)

الوسائط

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

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

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

أمثلة

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

Query

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

Response

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

​

reinterpretAsUUID

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

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

البنية

reinterpretAsUUID(fixed_string)

الوسائط

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

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

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

أمثلة

من String إلى UUID

Query

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

Response

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

​

toBFloat16

أُضيف في: v1.1.0

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

انظر أيضًا:

• toBFloat16OrZero.
• toBFloat16OrNull.

الصيغة

toBFloat16(expr)

الوسائط

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

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

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

أمثلة

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

Query

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

Response

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

​

toBFloat16OrNull

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

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

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

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

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

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

تسمح الدالة بفقدان الدقة بصمت أثناء التحويل من التمثيل النصي.

انظر أيضًا:

• toBFloat16.
• toBFloat16OrZero.

البنية

toBFloat16OrNull(x)

الوسيطات

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

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

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

أمثلة

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

Query

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

Response

\N	12.25	12.3125

​

toBFloat16OrZero

طُرح في: v1.1.0

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

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

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

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

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

تسمح الدالة بفقدان الدقة بصمت أثناء التحويل من التمثيل النصي.

انظر أيضًا:

• toBFloat16.
• toBFloat16OrNull.

الصياغة

toBFloat16OrZero(x)

الوسائط

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

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

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

أمثلة

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

Query

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

Response

0	12.25	12.3125

​

toBool

أُضيف في: v22.2.0

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

الصيغة

toBool(expr)

الوسائط

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

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

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

أمثلة

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

Query

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

Response

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

​

toDate

أُضيف في: v1.1.0

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

البنية

toDate(x)

المعاملات

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

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

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

أمثلة

تحويل String إلى Date

Query

SELECT toDate('2025-04-15')

Response

2025-04-15

تحويل DateTime إلى Date

Query

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

Response

2025-04-15

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

Query

SELECT toDate(20297)

Response

2025-07-28

​

toDate32

أُضيف في: v21.9.0

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

البنية

toDate32(expr)

وسيط

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

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

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

أمثلة

ضمن النطاق

Query

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

Response

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

قبل عام 1900

Query

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

Response

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

​

toDate32OrDefault

أُضيف في: 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

أمثلة

تحويل ناجح

Query

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

Response

1930-01-01

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

Query

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

Response

2020-01-01

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

Query

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

Response

2020-01-01

​

toDate32OrNull

أُضيف في: v21.9.0

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

البنية

toDate32OrNull(x)

الوسائط

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

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

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

أمثلة

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

Query

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

Response

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

​

toDate32OrZero

أُضيف في: 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

أمثلة

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

Query

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

Response

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

​

toDateOrDefault

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

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

الصياغة

toDateOrDefault(expr[, default])

الوسيطات

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

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

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

أمثلة

تحويل ناجح

Query

SELECT toDateOrDefault('2022-12-30')

Response

2022-12-30

فشل التحويل

Query

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

Response

2023-01-01

​

toDateOrNull

استُحدث في: 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

أمثلة

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

Query

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

Response

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

​

toDateOrZero

أُضيف في: v1.1.0

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

انظر أيضًا:

• toDate
• toDateOrNull
• toDateOrDefault

البنية

toDateOrZero(x)

الوسائط

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

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

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

أمثلة

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

Query

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

Response

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

​

toDateTime

أُضيف في: v1.1.0

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

إذا كانت expr رقمًا، فسيُفسَّر على أنه عدد الثواني منذ بداية حقبة Unix (أي كـ طابع زمني لـ Unix). إذا كانت expr من النوع String، فقد تُفسَّر على أنها طابع زمني لـ Unix أو على أنها تمثيل نصي لتاريخ أو لتاريخ مع وقت. لذلك، يُعطَّل صراحةً تحليل التمثيلات النصية للأرقام القصيرة (حتى 4 أرقام) بسبب الالتباس؛ فعلى سبيل المثال، قد تكون السلسلة '1999' سنةً (تمثيلًا نصيًا غير مكتمل لـ Date / DateTime) أو طابع زمني لـ Unix. ويُسمح بالسلاسل الرقمية الأطول.

إذا كانت expr قيمة من النوع Time أو Time64، فسيُفسَّر على أنه عدد الثواني منذ بداية حقبة Unix: ويُقرَّب الجزء الكسري من Time64 نزولًا نحو سالب اللانهاية، أما القيم الواقعة خارج نطاق DateTime فتتبع الإعداد date_time_overflow_behavior.

الصيغة

toDateTime(expr[, time_zone])

الوسيطات

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

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

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

أمثلة

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

Query

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

Response

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

​

toDateTime32

أُضيف: v20.9.0

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

الصيغة

toDateTime32(x[, timezone])

الوسيطات

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

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

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

أمثلة

من سلسلة نصية

Query

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

Response

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

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

Query

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

Response

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

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

Query

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

Response

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

​

toDateTime64

أُضيف في: v20.1.0

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

الصيغة

toDateTime64(expr, scale[, timezone])

الوسيطات

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

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

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

أمثلة

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

Query

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

Response

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

بصيغة Decimal بدقة

Query

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);

Response

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

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

Query

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

Response

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

​

toDateTime64OrDefault

أُضيف في: 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

أمثلة

تحويل ناجح

Query

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

Response

1976-10-18 00:00:00.300

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

Query

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

Response

2001-01-01 00:00:00.000

​

toDateTime64OrNull

استُحدثت في: 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

أمثلة

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

Query

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

Response

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

​

toDateTime64OrZero

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

يحوِّل قيمة الإدخال إلى قيمة من النوع DateTime64، لكنه يعيد قيمة DateTime64 الصفرية (حقبة Unix، 1970-01-01 00:00:00) إذا استلم وسيطة غير صالحة. وهو مماثل لـ toDateTime64، لكنه يعيد قيمة DateTime64 الصفرية إذا استلم وسيطة غير صالحة.

راجع أيضًا:

• toDateTime64.
• toDateTime64OrNull.
• toDateTime64OrDefault.

الصيغة

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

الوسيطات

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

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

تعيد قيمة من النوع DateTime64 عند النجاح، وإلا فتعيد قيمة DateTime64 الصفرية (1970-01-01 00:00:00) بالدقة المطلوبة. DateTime64

أمثلة

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

Query

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

Response

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

​

toDateTimeOrDefault

تم تقديمه في: 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

أمثلة

تحويل ناجح

Query

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

Response

2022-12-30 13:44:17

فشل التحويل

Query

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

Response

2023-01-01 00:00:00

​

toDateTimeOrNull

أُضيفت في: 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

أمثلة

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

Query

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

Response

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

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

Query

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

Response

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

​

toDateTimeOrZero

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

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

البنية

toDateTimeOrZero(x)

الوسيطات

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

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

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

أمثلة

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

Query

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

Response

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

​

toDecimal128

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

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

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

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

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

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

قد يحدث تجاوز إذا كانت قيمة expr تتجاوز حدود Decimal128:(-1*10^(38 - S), 1*10^(38 - S)). تُهمَل الأرقام الزائدة في الجزء الكسري (من دون تقريب). تؤدي الأرقام الزائدة في الجزء الصحيح إلى رفع استثناء.

تحذف التحويلات الأرقام الزائدة، وقد تعمل بطريقة غير متوقعة عند التعامل مع مدخلات Float32/Float64 لأن العمليات تُنفَّذ باستخدام تعليمات الفاصلة العائمة. على سبيل المثال: toDecimal128(1.15, 2) يساوي 1.14 لأن 1.15 * 100 في الفاصلة العائمة يساوي 114.99. يمكنك استخدام قيمة إدخال من نوع String بحيث تستخدم العمليات النوع الصحيح الأساسي: toDecimal128('1.15', 2) = 1.15

الصياغة

toDecimal128(expr, S)

الوسيطات

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

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

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

أمثلة

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

Query

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

Response

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)

​

toDecimal128OrDefault

تم تقديمه في: 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)

أمثلة

تحويل ناجح

Query

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

Response

0.023809523809523808

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

Query

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

Response

-1

​

toDecimal128OrNull

أُضيف في: 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

أمثلة

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

Query

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

Response

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

​

toDecimal128OrZero

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

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

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

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

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

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

إذا تجاوزت قيمة الإدخال حدود Decimal128:(-1*10^(38 - S), 1*10^(38 - S))، فستعيد الدالة 0.

البنية

toDecimal128OrZero(expr, S)

الوسيطات

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

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

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

أمثلة

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

Query

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

Response

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

​

toDecimal256

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

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

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

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

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

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

قد يحدث تجاوز إذا كانت قيمة expr تتجاوز حدود Decimal256:(-1*10^(76 - S), 1*10^(76 - S)). تُهمَل الأرقام الزائدة في الجزء الكسري (من دون تقريب). وتؤدي الأرقام الزائدة في الجزء الصحيح إلى إطلاق استثناء.

تُسقِط التحويلات الأرقام الزائدة، وقد تعمل على نحو غير متوقع عند التعامل مع مُدخلات Float32/Float64 لأن العمليات تُنفَّذ باستخدام تعليمات الفاصلة العائمة. على سبيل المثال: toDecimal256(1.15, 2) يساوي 1.14 لأن 1.15 * 100 في الفاصلة العائمة يساوي 114.99. يمكنك استخدام مُدخل String لكي تستخدم العمليات نوع العدد الصحيح الأساسي: toDecimal256('1.15', 2) = 1.15

الصياغة

toDecimal256(expr, S)

الوسيطات

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

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

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

أمثلة

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

Query

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

Response

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)

​

toDecimal256OrDefault

أُضيفت في: 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)

أمثلة

تحويل ناجح

Query

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

Response

0.023809523809523808

فشل التحويل

Query

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

Response

-1

​

toDecimal256OrNull

أُضيفت في: 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

أمثلة

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

Query

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

Response

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

​

toDecimal256OrZero

أُضيف في: v20.8.0

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

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

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

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

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

إذا تجاوزت قيمة الإدخال حدود Decimal256:(-1*10^(76 - S), 1*10^(76 - S))، فستعيد الدالة 0.

انظر أيضًا:

• toDecimal256.
• toDecimal256OrNull.
• toDecimal256OrDefault.

البنية

toDecimal256OrZero(expr, S)

الوسيطات

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

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

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

أمثلة

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

Query

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

Response

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

​

toDecimal32

أُضيف في: v18.12.0

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

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

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

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

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

قد يحدث تجاوز سعة إذا تجاوزت قيمة expr حدود Decimal32:(-1*10^(9 - S), 1*10^(9 - S)). تُهمَل الأرقام الزائدة في الجزء الكسري (من دون تقريب). أما الأرقام الزائدة في الجزء الصحيح فتؤدي إلى استثناء.

تتجاهل التحويلات الأرقام الزائدة، وقد تعمل على نحو غير متوقع عند التعامل مع مدخلات Float32/Float64 لأن العمليات تُنفَّذ باستخدام تعليمات الفاصلة العائمة. على سبيل المثال: toDecimal32(1.15, 2) تساوي 1.14 لأن 1.15 * 100 في الفاصلة العائمة يساوي 114.99. يمكنك استخدام مُدخل من النوع String لكي تستخدم العمليات النوع الصحيح الأساسي: toDecimal32('1.15', 2) = 1.15

الصيغة

toDecimal32(expr, S)

الوسيطات

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

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

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

أمثلة

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

Query

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

Response

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)

​

toDecimal32OrDefault

قُدِّمت في: 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)

أمثلة

تحويل ناجح

Query

SELECT toDecimal32OrDefault(toString(0.0001), 5)

Response

0.0001

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

Query

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

Response

-1

​

toDecimal32OrNull

أُضيفت في: 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

أمثلة

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

Query

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

Response

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

​

toDecimal32OrZero

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

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

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

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

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

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

إذا تجاوزت قيمة الإدخال حدود Decimal32:(-1*10^(9 - S), 1*10^(9 - S))، فستُرجِع الدالة 0.

البنية

toDecimal32OrZero(expr, S)

المعاملات

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

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

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

أمثلة

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

Query

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

Response

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

​

toDecimal64

أُضيف في: v18.12.0

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

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

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

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

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

قد يحدث تجاوز إذا كانت قيمة expr تتخطى حدود Decimal64:(-1*10^(18 - S), 1*10^(18 - S)). تُهمَل الخانات الزائدة في الجزء الكسري (من دون تقريب). تؤدي الخانات الزائدة في الجزء الصحيح إلى رفع استثناء.

تتجاهل التحويلات الخانات الزائدة، وقد تُعطي نتائج غير متوقعة عند التعامل مع مدخلات Float32/Float64 لأن العمليات تُنفَّذ باستخدام تعليمات الفاصلة العائمة. على سبيل المثال: toDecimal64(1.15, 2) تساوي 1.14 لأن 1.15 * 100 في الفاصلة العائمة تساوي 114.99. يمكنك استخدام قيمة إدخال من النوع String لكي تُجرى العمليات باستخدام النوع الصحيح الأساسي: toDecimal64('1.15', 2) = 1.15

البنية

toDecimal64(expr, S)

الوسائط

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

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

يُرجِع قيمة عشرية. Decimal(18, S)

أمثلة

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

Query

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

Response

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)

​

toDecimal64OrDefault

أُضيفت في: 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)

أمثلة

تحويل ناجح

Query

SELECT toDecimal64OrDefault(toString(0.0001), 18)

Response

0.0001

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

Query

SELECT toDecimal64OrDefault('Inf', 0, CAST('-1', 'Decimal64(0)'))

Response

-1

​

toDecimal64OrNull

أُضيف في: 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

أمثلة

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

Query

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

Response

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

​

toDecimal64OrZero

أُضيف في: v20.1.0

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

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

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

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

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

إذا تجاوزت قيمة الإدخال حدود Decimal64:(-1*10^(18 - S), 1*10^(18 - S))، فستعيد الدالة 0.

انظر أيضًا:

• toDecimal64.
• toDecimal64OrNull.
• toDecimal64OrDefault.

البنية

toDecimal64OrZero(expr, S)

الوسائط

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

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

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

أمثلة

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

Query

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

Response

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

​

toDecimalString

أُضيفت في: 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

أمثلة

تقريب عدد وتنسيقه

Query

SELECT toDecimalString(2.1456, 2)

Response

┌─toDecimalString(2.1456, 2)─┐
│ 2.15                       │
└────────────────────────────┘

الحشو بالأصفار

Query

SELECT toDecimalString(5, 3)

Response

┌─toDecimalString(5, 3)─┐
│ 5.000                 │
└───────────────────────┘

أنواع عددية مختلفة

Query

SELECT toDecimalString(CAST(123.456 AS Decimal(10,3)), 2) AS decimal_val,
       toDecimalString(CAST(42.7 AS Float32), 4) AS float_val

Response

┌─decimal_val─┬─float_val─┐
│ 123.46      │ 42.7000   │
└─────────────┴───────────┘

​

toFixedString

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

يحوّل وسيطًا من النوع String إلى النوع FixedString(N) (سلسلة نصية ذات طول ثابت مقداره N).

إذا كانت السلسلة النصية تحتوي على عدد بايتات أقل من N، فتُستكمل من اليمين ببايتات null. إذا كانت السلسلة النصية تحتوي على عدد بايتات أكبر من N، يُطرح استثناء.

البنية

toFixedString(s, N)

المعاملات

• s — السلسلة المطلوب تحويلها. String
• N — طول قيمة FixedString الناتجة. const UInt*

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

تُرجع قيمة FixedString بطول N. FixedString(N)

أمثلة

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

Query

-- The padding is made of null bytes, so the result is shown with `hex`.
SELECT hex(toFixedString('foo', 8)) AS s;

Response

┌─s────────────────┐
│ 666F6F0000000000 │
└──────────────────┘

​

toFloat32

أُضيف في: 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

أمثلة

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

Query

SELECT
    toFloat32(42.7),
    toFloat32('42.7'),
    toFloat32('NaN')
FORMAT Vertical

Response

Row 1:
──────
toFloat32(42.7):   42.7
toFloat32('42.7'): 42.7
toFloat32('NaN'):  nan

​

toFloat32OrDefault

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

على غرار toFloat32، تحوّل هذه الدالة قيمة الإدخال إلى قيمة من النوع Float32، لكنها تُرجع القيمة الافتراضية عند حدوث خطأ. إذا لم يتم تمرير قيمة default، فسيُرجع 0 عند حدوث خطأ.

الصيغة

toFloat32OrDefault(expr[, default])

المعاملات

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

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

تُرجع قيمة من النوع Float32 عند النجاح، وإلا فتُرجع القيمة الافتراضية إذا تم تمريرها، أو 0 إذا لم يتم ذلك. Float32

أمثلة

تحويل ناجح

Query

SELECT toFloat32OrDefault('8', CAST('0', 'Float32'))

Response

8

فشل التحويل

Query

SELECT toFloat32OrDefault('abc', CAST('0', 'Float32'))

Response

0

​

toFloat32OrNull

أُضيفت في: 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

أمثلة

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

Query

SELECT
    toFloat32OrNull('42.7'),
    toFloat32OrNull('NaN'),
    toFloat32OrNull('abc')
FORMAT Vertical

Response

Row 1:
──────
toFloat32OrNull('42.7'): 42.7
toFloat32OrNull('NaN'):  nan
toFloat32OrNull('abc'):  ᴺᵁᴸᴸ

​

toFloat32OrZero

أُضيف في: v1.1.0

يحوّل قيمة الإدخال إلى قيمة من النوع Float32، ويُرجع 0 في حال حدوث خطأ. يشبه toFloat32، لكنه يُرجع 0 بدلًا من إطلاق استثناء عند حدوث أخطاء في التحويل.

انظر أيضًا:

• toFloat32.
• toFloat32OrNull.
• toFloat32OrDefault.

الصيغة

toFloat32OrZero(x)

الوسيطات

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

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

يُرجع قيمة عائمة 32-بت عند النجاح، وإلا 0. Float32

أمثلة

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

Query

SELECT
    toFloat32OrZero('42.7'),
    toFloat32OrZero('abc')
FORMAT Vertical

Response

Row 1:
──────
toFloat32OrZero('42.7'): 42.7
toFloat32OrZero('abc'):  0

​

toFloat64

أُضيف في: 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

أمثلة

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

Query

SELECT
    toFloat64(42.7),
    toFloat64('42.7'),
    toFloat64('NaN')
FORMAT Vertical

Response

Row 1:
──────
toFloat64(42.7):   42.7
toFloat64('42.7'): 42.7
toFloat64('NaN'):  nan

​

toFloat64OrDefault

أُضيف في: v21.11.0

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

الصياغة

toFloat64OrDefault(expr[, default])

الوسيطات

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

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

يُرجع قيمة من النوع Float64 عند النجاح، وإلا فيُرجع القيمة الافتراضية إذا تم تمريرها، أو 0 إذا لم يتم تمريرها. Float64

أمثلة

تحويل ناجح

Query

SELECT toFloat64OrDefault('8', CAST('0', 'Float64'))

Response

8

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

Query

SELECT toFloat64OrDefault('abc', CAST('0', 'Float64'))

Response

0

​

toFloat64OrNull

أُضيف في: v1.1.0

يحوّل قيمة إدخال إلى قيمة من النوع Float64، لكنه يعيد NULL عند حدوث خطأ. يشبه toFloat64، لكنه يعيد NULL بدلًا من إطلاق استثناء عند حدوث أخطاء في التحويل.

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

• القيم من النوع (U)Int*.
• التمثيلات النصية لـ (U)Int8/16/32/128/256.
• القيم من النوع Float*، بما في ذلك NaN وInf.
• التمثيلات النصية من النوع Float*، بما في ذلك NaN وInf (دون حساسية لحالة الأحرف).

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

• التمثيلات النصية للقيم الثنائية والسداسية العشرية، مثل SELECT toFloat64OrNull('0xc0fe');.
• سلاسل نصية بتنسيق غير صالح.

انظر أيضًا:

• toFloat64.
• toFloat64OrZero.
• toFloat64OrDefault.

الصياغة

toFloat64OrNull(x)

الوسائط

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

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

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

أمثلة

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

Query

SELECT
    toFloat64OrNull('42.7'),
    toFloat64OrNull('NaN'),
    toFloat64OrNull('abc')
FORMAT Vertical

Response

Row 1:
──────
toFloat64OrNull('42.7'): 42.7
toFloat64OrNull('NaN'):  nan
toFloat64OrNull('abc'):  ᴺᵁᴸᴸ

​

toFloat64OrZero

أُضيف في: v1.1.0

يحوّل قيمة الإدخال إلى قيمة من النوع Float64، لكنه يعيد 0 في حال حدوث خطأ. يشبه toFloat64، لكنه يعيد 0 بدلًا من رفع استثناء عند حدوث أخطاء في التحويل.

انظر أيضًا:

• toFloat64.
• toFloat64OrNull.
• toFloat64OrDefault.

البنية

toFloat64OrZero(x)

الوسائط

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

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

يعيد قيمة Float64 عند النجاح، وإلا 0. Float64

أمثلة

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

Query

SELECT
    toFloat64OrZero('42.7'),
    toFloat64OrZero('abc')
FORMAT Vertical

Response

Row 1:
──────
toFloat64OrZero('42.7'): 42.7
toFloat64OrZero('abc'):  0

​

toInt128

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

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

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

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

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

• التمثيلات النصية لقيم Float*، بما في ذلك NaN وInf.
• التمثيلات النصية للقيم الثنائية والقيم السداسية العشرية، مثل SELECT toInt128('0xc0fe');.

إذا تعذّر تمثيل قيمة الإدخال ضمن حدود Int128، فقد يحدث تجاوز علوي أو سفلي في النتيجة. ولا يُعدّ ذلك خطأً.

انظر أيضًا:

• toInt128OrZero.
• toInt128OrNull.
• toInt128OrDefault.

الصيغة

toInt128(expr)

الوسائط

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

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

يُرجع قيمة عدد صحيح من نوع 128 بت. Int128

أمثلة

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

Query

SELECT
    toInt128(-128),
    toInt128(-128.8),
    toInt128('-128')
FORMAT Vertical

Response

Row 1:
──────
toInt128(-128):   -128
toInt128(-128.8): -128
toInt128('-128'): -128

​

toInt128OrDefault

أُضيف في: v21.11.0

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

البنية

toInt128OrDefault(expr[, default])

المعاملات

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

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

يُرجع قيمة من النوع Int128 عند النجاح، وإلا فيُرجع القيمة الافتراضية إذا تم تمريرها، أو 0 إذا لم تُمرَّر. Int128

أمثلة

تحويل ناجح

Query

SELECT toInt128OrDefault('-128', CAST('-1', 'Int128'))

Response

-128

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

Query

SELECT toInt128OrDefault('abc', CAST('-1', 'Int128'))

Response

-1

​

toInt128OrNull

أُضيف في: v20.8.0

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

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

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

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

• التمثيلات النصية لقيم Float*، بما في ذلك NaN وInf.
• التمثيلات النصية للقيم الثنائية والست عشرية، على سبيل المثال SELECT toInt128OrNull('0xc0fe');.

إذا تعذّر تمثيل قيمة الإدخال ضمن حدود Int128، يحدث overflow أو underflow في النتيجة. ولا يُعدّ ذلك خطأً.

انظر أيضًا:

• toInt128.
• toInt128OrZero.
• toInt128OrDefault.

الصياغة

toInt128OrNull(x)

الوسيطات

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

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

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

أمثلة

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

Query

SELECT
    toInt128OrNull('-128'),
    toInt128OrNull('abc')
FORMAT Vertical

Response

Row 1:
──────
toInt128OrNull('-128'): -128
toInt128OrNull('abc'):  ᴺᵁᴸᴸ

​

toInt128OrZero

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

يحوّل قيمة الإدخال إلى النوع Int128، لكنه يعيد 0 في حال حدوث خطأ. وهو يشبه toInt128، لكنه يعيد 0 بدلًا من إطلاق استثناء.

انظر أيضًا:

• toInt128.
• toInt128OrNull.
• toInt128OrDefault.

البنية

toInt128OrZero(x)

الوسيطات

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

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

تُعيد قيمة الإدخال بعد تحويلها، أو 0 إذا فشل التحويل. Int128

أمثلة

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

Query

SELECT toInt128OrZero('123')

Response

123

تُرجِع عمليةُ التحويل عند الفشل صفرًا

Query

SELECT toInt128OrZero('abc')

Response

0

​

toInt16

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

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

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

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

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

• التمثيلات النصية لقيم Float*، بما في ذلك NaN و Inf.
• التمثيلات النصية للقيم الثنائية والسداسية العشرية، مثل SELECT toInt16('0xc0fe');.

إذا تعذّر تمثيل قيمة الإدخال ضمن حدود Int16، يحدث overflow أو underflow في النتيجة. ولا يُعدّ ذلك خطأً. على سبيل المثال: SELECT toInt16(32768) == -32768;.

تستخدم الدالة rounding towards zero، ما يعني أنها تحذف الخانات الكسرية من الأرقام.

انظر أيضًا:

• toInt16OrZero.
• toInt16OrNull.
• toInt16OrDefault.

الصياغة

toInt16(expr)

الوسيطات

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

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

يُرجع قيمة عدد صحيح بطول 16 بت. Int16

أمثلة

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

Query

SELECT
    toInt16(-16),
    toInt16(-16.16),
    toInt16('-16')
FORMAT Vertical

Response

Row 1:
──────
toInt16(-16):    -16
toInt16(-16.16): -16
toInt16('-16'):  -16

​

toInt16OrDefault

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

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

البنية

toInt16OrDefault(expr[, default])

الوسيطات

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

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

يُعيد قيمة من النوع Int16 عند النجاح، وإلا يُعيد القيمة الافتراضية إذا تم تمريرها، أو 0 إذا لم يتم تمريرها. Int16

أمثلة

تحويل ناجح

Query

SELECT toInt16OrDefault('-16', CAST('-1', 'Int16'))

Response

-16

فشل التحويل

Query

SELECT toInt16OrDefault('abc', CAST('-1', 'Int16'))

Response

-1

​

toInt16OrNull

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

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

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

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

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

• التمثيلات النصية لقيم Float*، بما في ذلك NaN وInf.
• التمثيلات النصية للقيم الثنائية والسداسية العشرية، مثل SELECT toInt16OrNull('0xc0fe');.

إذا تعذّر تمثيل قيمة الإدخال ضمن حدود Int16، يحدث فيض أو نقص في النتيجة. ولا يُعدّ ذلك خطأً.

انظر أيضًا:

• toInt16.
• toInt16OrZero.
• toInt16OrDefault.

الصيغة

toInt16OrNull(x)

الوسائط

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

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

تعيد قيمة من النوع Int16، أو NULL إذا تعذر التحويل. Int16 أو NULL

أمثلة

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

Query

SELECT
    toInt16OrNull('-16'),
    toInt16OrNull('abc')
FORMAT Vertical

Response

Row 1:
──────
toInt16OrNull('-16'): -16
toInt16OrNull('abc'): ᴺᵁᴸᴸ

​

toInt16OrZero

أُضيف في: v1.1.0

مثل toInt16، تحوِّل هذه الدالة قيمة الإدخال إلى قيمة من النوع Int16، لكنها تُرجع 0 عند حدوث خطأ.

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

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

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

• التمثيلات النصية لقيم Float*، بما في ذلك NaN وInf.
• التمثيلات النصية للقيم الثنائية والستّ عشرية، على سبيل المثال SELECT toInt16OrZero('0xc0fe');.

إذا تعذّر تمثيل قيمة الإدخال ضمن حدود Int16، يحدث overflow أو underflow في النتيجة. ولا يُعدّ ذلك خطأً.

راجع أيضًا:

• toInt16.
• toInt16OrNull.
• toInt16OrDefault.

الصياغة

toInt16OrZero(x)

المعاملات

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

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

تُرجع قيمة من النوع Int16، أو 0 إذا تعذّر التحويل. Int16

أمثلة

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

Query

SELECT
    toInt16OrZero('16'),
    toInt16OrZero('abc')
FORMAT Vertical

Response

Row 1:
──────
toInt16OrZero('16'):  16
toInt16OrZero('abc'): 0

​

toInt256

أُضيف في: v1.1.0

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

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

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

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

• التمثيلات النصية لقيم Float*، بما في ذلك NaN وInf.
• التمثيلات النصية للقيم الثنائية والسداسية العشرية، مثل SELECT toInt256('0xc0fe');.

إذا تعذّر تمثيل قيمة الإدخال ضمن حدود Int256، فقد يحدث تجاوز أو قصور في النتيجة. لا يُعدّ ذلك خطأً.

انظر أيضًا:

• toInt256OrZero.
• toInt256OrNull.
• toInt256OrDefault.

البنية

toInt256(expr)

الوسيطات

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

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

يُرجع قيمة عدد صحيح من 256 بت. Int256

أمثلة

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

Query

SELECT
    toInt256(-256),
    toInt256(-256.256),
    toInt256('-256')
FORMAT Vertical

Response

Row 1:
──────
toInt256(-256):     -256
toInt256(-256.256): -256
toInt256('-256'):   -256

​

toInt256OrDefault

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

مثل toInt256، تحوِّل هذه الدالة قيمة الإدخال إلى قيمة من النوع Int256، لكنها تُرجع القيمة الافتراضية عند حدوث خطأ. إذا لم يتم تمرير قيمة default، فستُرجِع 0 عند حدوث خطأ.

الصياغة

toInt256OrDefault(expr[, default])

المعاملات

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

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

تُرجع قيمة من النوع Int256 عند النجاح، وإلا فتُرجع القيمة الافتراضية إذا تم تمريرها، أو 0 إذا لم يتم ذلك. Int256

أمثلة

تحويل ناجح

Query

SELECT toInt256OrDefault('-256', CAST('-1', 'Int256'))

Response

-256

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

Query

SELECT toInt256OrDefault('abc', CAST('-1', 'Int256'))

Response

-1

​

toInt256OrNull

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

مثل toInt256، تحوّل هذه الدالة قيمة إدخال إلى قيمة من النوع Int256، لكنها تعيد NULL عند حدوث خطأ.

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

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

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

• التمثيلات النصية لقيم Float*، بما في ذلك NaN وInf.
• التمثيلات النصية للقيم الثنائية والسداسية العشرية، على سبيل المثال SELECT toInt256OrNull('0xc0fe');.

إذا تعذر تمثيل قيمة الإدخال ضمن حدود Int256، يحدث overflow أو underflow في النتيجة. ولا يُعد ذلك خطأً.

راجع أيضًا:

• toInt256.
• toInt256OrZero.
• toInt256OrDefault.

البنية

toInt256OrNull(x)

المعاملات

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

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

تُعيد قيمة من النوع Int256، أو NULL إذا تعذّر التحويل. Int256 أو NULL

أمثلة

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

Query

SELECT
    toInt256OrNull('-256'),
    toInt256OrNull('abc')
FORMAT Vertical

Response

Row 1:
──────
toInt256OrNull('-256'): -256
toInt256OrNull('abc'):  ᴺᵁᴸᴸ

​

toInt256OrZero

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

يحوّل قيمة مُدخلة إلى النوع Int256، لكنه يعيد 0 في حال حدوث خطأ. يشبه toInt256، لكنه يعيد 0 بدلًا من إثارة استثناء.

انظر أيضًا:

• toInt256.
• toInt256OrNull.
• toInt256OrDefault.

البنية

toInt256OrZero(x)

الوسيطات

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

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

تُرجِع قيمة الإدخال بعد تحويلها، وإلا فتُرجِع 0 إذا فشل التحويل. Int256

أمثلة

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

Query

SELECT toInt256OrZero('123')

Response

123

تُرجِع عملية التحويل الفاشلة صفراً

Query

SELECT toInt256OrZero('abc')

Response

0

​

toInt32

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

تحوِّل قيمة إدخال إلى قيمة من النوع Int32. تطرح استثناءً في حال حدوث خطأ.

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

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

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

• التمثيلات النصية لقيم Float*، بما في ذلك NaN وInf.
• التمثيلات النصية للقيم الثنائية والقيم السداسية عشرية، على سبيل المثال SELECT toInt32('0xc0fe');.

إذا تعذّر تمثيل قيمة الإدخال ضمن حدود Int32، فستتجاوز النتيجة الحدّ الأعلى أو الأدنى للنطاق. ولا يُعدّ ذلك خطأً. على سبيل المثال: SELECT toInt32(2147483648) == -2147483648;

تستخدم الدالة التقريب نحو الصفر، ما يعني أنها تحذف الخانات الكسرية من الأعداد.

انظر أيضًا:

• toInt32OrZero.
• toInt32OrNull.
• toInt32OrDefault.

الصياغة

toInt32(expr)

الوسيطات

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

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

يُرجع قيمة عددٍ صحيحٍ مؤلفة من 32 بت. Int32

أمثلة

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

Query

SELECT
    toInt32(-32),
    toInt32(-32.32),
    toInt32('-32')
FORMAT Vertical

Response

Row 1:
──────
toInt32(-32):    -32
toInt32(-32.32): -32
toInt32('-32'):  -32

​

toInt32OrDefault

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

مثل toInt32، تحوِّل هذه الدالة قيمة الإدخال إلى قيمة من النوع Int32، لكنها تُرجِع القيمة الافتراضية عند حدوث خطأ. إذا لم يتم تمرير قيمة default، فستُرجِع 0 عند حدوث خطأ.

البنية

toInt32OrDefault(expr[, default])

الوسيطات

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

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

يُرجع قيمة من النوع Int32 عند النجاح، وإلا فيُرجع القيمة الافتراضية إذا تم تمريرها، أو 0 إذا لم يتم ذلك. Int32

أمثلة

تحويل ناجح

Query

SELECT toInt32OrDefault('-32', CAST('-1', 'Int32'))

Response

-32

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

Query

SELECT toInt32OrDefault('abc', CAST('-1', 'Int32'))

Response

-1

​

toInt32OrNull

طُرحت في: v1.1.0

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

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

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

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

• التمثيلات النصية لقيم Float*، بما في ذلك NaN وInf.
• التمثيلات النصية للقيم الثنائية والسداسية العشرية، على سبيل المثال SELECT toInt32OrNull('0xc0fe');.

إذا تعذّر تمثيل قيمة الإدخال ضمن حدود Int32، يحدث تجاوز للحد الأعلى أو الأدنى في النتيجة. ولا يُعدّ ذلك خطأ.

انظر أيضًا:

• toInt32.
• toInt32OrZero.
• toInt32OrDefault.

الصياغة

toInt32OrNull(x)

الوسيطات

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

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

يعيد قيمة من النوع Int32، أو NULL إذا تعذّر التحويل. Int32 أو NULL

أمثلة

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

Query

SELECT
    toInt32OrNull('-32'),
    toInt32OrNull('abc')
FORMAT Vertical

Response

Row 1:
──────
toInt32OrNull('-32'): -32
toInt32OrNull('abc'): ᴺᵁᴸᴸ

​

toInt32OrZero

أُضيف في: v1.1.0

على غرار toInt32، تُحوِّل هذه الدالة قيمة الإدخال إلى قيمة من النوع Int32، لكنها تُرجع 0 عند حدوث خطأ.

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

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

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

• التمثيلات النصية لقيم Float*، بما في ذلك NaN وInf.
• التمثيلات النصية للقيم الثنائية والسداسية العشرية، على سبيل المثال SELECT toInt32OrZero('0xc0fe');.

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

انظر أيضًا:

• toInt32.
• toInt32OrNull.
• toInt32OrDefault.

البنية

toInt32OrZero(x)

المعاملات

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

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

تُرجع قيمة من النوع Int32، وإلا فستُرجع 0 إذا تعذّر التحويل. Int32

أمثلة

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

Query

SELECT
    toInt32OrZero('32'),
    toInt32OrZero('abc')
FORMAT Vertical

Response

Row 1:
──────
toInt32OrZero('32'):  32
toInt32OrZero('abc'): 0

​

toInt64

أُضيف في: v1.1.0

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

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

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

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

• التمثيلات النصية لقيم Float*، بما في ذلك NaN وInf.
• التمثيلات النصية للقيم الثنائية والسداسية العشرية، مثل SELECT toInt64('0xc0fe');.

إذا تعذّر تمثيل قيمة الإدخال ضمن حدود Int64، فقد يحدث تجاوز علوي أو سفلي في النتيجة. ولا يُعدّ ذلك خطأً. على سبيل المثال: SELECT toInt64(9223372036854775808) == -9223372036854775808;

تستخدم الدالة التقريب نحو الصفر، ما يعني أنها تحذف الأرقام الكسرية من الأعداد.

انظر أيضًا:

• toInt64OrZero.
• toInt64OrNull.
• toInt64OrDefault.

البنية

toInt64(expr)

الوسائط

• expr — تعبير يُرجِع رقمًا أو تمثيلًا نصيًا لرقم. المدعوم: القيم أو التمثيلات النصية من النوع (U)Int*، والقيم من النوع Float*. غير المدعوم: التمثيلات النصية لقيم Float*، بما في ذلك NaN وInf، والتمثيلات النصية للقيم الثنائية والسداسية العشرية. تعبير

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

تُرجِع قيمة عدد صحيح من 64 بت. Int64

أمثلة

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

Query

SELECT
    toInt64(-64),
    toInt64(-64.64),
    toInt64('-64')
FORMAT Vertical

Response

Row 1:
──────
toInt64(-64):    -64
toInt64(-64.64): -64
toInt64('-64'):  -64

​

toInt64OrDefault

أُضيف في: v21.11.0

مثل toInt64، تحوِّل هذه الدالة قيمة الإدخال إلى قيمة من النوع Int64، لكنها تُرجع القيمة الافتراضية عند حدوث خطأ. إذا لم يتم تمرير قيمة default، فستُرجع 0 عند حدوث خطأ.

البنية

toInt64OrDefault(expr[, default])

الوسيطات

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

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

تُعاد قيمة من النوع Int64 عند النجاح، وإلا فتُعاد القيمة الافتراضية إذا تم تمريرها، أو 0 إن لم يتم ذلك. Int64

أمثلة

تحويل ناجح

Query

SELECT toInt64OrDefault('-64', CAST('-1', 'Int64'))

Response

-64

فشل التحويل

Query

SELECT toInt64OrDefault('abc', CAST('-1', 'Int64'))

Response

-1

​

toInt64OrNull

أُضيف في: v1.1.0

مثل toInt64، تحوّل هذه الدالة قيمة الإدخال إلى قيمة من النوع Int64، لكنها تعيد NULL في حال حدوث خطأ.

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

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

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

• التمثيلات النصية لقيم Float*، بما في ذلك NaN وInf.
• التمثيلات النصية للقيم الثنائية والسداسية العشرية، مثل SELECT toInt64OrNull('0xc0fe');.

إذا تعذّر تمثيل قيمة الإدخال ضمن حدود Int64، يحدث تجاوز للحد الأعلى أو الأدنى في النتيجة. ولا يُعد ذلك خطأ.

انظر أيضًا:

• toInt64.
• toInt64OrZero.
• toInt64OrDefault.

البنية

toInt64OrNull(x)

الوسيطات

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

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

يعيد قيمة من النوع Int64، أو NULL إذا تعذر التحويل. Int64 أو NULL

أمثلة

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

Query

SELECT
    toInt64OrNull('-64'),
    toInt64OrNull('abc')
FORMAT Vertical

Response

Row 1:
──────
toInt64OrNull('-64'): -64
toInt64OrNull('abc'): ᴺᵁᴸᴸ

​

toInt64OrZero

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

يحوّل قيمة إدخال إلى النوع Int64، لكنه يعيد 0 في حال حدوث خطأ. يشبه toInt64، لكنه يعيد 0 بدلًا من إطلاق استثناء.

انظر أيضًا:

• toInt64.
• toInt64OrNull.
• toInt64OrDefault.

الصياغة

toInt64OrZero(x)

الوسائط

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

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

تُعيد قيمة الإدخال بعد تحويلها، أو 0 إذا فشل التحويل. Int64

أمثلة

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

Query

SELECT toInt64OrZero('123')

Response

123

يعيد التحويل الفاشل صفراً

Query

SELECT toInt64OrZero('abc')

Response

0

​

toInt8

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

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

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

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

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

• التمثيلات النصية لقيم Float*، بما في ذلك NaN وInf.
• التمثيلات النصية للقيم الثنائية والسداسية العشرية، مثل SELECT toInt8('0xc0fe');.

إذا تعذّر تمثيل قيمة الإدخال ضمن حدود Int8، يحدث تجاوز سعة أو نقص سعة في النتيجة. ولا يُعد ذلك خطأً. على سبيل المثال: SELECT toInt8(128) == -128;.

تستخدم الدالة التقريب نحو الصفر، أي إنها تحذف الخانات الكسرية من الأرقام.

انظر أيضًا:

• toInt8OrZero.
• toInt8OrNull.
• toInt8OrDefault.

البنية

toInt8(expr)

المعاملات

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

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

يعيد قيمة عدد صحيح من 8 بتات. Int8

أمثلة

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

Query

SELECT
    toInt8(-8),
    toInt8(-8.8),
    toInt8('-8')
FORMAT Vertical

Response

Row 1:
──────
toInt8(-8):   -8
toInt8(-8.8): -8
toInt8('-8'): -8

​

toInt8OrDefault

أُضيف في: v21.11.0

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

الصيغة

toInt8OrDefault(expr[, default])

الوسيطات

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

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

تُعاد قيمة من النوع Int8 عند النجاح، وإلا فتُعاد القيمة الافتراضية إذا تم تمريرها، أو 0 إذا لم يتم تمريرها. Int8

أمثلة

تحويل ناجح

Query

SELECT toInt8OrDefault('-8', CAST('-1', 'Int8'))

Response

-8

فشل التحويل

Query

SELECT toInt8OrDefault('abc', CAST('-1', 'Int8'))

Response

-1

​

toInt8OrNull

أُضيف في: v1.1.0

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

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

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

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

• التمثيلات النصية لقيم Float*، بما في ذلك NaN وInf.
• التمثيلات النصية للقيم الثنائية والستّ عشرية، مثل SELECT toInt8OrNull('0xc0fe');.

إذا تعذّر تمثيل قيمة الإدخال ضمن حدود Int8، يحدث overflow أو underflow في النتيجة. ولا يُعدّ ذلك خطأ.

انظر أيضًا:

• toInt8.
• toInt8OrZero.
• toInt8OrDefault.

البنية

toInt8OrNull(x)

الوسائط

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

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

تعيد قيمة من النوع Int8، أو NULL إذا تعذّر التحويل. Int8 أو NULL

أمثلة

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

Query

SELECT
    toInt8OrNull('-8'),
    toInt8OrNull('abc')
FORMAT Vertical

Response

Row 1:
──────
toInt8OrNull('-8'):  -8
toInt8OrNull('abc'): ᴺᵁᴸᴸ

​

toInt8OrZero

أُضيف في: v1.1.0

مثل toInt8، تحوّل هذه الدالة قيمة الإدخال إلى قيمة من النوع Int8، لكنها تعيد 0 عند حدوث خطأ.

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

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

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

• التمثيلات النصية لقيم Float*، بما في ذلك NaN وInf.
• التمثيلات النصية للقيم الثنائية والسداسية العشرية، مثل SELECT toInt8OrZero('0xc0fe');.

إذا تعذّر تمثيل قيمة الإدخال ضمن حدود Int8، يحدث تجاوز علوي أو سفلي في النتيجة. ولا يُعدّ ذلك خطأ.

انظر أيضًا:

• toInt8.
• toInt8OrNull.
• toInt8OrDefault.

البنية

toInt8OrZero(x)

المعاملات

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

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

يعيد قيمة من النوع Int8، وإلا فيُعيد 0 إذا لم ينجح التحويل. Int8

أمثلة

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

Query

SELECT
    toInt8OrZero('8'),
    toInt8OrZero('abc')
FORMAT Vertical

Response

Row 1:
──────
toInt8OrZero('8'):   8
toInt8OrZero('abc'): 0

​

toInterval

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

تنشئ قيمة Interval من قيمة رقمية وسلسلة نصية للوحدة.

توفّر هذه الدالة طريقة موحّدة لإنشاء فترات زمنية من أنواع مختلفة (ثوانٍ، دقائق، ساعات، أيام، أسابيع، أشهر، أرباع سنوية، سنوات) باستخدام دالة واحدة فقط، وذلك عبر تحديد الوحدة كسلسلة نصية. سلسلة الوحدة غير حساسة لحالة الأحرف.

وهذا يكافئ استدعاء دوال مخصّصة لكل نوع مثل toIntervalSecond وtoIntervalMinute وtoIntervalDay وغيرها، لكنه يتيح تحديد الوحدة ديناميكيًا بوصفها معامل String.

الصياغة

toInterval(value, unit)

الوسائط

• value — القيمة الرقمية التي تمثل عدد الوحدات. يمكن أن تكون من أي نوع رقمي. Int8 أو Int16 أو Int32 أو Int64 أو UInt8 أو UInt16 أو UInt32 أو UInt64 أو Float32 أو Float64
• unit — وحدة الزمن. يجب أن تكون سلسلة نصية ثابتة. القيم الصالحة هي: ‘nanosecond’ و’microsecond’ و’millisecond’ و’second’ و’minute’ و’hour’ و’day’ و’week’ و’month’ و’quarter’ و’year’. String

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

تُرجع قيمة Interval من النوع المحدد. يعتمد نوع النتيجة على الوحدة: IntervalNanosecond أو IntervalMicrosecond أو IntervalMillisecond أو IntervalSecond أو IntervalMinute أو IntervalHour أو IntervalDay أو IntervalWeek أو IntervalMonth أو IntervalQuarter أو IntervalYear. Interval

أمثلة

إنشاء قيم Interval بوحدات مختلفة

Query

SELECT
    toInterval(5, 'second') AS seconds,
    toInterval(3, 'day') AS days,
    toInterval(2, 'month') AS months

Response

┌─seconds─┬─days─┬─months─┐
│       5 │    3 │      2 │
└─────────┴──────┴────────┘

استخدم الفترات في العمليات الحسابية على التواريخ

Query

SELECT
    now() AS current_time,
    now() + toInterval(1, 'hour') AS one_hour_later,
    now() - toInterval(7, 'day') AS week_ago

Response

┌─────────current_time─┬──one_hour_later─────┬────────────week_ago─┐
│ 2025-01-04 10:30:00  │ 2025-01-04 11:30:00 │ 2024-12-28 10:30:00 │
└──────────────────────┴─────────────────────┴─────────────────────┘

إنشاء الفاصل الزمني ديناميكيًا

Query

SELECT toDate('2025-01-01') + toInterval(number, 'day') AS dates
FROM numbers(5)

Response

┌──────dates─┐
│ 2025-01-01 │
│ 2025-01-02 │
│ 2025-01-03 │
│ 2025-01-04 │
│ 2025-01-05 │
└────────────┘

​

toIntervalDay

أُضيف في: v1.1.0

يُرجع فاصلًا زمنيًا من n يومًا من نوع البيانات IntervalDay.

الصياغة

toIntervalDay(n)

الوسيطات

• n — عدد الأيام. الأعداد الصحيحة أو تمثيلاتها النصية، وكذلك الأعداد العائمة. (U)Int* أو Float* أو String

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

تُرجع فترة زمنية من n أيام. Interval

أمثلة

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

Query

WITH
    toDate('2025-06-15') AS date,
    toIntervalDay(5) AS interval_to_days
SELECT date + interval_to_days AS result

Response

┌─────result─┐
│ 2025-06-20 │
└────────────┘

​

toIntervalHour

أُضيف في: v1.1.0

يعيد interval مقداره n ساعة من نوع البيانات IntervalHour.

الصياغة

toIntervalHour(n)

المعاملات

• n — عدد الساعات. أعداد صحيحة أو تمثيلاتها النصية، وأعداد عشرية. Int* أو UInt* أو Float* أو String

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

يعيد فاصلًا زمنيًا مقداره n ساعة. Interval

أمثلة

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

Query

WITH
    toDate('2025-06-15') AS date,
    toIntervalHour(12) AS interval_to_hours
SELECT date + interval_to_hours AS result

Response

┌──────────────result─┐
│ 2025-06-15 12:00:00 │
└─────────────────────┘

​

toIntervalMicrosecond

قُدِّم في: v22.6.0

يُرجع فاصلًا زمنيًا مقداره n ميكروثانية من نوع البيانات IntervalMicrosecond.

الصياغة

toIntervalMicrosecond(n)

الوسيطات

• n — عدد الميكروثواني. (U)Int* أو Float* أو String

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

تعيد قيمة Interval مقدارها n ميكروثانية. Interval

أمثلة

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

Query

WITH
    toDateTime('2025-06-15') AS date,
    toIntervalMicrosecond(30) AS interval_to_microseconds
SELECT date + interval_to_microseconds AS result

Response

┌─────────────────────result─┐
│ 2025-06-15 00:00:00.000030 │
└────────────────────────────┘

​

toIntervalMillisecond

تم تقديمه في: v22.6.0

يعيد فاصلًا زمنيًا مقداره n مللي ثانية من نوع البيانات IntervalMillisecond.

البنية

toIntervalMillisecond(n)

المعاملات

• n — عدد المللي ثواني. (U)Int* أو Float* أو String

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

يُرجِع فترة زمنية مقدارها n مللي ثانية. Interval

أمثلة

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

Query

WITH
    toDateTime('2025-06-15') AS date,
    toIntervalMillisecond(30) AS interval_to_milliseconds
SELECT date + interval_to_milliseconds AS result

Response

┌──────────────────result─┐
│ 2025-06-15 00:00:00.030 │
└─────────────────────────┘

​

toIntervalMinute

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

تعيد فاصلًا زمنيًا مقداره n دقيقة من نوع البيانات IntervalMinute.

البنية

toIntervalMinute(n)

المعاملات

• n — عدد الدقائق. الأعداد الصحيحة أو تمثيلاتها النصية، والأعداد العائمة. (U)Int* أو Float* أو String

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

يُرجع فاصلًا زمنيًا مقداره n دقيقة. Interval

أمثلة

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

Query

WITH
    toDate('2025-06-15') AS date,
    toIntervalMinute(12) AS interval_to_minutes
SELECT date + interval_to_minutes AS result

Response

┌──────────────result─┐
│ 2025-06-15 00:12:00 │
└─────────────────────┘

​

toIntervalMonth

أُضيف في: v1.1.0

يعيد فاصلًا زمنيًا مقداره n شهرًا من نوع البيانات IntervalMonth.

البنية

toIntervalMonth(n)

الوسيطات

• n — عدد الأشهر. (U)Int* أو Float* أو String

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

تُرجِع فترةً مقدارها n شهرًا. Interval

أمثلة

مثال استخدام

Query

WITH
    toDate('2025-06-15') AS date,
    toIntervalMonth(1) AS interval_to_month
SELECT date + interval_to_month AS result

Response

┌─────result─┐
│ 2025-07-15 │
└────────────┘

​

toIntervalNanosecond

قُدِّم في: v22.6.0

يعيد فاصلًا زمنيًا مقداره n نانوثانية من نوع البيانات IntervalNanosecond.

الصياغة

toIntervalNanosecond(n)

الوسيطات

• n — عدد النانوثواني. (U)Int* أو Float* أو String

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

تُرجِع فاصلًا زمنيًا مقداره n نانوثانية. Interval

أمثلة

مثال استخدام

Query

WITH
    toDateTime('2025-06-15') AS date,
    toIntervalNanosecond(30) AS interval_to_nanoseconds
SELECT date + interval_to_nanoseconds AS result

Response

┌────────────────────────result─┐
│ 2025-06-15 00:00:00.000000030 │
└───────────────────────────────┘

​

toIntervalQuarter

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

تعيد فاصلًا زمنيًا من n أرباع من نوع البيانات IntervalQuarter.

الصياغة

toIntervalQuarter(n)

الوسيطات

• n — عدد أرباع السنة. (U)Int* أو Float* أو String

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

يُرجع فاصلًا زمنيًا مقداره n من أرباع السنة. Interval

أمثلة

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

Query

WITH
    toDate('2025-06-15') AS date,
    toIntervalQuarter(1) AS interval_to_quarter
SELECT date + interval_to_quarter AS result

Response

┌─────result─┐
│ 2025-09-15 │
└────────────┘

​

toIntervalSecond

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

تعيد قيمة interval من n ثانية، من نوع البيانات IntervalSecond.

البنية

toIntervalSecond(n)

الوسيطات

• n — عدد الثواني. الأعداد الصحيحة أو تمثيلاتها النصية، والأعداد ذات الفاصلة العائمة. (U)Int* أو Float* أو String

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

يُرجِع فاصلًا زمنيًا مقداره n ثانية. Interval

أمثلة

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

Query

WITH
    toDate('2025-06-15') AS date,
    toIntervalSecond(30) AS interval_to_seconds
SELECT date + interval_to_seconds AS result

Response

┌──────────────result─┐
│ 2025-06-15 00:00:30 │
└─────────────────────┘

​

toIntervalWeek

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

تعيد فاصلًا زمنيًا مقداره n أسبوعًا من نوع البيانات IntervalWeek.

الصياغة

toIntervalWeek(n)

المعاملات

• n — عدد الأسابيع. (U)Int* أو Float* أو String

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

يعيد فترة n أسابيع. Interval

أمثلة

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

Query

WITH
    toDate('2025-06-15') AS date,
    toIntervalWeek(1) AS interval_to_week
SELECT date + interval_to_week AS result

Response

┌─────result─┐
│ 2025-06-22 │
└────────────┘

​

toIntervalYear

أُضيف في: v1.1.0

يعيد interval من n سنة من نوع البيانات IntervalYear.

الصيغة

toIntervalYear(n)

المعاملات

• n — عدد السنوات. (U)Int* أو Float* أو String

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

تعيد فاصلًا زمنيًا مقداره n سنة. Interval

أمثلة

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

Query

WITH
    toDate('2024-06-15') AS date,
    toIntervalYear(1) AS interval_to_year
SELECT date + interval_to_year AS result

Response

┌─────result─┐
│ 2025-06-15 │
└────────────┘

​

toLowCardinality

قُدِّم في: v18.12.0

يحوّل وسيط الإدخال إلى إصدار LowCardinality من نوع البيانات نفسه.

للتحويل من نوع البيانات LowCardinality إلى نوع بيانات عادي، استخدم الدالة CAST. على سبيل المثال: CAST(x AS String).

البنية

toLowCardinality(expr)

الوسائط

• expr — تعبير ينتج أحد أنواع البيانات المدعومة. String أو FixedString أو Date أو DateTime أو (U)Int* أو Float*

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

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

أمثلة

مثال على الاستخدام

Query

SELECT toLowCardinality('1')

Response

┌─toLowCardinality('1')─┐
│ 1                     │
└───────────────────────┘

​

toString

قُدِّمت في: v1.1.0

تحوِّل القيم إلى تمثيلها النصي. وبالنسبة إلى وسيطات DateTime، يمكن أن تأخذ الدالة وسيطة String ثانية تحتوي على اسم المنطقة الزمنية.

البنية

toString(value[, timezone])

الوسائط

• value — القيمة المراد تحويلها إلى سلسلة نصية. Any
• timezone — اختياري. اسم المنطقة الزمنية لتحويل DateTime. String

القيمة المُعادة

تعيد تمثيلًا نصيًا لقيمة الإدخال. String

أمثلة

مثال على الاستخدام

Query

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

Response

┌──────────────────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 │
└─────────────────────┴───────────────────┴─────────────────────┘

​

toStringCutToZero

أُضيفت في: v1.1.0

تقبل argument من النوع String أو FixedString، وتُرجع قيمة من النوع String تحتوي على نسخة من السلسلة الأصلية مقصوصة عند أول بايت صفري.

تُعد البايتات الصفرية (\0) بمثابة مُنهِيات للسلاسل. تكون هذه الدالة مفيدة لمعالجة السلاسل بأسلوب C أو البيانات الثنائية، حيث تشير البايتات الصفرية إلى نهاية المحتوى المفيد.

الصياغة

toStringCutToZero(s)

الوسائط

• s — قيمة من النوع String أو FixedString المراد معالجتها. String أو FixedString

القيمة المُعادة

تُرجع String تحتوي على الأحرف التي تسبق أول بايت صفري. String

أمثلة

مثال على الاستخدام

Query

SELECT
    toStringCutToZero('hello'),
    toStringCutToZero('hello\0world')

Response

┌─toStringCutToZero('hello')─┬─toStringCutToZero('hello\0world')─┐
│ hello                      │ hello                             │
└────────────────────────────┴───────────────────────────────────┘

​

toTime

أُضيف في: v25.5.0

يحوّل قيمة الإدخال إلى النوع Time. يدعم التحويل من String وFixedString وDateTime وDateTime64 وTime64 أو من الأنواع الرقمية التي تمثل عدد الثواني منذ منتصف الليل. تُقيَّد القيم الرقمية الواقعة خارج نطاق النوع (-999:59:59 إلى 999:59:59، أي -3599999 إلى 3599999 ثانية) بحدود النطاق، ولا يمكن تحويل قيم الفاصلة العائمة غير المنتهية (NaN وinf و-inf) وينتج عن ذلك استثناء. تُقرَّب قيم Time64 نزولًا نحو اللانهاية السالبة إلى ثوانٍ كاملة وتُقيَّد بالنطاق نفسه.

قبل v25.5، كانت toTime دالة مختلفة تحوّل تاريخًا مع وقت إلى تاريخ ثابت (1970-01-02) مع الحفاظ على مكوّن الوقت. ولا تزال تلك الدالة متاحة بالاسم toTimeWithFixedDate.

يؤدي أيضًا ضبط use_legacy_to_time على 1 إلى إبقاء الاسم toTime مرتبطًا بالدالة القديمة، أي إن استدعاءات toTime تُفسَّر على أنها toTimeWithFixedDate بدلًا من دالة التحويل الموضحة هنا. أثناء تمكين الإعداد، استخدم CAST(x AS Time) أو x::Time للتحويل إلى النوع Time. تكون القيمة الافتراضية للإعداد 0 منذ v26.7، لكنها كانت 1 من v25.6 إلى v26.6، ولهذا تضبطها الأمثلة أدناه صراحةً.

الصيغة

toTime(x)

وسيطات الدالة

• x — قيمة الإدخال المراد تحويلها. String أو FixedString أو DateTime أو DateTime64 أو Time64 أو (U)Int* أو BFloat16 أو Float*

القيمة المعادة

تُرجِع القيمة المُحوَّلة. Time

أمثلة

التحويل من DateTime64 إلى Time

Query

SET enable_time_time64_type = 1;
SET use_legacy_to_time = 0;
SELECT toTime(toDateTime64('2025-04-15 14:30:25.123', 3))

Response

14:30:25

التحويل من DateTime إلى Time

Query

SET enable_time_time64_type = 1;
SET use_legacy_to_time = 0;
SELECT toTime(toDateTime('2025-04-15 14:30:25'))

Response

14:30:25

تحويل الأعداد الصحيحة (بالثواني منذ epoch) إلى Time

Query

SET enable_time_time64_type = 1;
SET use_legacy_to_time = 0;
SELECT toTime(toDateTime(52225, 'UTC'))

Response

14:30:25

​

toTime64

أُضيف في: v25.6.0

يحوّل قيمة الإدخال إلى النوع Time64. يدعم التحويل من String وFixedString وDateTime64 أو من الأنواع الرقمية التي تمثل الثواني منذ منتصف الليل. يوفّر دقة أقل من الثانية لقيم الوقت، حتى scale من الخانات الكسرية.

الصياغة

toTime64(x, scale)

الوسيطات

• x — قيمة الإدخال المطلوب تحويلها. String أو FixedString أو DateTime64 أو (U)Int* أو Float*
• scale — الدقة (عدد الخانات الكسرية، من 0 إلى 9) في قيمة Time64 الناتجة. (U)Int*

القيمة المعادة

تُرجِع القيمة المحوَّلة بالدقة scale المطلوبة. Time64

أمثلة

تحويل String إلى Time64

Query

SET enable_time_time64_type = 1;
SELECT toTime64('14:30:25.123456', 6)

Response

14:30:25.123456

تحويل DateTime64 إلى Time64

Query

SET enable_time_time64_type = 1;
SELECT toTime64(toDateTime64('2025-04-15 14:30:25.123456', 6), 6)

Response

14:30:25.123456

تحويل Float (عدد الثواني منذ منتصف الليل) إلى Time64

Query

SET enable_time_time64_type = 1;
SELECT toTime64(52225.123456, 6)

Response

14:30:25.123456

​

toTime64OrNull

أُضيف في: v25.6.0

يحوّل قيمة الإدخال إلى قيمة من النوع Time64، ولكنه يعيد NULL في حال حدوث خطأ. يشبه toTime64، لكنه يعيد NULL بدلًا من طرح استثناء عند حدوث أخطاء في التحويل.

انظر أيضًا:

• toTime64
• toTime64OrZero

البنية

toTime64OrNull(x[, precision])

الوسيطات

• x — تمثيل نصي لوقت بدقة أقل من الثانية. String
• precision — اختياري. دقة أقل من الثانية للقيمة المُعادة. UInt8

القيمة المُعادة

تعيد قيمة من النوع Time64 عند النجاح، وإلا NULL. Time64 أو NULL

أمثلة

مثال للاستخدام

Query

SELECT toTime64OrNull('12:30:45.123'), toTime64OrNull('invalid')

Response

┌─toTime64OrNull('12:30:45.123')─┬─toTime64OrNull('invalid')─┐
│                   12:30:45.123 │                      ᴺᵁᴸᴸ │
└────────────────────────────────┴───────────────────────────┘

​

toTime64OrZero

أُضيف في: v25.6.0

يحوِّل قيمة الإدخال إلى قيمة من النوع Time64، لكنه يُرجع قيمة Time64 الصفرية (00:00:00) في حال استلام وسيطة غير صالحة. يشبه toTime64، لكنه يُرجع قيمة Time64 الصفرية في حال استلام وسيطة غير صالحة.

انظر أيضًا:

• toTime64.
• toTime64OrNull.

البنية

toTime64OrZero(x[, precision])

وسيطة

• x — تمثيل نصي لوقت بدقة أقل من الثانية. String
• precision — اختياري. دقة أقل من الثانية للقيمة المُعادة. UInt8

القيمة المُعادة

تُرجِع قيمة من النوع Time64 عند النجاح، وإلا القيمة الصفرية من النوع Time64 (00:00:00) بالدقة المطلوبة. Time64

أمثلة

مثال على الاستخدام

Query

SELECT toTime64OrZero('12:30:45.123'), toTime64OrZero('invalid')

Response

┌─toTime64OrZero('12:30:45.123')─┬─toTime64OrZero('invalid')─┐
│                   12:30:45.123 │              00:00:00.000 │
└────────────────────────────────┴───────────────────────────┘

​

toTimeOrNull

طُرح في: v25.5.0

يحوّل قيمة الإدخال إلى قيمة من النوع Time، ولكنه يعيد NULL في حال حدوث خطأ. يشبه toTime، لكنه يعيد NULL بدلًا من طرح استثناء عند حدوث أخطاء في التحويل.

انظر أيضًا:

• toTime
• toTimeOrZero

بنية

toTimeOrNull(x)

وسيطة

• x — تمثيل نصي لوقت. String

القيمة المعادة

يعيد قيمة Time عند النجاح، وإلا NULL. Time أو NULL

أمثلة

مثال للاستخدام

Query

SELECT toTimeOrNull('12:30:45'), toTimeOrNull('invalid')

Response

┌─toTimeOrNull('12:30:45')─┬─toTimeOrNull('invalid')─┐
│                 12:30:45 │                    ᴺᵁᴸᴸ │
└──────────────────────────┴─────────────────────────┘

​

toTimeOrZero

استُحدث في: v25.5.0

يحوّل قيمة الإدخال إلى قيمة من النوع Time، لكنه يعيد 00:00:00 في حال حدوث خطأ. يشبه toTime، لكنه يعيد 00:00:00 بدلًا من إطلاق استثناء عند حدوث أخطاء في التحويل.

بنية

toTimeOrZero(x)

الوسيطات

• x — تمثيل نصي لوقت. String

القيمة المُعادة

تُعيد قيمة من النوع Time عند النجاح، وإلا 00:00:00.

أمثلة

مثال على الاستخدام

Query

SELECT toTimeOrZero('12:30:45'), toTimeOrZero('invalid')

Response

┌─toTimeOrZero('12:30:45')─┬─toTimeOrZero('invalid')─┐
│                 12:30:45 │                00:00:00 │
└──────────────────────────┴─────────────────────────┘

​

toUInt128

ظهر في: v1.1.0

يحوّل قيمة الإدخال إلى قيمة من النوع UInt128. يطرح استثناءً في حال حدوث خطأ. تستخدم الدالة التقريب باتجاه الصفر، ما يعني أنها تحذف الخانات الكسرية من الأعداد.

الوسيطات المدعومة:

• القيم أو التمثيلات النصية من النوع (U)Int*.
• القيم من النوع Float*.

الوسيطات غير المدعومة:

• التمثيلات النصية لقيم Float*، بما في ذلك NaN وInf.
• التمثيلات النصية للقيم الثنائية والسداسية العشرية، مثل SELECT toUInt128('0xc0fe');.

إذا تعذّر تمثيل قيمة الإدخال ضمن حدود UInt128، فستحدث حالة تجاوز علوي أو سفلي في النتيجة. ولا يُعد ذلك خطأً.

انظر أيضًا:

• toUInt128OrZero.
• toUInt128OrNull.
• toUInt128OrDefault.

البنية

toUInt128(expr)

الوسائط

• expr — تعبير يُرجع عددًا أو تمثيلًا نصيًا لعدد. تعبير

القيمة المعادة

تُرجع قيمة عدد صحيح غير موقّع بطول 128 بت. UInt128

أمثلة

مثال على الاستخدام

Query

SELECT
    toUInt128(128),
    toUInt128(128.8),
    toUInt128('128')
FORMAT Vertical

Response

Row 1:
──────
toUInt128(128):   128
toUInt128(128.8): 128
toUInt128('128'): 128

​

toUInt128OrDefault

أُضيف في: v21.11.0

مثل toUInt128، تحوّل هذه الدالة قيمة مُدخلة إلى قيمة من النوع UInt128، لكنها تُرجع القيمة الافتراضية في حال حدوث خطأ. إذا لم يتم تمرير قيمة default، فستُرجع 0 عند حدوث خطأ.

البنية

toUInt128OrDefault(expr[, default])

الوسيطات

• expr — تعبير يُرجع رقمًا أو تمثيلًا نصيًا لرقم. String أو (U)Int* أو Float*
• default — اختياري. القيمة الافتراضية التي تُعاد إذا تعذّر التحليل. UInt128

القيمة المُعادة

يعيد قيمة من النوع UInt128 عند النجاح، وإلا يعيد القيمة الافتراضية إذا تم تمريرها، أو 0 إذا لم تُمرَّر. UInt128

أمثلة

تحويل ناجح

Query

SELECT toUInt128OrDefault('128', CAST('0', 'UInt128'))

Response

128

تعذّر التحويل

Query

SELECT toUInt128OrDefault('abc', CAST('0', 'UInt128'))

Response

0

​

toUInt128OrNull

أُضيف في: v21.6.0

على غرار toUInt128، تحوّل هذه الدالة قيمة الإدخال إلى قيمة من النوع UInt128، لكنها تُرجع NULL في حال حدوث خطأ.

الوسيطات المدعومة:

• التمثيلات النصية لقيم (U)Int*.

الوسيطات غير المدعومة (تُرجع NULL):

• التمثيلات النصية لقيم Float*، بما في ذلك NaN وInf.
• التمثيلات النصية للقيم الثنائية والسداسية العشرية، مثل SELECT toUInt128OrNull('0xc0fe');.

إذا تعذّر تمثيل قيمة الإدخال ضمن حدود UInt128، يحدث overflow أو underflow في النتيجة. ولا يُعدّ ذلك خطأً.

انظر أيضًا:

• toUInt128.
• toUInt128OrZero.
• toUInt128OrDefault.

الصياغة

toUInt128OrNull(x)

المعاملات

• x — تمثيل نصي لرقم. String

القيمة المعادة

تعيد قيمة من النوع UInt128، أو NULL إذا تعذّر التحويل. UInt128 أو NULL

أمثلة

مثال على الاستخدام

Query

SELECT
    toUInt128OrNull('128'),
    toUInt128OrNull('abc')
FORMAT Vertical

Response

Row 1:
──────
toUInt128OrNull('128'): 128
toUInt128OrNull('abc'): ᴺᵁᴸᴸ

​

toUInt128OrZero

أُضيف في: v1.1.0

مثل toUInt128، تحوّل هذه الدالة قيمة الإدخال إلى قيمة من النوع UInt128، لكنها تُرجع 0 في حال حدوث خطأ.

الوسيطات المدعومة:

• التمثيلات النصية لقيم (U)Int*.

الوسيطات غير المدعومة (تُرجع 0):

• التمثيلات النصية لقيم Float*، بما في ذلك NaN وInf.
• التمثيلات النصية للقيم الثنائية والسداسية العشرية، على سبيل المثال SELECT toUInt128OrZero('0xc0fe');.

إذا تعذّر تمثيل قيمة الإدخال ضمن حدود UInt128، يحدث تجاوز سعة أو نقص سعة في النتيجة. ولا يُعدّ ذلك خطأً.

انظر أيضًا:

• toUInt128.
• toUInt128OrNull.
• toUInt128OrDefault.

البنية

toUInt128OrZero(x)

الوسيطات

• x — تمثيل نصي لرقم. String

القيمة المُعادة

يعيد قيمة من النوع UInt128، أو 0 إذا فشلت عملية التحويل. UInt128

أمثلة

مثال على الاستخدام

Query

SELECT
    toUInt128OrZero('128'),
    toUInt128OrZero('abc')
FORMAT Vertical

Response

Row 1:
──────
toUInt128OrZero('128'): 128
toUInt128OrZero('abc'): 0

​

toUInt16

استُحدثت في: v1.1.0

تُحوِّل قيمة إدخال إلى قيمة من النوع UInt16. تُطلق استثناءً في حال حدوث خطأ.

الوسيطات المدعومة:

• القيم أو التمثيلات النصية من النوع (U)Int*.
• القيم من النوع Float*.

الوسيطات غير المدعومة:

• التمثيلات النصية لقيم Float*، بما في ذلك NaN وInf.
• التمثيلات النصية للقيم الثنائية والست عشرية، مثل: SELECT toUInt16('0xc0fe');.

إذا تعذّر تمثيل قيمة الإدخال ضمن حدود UInt16، يحدث تجاوز أو نقص في النتيجة. ولا يُعدّ ذلك خطأً. على سبيل المثال: SELECT toUInt16(65536) == 0;.

تستخدم الدالة التقريب باتجاه الصفر، ما يعني أنها تقطع الخانات الكسرية من الأعداد.

انظر أيضًا:

• toUInt16OrZero.
• toUInt16OrNull.
• toUInt16OrDefault.

الصياغة

toUInt16(expr)

الوسائط

• expr — تعبير يُرجع عددًا أو تمثيلًا نصيًا لعدد. تعبير

القيمة المعادة

تُرجع قيمة عدد صحيح غير موقّع من 16 بت. UInt16

أمثلة

مثال على الاستخدام

Query

SELECT
    toUInt16(16),
    toUInt16(16.16),
    toUInt16('16')
FORMAT Vertical

Response

Row 1:
──────
toUInt16(16):    16
toUInt16(16.16): 16
toUInt16('16'):  16

​

toUInt16OrDefault

تم تقديمه في: v21.11.0

على غرار toUInt16، تحوّل هذه الدالة قيمة الإدخال إلى قيمة من النوع UInt16، لكنها تُرجِع القيمة الافتراضية في حال حدوث خطأ. إذا لم يتم تمرير قيمة default، فستُرجَع القيمة 0 عند حدوث خطأ.

الصياغة

toUInt16OrDefault(expr[, default])

الوسيطات

• expr — تعبير يُرجع رقمًا أو تمثيلًا نصيًا لرقم. String أو (U)Int* أو Float*
• default — اختياري. القيمة الافتراضية التي تُعاد إذا تعذّر التحليل. UInt16

القيمة المعادة

يُرجع قيمة من النوع UInt16 عند النجاح، وإلا يُرجع القيمة الافتراضية إذا تم تمريرها، أو 0 إذا لم يتم تمريرها. UInt16

أمثلة

تحويل ناجح

Query

SELECT toUInt16OrDefault('16', CAST('0', 'UInt16'))

Response

16

فشل التحويل

Query

SELECT toUInt16OrDefault('abc', CAST('0', 'UInt16'))

Response

0

​

toUInt16OrNull

أُضيفت في: v1.1.0

مثل toUInt16، تحوّل هذه الدالة قيمة مُدخلة إلى قيمة من النوع UInt16، لكنها تُرجع NULL عند حدوث خطأ.

الوسائط المدعومة:

• تمثيلات نصية لقيم (U)Int8/16/32/128/256.

الوسائط غير المدعومة (تُرجع NULL):

• تمثيلات نصية لقيم Float*، بما في ذلك NaN وInf.
• تمثيلات نصية للقيم الثنائية والسداسية العشرية، مثل SELECT toUInt16OrNull('0xc0fe');.

إذا تعذّر تمثيل قيمة الإدخال ضمن حدود UInt16، يحدث overflow أو underflow في النتيجة. لا يُعدّ ذلك خطأ.

انظر أيضًا:

• toUInt16.
• toUInt16OrZero.
• toUInt16OrDefault.

البنية

toUInt16OrNull(x)

الوسيطات

• x — تمثيل نصي لرقم. String

القيمة المعادة

يعيد قيمة من النوع UInt16، أو NULL إذا تعذّر التحويل. UInt16 أو NULL

أمثلة

مثال على الاستخدام

Query

SELECT
    toUInt16OrNull('16'),
    toUInt16OrNull('abc')
FORMAT Vertical

Response

Row 1:
──────
toUInt16OrNull('16'):  16
toUInt16OrNull('abc'): ᴺᵁᴸᴸ

​

toUInt16OrZero

قُدِّمت في: v1.1.0

على غرار toUInt16، تحوِّل هذه الدالة قيمة الإدخال إلى قيمة من النوع UInt16، لكنها تُرجع 0 في حال حدوث خطأ.

الوسيطات المدعومة:

• التمثيلات النصية لقيم (U)Int8/16/32/128/256.

الوسيطات غير المدعومة (تُرجع 0):

• التمثيلات النصية لقيم Float*، بما في ذلك NaN وInf.
• التمثيلات النصية للقيم الثنائية والسداسية العشرية، على سبيل المثال SELECT toUInt16OrZero('0xc0fe');.

إذا تعذّر تمثيل قيمة الإدخال ضمن حدود UInt16، يحدث تجاوز سعة أو نقص سعة في النتيجة. ولا يُعدّ ذلك خطأ.

انظر أيضًا:

• toUInt16.
• toUInt16OrNull.
• toUInt16OrDefault.

الصيغة

toUInt16OrZero(x)

الوسائط

• x — تمثيل سلسلة نصية لرقم. String

القيمة المُعادة

يعيد قيمة من النوع UInt16، أو 0 إذا تعذّر التحويل. UInt16

أمثلة

مثال على الاستخدام

Query

SELECT
    toUInt16OrZero('16'),
    toUInt16OrZero('abc')
FORMAT Vertical

Response

Row 1:
──────
toUInt16OrZero('16'):  16
toUInt16OrZero('abc'): 0

​

toUInt256

تم تقديمها في: v1.1.0

تحوّل قيمة الإدخال إلى قيمة من النوع UInt256. تطرح استثناءً في حال حدوث خطأ. تستخدم الدالة التقريب نحو الصفر، أي إنها تحذف الخانات الكسرية من الأعداد.

الوسيطات المدعومة:

• القيم أو تمثيلاتها النصية من النوع (U)Int*.
• القيم من النوع Float*.

الوسيطات غير المدعومة:

• التمثيلات النصية لقيم Float*، بما في ذلك NaN وInf.
• التمثيلات النصية للقيم الثنائية والست عشرية، مثل SELECT toUInt256('0xc0fe');.

إذا تعذر تمثيل قيمة الإدخال ضمن حدود UInt256، فقد يحدث تجاوز أو نقص في السعة في النتيجة. ولا يُعدّ ذلك خطأً.

راجع أيضًا:

• toUInt256OrZero.
• toUInt256OrNull.
• toUInt256OrDefault.

البنية

toUInt256(expr)

الوسائط

• expr — تعبير يُرجِع رقمًا أو تمثيلًا نصيًا لرقم. تعبير

القيمة المُعادة

يُرجِع قيمة عدد صحيح غير موقَّع بطول 256 بت. UInt256

أمثلة

مثال على الاستخدام

Query

SELECT
    toUInt256(256),
    toUInt256(256.256),
    toUInt256('256')
FORMAT Vertical

Response

Row 1:
──────
toUInt256(256):     256
toUInt256(256.256): 256
toUInt256('256'):   256

​

toUInt256OrDefault

أُضيف في: v21.11.0

على غرار toUInt256، تحوّل هذه الدالة قيمة الإدخال إلى قيمة من النوع UInt256، لكنها تُرجع القيمة الافتراضية عند حدوث خطأ. إذا لم يتم تمرير قيمة default، فستُرجع 0 عند حدوث خطأ.

الصياغة

toUInt256OrDefault(expr[, default])

الوسيطات

• expr — تعبير يُرجع رقمًا أو تمثيلًا نصيًا لرقم. String أو (U)Int* أو Float*
• default — اختياري. القيمة الافتراضية التي ستُعاد إذا تعذّر التحليل. UInt256

القيمة المعادة

يُرجع قيمة من النوع UInt256 عند النجاح، وإلا فيُرجع القيمة الافتراضية إذا تم تمريرها، أو 0 إذا لم يتم تمريرها. UInt256

أمثلة

تحويل ناجح

Query

SELECT toUInt256OrDefault('-256', CAST('0', 'UInt256'))

Response

0

فشل التحويل

Query

SELECT toUInt256OrDefault('abc', CAST('0', 'UInt256'))

Response

0

​

toUInt256OrNull

أُضيف في: v20.8.0

مثل toUInt256، تحوّل هذه الدالة قيمة الإدخال إلى قيمة من النوع UInt256، لكنها تُرجع NULL في حال حدوث خطأ.

الوسيطات المدعومة:

• التمثيلات النصية لقيم (U)Int*.

الوسيطات غير المدعومة (تُرجع NULL):

• التمثيلات النصية لقيم Float*، بما في ذلك NaN وInf.
• التمثيلات النصية للقيم الثنائية والست عشرية، على سبيل المثال SELECT toUInt256OrNull('0xc0fe');.

إذا تعذّر تمثيل قيمة الإدخال ضمن حدود UInt256، يحدث فيض أو نقص في النتيجة. ولا يُعدّ ذلك خطأ.

انظر أيضًا:

• toUInt256.
• toUInt256OrZero.
• toUInt256OrDefault.

الصياغة

toUInt256OrNull(x)

المعاملات

• x — تمثيل نصي لرقم. String

القيمة المُعادة

ترجع قيمة من النوع UInt256، أو NULL إذا تعذر التحويل. UInt256 أو NULL

أمثلة

مثال على الاستخدام

Query

SELECT
    toUInt256OrNull('256'),
    toUInt256OrNull('abc')
FORMAT Vertical

Response

Row 1:
──────
toUInt256OrNull('256'): 256
toUInt256OrNull('abc'): ᴺᵁᴸᴸ

​

toUInt256OrZero

أُضيف في: v20.8.0

مثل toUInt256، تحوّل هذه الدالة قيمة الإدخال إلى قيمة من النوع UInt256، لكنها تُرجع 0 عند حدوث خطأ.

الوسائط المدعومة:

• التمثيلات النصية لقيم (U)Int*.

الوسائط غير المدعومة (تُرجع 0):

• التمثيلات النصية لقيم Float*، بما في ذلك NaN وInf.
• التمثيلات النصية للقيم الثنائية والسداسية العشرية، مثل SELECT toUInt256OrZero('0xc0fe');.

إذا تعذّر تمثيل قيمة الإدخال ضمن حدود UInt256، يحدث تجاوز أو نقص في النتيجة. ولا يُعدّ ذلك خطأً.

انظر أيضًا:

• toUInt256.
• toUInt256OrNull.
• toUInt256OrDefault.

البنية

toUInt256OrZero(x)

الوسيطات

• x — تمثيل نصي لعدد. String

القيمة المعادة

يعيد قيمة من النوع UInt256، أو 0 إذا تعذّر التحويل. UInt256

أمثلة

مثال على الاستخدام

Query

SELECT
    toUInt256OrZero('256'),
    toUInt256OrZero('abc')
FORMAT Vertical

Response

Row 1:
──────
toUInt256OrZero('256'): 256
toUInt256OrZero('abc'): 0

​

toUInt32

أُضيف في: v1.1.0

يحوّل قيمة الإدخال إلى قيمة من النوع UInt32. يطرح استثناءً عند حدوث خطأ.

الوسيطات المدعومة:

• القيم أو التمثيلات النصية من النوع (U)Int*.
• القيم من النوع Float*.

الوسيطات غير المدعومة:

• التمثيلات النصية لقيم Float*، بما في ذلك NaN وInf.
• التمثيلات النصية للقيم الثنائية والسداسية العشرية، مثل SELECT toUInt32('0xc0fe');.

إذا تعذّر تمثيل قيمة الإدخال ضمن حدود UInt32، فستحدث زيادة أو نقصان خارج النطاق في النتيجة. ولا يُعدّ ذلك خطأً. على سبيل المثال: SELECT toUInt32(4294967296) == 0;

تستخدم الدالة التقريب نحو الصفر، ما يعني أنها تحذف الخانات الكسرية من الأعداد.

انظر أيضًا:

• toUInt32OrZero.
• toUInt32OrNull.
• toUInt32OrDefault.

البنية

toUInt32(expr)

الوسائط

• expr — تعبير يُرجع رقمًا أو تمثيلًا نصيًا لرقم. تعبير

القيمة المُعادة

تُرجع قيمة عدد صحيح غير موقّع بعرض 32 بت. UInt32

أمثلة

مثال على الاستخدام

Query

SELECT
    toUInt32(32),
    toUInt32(32.32),
    toUInt32('32')
FORMAT Vertical

Response

Row 1:
──────
toUInt32(32):    32
toUInt32(32.32): 32
toUInt32('32'):  32

​

toUInt32OrDefault

أُضيف في: v21.11.0

مثل toUInt32، تحوّل هذه الدالة قيمة الإدخال إلى قيمة من النوع UInt32، لكنها تُعيد القيمة الافتراضية عند حدوث خطأ. إذا لم تُمرَّر قيمة default، فستُعاد القيمة 0 عند حدوث خطأ.

الصيغة

toUInt32OrDefault(expr[, default])

المعاملات

• expr — تعبير يُرجع رقمًا أو تمثيلًا نصيًا لرقم. String أو (U)Int* أو Float*
• default — اختياري. القيمة الافتراضية التي تُرجع إذا تعذّر التحليل. UInt32

القيمة المُعادة

تُرجع قيمة من النوع UInt32 عند النجاح، وإلا فتُرجع القيمة الافتراضية إذا تم تمريرها، أو 0 إذا لم يتم ذلك. UInt32

أمثلة

تحويل ناجح

Query

SELECT toUInt32OrDefault('32', CAST('0', 'UInt32'))

Response

32

تعذّر التحويل

Query

SELECT toUInt32OrDefault('abc', CAST('0', 'UInt32'))

Response

0

​

toUInt32OrNull

أُضيف في: v1.1.0

على غرار toUInt32، تحوّل هذه الدالة قيمة الإدخال إلى قيمة من النوع UInt32، لكنها تُرجع NULL في حال حدوث خطأ.

الوسيطات المدعومة:

• التمثيلات النصية لقيم (U)Int8/16/32/128/256.

الوسيطات غير المدعومة (تُرجع NULL):

• التمثيلات النصية لقيم Float*، بما في ذلك NaN وInf.
• التمثيلات النصية للقيم الثنائية والسداسية العشرية، مثل SELECT toUInt32OrNull('0xc0fe');.

إذا تعذّر تمثيل قيمة الإدخال ضمن حدود UInt32، يحدث تجاوز سعة أو نقص سعة في النتيجة. ولا يُعدّ ذلك خطأ.

انظر أيضًا:

• toUInt32.
• toUInt32OrZero.
• toUInt32OrDefault.

البنية

toUInt32OrNull(x)

المعاملات

• x — تمثيل نصي لعدد. String

القيمة المُعادة

تُرجِع قيمة من النوع UInt32، أو NULL إذا أخفقت عملية التحويل. UInt32 أو NULL

أمثلة

مثال على الاستخدام

Query

SELECT
    toUInt32OrNull('32'),
    toUInt32OrNull('abc')
FORMAT Vertical

Response

Row 1:
──────
toUInt32OrNull('32'):  32
toUInt32OrNull('abc'): ᴺᵁᴸᴸ

​

toUInt32OrZero

قُدِّم في: v1.1.0

مثل toUInt32، تحوّل هذه الدالة قيمة إدخال إلى قيمة من النوع UInt32، لكنها تُرجع 0 عند حدوث خطأ.

الوسيطات المدعومة:

• التمثيلات النصية لقيم (U)Int8/16/32/128/256.

الوسيطات غير المدعومة (تُرجع 0):

• التمثيلات النصية لقيم Float*، بما في ذلك NaN وInf.
• التمثيلات النصية للقيم الثنائية والستّ عشرية، مثل SELECT toUInt32OrZero('0xc0fe');.

إذا تعذّر تمثيل قيمة الإدخال ضمن حدود UInt32، يحدث تجاوز للحد الأعلى أو الأدنى في النتيجة. ولا يُعدّ ذلك خطأً.

راجع أيضًا:

• toUInt32.
• toUInt32OrNull.
• toUInt32OrDefault.

الصياغة

toUInt32OrZero(x)

المعاملات

• x — تمثيل نصي لعدد. String

القيمة المُعادة

تُرجِع قيمة من النوع UInt32، وإلا فتُرجِع 0 إذا تعذّر التحويل. UInt32

أمثلة

مثال على الاستخدام

Query

SELECT
    toUInt32OrZero('32'),
    toUInt32OrZero('abc')
FORMAT Vertical

Response

Row 1:
──────
toUInt32OrZero('32'):  32
toUInt32OrZero('abc'): 0

​

toUInt64

أُضيف في: v1.1.0

يحوّل قيمة الإدخال إلى قيمة من النوع UInt64. يطرح استثناءً عند حدوث خطأ.

الوسيطات المدعومة:

• القيم أو التمثيلات النصية من النوع (U)Int*.
• القيم من النوع Float*.

الأنواع غير المدعومة:

• التمثيلات النصية لقيم Float*، بما في ذلك NaN وInf.
• التمثيلات النصية للقيم الثنائية والستّ عشرية، مثل SELECT toUInt64('0xc0fe');.

إذا تعذّر تمثيل قيمة الإدخال ضمن حدود UInt64، فستحدث في النتيجة حالة تجاوز علوي أو سفلي. ولا يُعدّ ذلك خطأً. على سبيل المثال: SELECT toUInt64(18446744073709551616) == 0;

تستخدم الدالة التقريب نحو الصفر، ما يعني أنها تحذف الخانات الكسرية من الأعداد.

انظر أيضًا:

• toUInt64OrZero.
• toUInt64OrNull.
• toUInt64OrDefault.

الصياغة

toUInt64(expr)

الوسائط

• expr — تعبير يُرجع عددًا أو تمثيلًا نصيًا لعدد. تعبير

القيمة المُعادة

يُرجع قيمة عدد صحيح غير موقّع بطول 64 بت. UInt64

أمثلة

مثال على الاستخدام

Query

SELECT
    toUInt64(64),
    toUInt64(64.64),
    toUInt64('64')
FORMAT Vertical

Response

Row 1:
──────
toUInt64(64):    64
toUInt64(64.64): 64
toUInt64('64'):  64

​

toUInt64OrDefault

قُدِّمت في: v21.11.0

مثل toUInt64، تحوّل هذه الدالة قيمة الإدخال إلى قيمة من النوع UInt64، لكنها تُرجع القيمة الافتراضية في حال حدوث خطأ. إذا لم يتم تمرير قيمة default، فستُرجع 0 عند حدوث خطأ.

الصيغة

toUInt64OrDefault(expr[, default])

الوسيطات

• expr — تعبير يُرجع عددًا أو تمثيلًا نصيًا لعدد. String أو (U)Int* أو Float*
• default — اختياري. القيمة الافتراضية التي تُعاد إذا تعذّر التحليل. UInt64

القيمة المُعادة

تُرجع قيمة من النوع UInt64 عند النجاح، وإلا فتُرجع القيمة الافتراضية إذا تم تمريرها، أو 0 إذا لم يتم ذلك. UInt64

أمثلة

تحويل ناجح

Query

SELECT toUInt64OrDefault('64', CAST('0', 'UInt64'))

Response

64

تعذّر التحويل

Query

SELECT toUInt64OrDefault('abc', CAST('0', 'UInt64'))

Response

0

​

toUInt64OrNull

تم تقديمه في: v1.1.0

على غرار toUInt64، تحوّل هذه الدالة قيمة الإدخال إلى قيمة من النوع UInt64، ولكنها تُرجع NULL في حال حدوث خطأ.

الوسيطات المدعومة:

• التمثيلات النصية لقيم (U)Int*.

الوسيطات غير المدعومة (تُرجع NULL):

• التمثيلات النصية لقيم Float*، بما في ذلك NaN وInf.
• التمثيلات النصية للقيم الثنائية والسداسية العشرية، على سبيل المثال SELECT toUInt64OrNull('0xc0fe');.

إذا تعذّر تمثيل قيمة الإدخال ضمن حدود UInt64، يحدث overflow أو underflow في النتيجة. ولا يُعدّ ذلك خطأً.

انظر أيضًا:

• toUInt64.
• toUInt64OrZero.
• toUInt64OrDefault.

الصياغة

toUInt64OrNull(x)

المعاملات

• x — تمثيل نصي لرقم. String

القيمة المُعادة

تُرجِع قيمة من النوع UInt64، أو NULL إذا تعذّر التحويل. UInt64 أو NULL

أمثلة

مثال على الاستخدام

Query

SELECT
    toUInt64OrNull('64'),
    toUInt64OrNull('abc')
FORMAT Vertical

Response

Row 1:
──────
toUInt64OrNull('64'):  64
toUInt64OrNull('abc'): ᴺᵁᴸᴸ

​

toUInt64OrZero

أُضيفت في: v1.1.0

على غرار toUInt64، تحوّل هذه الدالة قيمة الإدخال إلى قيمة من النوع UInt64، لكنها تُرجع 0 في حال حدوث خطأ.

الوسيطات المدعومة:

• التمثيلات النصية لقيم (U)Int*.

الوسيطات غير المدعومة (تُرجع 0):

• التمثيلات النصية لقيم Float*، بما في ذلك NaN وInf.
• التمثيلات النصية للقيم الثنائية والستّ عشرية، مثل SELECT toUInt64OrZero('0xc0fe');.

إذا تعذّر تمثيل قيمة الإدخال ضمن حدود UInt64، يحدث overflow أو underflow في النتيجة. ولا يُعدّ ذلك خطأ.

انظر أيضًا:

• toUInt64.
• toUInt64OrNull.
• toUInt64OrDefault.

البنية

toUInt64OrZero(x)

الوسائط

• x — تمثيل نصي لعدد. String

القيمة المُعادة

تُعيد قيمة من النوع UInt64، وإلا فتُعيد 0 إذا فشل التحويل. UInt64

أمثلة

مثال على الاستخدام

Query

SELECT
    toUInt64OrZero('64'),
    toUInt64OrZero('abc')
FORMAT Vertical

Response

Row 1:
──────
toUInt64OrZero('64'):  64
toUInt64OrZero('abc'): 0

​

toUInt8

تم تقديمه في: v1.1.0

يحوّل قيمة الإدخال إلى قيمة من النوع UInt8. يطرح استثناءً في حال حدوث خطأ.

الوسيطات المدعومة:

• القيم أو التمثيلات النصية من النوع (U)Int*.
• القيم من النوع Float*.

الوسيطات غير المدعومة:

• التمثيلات النصية لقيم Float*، بما في ذلك NaN وInf.
• التمثيلات النصية للقيم الثنائية والسداسية العشرية، مثل SELECT toUInt8('0xc0fe');.

إذا تعذّر تمثيل قيمة الإدخال ضمن حدود UInt8، يحدث فائض أو نقص في النتيجة. لا يُعدّ ذلك خطأً. على سبيل المثال: SELECT toUInt8(256) == 0;.

تستخدم الدالة التقريب نحو الصفر، ما يعني أنها تحذف الخانات الكسرية من الأعداد.

انظر أيضًا:

• toUInt8OrZero.
• toUInt8OrNull.
• toUInt8OrDefault.

الصياغة

toUInt8(expr)

الوسائط

• expr — تعبير يُرجع رقمًا أو تمثيلًا نصيًا لرقم. تعبير

القيمة المُعادة

يُرجع قيمة من نوع عدد صحيح غير موقّع من 8 بتات. UInt8

أمثلة

مثال على الاستخدام

Query

SELECT
    toUInt8(8),
    toUInt8(8.8),
    toUInt8('8')
FORMAT Vertical

Response

Row 1:
──────
toUInt8(8):   8
toUInt8(8.8): 8
toUInt8('8'): 8

​

toUInt8OrDefault

قُدِّمت في: v21.11.0

على غرار toUInt8، تحوّل هذه الدالة قيمة الإدخال إلى قيمة من النوع UInt8، لكنها تُرجِع القيمة الافتراضية عند حدوث خطأ. إذا لم تُمرَّر قيمة default، فستُرجِع 0 عند حدوث خطأ.

الصياغة

toUInt8OrDefault(expr[, default])

الوسائط

• expr — تعبير يُرجِع رقمًا أو تمثيلًا نصيًا لرقم. String أو (U)Int* أو Float*
• default — اختياري. القيمة الافتراضية التي تُعاد إذا فشلت عملية التحليل. UInt8

القيمة المُعادة

يُرجِع قيمة من النوع UInt8 عند النجاح، وإلا يُرجِع القيمة الافتراضية إذا تم تمريرها، أو 0 إذا لم يتم ذلك. UInt8

أمثلة

تحويل ناجح

Query

SELECT toUInt8OrDefault('8', CAST('0', 'UInt8'))

Response

8

تعذّر التحويل

Query

SELECT toUInt8OrDefault('abc', CAST('0', 'UInt8'))

Response

0

​

toUInt8OrNull

تم تقديمها في: v1.1.0

مثل toUInt8، تحوِّل هذه الدالة قيمة الإدخال إلى قيمة من النوع UInt8، ولكنها تُرجِع NULL في حال حدوث خطأ.

الوسيطات المدعومة:

• التمثيلات النصية لـ (U)Int8/16/32/128/256.

الوسيطات غير المدعومة (تُرجِع NULL):

• التمثيلات النصية لقيم Float* العادية، بما في ذلك NaN وInf.
• التمثيلات النصية للقيم الثنائية والسداسية العشرية، على سبيل المثال SELECT toUInt8OrNull('0xc0fe');.

إذا تعذّر تمثيل قيمة الإدخال ضمن حدود UInt8، فستحدث حالة تجاوز أو نقص في النتيجة. ولا يُعَدّ ذلك خطأً.

انظر أيضًا:

• toUInt8.
• toUInt8OrZero.
• toUInt8OrDefault.

الصياغة

toUInt8OrNull(x)

الوسيطات

• x — تمثيل نصي لرقم. String

القيمة المعادة

يعيد قيمة من النوع UInt8، وإلا فيُرجع NULL إذا أخفق التحويل. UInt8 أو NULL

أمثلة

مثال على الاستخدام

Query

SELECT
    toUInt8OrNull('42'),
    toUInt8OrNull('abc')
FORMAT Vertical

Response

Row 1:
──────
toUInt8OrNull('42'):  42
toUInt8OrNull('abc'): ᴺᵁᴸᴸ

​

toUInt8OrZero

تم تقديمها في: v1.1.0

مثل toUInt8، تحوّل هذه الدالة قيمة الإدخال إلى قيمة من النوع UInt8، ولكنها تُرجع 0 عند حدوث خطأ.

الوسيطات المدعومة:

• التمثيلات النصية لقيم (U)Int8/16/32/128/256.

الوسيطات غير المدعومة (تُرجع 0):

• التمثيلات النصية لقيم Float* العادية، بما في ذلك NaN وInf.
• التمثيلات النصية للقيم الثنائية والسداسية العشرية، على سبيل المثال SELECT toUInt8OrZero('0xc0fe');.

إذا تعذّر تمثيل قيمة الإدخال ضمن حدود UInt8، يحدث overflow أو underflow في النتيجة. ولا يُعدّ ذلك خطأً.

انظر أيضًا:

• toUInt8.
• toUInt8OrNull.
• toUInt8OrDefault.

البنية

toUInt8OrZero(x)

الوسائط

• x — تمثيل نصي لعدد. String

القيمة المُعادة

تعيد قيمة من النوع UInt8، أو 0 إذا تعذر التحويل. UInt8

أمثلة

مثال على الاستخدام

Query

SELECT
    toUInt8OrZero('-8'),
    toUInt8OrZero('abc')
FORMAT Vertical

Response

Row 1:
──────
toUInt8OrZero('-8'):  0
toUInt8OrZero('abc'): 0

​

toUUID

أُضيف في الإصدار: v1.1.0

يحوّل قيمة من النوع String إلى قيمة من النوع UUID.

الصيغة

toUUID(string)

الوسيطات

• string — قيمة UUID على هيئة سلسلة نصية. String أو FixedString

القيمة المعادة

تعيد قيمة UUID من التمثيل النصي لـ UUID. UUID

أمثلة

مثال على الاستخدام

Query

SELECT toUUID('61f0c404-5cb3-11e7-907b-a6006ad3dba0') AS uuid

Response

┌─uuid─────────────────────────────────┐
│ 61f0c404-5cb3-11e7-907b-a6006ad3dba0 │
└──────────────────────────────────────┘

​

toUUIDOrZero

أُضيف في: v20.12.0

يحوّل قيمة إدخال إلى قيمة من النوع UUID، لكنه يعيد UUID صفريًا في حال حدوث خطأ. وهو مشابه لـ toUUID، لكنه يعيد UUID صفريًا (00000000-0000-0000-0000-000000000000) بدلًا من طرح استثناء عند حدوث أخطاء في التحويل.

الوسيطات المدعومة:

• التمثيلات النصية لـ UUID بالتنسيق القياسي (8-4-4-4-12 رقمًا سداسيًا عشريًا).
• التمثيلات النصية لـ UUID من دون واصلات (32 رقمًا سداسيًا عشريًا).

الوسيطات غير المدعومة (تعيد UUID صفريًا):

• تنسيقات نصية غير صالحة.
• أنواع غير نصية.

الصياغة

toUUIDOrZero(x)

الوسائط

• x — تمثيل نصي لـ UUID. String

القيمة المُعادة

يعيد قيمة UUID عند النجاح، وإلا فيُعيد UUID صفريًا (00000000-0000-0000-0000-000000000000). UUID

أمثلة

مثال على الاستخدام

Query

SELECT
    toUUIDOrZero('550e8400-e29b-41d4-a716-446655440000') AS valid_uuid,
    toUUIDOrZero('invalid-uuid') AS invalid_uuid

Response

┌─valid_uuid───────────────────────────┬─invalid_uuid─────────────────────────┐
│ 550e8400-e29b-41d4-a716-446655440000 │ 00000000-0000-0000-0000-000000000000 │
└──────────────────────────────────────┴──────────────────────────────────────┘

​

toUnixTimestamp64Micro

استُحدث في: v20.5.0

يحوّل DateTime64 إلى قيمة من النوع Int64 بدقة ميكروثانية ثابتة. تُضبط قيمة الإدخال بالزيادة أو النقصان بحسب دقتها.

قيمة الإخراج مرتبطة بـ UTC، وليس بالمنطقة الزمنية لقيمة الإدخال.

الصياغة

toUnixTimestamp64Micro(value)

المعاملات

• value — قيمة من النوع DateTime64 بأي درجة دقة. DateTime64

القيمة المُعادة

يعيد طابعًا زمنيًا بتنسيق Unix بالميكروثانية. Int64

أمثلة

مثال على الاستخدام

Query

WITH toDateTime64('2025-02-13 23:31:31.011123', 6, 'UTC') AS dt64
SELECT toUnixTimestamp64Micro(dt64);

Response

┌─toUnixTimestamp64Micro(dt64)─┐
│             1739489491011123 │
└──────────────────────────────┘

​

toUnixTimestamp64Milli

أُضيف في: v20.5.0

يحوّل DateTime64 إلى قيمة Int64 بدقة ميلي ثانية ثابتة. وتُزاد قيمة الإدخال أو تُخفض بالشكل المناسب وفقًا لدقتها.

تستند قيمة الإخراج إلى UTC، وليس إلى المنطقة الزمنية لقيمة الإدخال.

الصيغة

toUnixTimestamp64Milli(value)

الوسائط

• value — قيمة من نوع DateTime64 بأي درجة دقة. DateTime64

القيمة المُعادة

تُرجِع طابعًا زمنيًا بتنسيق Unix بالمللي ثانية. Int64

أمثلة

مثال على الاستخدام

Query

WITH toDateTime64('2025-02-13 23:31:31.011', 3, 'UTC') AS dt64
SELECT toUnixTimestamp64Milli(dt64);

Response

┌─toUnixTimestamp64Milli(dt64)─┐
│                1739489491011 │
└──────────────────────────────┘

​

toUnixTimestamp64Nano

أُضيف في: v20.5.0

يحوّل DateTime64 إلى قيمة Int64 بدقة نانوثانية ثابتة. ويُزاد مقياس قيمة الإدخال أو يُخفَّض حسب دقتها.

تُحتسب قيمة الإخراج بالنسبة إلى UTC، وليس بالنسبة إلى المنطقة الزمنية لقيمة الإدخال.

الصياغة

toUnixTimestamp64Nano(value)

الوسائط

• value — قيمة من نوع DateTime64 بأي مستوى دقة. DateTime64

القيمة المُعادة

يعيد طابعًا زمنيًا بنظام Unix بوحدة النانوثانية. Int64

أمثلة

مثال على الاستخدام

Query

WITH toDateTime64('2025-02-13 23:31:31.011123456', 9, 'UTC') AS dt64
SELECT toUnixTimestamp64Nano(dt64);

Response

┌─toUnixTimestamp64Nano(dt64)─┐
│         1739489491011123456 │
└─────────────────────────────┘

​

toUnixTimestamp64Second

أُضيفت في: v24.12.0

يحوّل قيمة DateTime64 إلى قيمة Int64 بدقة ثابتة بالثواني. تُزاد قيمة الإدخال أو تُخفَّض بالشكل المناسب وفقًا لدقتها.

قيمة الخرج مرتبطة بـ UTC، وليست مرتبطة بالمنطقة الزمنية لقيمة الإدخال.

الصياغة

toUnixTimestamp64Second(value)

الوسائط

• value — قيمة من نوع DateTime64 بأي درجة precision. DateTime64

القيمة المعادة

تُرجِع طابعًا زمنيًا لـ Unix بالثواني. Int64

أمثلة

مثال استخدام

Query

WITH toDateTime64('2025-02-13 23:31:31.011', 3, 'UTC') AS dt64
SELECT toUnixTimestamp64Second(dt64);

Response

┌─toUnixTimestamp64Second(dt64)─┐
│                    1739489491 │
└───────────────────────────────┘