> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-fbfa8bee.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
> توثيق دوال التعامل مع التواريخ والأوقات
# دوال التعامل مع التواريخ والأوقات
تقبل معظم الدوال في هذا القسم وسيطة اختيارية للمنطقة الزمنية، مثل `Europe/Amsterdam`. وفي هذه الحالة، تكون المنطقة الزمنية المستخدمة هي المنطقة المحددة بدلًا من المنطقة الزمنية المحلية (الافتراضية).
**مثال**
```sql theme={null}
SELECT
toDateTime('2016-06-15 23:00:00') AS time,
toDate(time) AS date_local,
toDate(time, 'Asia/Yekaterinburg') AS date_yekat,
toString(time, 'US/Samoa') AS time_samoa
```
```text theme={null}
┌────────────────time─┬─date_local─┬─date_yekat─┬─time_samoa──────────┐
│ 2016-06-15 23:00:00 │ 2016-06-15 │ 2016-06-16 │ 2016-06-15 09:00:00 │
└─────────────────────┴────────────┴────────────┴─────────────────────┘
```
لتحقيق التوافق مع معيار SQL، يمكن استخدام الدوال التالية دون أقواس: `NOW` و`CURRENT_TIMESTAMP` و`LOCALTIME` و`LOCALTIMESTAMP` و`TODAY` و`CURRENT_DATE`.
{/*AUTOGENERATED_START*/}
## UTCTimestamp
أُضيف في: v22.11.0
يعيد التاريخ والوقت الحاليَّين في لحظة تحليل الاستعلام. وهذه الدالة عبارة عن تعبير ثابت.
تعطي هذه الدالة النتيجة نفسها التي تعطيها `now('UTC')`. وقد أُضيفت فقط لدعم MySQL. ويُعد [`now`](#now) الخيار المفضّل.
**الصياغة**
```sql theme={null}
UTCTimestamp()
```
**الأسماء المستعارة**: `UTC_timestamp`
**المعاملات**
* لا يوجد.
**القيمة المُعادة**
تعيد التاريخ والوقت الحاليين عند لحظة تحليل الاستعلام. [`DateTime`](/ar/reference/data-types/datetime)
**أمثلة**
**الحصول على الطابع الزمني الحالي بتوقيت UTC**
```sql title=Query theme={null}
SELECT UTCTimestamp()
```
```response title=Response theme={null}
┌──────UTCTimestamp()─┐
│ 2024-05-28 08:32:09 │
└─────────────────────┘
```
## YYYYMMDDToDate
أُضيف في: v23.9.0
يحوّل رقمًا يتضمن السنة والشهر واليوم إلى `Date`.
هذه الدالة هي عكس الدالة [`toYYYYMMDD()`](/ar/reference/functions/regular-functions/date-time-functions#toYYYYMMDD).
تكون النتيجة غير معرّفة إذا كان الإدخال لا يمثّل قيمة Date صالحة.
**البنية**
```sql theme={null}
YYYYMMDDToDate(YYYYMMDD)
```
**الوسائط**
* `YYYYMMDD` — رقم يتضمن السنة والشهر واليوم. [`(U)Int*`](/ar/reference/data-types/int-uint) أو [`Float*`](/ar/reference/data-types/float) أو [`Decimal`](/ar/reference/data-types/decimal)
**القيمة المُعادة**
يُرجع قيمة من نوع `Date` من الوسائط المقدَّمة [`Date`](/ar/reference/data-types/date)
**أمثلة**
**مثال**
```sql title=Query theme={null}
SELECT YYYYMMDDToDate(20230911);
```
```response title=Response theme={null}
┌─toYYYYMMDD(20230911)─┐
│ 2023-09-11 │
└──────────────────────┘
```
## YYYYMMDDToDate32
أُضيف في: v23.9.0
يحوِّل رقمًا يتضمن السنة والشهر واليوم إلى `Date32`.
هذه الدالة هي عكس الدالة [`toYYYYMMDD()`](/ar/reference/functions/regular-functions/date-time-functions#toYYYYMMDD).
يكون الناتج غير معرّف إذا لم يُشفِّر الإدخال قيمة `Date32` صالحة.
**الصيغة**
```sql theme={null}
YYYYMMDDToDate32(YYYYMMDD)
```
**الوسائط**
* `YYYYMMDD` — رقم يحتوي على السنة والشهر واليوم. [`(U)Int*`](/ar/reference/data-types/int-uint) أو [`Float*`](/ar/reference/data-types/float) أو [`Decimal`](/ar/reference/data-types/decimal)
**القيمة المُعادة**
تُرجِع قيمة `Date32` من الوسائط المُدخلة [`Date32`](/ar/reference/data-types/date32)
**أمثلة**
**مثال**
```sql title=Query theme={null}
SELECT YYYYMMDDToDate32(20000507);
```
```response title=Response theme={null}
┌─YYYYMMDDToDate32(20000507)─┐
│ 2000-05-07 │
└────────────────────────────┘
```
## YYYYMMDDhhmmssToDateTime
أُضيفت في: v23.9.0
تحوّل رقمًا يحتوي على السنة والشهر واليوم والساعة والدقيقة والثانية إلى `DateTime`.
هذه الدالة هي عكس الدالة [`toYYYYMMDDhhmmss()`](/ar/reference/functions/regular-functions/date-time-functions#toYYYYMMDDhhmmss).
يكون الناتج غير معرّف إذا كان الإدخال لا يمثّل قيمة `DateTime` صالحة.
**البنية**
```sql theme={null}
YYYYMMDDhhmmssToDateTime(YYYYMMDDhhmmss[, timezone])
```
**الوسائط**
* `YYYYMMDDhhmmss` — رقم يحتوي على السنة والشهر واليوم والساعة والدقيقة والثانية. [`(U)Int*`](/ar/reference/data-types/int-uint) أو [`Float*`](/ar/reference/data-types/float) أو [`Decimal`](/ar/reference/data-types/decimal)
* `timezone` — اسم المنطقة الزمنية. [`String`](/ar/reference/data-types/string)
**القيمة المعادة**
تُرجع قيمة `DateTime` من الوسائط المحددة [`DateTime`](/ar/reference/data-types/datetime)
**أمثلة**
**مثال**
```sql title=Query theme={null}
SELECT YYYYMMDDToDateTime(20230911131415);
```
```response title=Response theme={null}
┌──────YYYYMMDDhhmmssToDateTime(20230911131415)─┐
│ 2023-09-11 13:14:15 │
└───────────────────────────────────────────────┘
```
## YYYYMMDDhhmmssToDateTime64
أُضيفت في: v23.9.0
تحوّل رقمًا يحتوي على السنة والشهر واليوم والساعة والدقيقة والثانية إلى `DateTime64`.
هذه الدالة هي عكس الدالة [`toYYYYMMDDhhmmss()`](/ar/reference/functions/regular-functions/date-time-functions#toYYYYMMDDhhmmss).
يكون الناتج غير معرّف إذا كان الإدخال لا يرمّز قيمة `DateTime64` صالحة.
**الصيغة**
```sql theme={null}
YYYYMMDDhhmmssToDateTime64(YYYYMMDDhhmmss[, precision[, timezone]])
```
**المعاملات**
* `YYYYMMDDhhmmss` — رقم يحتوي على السنة والشهر واليوم والساعة والدقيقة والثانية. [`(U)Int*`](/ar/reference/data-types/int-uint) أو [`Float*`](/ar/reference/data-types/float) أو [`Decimal`](/ar/reference/data-types/decimal)
* `precision` — دقة الجزء الكسري (0-9). [`UInt8`](/ar/reference/data-types/int-uint)
* `timezone` — اسم المنطقة الزمنية. [`String`](/ar/reference/data-types/string)
**القيمة المُعادة**
تعيد قيمة `DateTime64` من المعاملات المحددة [`DateTime64`](/ar/reference/data-types/datetime64)
**أمثلة**
**مثال**
```sql title=Query theme={null}
SELECT YYYYMMDDhhmmssToDateTime64(20230911131415, 3, 'Asia/Istanbul');
```
```response title=Response theme={null}
┌─YYYYMMDDhhmm⋯/Istanbul')─┐
│ 2023-09-11 13:14:15.000 │
└──────────────────────────┘
```
## addDate
أُضيف في: v23.9.0
يضيف الفاصل الزمني إلى التاريخ المُقدَّم، أو التاريخ مع الوقت، أو التاريخ أو التاريخ مع الوقت المُمثَّل كسلسلة نصية.
إذا أسفرت الإضافة عن قيمة تقع خارج حدود نوع البيانات، فستكون النتيجة غير معرّفة.
**الصيغة**
```sql theme={null}
addDate(datetime, interval)
```
**المعاملات**
* `datetime` — التاريخ أو التاريخ مع الوقت الذي يُضاف إليه `interval`. [`Date`](/ar/reference/data-types/date) أو [`Date32`](/ar/reference/data-types/date32) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64) أو [`String`](/ar/reference/data-types/string)
* `interval` — الفترة الزمنية المراد إضافتها. [`Interval`](/ar/reference/data-types/int-uint)
**القيمة المُعادة**
تُعيد تاريخًا أو تاريخًا مع وقت ناتجًا عن إضافة `interval` إلى `datetime`. [`Date`](/ar/reference/data-types/date) أو [`Date32`](/ar/reference/data-types/date32) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
**أمثلة**
**إضافة فترة زمنية إلى تاريخ**
```sql title=Query theme={null}
SELECT addDate(toDate('2018-01-01'), INTERVAL 3 YEAR)
```
```response title=Response theme={null}
┌─addDate(toDa⋯valYear(3))─┐
│ 2021-01-01 │
└──────────────────────────┘
```
## addDays
أُضيفت في: v1.1.0
تضيف عددًا محددًا من الأيام إلى تاريخ، أو تاريخ ووقت، أو تاريخ مُرمَّز كسلسلة نصية، أو تاريخ ووقت مُرمَّز كسلسلة نصية.
**البنية**
```sql theme={null}
addDays(datetime, num)
```
**الوسائط**
* `datetime` — تاريخ أو تاريخ مع وقت يُراد إضافة العدد المحدد من الأيام إليه. [`Date`](/ar/reference/data-types/date) أو [`Date32`](/ar/reference/data-types/date32) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64) أو [`String`](/ar/reference/data-types/string)
* `num` — عدد الأيام المراد إضافتها. [`(U)Int*`](/ar/reference/data-types/int-uint) أو [`Float*`](/ar/reference/data-types/float)
**القيمة المُعادة**
يعيد `datetime` بعد إضافة `num` يومًا إليه. [`Date`](/ar/reference/data-types/date) أو [`Date32`](/ar/reference/data-types/date32) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
**أمثلة**
**إضافة أيام إلى أنواع تاريخ مختلفة**
```sql title=Query theme={null}
WITH
toDate('2024-01-01') AS date,
toDateTime('2024-01-01 00:00:00') AS date_time,
'2024-01-01 00:00:00' AS date_time_string
SELECT
addDays(date, 5) AS add_days_with_date,
addDays(date_time, 5) AS add_days_with_date_time,
addDays(date_time_string, 5) AS add_days_with_date_time_string
```
```response title=Response theme={null}
┌─add_days_with_date─┬─add_days_with_date_time─┬─add_days_with_date_time_string─┐
│ 2024-01-06 │ 2024-01-06 00:00:00 │ 2024-01-06 00:00:00.000 │
└────────────────────┴─────────────────────────┴────────────────────────────────┘
```
**استخدام صيغة INTERVAL البديلة**
```sql title=Query theme={null}
SELECT dateAdd('1998-06-16'::Date, INTERVAL 10 day)
```
```response title=Response theme={null}
┌─plus(CAST('1⋯valDay(10))─┐
│ 1998-06-26 │
└──────────────────────────┘
```
## addHours
أُضيف في: v1.1.0
يضيف عددًا محددًا من الساعات إلى تاريخ، أو تاريخ ووقت، أو تاريخ مُرمَّز كسلسلة نصية، أو تاريخ ووقت مُرمَّزَين كسلسلة نصية.
**الصيغة**
```sql theme={null}
addHours(datetime, num)
```
**الوسائط**
* `datetime` — تاريخ أو تاريخ مع وقت يُضاف إليه عدد الساعات المحدد. [`Date`](/ar/reference/data-types/date) أو [`Date32`](/ar/reference/data-types/date32) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64) أو [`String`](/ar/reference/data-types/string)
* `num` — عدد الساعات المراد إضافتها. [`(U)Int*`](/ar/reference/data-types/int-uint) أو [`Float*`](/ar/reference/data-types/float)
**القيمة المُعادة**
تعيد `datetime` بعد إضافة `num` ساعة إليه. [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64(3)`](/ar/reference/data-types/datetime64)
**أمثلة**
**إضافة ساعات إلى أنواع تاريخ مختلفة**
```sql title=Query theme={null}
WITH
toDate('2024-01-01') AS date,
toDateTime('2024-01-01 00:00:00') AS date_time,
'2024-01-01 00:00:00' AS date_time_string
SELECT
addHours(date, 12) AS add_hours_with_date,
addHours(date_time, 12) AS add_hours_with_date_time,
addHours(date_time_string, 12) AS add_hours_with_date_time_string
```
```response title=Response theme={null}
┌─add_hours_with_date─┬─add_hours_with_date_time─┬─add_hours_with_date_time_string─┐
│ 2024-01-01 12:00:00 │ 2024-01-01 12:00:00 │ 2024-01-01 12:00:00.000 │
└─────────────────────┴──────────────────────────┴─────────────────────────────────┘
```
**استخدام البنية البديلة لـ INTERVAL**
```sql title=Query theme={null}
SELECT dateAdd('1998-06-16'::Date, INTERVAL 10 hour)
```
```response title=Response theme={null}
┌─plus(CAST('1⋯alHour(10))─┐
│ 1998-06-16 10:00:00 │
└──────────────────────────┘
```
## addInterval
أُضيف في: v22.11.0
يضيف فترة زمنية إلى فترة زمنية أخرى أو إلى Tuple من الفترات الزمنية.
ستُدمج الفترات الزمنية من النوع نفسه في فترة زمنية واحدة. على سبيل المثال، إذا تم تمرير `toIntervalDay(1)` و `toIntervalDay(2)`، فستكون النتيجة `(3)` بدلًا من `(1,1)`.
**الصيغة**
```sql theme={null}
addInterval(interval_1, interval_2)
```
**الوسيطات**
* `interval_1` — قيمة Interval الأولى أو `Tuple` من قيم `Interval`. [`Interval`](/ar/reference/data-types/int-uint) أو [`Tuple(Interval)`](/ar/reference/data-types/tuple)
* `interval_2` — قيمة Interval الثانية المراد إضافتها. [`Interval`](/ar/reference/data-types/int-uint)
**القيمة المُعادة**
يُرجع `Tuple` من قيم `Interval` [`Tuple(Interval)`](/ar/reference/data-types/tuple)
**أمثلة**
**إضافة فواصل زمنية**
```sql title=Query theme={null}
SELECT addInterval(INTERVAL 1 DAY, INTERVAL 1 MONTH);
SELECT addInterval((INTERVAL 1 DAY, INTERVAL 1 YEAR), INTERVAL 1 MONTH);
SELECT addInterval(INTERVAL 2 DAY, INTERVAL 1 DAY)
```
```response title=Response theme={null}
┌─addInterval(toIntervalDay(1), toIntervalMonth(1))─┐
│ (1,1) │
└───────────────────────────────────────────────────┘
┌─addInterval((toIntervalDay(1), toIntervalYear(1)), toIntervalMonth(1))─┐
│ (1,1,1) │
└────────────────────────────────────────────────────────────────────────┘
┌─addInterval(toIntervalDay(2), toIntervalDay(1))─┐
│ (3) │
└─────────────────────────────────────────────────┘
```
## addMicroseconds
أُضيف في: v22.6.0
يضيف عددًا محددًا من الميكروثواني إلى تاريخ ووقت، أو إلى تاريخ ووقت مُرمَّز كسلسلة نصية.
**البنية**
```sql theme={null}
addMicroseconds(datetime, num)
```
**الوسائط**
* `datetime` — تاريخ ووقت يُضاف إليه العدد المحدد من الميكروثواني. [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64) أو [`String`](/ar/reference/data-types/string)
* `num` — عدد الميكروثواني المطلوب إضافته. [`(U)Int*`](/ar/reference/data-types/int-uint) أو [`Float*`](/ar/reference/data-types/float)
**القيمة المُعادة**
تُرجِع `date_time` بعد إضافة `num` من الميكروثواني [`DateTime64`](/ar/reference/data-types/datetime64)
**أمثلة**
**إضافة ميكروثوانٍ إلى أنواع مختلفة من التاريخ والوقت**
```sql title=Query theme={null}
WITH
toDateTime('2024-01-01 00:00:00') AS date_time,
'2024-01-01 00:00:00' AS date_time_string
SELECT
addMicroseconds(date_time, 1000000) AS add_microseconds_with_date_time,
addMicroseconds(date_time_string, 1000000) AS add_microseconds_with_date_time_string
```
```response title=Response theme={null}
┌─add_microseconds_with_date_time─┬─add_microseconds_with_date_time_string─┐
│ 2024-01-01 00:00:01.000000 │ 2024-01-01 00:00:01.000000 │
└─────────────────────────────────┴────────────────────────────────────────┘
```
**استخدام صيغة INTERVAL البديلة**
```sql title=Query theme={null}
SELECT dateAdd('1998-06-16'::DateTime, INTERVAL 10 microsecond)
```
```response title=Response theme={null}
┌─plus(CAST('19⋯osecond(10))─┐
│ 1998-06-16 00:00:00.000010 │
└────────────────────────────┘
```
## addMilliseconds
أُضيفت في: v22.6.0
تضيف عددًا محددًا من المللي ثانية إلى قيمة تاريخ ووقت أو إلى تاريخ ووقت مُرمَّزَين كسلسلة نصية.
**البنية**
```sql theme={null}
addMilliseconds(datetime, num)
```
**الوسائط**
* `datetime` — تاريخ ووقت يُضاف إليه العدد المحدد من المللي ثانية. [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64) أو [`String`](/ar/reference/data-types/string)
* `num` — عدد المللي ثانية المطلوب إضافته. [`(U)Int*`](/ar/reference/data-types/int-uint) أو [`Float*`](/ar/reference/data-types/float)
**القيمة المعادة**
تعيد `datetime` بعد إضافة `num` مللي ثانية إليه [`DateTime64`](/ar/reference/data-types/datetime64)
**أمثلة**
**إضافة مللي ثانية إلى أنواع مختلفة من التاريخ والوقت**
```sql title=Query theme={null}
WITH
toDateTime('2024-01-01 00:00:00') AS date_time,
'2024-01-01 00:00:00' AS date_time_string
SELECT
addMilliseconds(date_time, 1000) AS add_milliseconds_with_date_time,
addMilliseconds(date_time_string, 1000) AS add_milliseconds_with_date_time_string
```
```response title=Response theme={null}
┌─add_milliseconds_with_date_time─┬─add_milliseconds_with_date_time_string─┐
│ 2024-01-01 00:00:01.000 │ 2024-01-01 00:00:01.000 │
└─────────────────────────────────┴────────────────────────────────────────┘
```
**استخدام صيغة INTERVAL البديلة**
```sql title=Query theme={null}
SELECT dateAdd('1998-06-16'::DateTime, INTERVAL 10 millisecond)
```
```response title=Response theme={null}
┌─plus(CAST('1⋯second(10))─┐
│ 1998-06-16 00:00:00.010 │
└──────────────────────────┘
```
## addMinutes
أُضيف في: v1.1.0
يضيف عددًا محددًا من الدقائق إلى تاريخ، أو تاريخ ووقت، أو تاريخ مُرمَّز كسلسلة نصية، أو تاريخ ووقت مُرمَّز كسلسلة نصية.
**البنية**
```sql theme={null}
addMinutes(datetime, num)
```
**الوسيطات**
* `datetime` — تاريخ أو قيمة تاريخ/وقت يُضاف إليها العدد المحدد من الدقائق. [`Date`](/ar/reference/data-types/date) أو [`Date32`](/ar/reference/data-types/date32) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64) أو [`String`](/ar/reference/data-types/string)
* `num` — عدد الدقائق المراد إضافتها. [`(U)Int*`](/ar/reference/data-types/int-uint) أو [`Float*`](/ar/reference/data-types/float)
**القيمة المُعادة**
تعيد `datetime` بعد إضافة `num` دقيقةً إليه. [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64(3)`](/ar/reference/data-types/datetime64)
**أمثلة**
**إضافة دقائق إلى أنواع تاريخ مختلفة**
```sql title=Query theme={null}
WITH
toDate('2024-01-01') AS date,
toDateTime('2024-01-01 00:00:00') AS date_time,
'2024-01-01 00:00:00' AS date_time_string
SELECT
addMinutes(date, 20) AS add_minutes_with_date,
addMinutes(date_time, 20) AS add_minutes_with_date_time,
addMinutes(date_time_string, 20) AS add_minutes_with_date_time_string
```
```response title=Response theme={null}
┌─add_minutes_with_date─┬─add_minutes_with_date_time─┬─add_minutes_with_date_time_string─┐
│ 2024-01-01 00:20:00 │ 2024-01-01 00:20:00 │ 2024-01-01 00:20:00.000 │
└───────────────────────┴────────────────────────────┴───────────────────────────────────┘
```
**استخدام البنية البديلة لـ INTERVAL**
```sql title=Query theme={null}
SELECT dateAdd('1998-06-16'::Date, INTERVAL 10 minute)
```
```response title=Response theme={null}
┌─plus(CAST('1⋯Minute(10))─┐
│ 1998-06-16 00:10:00 │
└──────────────────────────┘
```
## addMonths
أُضيف في: v1.1.0
يضيف عددًا محددًا من الأشهر إلى تاريخ، أو تاريخ ووقت، أو تاريخ أو تاريخ ووقت مُرمَّزَين كسلسلة نصية.
**الصيغة**
```sql theme={null}
addMonths(datetime, num)
```
**الوسائط**
* `datetime` — تاريخ أو تاريخ مع وقت لإضافة عدد محدد من الأشهر إليه. [`Date`](/ar/reference/data-types/date) أو [`Date32`](/ar/reference/data-types/date32) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64) أو [`String`](/ar/reference/data-types/string)
* `num` — عدد الأشهر المراد إضافتها. [`(U)Int*`](/ar/reference/data-types/int-uint) أو [`Float*`](/ar/reference/data-types/float)
**القيمة المعادة**
يعيد `datetime` بعد إضافة `num` من الأشهر إليه [`Date`](/ar/reference/data-types/date) أو [`Date32`](/ar/reference/data-types/date32) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
**أمثلة**
**إضافة أشهر إلى أنواع تاريخ مختلفة**
```sql title=Query theme={null}
WITH
toDate('2024-01-01') AS date,
toDateTime('2024-01-01 00:00:00') AS date_time,
'2024-01-01 00:00:00' AS date_time_string
SELECT
addMonths(date, 6) AS add_months_with_date,
addMonths(date_time, 6) AS add_months_with_date_time,
addMonths(date_time_string, 6) AS add_months_with_date_time_string
```
```response title=Response theme={null}
┌─add_months_with_date─┬─add_months_with_date_time─┬─add_months_with_date_time_string─┐
│ 2024-07-01 │ 2024-07-01 00:00:00 │ 2024-07-01 00:00:00.000 │
└──────────────────────┴───────────────────────────┴──────────────────────────────────┘
```
**استخدام صيغة INTERVAL البديلة**
```sql title=Query theme={null}
SELECT dateAdd('1998-06-16'::Date, INTERVAL 10 month)
```
```response title=Response theme={null}
┌─plus(CAST('1⋯lMonth(10))─┐
│ 1999-04-16 │
└──────────────────────────┘
```
## addNanoseconds
أُضيف في الإصدار: v22.6.0
يضيف عددًا محددًا من النانوثواني إلى تاريخ ووقت أو إلى تاريخ ووقت مُرمَّزَين كسلسلة نصية.
**الصيغة**
```sql theme={null}
addNanoseconds(datetime, num)
```
**الوسيطات**
* `datetime` — قيمة تاريخ ووقت يُراد إضافة العدد المحدد من النانوثواني إليها. [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64) أو [`String`](/ar/reference/data-types/string)
* `num` — عدد النانوثواني المراد إضافتها. [`(U)Int*`](/ar/reference/data-types/int-uint) أو [`Float*`](/ar/reference/data-types/float)
**القيمة المُعادة**
تُرجِع `datetime` بعد إضافة `num` من النانوثواني إليه من النوع [`DateTime64`](/ar/reference/data-types/datetime64)
**أمثلة**
**إضافة نانوثوانٍ إلى أنواع مختلفة من التاريخ والوقت**
```sql title=Query theme={null}
WITH
toDateTime('2024-01-01 00:00:00') AS date_time,
'2024-01-01 00:00:00' AS date_time_string
SELECT
addNanoseconds(date_time, 1000) AS add_nanoseconds_with_date_time,
addNanoseconds(date_time_string, 1000) AS add_nanoseconds_with_date_time_string
```
```response title=Response theme={null}
┌─add_nanoseconds_with_date_time─┬─add_nanoseconds_with_date_time_string─┐
│ 2024-01-01 00:00:00.000001000 │ 2024-01-01 00:00:00.000001000 │
└────────────────────────────────┴───────────────────────────────────────┘
```
**استخدام الصياغة البديلة لـ INTERVAL**
```sql title=Query theme={null}
SELECT dateAdd('1998-06-16'::DateTime, INTERVAL 1000 nanosecond)
```
```response title=Response theme={null}
┌─plus(CAST('199⋯osecond(1000))─┐
│ 1998-06-16 00:00:00.000001000 │
└───────────────────────────────┘
```
## addQuarters
أُضيف في: v20.1.0
يضيف عددًا محددًا من أرباع السنة إلى تاريخ، أو تاريخ ووقت، أو تاريخ مُرمَّز كسلسلة نصية، أو تاريخ ووقت مُرمَّز كسلسلة نصية.
**الصيغة**
```sql theme={null}
addQuarters(datetime, num)
```
**الوسيطات**
* `datetime` — تاريخ أو تاريخ ووقت يُضاف إليه العدد المحدد من أرباع السنة. [`Date`](/ar/reference/data-types/date) أو [`Date32`](/ar/reference/data-types/date32) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64) أو [`String`](/ar/reference/data-types/string)
* `num` — عدد أرباع السنة المطلوب إضافتها. [`(U)Int*`](/ar/reference/data-types/int-uint) أو [`Float*`](/ar/reference/data-types/float)
**القيمة المعادة**
تعيد `datetime` بعد إضافة `num` من أرباع السنة إليه [`Date`](/ar/reference/data-types/date) أو [`Date32`](/ar/reference/data-types/date32) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
**أمثلة**
**إضافة أرباع السنة إلى أنواع مختلفة من التاريخ**
```sql title=Query theme={null}
WITH
toDate('2024-01-01') AS date,
toDateTime('2024-01-01 00:00:00') AS date_time,
'2024-01-01 00:00:00' AS date_time_string
SELECT
addQuarters(date, 1) AS add_quarters_with_date,
addQuarters(date_time, 1) AS add_quarters_with_date_time,
addQuarters(date_time_string, 1) AS add_quarters_with_date_time_string
```
```response title=Response theme={null}
┌─add_quarters_with_date─┬─add_quarters_with_date_time─┬─add_quarters_with_date_time_string─┐
│ 2024-04-01 │ 2024-04-01 00:00:00 │ 2024-04-01 00:00:00.000 │
└────────────────────────┴─────────────────────────────┴────────────────────────────────────┘
```
**استخدام صيغة INTERVAL البديلة**
```sql title=Query theme={null}
SELECT dateAdd('1998-06-16'::Date, INTERVAL 10 quarter)
```
```response title=Response theme={null}
┌─plus(CAST('1⋯uarter(10))─┐
│ 2000-12-16 │
└──────────────────────────┘
```
## addSeconds
قُدِّم في: v1.1.0
يضيف عددًا محددًا من الثواني إلى تاريخ، أو تاريخ ووقت، أو تاريخ مُمثَّل كسلسلة نصية، أو تاريخ ووقت مُمثَّل كسلسلة نصية.
**الصيغة**
```sql theme={null}
addSeconds(datetime, num)
```
**الوسيطات**
* `datetime` — تاريخ أو تاريخ مع وقت لإضافة العدد المحدد من الثواني إليه. [`Date`](/ar/reference/data-types/date) أو [`Date32`](/ar/reference/data-types/date32) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64) أو [`String`](/ar/reference/data-types/string)
* `num` — عدد الثواني المراد إضافته. [`(U)Int*`](/ar/reference/data-types/int-uint) أو [`Float*`](/ar/reference/data-types/float)
**القيمة المعادة**
يعيد `datetime` بعد إضافة `num` ثانية إليه. [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64(3)`](/ar/reference/data-types/datetime64)
**أمثلة**
**إضافة ثوانٍ إلى أنواع تاريخ متعددة**
```sql title=Query theme={null}
WITH
toDate('2024-01-01') AS date,
toDateTime('2024-01-01 00:00:00') AS date_time,
'2024-01-01 00:00:00' AS date_time_string
SELECT
addSeconds(date, 30) AS add_seconds_with_date,
addSeconds(date_time, 30) AS add_seconds_with_date_time,
addSeconds(date_time_string, 30) AS add_seconds_with_date_time_string
```
```response title=Response theme={null}
┌─add_seconds_with_date─┬─add_seconds_with_date_time─┬─add_seconds_with_date_time_string─┐
│ 2024-01-01 00:00:30 │ 2024-01-01 00:00:30 │ 2024-01-01 00:00:30.000 │
└───────────────────────┴────────────────────────────┴───────────────────────────────────┘
```
**استخدام الصياغة البديلة لـ INTERVAL**
```sql title=Query theme={null}
SELECT dateAdd('1998-06-16'::Date, INTERVAL 10 second)
```
```response title=Response theme={null}
┌─dateAdd('1998-06-16'::Date, INTERVAL 10 second)─┐
│ 1998-06-16 00:00:10 │
└─────────────────────────────────────────────────┘
```
## addTupleOfIntervals
أُضيف في: v22.11.0
يضيف بالتتابع Tuple من قيم interval إلى تاريخ أو تاريخ مع وقت.
**البنية**
```sql theme={null}
addTupleOfIntervals(datetime, intervals)
```
**الوسيطات**
* `datetime` — تاريخ أو تاريخ مع وقت لإضافة الفترات إليه. [`Date`](/ar/reference/data-types/date) أو [`Date32`](/ar/reference/data-types/date32) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
* `intervals` — `Tuple` من الفترات لإضافتها إلى `datetime`. [`Tuple(Interval)`](/ar/reference/data-types/tuple)
**القيمة المُعادة**
يُرجع `date` بعد إضافة `intervals` [`Date`](/ar/reference/data-types/date) أو [`Date32`](/ar/reference/data-types/date32) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
**أمثلة**
**إضافة Tuple من الفترات إلى تاريخ**
```sql title=Query theme={null}
WITH toDate('2018-01-01') AS date
SELECT addTupleOfIntervals(date, (INTERVAL 1 DAY, INTERVAL 1 MONTH, INTERVAL 1 YEAR))
```
```response title=Response theme={null}
┌─addTupleOfIntervals(date, (toIntervalDay(1), toIntervalMonth(1), toIntervalYear(1)))─┐
│ 2019-02-02 │
└──────────────────────────────────────────────────────────────────────────────────────┘
```
## addWeeks
أُضيفت في: v1.1.0
يضيف عددًا محددًا من الأسابيع إلى تاريخ، أو تاريخ مع وقت، أو تاريخ أو تاريخ مع وقت مُشفَّر كسلسلة نصية.
**الصيغة**
```sql theme={null}
addWeeks(datetime, num)
```
**الوسيطات**
* `datetime` — تاريخ أو تاريخ يتضمن وقتًا لإضافة العدد المحدد من الأسابيع إليه. [`Date`](/ar/reference/data-types/date) or [`Date32`](/ar/reference/data-types/date32) or [`DateTime`](/ar/reference/data-types/datetime) or [`DateTime64`](/ar/reference/data-types/datetime64) or [`String`](/ar/reference/data-types/string)
* `num` — عدد الأسابيع المراد إضافتها. [`(U)Int*`](/ar/reference/data-types/int-uint) or [`Float*`](/ar/reference/data-types/float)
**القيمة المعادة**
تعيد `datetime` بعد إضافة `num` من الأسابيع إليه [`Date`](/ar/reference/data-types/date) or [`Date32`](/ar/reference/data-types/date32) or [`DateTime`](/ar/reference/data-types/datetime) or [`DateTime64`](/ar/reference/data-types/datetime64)
**أمثلة**
**إضافة أسابيع إلى أنواع مختلفة من التواريخ**
```sql title=Query theme={null}
WITH
toDate('2024-01-01') AS date,
toDateTime('2024-01-01 00:00:00') AS date_time,
'2024-01-01 00:00:00' AS date_time_string
SELECT
addWeeks(date, 5) AS add_weeks_with_date,
addWeeks(date_time, 5) AS add_weeks_with_date_time,
addWeeks(date_time_string, 5) AS add_weeks_with_date_time_string
```
```response title=Response theme={null}
┌─add_weeks_with_date─┬─add_weeks_with_date_time─┬─add_weeks_with_date_time_string─┐
│ 2024-02-05 │ 2024-02-05 00:00:00 │ 2024-02-05 00:00:00.000 │
└─────────────────────┴──────────────────────────┴─────────────────────────────────┘
```
**استخدام الصياغة البديلة لـ INTERVAL**
```sql title=Query theme={null}
SELECT dateAdd('1998-06-16'::Date, INTERVAL 10 week)
```
```response title=Response theme={null}
┌─plus(CAST('1⋯alWeek(10))─┐
│ 1998-08-25 │
└──────────────────────────┘
```
## addYears
أُضيفت في: v1.1.0
تضيف عددًا محددًا من السنوات إلى تاريخ، أو تاريخ ووقت، أو تاريخ أو تاريخ ووقت ممثَّلَين كسلسلة نصية.
**البنية**
```sql theme={null}
addYears(datetime, num)
```
**الوسيطات**
* `datetime` — تاريخ أو تاريخ مع وقت لإضافة العدد المحدد من السنوات إليه. [`Date`](/ar/reference/data-types/date) أو [`Date32`](/ar/reference/data-types/date32) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64) أو [`String`](/ar/reference/data-types/string)
* `num` — عدد السنوات المراد إضافتها. [`(U)Int*`](/ar/reference/data-types/int-uint) أو [`Float*`](/ar/reference/data-types/float)
**القيمة المُعادة**
تُعيد `datetime` بعد إضافة `num` سنة إليه. [`Date`](/ar/reference/data-types/date) أو [`Date32`](/ar/reference/data-types/date32) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
**أمثلة**
**إضافة سنوات إلى أنواع تاريخ مختلفة**
```sql title=Query theme={null}
WITH
toDate('2024-01-01') AS date,
toDateTime('2024-01-01 00:00:00') AS date_time,
'2024-01-01 00:00:00' AS date_time_string
SELECT
addYears(date, 1) AS add_years_with_date,
addYears(date_time, 1) AS add_years_with_date_time,
addYears(date_time_string, 1) AS add_years_with_date_time_string
```
```response title=Response theme={null}
┌─add_years_with_date─┬─add_years_with_date_time─┬─add_years_with_date_time_string─┐
│ 2025-01-01 │ 2025-01-01 00:00:00 │ 2025-01-01 00:00:00.000 │
└─────────────────────┴──────────────────────────┴─────────────────────────────────┘
```
**استخدام البنية البديلة لـ INTERVAL**
```sql title=Query theme={null}
SELECT dateAdd('1998-06-16'::Date, INTERVAL 10 year)
```
```response title=Response theme={null}
┌─plus(CAST('1⋯alYear(10))─┐
│ 2008-06-16 │
└──────────────────────────┘
```
## age
أُضيف في: v23.1.0
يعيد مكوّن الوحدة من الفرق بين `startdate` و`enddate`.
ويُحسب الفرق باستخدام دقة مقدارها 1 نانوثانية.
على سبيل المثال، يكون الفرق بين 2021-12-29 و2022-01-01 هو 3 أيام لوحدة اليوم،
و0 شهرًا لوحدة الشهر، و0 سنة لوحدة السنة.
كبديل للدالة age، راجع الدالة [`dateDiff`](#dateDiff).
**البنية**
```sql theme={null}
age('unit', startdate, enddate[, timezone])
```
**المعاملات**
* `unit` — نوع الفاصل الزمني للنتيجة.
| Unit | القيم الممكنة |
| ----------- | ---------------------------------------- |
| nanosecond | `nanosecond`, `nanoseconds`, `ns` |
| microsecond | `microsecond`, `microseconds`, `us`, `u` |
| millisecond | `millisecond`, `milliseconds`, `ms` |
| second | `second`, `seconds`, `ss`, `s` |
| minute | `minute`, `minutes`, `mi`, `n` |
| hour | `hour`, `hours`, `hh`, `h` |
| day | `day`, `days`, `dd`, `d` |
| week | `week`, `weeks`, `wk`, `ww` |
| month | `month`, `months`, `mm`, `m` |
| quarter | `quarter`, `quarters`, `qq`, `q` |
| year | `year`, `years`, `yyyy`, `yy` |
* `startdate` — أول قيمة زمنية للطرح (المطروح). [`Date`](/ar/reference/data-types/date) أو [`Date32`](/ar/reference/data-types/date32) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
* `enddate` — ثاني قيمة زمنية يُطرح منها (المطروح منه). [`Date`](/ar/reference/data-types/date) أو [`Date32`](/ar/reference/data-types/date32) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
* `timezone` — اختياري. اسم المنطقة الزمنية. إذا تم تحديده، فسيُطبَّق على كلٍّ من startdate و enddate. وإذا لم يتم تحديده، فستُستخدم المنطقتان الزمنيتان لـ startdate و enddate. وإذا لم تكونا متماثلتين، فالنتيجة غير محددة. [`String`](/ar/reference/data-types/string)
**القيمة المعادة**
تعيد الفرق بين enddate و startdate معبَّرًا عنه بوحدة unit. [`Int32`](/ar/reference/data-types/int-uint)
**أمثلة**
**حساب العمر بالساعات**
```sql title=Query theme={null}
SELECT age('hour', toDateTime('2018-01-01 22:30:00'), toDateTime('2018-01-02 23:00:00'))
```
```response title=Response theme={null}
┌─age('hour', toDateTime('2018-01-01 22:30:00'), toDateTime('2018-01-02 23:00:00'))─┐
│ 24 │
└───────────────────────────────────────────────────────────────────────────────────┘
```
**حساب العمر بوحدات مختلفة**
```sql title=Query theme={null}
SELECT
toDate('2022-01-01') AS e,
toDate('2021-12-29') AS s,
age('day', s, e) AS day_age,
age('month', s, e) AS month_age,
age('year', s, e) AS year_age
```
```response title=Response theme={null}
┌──────────e─┬──────────s─┬─day_age─┬─month_age─┬─year_age─┐
│ 2022-01-01 │ 2021-12-29 │ 3 │ 0 │ 0 │
└────────────┴────────────┴─────────┴───────────┴──────────┘
```
## changeDay
قُدِّم في: v24.7.0
يغيّر مكوّن اليوم في قيمة من النوع Date أو في قيمة تاريخ ووقت.
**الصياغة**
```sql theme={null}
changeDay(date_or_datetime, value)
```
**المعاملات**
* `date_or_datetime` — القيمة المطلوب تغييرها. [`Date`](/ar/reference/data-types/date) أو [`Date32`](/ar/reference/data-types/date32) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
* `value` — القيمة الجديدة. [`(U)Int*`](/ar/reference/data-types/int-uint)
**القيمة المُعادة**
تُرجع قيمة من النوع نفسه لـ `date_or_datetime` مع تعديل مكوّن اليوم. [`Date`](/ar/reference/data-types/date) أو [`Date32`](/ar/reference/data-types/date32) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
**أمثلة**
**مثال على الاستخدام**
```sql title=Query theme={null}
SELECT changeDay('2024-01-31'::DateTime, 15)
```
```response title=Response theme={null}
2024-01-15 00:00:00
```
## changeHour
أُضيفت في: v24.7.0
تُغيّر مكوّن الساعة في قيمة من نوع تاريخ أو تاريخ ووقت.
**البنية**
```sql theme={null}
changeHour(date_or_datetime, value)
```
**الوسيطات**
* `date_or_datetime` — القيمة المراد تغييرها. [`Date`](/ar/reference/data-types/date) أو [`Date32`](/ar/reference/data-types/date32) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
* `value` — القيمة الجديدة. [`(U)Int*`](/ar/reference/data-types/int-uint)
**القيمة المعادة**
ترجع قيمة من نفس نوع `date_or_datetime` مع تعديل مكوّن الساعة. [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
**أمثلة**
**مثال على الاستخدام**
```sql title=Query theme={null}
SELECT changeHour('2024-01-01 12:00:00'::DateTime, 5)
```
```response title=Response theme={null}
2024-01-01 05:00:00
```
## changeMinute
أُضيف في: v24.7.0
يُغيّر مكوّن الدقائق في `date or date time`.
**البنية**
```sql theme={null}
changeMinute(date_or_datetime, value)
```
**المعاملات**
* `date_or_datetime` — القيمة المراد تغييرها. [`Date`](/ar/reference/data-types/date) أو [`Date32`](/ar/reference/data-types/date32) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
* `value` — القيمة الجديدة. [`(U)Int*`](/ar/reference/data-types/int-uint)
**القيمة المُعادة**
يعيد قيمة من النوع نفسه لـ `date_or_datetime` بعد تعديل مكوّن الدقيقة. [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
**أمثلة**
**مثال للاستخدام**
```sql title=Query theme={null}
SELECT changeMinute('2024-01-01 12:30:00'::DateTime, 45)
```
```response title=Response theme={null}
2024-01-01 12:45:00
```
## changeMonth
استُحدث في: v24.7.0
يُغيّر مكوّن الشهر في قيمة من نوع تاريخ أو تاريخ ووقت.
**البنية**
```sql theme={null}
changeMonth(date_or_datetime, value)
```
**الوسيطات**
* `date_or_datetime` — القيمة المراد تغييرها. [`Date`](/ar/reference/data-types/date) أو [`Date32`](/ar/reference/data-types/date32) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
* `value` — القيمة الجديدة. [`(U)Int*`](/ar/reference/data-types/int-uint)
**القيمة المُعادة**
تُرجِع قيمة من النوع نفسه لـ `date_or_datetime` مع تعديل مكوّن الشهر. [`Date`](/ar/reference/data-types/date) أو [`Date32`](/ar/reference/data-types/date32) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
**أمثلة**
**مثال على الاستخدام**
```sql title=Query theme={null}
SELECT changeMonth('2024-01-01'::DateTime, 12)
```
```response title=Response theme={null}
2024-12-01 00:00:00
```
## changeSecond
أُضيف في: v24.7.0
يُغيّر مكوّن الثواني في قيمة من نوع date أو date time.
**البنية**
```sql theme={null}
changeSecond(date_or_datetime, value)
```
**الوسيطات**
* `date_or_datetime` — القيمة المراد تغييرها. [`Date`](/ar/reference/data-types/date) أو [`Date32`](/ar/reference/data-types/date32) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
* `value` — القيمة الجديدة. [`(U)Int*`](/ar/reference/data-types/int-uint)
**القيمة المُعادة**
تُعيد قيمة من النوع نفسه لـ `date_or_datetime` مع تعديل مكوّن الثواني. [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
**أمثلة**
**مثال على الاستخدام**
```sql title=Query theme={null}
SELECT changeSecond('2024-01-01 12:30:45'::DateTime, 15)
```
```response title=Response theme={null}
2024-01-01 12:30:15
```
## changeYear
قُدِّمت في: v24.7.0
تُغيِّر مكوّن السنة في قيمة من نوع Date أو DateTime.
**الصياغة**
```sql theme={null}
changeYear(date_or_datetime, value)
```
**الوسيطات**
* `date_or_datetime` — القيمة المراد تغييرها. [`Date`](/ar/reference/data-types/date) أو [`Date32`](/ar/reference/data-types/date32) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
* `value` — القيمة الجديدة. [`(U)Int*`](/ar/reference/data-types/int-uint)
**القيمة المُعادة**
تُعيد قيمة من النوع نفسه لـ `date_or_datetime` مع تعديل مكوّن السنة. [`Date`](/ar/reference/data-types/date) أو [`Date32`](/ar/reference/data-types/date32) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
**أمثلة**
**مثال على الاستخدام**
```sql title=Query theme={null}
SELECT changeYear('2024-01-01'::DateTime, 2023)
```
```response title=Response theme={null}
2023-01-01 00:00:00
```
## dateDiff
تم تقديمه في: v23.4.0
يعيد عدد حدود `unit` المحددة التي جرى تجاوزها بين `startdate` و`enddate`.
يُحسب الفرق باستخدام الوحدات النسبية. على سبيل المثال، الفرق بين 2021-12-29 و2022-01-01 هو 3 أيام للوحدة day
(راجع [`toRelativeDayNum`](#toRelativeDayNum))، وشهر واحد للوحدة month (راجع [`toRelativeMonthNum`](#toRelativeMonthNum))، وسنة واحدة للوحدة year
(راجع [`toRelativeYearNum`](#toRelativeYearNum)).
إذا جرى تحديد الوحدة `week`، فإن `dateDiff` يفترض أن الأسابيع تبدأ يوم الاثنين.
لاحظ أن هذا السلوك يختلف عن سلوك الدالة `toWeek()`، حيث تبدأ الأسابيع افتراضيًا يوم الأحد.
كبديل لـ `dateDiff`، راجع الدالة [`age`](#age).
**البنية**
```sql theme={null}
dateDiff(unit, startdate, enddate[, timezone])
```
**الأسماء المستعارة**: `timestampDiff`, `TIMESTAMP_DIFF`, `DATE_DIFF`, `date_diff`, `timestamp_diff`
**المعاملات**
* `unit` — نوع الفاصل الزمني المستخدم في النتيجة.
| الوحدة | القيم الممكنة |
| ---------- | ---------------------------------------- |
| نانوثانية | `nanosecond`, `nanoseconds`, `ns` |
| ميكروثانية | `microsecond`, `microseconds`, `us`, `u` |
| مللي ثانية | `millisecond`, `milliseconds`, `ms` |
| ثانية | `second`, `seconds`, `ss`, `s` |
| دقيقة | `minute`, `minutes`, `mi`, `n` |
| ساعة | `hour`, `hours`, `hh`, `h` |
| يوم | `day`, `days`, `dd`, `d` |
| أسبوع | `week`, `weeks`, `wk`, `ww` |
| شهر | `month`, `months`, `mm`, `m` |
| ربع سنة | `quarter`, `quarters`, `qq`, `q` |
| سنة | `year`, `years`, `yyyy`, `yy` |
* `startdate` — القيمة الزمنية الأولى التي تُطرح (المطروح). [`Date`](/ar/reference/data-types/date) أو [`Date32`](/ar/reference/data-types/date32) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
* `enddate` — القيمة الزمنية الثانية التي يُطرح منها (المطروح منه). [`Date`](/ar/reference/data-types/date) أو [`Date32`](/ar/reference/data-types/date32) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
* `timezone` — اختياري. اسم المنطقة الزمنية. إذا تم تحديده، فسيُطبَّق على كلٍّ من `startdate` و`enddate`. وإذا لم يتم تحديده، فستُستخدم المنطقتان الزمنيتان لـ `startdate` و`enddate`. وإذا لم تكونا متماثلتين، فستكون النتيجة غير محددة. [`String`](/ar/reference/data-types/string)
**القيمة المعادة**
تعيد الفرق بين `enddate` و`startdate` معبَّرًا عنه بوحدة `unit`. [`Int64`](/ar/reference/data-types/int-uint)
**أمثلة**
**حساب فرق التاريخ بالساعات**
```sql title=Query theme={null}
SELECT dateDiff('hour', toDateTime('2018-01-01 22:00:00'), toDateTime('2018-01-02 23:00:00')) AS res
```
```response title=Response theme={null}
┌─res─┐
│ 25 │
└─────┘
```
**احسب الفرق بين التواريخ بوحدات مختلفة**
```sql title=Query theme={null}
SELECT
toDate('2022-01-01') AS e,
toDate('2021-12-29') AS s,
dateDiff('day', s, e) AS day_diff,
dateDiff('month', s, e) AS month_diff,
dateDiff('year', s, e) AS year_diff
```
```response title=Response theme={null}
┌──────────e─┬──────────s─┬─day_diff─┬─month_diff─┬─year_diff─┐
│ 2022-01-01 │ 2021-12-29 │ 3 │ 1 │ 1 │
└────────────┴────────────┴──────────┴────────────┴───────────┘
```
## dateName
أُضيف في: v21.7.0
يعيد الجزء المحدد من التاريخ.
القيم الممكنة:
* 'year'
* 'quarter'
* 'month'
* 'week'
* 'dayofyear'
* 'day'
* 'weekday'
* 'hour'
* 'minute'
* 'second'
**البنية**
```sql theme={null}
dateName(date_part, date[, timezone])
```
**المعاملات**
* `date_part` — جزء التاريخ الذي تريد استخراجه. [`String`](/ar/reference/data-types/string)
* `datetime` — قيمة تاريخ أو تاريخ ووقت. [`Date`](/ar/reference/data-types/date) أو [`Date32`](/ar/reference/data-types/date32) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
* `timezone` — اختياري. المنطقة الزمنية. [`String`](/ar/reference/data-types/string)
**القيمة المعادة**
تُرجع الجزء المحدد من التاريخ. [`String`](/ar/reference/data-types/string)
**أمثلة**
**استخراج أجزاء مختلفة من التاريخ**
```sql title=Query theme={null}
WITH toDateTime('2021-04-14 11:22:33') AS date_value
SELECT
dateName('year', date_value),
dateName('month', date_value),
dateName('day', date_value)
```
```response title=Response theme={null}
┌─dateName('year', date_value)─┬─dateName('month', date_value)─┬─dateName('day', date_value)─┐
│ 2021 │ April │ 14 │
└──────────────────────────────┴───────────────────────────────┴─────────────────────────────┘
```
## dateTrunc
أُضيفت في: v20.8.0
تقصّ قيمة تاريخ ووقت إلى الجزء المحدد من التاريخ.
**الصيغة**
```sql theme={null}
dateTrunc(unit, datetime[, timezone])
```
**الأسماء البديلة**: `DATE_TRUNC`
**الوسيطات**
* `unit` —
وحدة الفترة الزمنية المراد اقتطاع النتيجة إليها. القيم الممكنة: `nanosecond` (فقط DateTime64)، `microsecond` (فقط DateTime64)، `millisecond` (فقط DateTime64)، `second`، `minute`، `hour`، `day`، `week`، `month`، `quarter`، `year`.
[`String`](/ar/reference/data-types/string)
* `datetime` — التاريخ والوقت. [`Date`](/ar/reference/data-types/date) أو [`Date32`](/ar/reference/data-types/date32) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
* `timezone` — اختياري. اسم المنطقة الزمنية لقيمة التاريخ والوقت المعادة. إذا لم يتم تحديده، تستخدم الدالة المنطقة الزمنية الخاصة بالوسيطة `datetime`. [`String`](/ar/reference/data-types/string)
**القيمة المعادة**
تعيد قيمة التاريخ والوقت بعد اقتطاعها.
| وسيطة `unit` | وسيطة `datetime` | نوع الإرجاع |
| -------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------ |
| Year, Quarter, Month, Week | `Date32` أو `DateTime64` أو `Date` أو `DateTime` | [`Date32`](/ar/reference/data-types/date32) أو [`Date`](/ar/reference/data-types/date) |
| Day, Hour, Minute, Second | `Date32`، `DateTime64`، `Date`، أو `DateTime` | [`DateTime64`](/ar/reference/data-types/datetime64) أو [`DateTime`](/ar/reference/data-types/datetime) |
| Millisecond, Microsecond, | أي قيمة | [`DateTime64`](/ar/reference/data-types/datetime64) |
| Nanosecond | | بمقياس 3 أو 6 أو 9 |
**أمثلة**
**الاقتطاع من دون منطقة زمنية**
```sql title=Query theme={null}
SELECT now(), dateTrunc('hour', now());
```
```response title=Response theme={null}
┌───────────────now()─┬─dateTrunc('hour', now())──┐
│ 2020-09-28 10:40:45 │ 2020-09-28 10:00:00 │
└─────────────────────┴───────────────────────────┘
```
**الاقتطاع مع تحديد المنطقة الزمنية**
```sql title=Query theme={null}
SELECT now(), dateTrunc('hour', now(), 'Asia/Istanbul');
```
```response title=Response theme={null}
┌───────────────now()─┬─dateTrunc('hour', now(), 'Asia/Istanbul')──┐
│ 2020-09-28 10:46:26 │ 2020-09-28 13:00:00 │
└─────────────────────┴────────────────────────────────────────────┘
```
## formatDateTime
أُضيف في: v1.1.0
ينسّق تاريخًا أو تاريخًا مع وقت وفقًا لسلسلة التنسيق المحددة. يكون `format` تعبيرًا ثابتًا، لذا لا يمكنك استخدام عدة تنسيقات لعمود نتيجة واحد.
تستخدم `formatDateTime` أسلوب تنسيق datetime الخاص بـ MySQL، راجع [وثائق MySQL](https://dev.mysql.com/doc/refman/8.0/en/date-and-time-functions.html#function_date-format).
العملية العكسية لهذه الدالة هي [`parseDateTime`](/ar/reference/functions/regular-functions/type-conversion-functions#parseDateTime).
باستخدام حقول الاستبدال، يمكنك تحديد نمط للسلسلة الناتجة.
يوضح عمود المثال في الجدول أدناه نتيجة التنسيق للقيمة `2018-01-02 22:33:44`.
**حقول الاستبدال:**
| العنصر النائب | الوصف | مثال |
| ------------- | -------------------------------------------------------- | ---------- |
| %a | الاسم المختصر ليوم الأسبوع (Mon-Sun) | Mon |
| %b | الاسم المختصر للشهر (Jan-Dec) | Jan |
| %c | الشهر كرقم صحيح (01-12) | 01 |
| %C | السنة مقسومة على 100 ومحوّلة إلى عدد صحيح (00-99) | 20 |
| %d | يوم الشهر مع أصفار بادئة (01-31) | 02 |
| %D | تاريخ قصير بصيغة MM/DD/YY، ويكافئ %m/%d/%y | 01/02/18 |
| %e | يوم الشهر مع مسافات بادئة (1-31) | 2 |
| %f | الجزء الكسري من الثانية | 123456 |
| %F | تاريخ قصير بصيغة YYYY-MM-DD، ويكافئ %Y-%m-%d | 2018-01-02 |
| %g | تنسيق سنة من رقمين، متوافق مع ISO 8601 | 18 |
| %G | تنسيق سنة من أربعة أرقام لرقم الأسبوع وفق ISO | 2018 |
| %h | الساعة بتنسيق 12 ساعة (01-12) | 09 |
| %H | الساعة بتنسيق 24 ساعة (00-23) | 22 |
| %i | الدقيقة (00-59) | 33 |
| %I | الساعة بتنسيق 12 ساعة (01-12) | 10 |
| %j | يوم السنة (001-366) | 002 |
| %k | الساعة بتنسيق 24 ساعة (00-23) | 14 |
| %l | الساعة بتنسيق 12 ساعة (01-12) | 09 |
| %m | الشهر كرقم صحيح (01-12) | 01 |
| %M | الاسم الكامل للشهر (January-December) | January |
| %n | محرف سطر جديد | |
| %p | مؤشر AM أو PM | PM |
| %Q | الربع (1-4) | 1 |
| %r | وقت 12 ساعة بصيغة HH:MM AM/PM، ويكافئ %h:%i %p | 10:30 PM |
| %R | وقت 24 ساعة بصيغة HH:MM، ويكافئ %H:%i | 22:33 |
| %s | الثانية (00-59) | 44 |
| %S | الثانية (00-59) | 44 |
| %t | محرف tab أفقي | |
| %T | تنسيق الوقت ISO 8601 (HH:MM:SS)، ويكافئ %H:%i:%S | 22:33:44 |
| %u | يوم الأسبوع في ISO 8601 كرقم يبدأ فيه الاثنين من 1 (1-7) | 2 |
| %V | رقم الأسبوع وفق ISO 8601 (01-53) | 01 |
| %w | يوم الأسبوع كرقم صحيح يبدأ فيه الأحد من 0 (0-6) | 2 |
| %W | الاسم الكامل ليوم الأسبوع (Monday-Sunday) | Monday |
| %y | السنة، آخر رقمين (00-99) | 18 |
| %Y | السنة | 2018 |
| %z | إزاحة الوقت عن UTC بصيغة +HHMM أو -HHMM | -0500 |
| %% | علامة % | % |
* في إصدارات ClickHouse الأقدم من v23.4، تطبع `%f` صفرًا واحدًا (0) إذا كانت القيمة المنسّقة من النوع Date أو Date32 أو DateTime (التي لا تحتوي على أجزاء كسرية من الثانية) أو من النوع DateTime64 بدقة تساوي 0.
* في إصدارات ClickHouse الأقدم من v25.1، تطبع `%f` عددًا من الخانات يساوي precision الخاصة بـ DateTime64 بدلًا من 6 خانات ثابتة.
* في إصدارات ClickHouse الأقدم من v23.4، تطبع `%M` الدقيقة (00-59) بدلًا من الاسم الكامل للشهر (January-December).
**البنية**
```sql theme={null}
formatDateTime(datetime, format[, timezone])
```
**الأسماء المستعارة**: `DATE_FORMAT`
**الوسيطات**
* `datetime` — تاريخ أو تاريخ ووقت المراد تنسيقه. [`Date`](/ar/reference/data-types/date) أو [`Date32`](/ar/reference/data-types/date32) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
* `format` — سلسلة تنسيق تحتوي على حقول استبدال. [`String`](/ar/reference/data-types/string)
* `timezone` — اختياري. اسم المنطقة الزمنية للوقت المنسَّق. [`String`](/ar/reference/data-types/string)
**القيمة المُعادة**
يعيد قيم التاريخ والوقت وفقًا للتنسيق المحدد. [`String`](/ar/reference/data-types/string)
**أمثلة**
**تنسيق التاريخ باستخدام العنصر النائب للسنة**
```sql title=Query theme={null}
SELECT formatDateTime(toDate('2010-01-04'), '%g')
```
```response title=Response theme={null}
┌─formatDateTime(toDate('2010-01-04'), '%g')─┐
│ 10 │
└────────────────────────────────────────────┘
```
**تنسيق DateTime64 بأجزاء من الثانية**
```sql title=Query theme={null}
SELECT formatDateTime(toDateTime64('2010-01-04 12:34:56.123456', 7), '%f')
```
```response title=Response theme={null}
┌─formatDateTime(toDateTime64('2010-01-04 12:34:56.123456', 7), '%f')─┐
│ 1234560 │
└─────────────────────────────────────────────────────────────────────┘
```
**التنسيق باستخدام المنطقة الزمنية**
```sql title=Query theme={null}
SELECT
now() AS ts,
time_zone,
formatDateTime(ts, '%T', time_zone) AS str_tz_time
FROM system.time_zones
WHERE time_zone LIKE 'Europe%'
LIMIT 10
```
```response title=Response theme={null}
┌──────────────────ts─┬─time_zone─────────┬─str_tz_time─┐
│ 2023-09-08 19:13:40 │ Europe/Amsterdam │ 21:13:40 │
│ 2023-09-08 19:13:40 │ Europe/Andorra │ 21:13:40 │
│ 2023-09-08 19:13:40 │ Europe/Astrakhan │ 23:13:40 │
│ 2023-09-08 19:13:40 │ Europe/Athens │ 22:13:40 │
│ 2023-09-08 19:13:40 │ Europe/Belfast │ 20:13:40 │
│ 2023-09-08 19:13:40 │ Europe/Belgrade │ 21:13:40 │
│ 2023-09-08 19:13:40 │ Europe/Berlin │ 21:13:40 │
│ 2023-09-08 19:13:40 │ Europe/Bratislava │ 21:13:40 │
│ 2023-09-08 19:13:40 │ Europe/Brussels │ 21:13:40 │
│ 2023-09-08 19:13:40 │ Europe/Bucharest │ 22:13:40 │
└─────────────────────┴───────────────────┴─────────────┘
```
## formatDateTimeInJodaSyntax
أُضيفت في: v20.1.0
تُشبه `formatDateTime`، إلا أنها تنسّق قيم التاريخ والوقت بأسلوب Joda بدلًا من أسلوب MySQL. راجع [توثيق Joda Time](https://joda-time.sourceforge.net/apidocs/org/joda/time/format/DateTimeFormat.html).
العملية العكسية لهذه الدالة هي [`parseDateTimeInJodaSyntax`](/ar/reference/functions/regular-functions/type-conversion-functions#parseDateTimeInJodaSyntax).
باستخدام حقول الاستبدال، يمكنك تحديد نمط للسلسلة الناتجة.
**حقول الاستبدال:**
| العنصر النائب | الوصف | العرض | أمثلة |
| ------------- | ----------------------------------- | ---------- | -------------------------- |
| G | العصر | نص | AD |
| C | قرن العصر (>=0) | رقم | 20 |
| Y | سنة العصر (>=0) | سنة | 1996 |
| x | سنة الأسبوع (غير مدعومة بعد) | سنة | 1996 |
| w | أسبوع سنة الأسبوع (غير مدعوم بعد) | رقم | 27 |
| e | يوم الأسبوع | رقم | 2 |
| E | يوم الأسبوع | نص | Tuesday; Tue |
| y | السنة | سنة | 1996 |
| D | اليوم من السنة | رقم | 189 |
| M | شهر السنة | شهر | July; Jul; 07 |
| d | يوم الشهر | رقم | 10 |
| a | نصف اليوم | نص | PM |
| K | ساعة نصف اليوم (0\~11) | رقم | 0 |
| h | ساعة نصف اليوم بنظام الساعة (1\~12) | رقم | 12 |
| H | ساعة اليوم (0\~23) | رقم | 0 |
| k | ساعة اليوم بنظام الساعة (1\~24) | رقم | 24 |
| m | دقيقة الساعة | رقم | 30 |
| s | ثانية الدقيقة | رقم | 55 |
| S | جزء من الثانية | رقم | 978 |
| z | المنطقة الزمنية | نص | Eastern Standard Time; EST |
| Z | إزاحة المنطقة الزمنية | منطقة | -0800; -0812 |
| ' | إفلات للنص | فاصل | |
| '' | علامة اقتباس مفردة | قيمة حرفية | ' |
**البنية**
```sql theme={null}
formatDateTimeInJodaSyntax(datetime, format[, timezone])
```
**الوسائط**
* `datetime` — تاريخ أو تاريخ ووقت لتنسيقه. [`DateTime`](/ar/reference/data-types/datetime) أو [`Date`](/ar/reference/data-types/date) أو [`Date32`](/ar/reference/data-types/date32) أو [`DateTime64`](/ar/reference/data-types/datetime64)
* `format` — سلسلة تنسيق تتضمن حقول استبدال بنمط Joda. [`String`](/ar/reference/data-types/string)
* `timezone` — اختياري. اسم المنطقة الزمنية للوقت المنسَّق. [`String`](/ar/reference/data-types/string)
**القيمة المُعادة**
يعرض قيم الوقت والتاريخ وفقًا للتنسيق المحدد. [`String`](/ar/reference/data-types/string)
**أمثلة**
**تنسيق التاريخ والوقت باستخدام بنية Joda**
```sql title=Query theme={null}
SELECT formatDateTimeInJodaSyntax(toDateTime('2010-01-04 12:34:56'), 'yyyy-MM-dd HH:mm:ss')
```
```response title=Response theme={null}
┌─formatDateTimeInJodaSyntax(toDateTime('2010-01-04 12:34:56'), 'yyyy-MM-dd HH:mm:ss')─┐
│ 2010-01-04 12:34:56 │
└─────────────────────────────────────────────────────────────────────────────────────────┘
```
## fromDaysSinceYearZero
أُضيفت في: v23.11.0
بالنسبة إلى عدد معيّن من الأيام المنقضية منذ [1 January 0000](https://en.wikipedia.org/wiki/Year_zero)، تُرجِع هذه الدالة التاريخ الموافق في [التقويم الغريغوري الاستباقي المعرّف وفق ISO 8601](https://en.wikipedia.org/wiki/Gregorian_calendar#Proleptic_Gregorian_calendar).
يكون الحساب مماثلًا لما في الدالة `FROM_DAYS()` في MySQL. وتكون النتيجة غير معرّفة إذا تعذّر تمثيلها ضمن حدود النوع [Date](/ar/reference/data-types/date).
**الصيغة**
```sql theme={null}
fromDaysSinceYearZero(days)
```
**الأسماء البديلة**: `FROM_DAYS`
**الوسائط**
* `days` — عدد الأيام المنقضية منذ العام صفر. [`UInt32`](/ar/reference/data-types/int-uint)
**القيمة المُعادة**
تعيد التاريخ الموافق لعدد الأيام المنقضية منذ العام صفر. [`Date`](/ar/reference/data-types/date)
**أمثلة**
**تحويل الأيام منذ العام صفر إلى تواريخ**
```sql title=Query theme={null}
SELECT
fromDaysSinceYearZero(739136) AS date1,
fromDaysSinceYearZero(toDaysSinceYearZero(toDate('2023-09-08'))) AS date2
```
```response title=Response theme={null}
┌──────date1─┬──────date2─┐
│ 2023-09-08 │ 2023-09-08 │
└────────────┴────────────┘
```
## fromDaysSinceYearZero32
أُضيف في: v23.11.0
بالنسبة إلى عدد معيّن من الأيام المنقضية منذ [1 January 0000](https://en.wikipedia.org/wiki/Year_zero)، تُرجِع الدالة التاريخ المقابل في [التقويم الغريغوري الممتد استباقيًا كما يحدده ISO 8601](https://en.wikipedia.org/wiki/Gregorian_calendar#Proleptic_Gregorian_calendar).
ويكون الحساب مماثلًا لما في الدالة `FROM_DAYS()` في MySQL. وتكون النتيجة غير معرّفة إذا تعذّر تمثيلها ضمن حدود النوع [`Date32`](/ar/reference/data-types/date32).
**البنية**
```sql theme={null}
fromDaysSinceYearZero32(days)
```
**الوسائط**
* `days` — عدد الأيام المنقضية منذ السنة صفر. [`UInt32`](/ar/reference/data-types/int-uint)
**القيمة المُعادة**
تُرجِع التاريخ الموافق لعدد الأيام المنقضية منذ السنة صفر. [`Date32`](/ar/reference/data-types/date32)
**أمثلة**
**تحويل الأيام منذ السنة صفر إلى تواريخ**
```sql title=Query theme={null}
SELECT
fromDaysSinceYearZero32(739136) AS date1,
fromDaysSinceYearZero32(toDaysSinceYearZero(toDate('2023-09-08'))) AS date2
```
```response title=Response theme={null}
┌──────date1─┬──────date2─┐
│ 2023-09-08 │ 2023-09-08 │
└────────────┴────────────┘
```
## fromModifiedJulianDay
أُضيفت في: v21.1.0
تحوّل رقم [Modified Julian Day](https://en.wikipedia.org/wiki/Julian_day#Variants) إلى تاريخ وفق [Proleptic Gregorian calendar](https://en.wikipedia.org/wiki/Proleptic_Gregorian_calendar) بصيغة نصية `YYYY-MM-DD`. تدعم هذه الدالة أرقام الأيام من `-678941` إلى `2973483` (وهي تمثل 0000-01-01 و9999-12-31 على التوالي). وتُطلق استثناءً إذا كان رقم اليوم خارج النطاق المدعوم.
**البنية**
```sql theme={null}
fromModifiedJulianDay(day)
```
**الوسائط**
* `day` — رقم اليوم اليولياني المُعدَّل. [`(U)Int*`](/ar/reference/data-types/int-uint)
**القيمة المُرجَعة**
تعيد التاريخ بصيغة نصية. [`String`](/ar/reference/data-types/string)
**أمثلة**
**تحويل اليوم اليولياني المُعدَّل إلى تاريخ**
```sql title=Query theme={null}
SELECT fromModifiedJulianDay(58849)
```
```response title=Response theme={null}
┌─fromModifiedJulianDay(58849)─┐
│ 2020-01-01 │
└──────────────────────────────┘
```
## fromModifiedJulianDayOrNull
أُضيف في: v21.1.0
يشبه [`fromModifiedJulianDay()`](#fromModifiedJulianDay)، لكنه يعيد `NULL` بدلًا من إطلاق استثناءات.
**الصيغة**
```sql theme={null}
fromModifiedJulianDayOrNull(day)
```
**الوسائط**
* `day` — رقم اليوم اليولياني المعدّل. [`(U)Int*`](/ar/reference/data-types/int-uint)
**القيمة المُعادة**
يعيد التاريخ بصيغة نصية إذا كانت قيمة الوسيط `day` صالحة، وإلا فستكون `null`. [`Nullable(String)`](/ar/reference/data-types/nullable)
**أمثلة**
**تحويل اليوم اليولياني المعدّل إلى تاريخ مع التعامل مع القيم `null`**
```sql title=Query theme={null}
SELECT fromModifiedJulianDayOrNull(58849);
SELECT fromModifiedJulianDayOrNull(60000000); -- invalid argument, returns NULL
```
```response title=Response theme={null}
┌─fromModified⋯Null(58849)─┐
│ 2020-01-01 │
└──────────────────────────┘
┌─fromModified⋯l(60000000)─┐
│ ᴺᵁᴸᴸ │
└──────────────────────────┘
```
## fromUTCTimestamp
أُضيف في: v22.1.0
يحوّل قيمة تاريخ أو تاريخ مع وقت من المنطقة الزمنية UTC إلى قيمة تاريخ أو تاريخ مع وقت بالمنطقة الزمنية المحددة. تُضمَّن هذه الدالة أساسًا للتوافق مع Apache Spark وأطر العمل المماثلة.
**الصيغة**
```sql theme={null}
fromUTCTimestamp(datetime, time_zone)
```
**الأسماء المستعارة**: `from_utc_timestamp`
**الوسيطات**
* `datetime` — قيمة ثابتة من نوع تاريخ أو تاريخ مع وقت، أو تعبير. [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
* `time_zone` — قيمة ثابتة من نوع String أو تعبير يمثّل المنطقة الزمنية. [`String`](/ar/reference/data-types/string)
**القيمة المعادة**
يعيد قيمة من نوع DateTime/DateTime64 في المنطقة الزمنية المحددة. [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
**أمثلة**
**تحويل المنطقة الزمنية UTC إلى المنطقة الزمنية المحددة**
```sql title=Query theme={null}
SELECT fromUTCTimestamp(toDateTime64('2023-03-16 10:00:00', 3), 'Asia/Shanghai')
```
```response title=Response theme={null}
┌─fromUTCTimestamp(toDateTime64('2023-03-16 10:00:00',3), 'Asia/Shanghai')─┐
│ 2023-03-16 18:00:00.000 │
└─────────────────────────────────────────────────────────────────────────┘
```
## fromUnixTimestamp
أُضيف في: v20.8.0
تحوّل هذه الدالة طابعًا زمنيًا بنظام Unix إلى تاريخ تقويمي ووقت من اليوم.
يمكن استدعاؤها بطريقتين:
* عند تمرير وسيط واحد من النوع [`Integer`](/ar/reference/data-types/int-uint)، فإنها تُرجع قيمة من النوع [`DateTime`](/ar/reference/data-types/datetime)، أي إنها تتصرف مثل [`toDateTime`](/ar/reference/functions/regular-functions/type-conversion-functions#toDateTime).
* عند تمرير وسيطين أو ثلاثة، بحيث يكون الوسيط الأول قيمة من النوع [`Integer`](/ar/reference/data-types/int-uint) أو [`Date`](/ar/reference/data-types/date) أو [`Date32`](/ar/reference/data-types/date32) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)، ويكون الوسيط الثاني سلسلة تنسيق ثابتة، ويكون الوسيط الثالث سلسلة اختيارية ثابتة للمنطقة الزمنية، فإن الدالة تُرجع قيمة من النوع [`String`](/ar/reference/data-types/string)، أي إنها تتصرف مثل [`formatDateTime`](#formatDateTime).
في هذه الحالة، يُستخدم [نمط MySQL لتنسيق التاريخ والوقت](https://dev.mysql.com/doc/refman/8.0/en/date-and-time-functions.html#function_date-format).
**البنية**
```sql theme={null}
fromUnixTimestamp(timestamp)
fromUnixTimestamp(timestamp[, format[, timezone]])
```
**الأسماء البديلة**: `FROM_UNIXTIME`
**الوسائط**
* `timestamp` — طابع زمني لـ Unix أو قيمة تاريخ/تاريخ مع وقت. [`(U)Int*`](/ar/reference/data-types/int-uint) أو [`Date`](/ar/reference/data-types/date) أو [`Date32`](/ar/reference/data-types/date32) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
* `format` — اختياري. سلسلة تنسيق ثابتة لتنسيق الإخراج. [`String`](/ar/reference/data-types/string)
* `timezone` — اختياري. سلسلة ثابتة للمنطقة الزمنية. [`String`](/ar/reference/data-types/string)
**القيمة المُعادة**
يعيد قيمة `DateTime` للطابع الزمني عند استدعائه بوسيطة واحدة، أو قيمة `String` عند استدعائه بوسيطتين أو ثلاث وسيطات. [`DateTime`](/ar/reference/data-types/datetime) أو [`String`](/ar/reference/data-types/string)
**أمثلة**
**تحويل طابع زمني لـ Unix إلى `DateTime`**
```sql title=Query theme={null}
SELECT fromUnixTimestamp(423543535)
```
```response title=Response theme={null}
┌─fromUnixTimestamp(423543535)─┐
│ 1983-06-04 10:58:55 │
└──────────────────────────────┘
```
**تحويل طابع زمني لـ Unix باستخدام تنسيق**
```sql title=Query theme={null}
SELECT fromUnixTimestamp(1234334543, '%Y-%m-%d %R:%S') AS DateTime
```
```response title=Response theme={null}
┌─DateTime────────────┐
│ 2009-02-11 14:42:23 │
└─────────────────────┘
```
## fromUnixTimestampInJodaSyntax
أُضيفت في: v23.1.0
تُحوِّل هذه الدالة طابعًا زمنيًا بنظام Unix إلى تاريخ تقويمي ووقت من اليوم.
يمكن استدعاؤها بطريقتين:
عند تمرير وسيط واحد من النوع [`Integer`](/ar/reference/data-types/int-uint)، فإنها تُرجع قيمة من النوع [`DateTime`](/ar/reference/data-types/datetime)، أي إنها تعمل مثل [`toDateTime`](/ar/reference/functions/regular-functions/type-conversion-functions#toDateTime).
عند تمرير وسيطين أو ثلاثة وسائط، بحيث تكون قيمة الوسيط الأول من النوع [`Integer`](/ar/reference/data-types/int-uint) أو [`Date`](/ar/reference/data-types/date) أو [`Date32`](/ar/reference/data-types/date32) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)، ويكون الوسيط الثاني سلسلة تنسيق ثابتة، ويكون الوسيط الثالث سلسلة منطقة زمنية ثابتة اختيارية، فإن الدالة تُرجع قيمة من النوع [`String`](/ar/reference/data-types/string)، أي إنها تعمل مثل [`formatDateTimeInJodaSyntax`](#formatDateTimeInJodaSyntax). في هذه الحالة، يُستخدم [نمط تنسيق التاريخ والوقت في Joda](https://joda-time.sourceforge.net/apidocs/org/joda/time/format/DateTimeFormat.html).
**البنية**
```sql theme={null}
fromUnixTimestampInJodaSyntax(timestamp)
fromUnixTimestampInJodaSyntax(timestamp, format[, timezone])
```
**الوسائط**
* `timestamp` — طابع زمني بنظام Unix أو قيمة تاريخ/وقت. [`(U)Int*`](/ar/reference/data-types/int-uint) أو [`Date`](/ar/reference/data-types/date) أو [`Date32`](/ar/reference/data-types/date32) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
* `format` — اختياري. سلسلة تنسيق ثابتة تستخدم بناء جملة Joda لتنسيق الإخراج. [`String`](/ar/reference/data-types/string)
* `timezone` — اختياري. سلسلة ثابتة للمنطقة الزمنية. [`String`](/ar/reference/data-types/string)
**القيمة المعادة**
يعيد قيمة تاريخ مع وقت عند استدعائه بوسيطة واحدة، أو قيمة من النوع `String` عند استدعائه بوسيطتين أو ثلاث وسيطات.} [`DateTime`](/ar/reference/data-types/datetime) أو [`String`](/ar/reference/data-types/string)
**أمثلة**
**تحويل طابع زمني بنظام Unix باستخدام تنسيق Joda**
```sql title=Query theme={null}
SELECT fromUnixTimestampInJodaSyntax(1234334543, 'yyyy-MM-dd HH:mm:ss', 'UTC') AS DateTime
```
```response title=Response theme={null}
┌─DateTime────────────┐
│ 2009-02-11 06:42:23 │
└─────────────────────┘
```
## localtime
أُضيف في: v26.7.0
يعيد الوقت الحالي من اليوم وفق المنطقة الزمنية الخاصة بالخادم (أو الجلسة) في لحظة تحليل الاستعلام.
الدالة تعبير ثابت. وهي `LOCALTIME` القياسية في SQL / PostgreSQL، وتكافئ `CAST(now() AS Time)`.
**البنية**
```sql theme={null}
localtime()
```
**المعاملات**
* لا يوجد.
**القيمة المُعادة**
يعيد الوقت الحالي. [`Time`](/ar/reference/data-types/time)
**أمثلة**
**صيغة SQL القياسية من دون أقواس**
```sql title=Query theme={null}
SELECT LOCALTIME
```
```response title=Response theme={null}
┌───────LOCALTIME─┐
│ 07:42:09 │
└─────────────────┘
```
## makeDate
أُضيفت في: v22.6.0
تنشئ قيمة `Date` من أحد الخيارين التاليين:
* سنة وشهر ويوم
* سنة ورقم اليوم في السنة
**الصيغة**
```sql theme={null}
makeDate(year, month, day)
makeDate(year, day_of_year)
```
**الوسيطات**
* `year` — رقم السنة. [`(U)Int*`](/ar/reference/data-types/int-uint) أو [`Float*`](/ar/reference/data-types/float) أو [`Decimal`](/ar/reference/data-types/decimal)
* `month` — رقم الشهر (1-12). [`(U)Int*`](/ar/reference/data-types/int-uint) أو [`Float*`](/ar/reference/data-types/float) أو [`Decimal`](/ar/reference/data-types/decimal)
* `day` — رقم اليوم في الشهر (1-31). [`(U)Int*`](/ar/reference/data-types/int-uint) أو [`Float*`](/ar/reference/data-types/float) أو [`Decimal`](/ar/reference/data-types/decimal)
* `day_of_year` — رقم اليوم في السنة (1-365). [`(U)Int*`](/ar/reference/data-types/int-uint) أو [`Float*`](/ar/reference/data-types/float) أو [`Decimal`](/ar/reference/data-types/decimal)
**القيمة المعادة**
تعيد قيمة `Date` مُنشأة من الوسيطات المقدَّمة [`Date`](/ar/reference/data-types/date)
**أمثلة**
**إنشاء Date من سنة وشهر ويوم**
```sql title=Query theme={null}
SELECT makeDate(2023, 2, 28) AS date;
```
```response title=Response theme={null}
┌───────date─┐
│ 2023-02-28 │
└────────────┘
```
**Date من السنة ويوم السنة**
```sql title=Query theme={null}
SELECT makeDate(2023, 42) AS date;
```
```response title=Response theme={null}
┌───────date─┐
│ 2023-02-11 │
└────────────┘
```
## makeDate32
أُضيفت في: v22.6.0
تُنشئ `Date32` من أحد الخيارين التاليين:
* سنة وشهر ويوم
* سنة ويوم من أيام السنة
**الصياغة**
```sql theme={null}
makeDate32(year, month, day)
makeDate32(year, day_of_year)
```
**الوسائط**
* `year` — رقم السنة. [`(U)Int*`](/ar/reference/data-types/int-uint) أو [`Float*`](/ar/reference/data-types/float) أو [`Decimal`](/ar/reference/data-types/decimal)
* `month` — رقم الشهر (1-12). [`(U)Int*`](/ar/reference/data-types/int-uint) أو [`Float*`](/ar/reference/data-types/float) أو [`Decimal`](/ar/reference/data-types/decimal)
* `day` — رقم اليوم في الشهر (1-31). [`(U)Int*`](/ar/reference/data-types/int-uint) أو [`Float*`](/ar/reference/data-types/float) أو [`Decimal`](/ar/reference/data-types/decimal)
* `day_of_year` — رقم اليوم في السنة (1-365). [`(U)Int*`](/ar/reference/data-types/int-uint) أو [`Float*`](/ar/reference/data-types/float) أو [`Decimal`](/ar/reference/data-types/decimal)
**القيمة المعادة**
يعيد قيمة `Date32` مُنشأة من الوسائط المقدَّمة [`Date32`](/ar/reference/data-types/date32)
**أمثلة**
**`Date32` من سنة وشهر ويوم**
```sql title=Query theme={null}
SELECT makeDate(2023, 2, 28) AS date;
```
```response title=Response theme={null}
┌───────date─┐
│ 2023-02-28 │
└────────────┘
```
**Date32 من السنة ورقم اليوم في السنة**
```sql title=Query theme={null}
SELECT makeDate(2023, 42) AS date;
```
```response title=Response theme={null}
┌───────date─┐
│ 2023-02-11 │
└────────────┘
```
## makeDateTime
أُضيفت في: v22.6.0
تنشئ قيمة `DateTime` من السنة والشهر واليوم والساعة والدقيقة والثانية، مع timezone اختياري.
**الصيغة**
```sql theme={null}
makeDateTime(year, month, day, hour, minute, second[, timezone])
```
**الوسيطات**
* `year` — رقم السنة. [`(U)Int*`](/ar/reference/data-types/int-uint) أو [`Float*`](/ar/reference/data-types/float) أو [`Decimal`](/ar/reference/data-types/decimal)
* `month` — رقم الشهر (1-12). [`(U)Int*`](/ar/reference/data-types/int-uint) أو [`Float*`](/ar/reference/data-types/float) أو [`Decimal`](/ar/reference/data-types/decimal)
* `day` — يوم من الشهر (1-31). [`(U)Int*`](/ar/reference/data-types/int-uint) أو [`Float*`](/ar/reference/data-types/float) أو [`Decimal`](/ar/reference/data-types/decimal)
* `hour` — الساعة (0-23). [`(U)Int*`](/ar/reference/data-types/int-uint) أو [`Float*`](/ar/reference/data-types/float) أو [`Decimal`](/ar/reference/data-types/decimal)
* `minute` — الدقيقة (0-59). [`(U)Int*`](/ar/reference/data-types/int-uint) أو [`Float*`](/ar/reference/data-types/float) أو [`Decimal`](/ar/reference/data-types/decimal)
* `second` — الثانية (0-59). [`(U)Int*`](/ar/reference/data-types/int-uint) أو [`Float*`](/ar/reference/data-types/float) أو [`Decimal`](/ar/reference/data-types/decimal)
* `timezone` — اسم المنطقة الزمنية. [`String`](/ar/reference/data-types/string)
**القيمة المعادة**
تعيد قيمة `DateTime` مُنشأة من الوسيطات المقدَّمة [`DateTime`](/ar/reference/data-types/datetime)
**أمثلة**
**DateTime من السنة والشهر واليوم والساعة والدقيقة والثانية**
```sql title=Query theme={null}
SELECT makeDateTime(2023, 2, 28, 17, 12, 33) AS DateTime;
```
```response title=Response theme={null}
┌────────────DateTime─┐
│ 2023-02-28 17:12:33 │
└─────────────────────┘
```
## makeDateTime64
أُضيفت في: v22.6.0
تنشئ قيمة `DateTime64` من السنة والشهر واليوم والساعة والدقيقة والثانية، مع جزء كسري اختياري، ودقة، ومنطقة زمنية.
**البنية**
```sql theme={null}
makeDateTime64(year, month, day, hour, minute, second[, fraction[, precision[, timezone]]])
```
**الوسائط**
* `year` — رقم السنة. [`(U)Int*`](/ar/reference/data-types/int-uint) أو [`Float*`](/ar/reference/data-types/float) أو [`Decimal`](/ar/reference/data-types/decimal)
* `month` — رقم الشهر (1-12). [`(U)Int*`](/ar/reference/data-types/int-uint) أو [`Float*`](/ar/reference/data-types/float) أو [`Decimal`](/ar/reference/data-types/decimal)
* `day` — يوم الشهر (1-31). [`(U)Int*`](/ar/reference/data-types/int-uint) أو [`Float*`](/ar/reference/data-types/float) أو [`Decimal`](/ar/reference/data-types/decimal)
* `hour` — الساعة (0-23). [`(U)Int*`](/ar/reference/data-types/int-uint) أو [`Float*`](/ar/reference/data-types/float) أو [`Decimal`](/ar/reference/data-types/decimal)
* `minute` — الدقيقة (0-59). [`(U)Int*`](/ar/reference/data-types/int-uint) أو [`Float*`](/ar/reference/data-types/float) أو [`Decimal`](/ar/reference/data-types/decimal)
* `second` — الثانية (0-59). [`(U)Int*`](/ar/reference/data-types/int-uint) أو [`Float*`](/ar/reference/data-types/float) أو [`Decimal`](/ar/reference/data-types/decimal)
* `fraction` — الجزء الكسري من الثانية. [`(U)Int*`](/ar/reference/data-types/int-uint) أو [`Float*`](/ar/reference/data-types/float) أو [`Decimal`](/ar/reference/data-types/decimal)
* `precision` — دقة الجزء الكسري (0-9). [`UInt8`](/ar/reference/data-types/int-uint)
* `timezone` — اسم المنطقة الزمنية. [`String`](/ar/reference/data-types/string)
**القيمة المُعادة**
تُرجِع قيمة `DateTime64` مُنشأة من الوسائط المُعطاة [`DateTime64`](/ar/reference/data-types/datetime64)
**أمثلة**
**DateTime64 من السنة والشهر واليوم والساعة والدقيقة والثانية**
```sql title=Query theme={null}
SELECT makeDateTime64(2023, 5, 15, 10, 30, 45, 779, 5);
```
```response title=Response theme={null}
┌─makeDateTime64(2023, 5, 15, 10, 30, 45, 779, 5)─┐
│ 2023-05-15 10:30:45.00779 │
└─────────────────────────────────────────────────┘
```
## monthName
أُضيف في: v22.1.0
تُرجع اسم الشهر كسلسلة نصية من قيمة من نوع تاريخ أو تاريخ مع وقت.
**البنية**
```sql theme={null}
monthName(datetime)
```
**الوسيطات**
* `datetime` — تاريخ أو تاريخ يتضمن وقتًا. [`Date`](/ar/reference/data-types/date) أو [`Date32`](/ar/reference/data-types/date32) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
**القيمة المُعادة**
يعيد اسم الشهر. [`String`](/ar/reference/data-types/string)
**أمثلة**
**الحصول على اسم الشهر من التاريخ**
```sql title=Query theme={null}
WITH toDateTime('2021-04-14 11:22:33') AS date_value
SELECT monthName(date_value)
```
```response title=Response theme={null}
┌─monthName(date_value)─┐
│ April │
└───────────────────────┘
```
## now
ظهرت في: v1.1.0
تعيد التاريخ والوقت الحاليين عند لحظة تحليل الاستعلام. الدالة تعبير ثابت.
**الصياغة**
```sql theme={null}
now([timezone])
```
**الأسماء البديلة**: `localtimestamp`, `current_timestamp`
**الوسائط**
* `timezone` — اختياري. اسم المنطقة الزمنية للقيمة المُعادة. [`String`](/ar/reference/data-types/string)
**القيمة المُعادة**
يعيد التاريخ والوقت الحاليَّين. [`DateTime`](/ar/reference/data-types/datetime)
**أمثلة**
**استعلام بدون منطقة زمنية**
```sql title=Query theme={null}
SELECT now()
```
```response title=Response theme={null}
┌───────────────now()─┐
│ 2020-10-17 07:42:09 │
└─────────────────────┘
```
**استعلام مع تحديد المنطقة الزمنية**
```sql title=Query theme={null}
SELECT now('Asia/Istanbul')
```
```response title=Response theme={null}
┌─now('Asia/Istanbul')─┐
│ 2020-10-17 10:42:23 │
└──────────────────────┘
```
**صياغة SQL القياسية دون أقواس**
```sql title=Query theme={null}
SELECT NOW, CURRENT_TIMESTAMP
```
```response title=Response theme={null}
┌─────────────────NOW─┬───CURRENT_TIMESTAMP─┐
│ 2020-10-17 07:42:19 │ 2020-10-17 07:42:19 │
└─────────────────────┴─────────────────────┘
```
## now64
أُضيفت في: v20.1.0
تعيد التاريخ والوقت الحاليَّين بدقة أجزاء الثانية عند لحظة تحليل الاستعلام. الدالة تعبير ثابت.
**البنية**
```sql theme={null}
now64([scale[, timezone]])
```
**المعاملات**
* `scale` — اختياري. حجم الخطوة (الدقة): `10^-precision` ثانية. النطاق الصالح: \[0 : 9]. تُستخدم عادةً القيم 3 (افتراضي) (مللي ثانية)، و6 (ميكروثانية)، و9 (نانوثانية). [`UInt8`](/ar/reference/data-types/int-uint)
* `timezone` — اختياري. اسم المنطقة الزمنية للقيمة المُعادة. [`String`](/ar/reference/data-types/string)
**القيمة المُعادة**
تعيد التاريخ والوقت الحاليين بدقة أجزاء من الثانية. [`DateTime64`](/ar/reference/data-types/datetime64)
**أمثلة**
**استعلام بدقة افتراضية ومخصّصة**
```sql title=Query theme={null}
SELECT now64(), now64(9, 'Asia/Istanbul')
```
```response title=Response theme={null}
┌─────────────────now64()─┬─────now64(9, 'Asia/Istanbul')─┐
│ 2022-08-21 19:34:26.196 │ 2022-08-21 22:34:26.196542766 │
└─────────────────────────┴───────────────────────────────┘
```
## nowInBlock
أُضيفت في: v22.8.0
تعيد التاريخ والوقت الحاليين عند معالجة كل كتلة من البيانات. وعلى عكس الدالة [`now`](#now)، فهي ليست تعبيرًا ثابتًا، وستختلف القيمة المعادة من كتلة إلى أخرى في الاستعلامات طويلة التشغيل.
من المنطقي استخدام هذه الدالة لتوليد الوقت الحالي في استعلامات `INSERT SELECT` طويلة التشغيل.
**البنية**
```sql theme={null}
nowInBlock([timezone])
```
**الوسيطات**
* `timezone` — اختياري. اسم المنطقة الزمنية للقيمة المعادة. [`String`](/ar/reference/data-types/string)
**القيمة المعادة**
تعيد التاريخ والوقت الحاليين في لحظة معالجة كل كتلة من البيانات. [`DateTime`](/ar/reference/data-types/datetime)
**أمثلة**
**الفرق عن الدالة now()**
```sql title=Query theme={null}
SELECT
now(),
nowInBlock(),
sleep(1)
FROM numbers(3)
SETTINGS max_block_size = 1
FORMAT PrettyCompactMonoBlock
```
```response title=Response theme={null}
┌───────────────now()─┬────────nowInBlock()─┬─sleep(1)─┐
│ 2022-08-21 19:41:19 │ 2022-08-21 19:41:19 │ 0 │
│ 2022-08-21 19:41:19 │ 2022-08-21 19:41:20 │ 0 │
│ 2022-08-21 19:41:19 │ 2022-08-21 19:41:21 │ 0 │
└─────────────────────┴─────────────────────┴──────────┘
```
## nowInBlock64
استُحدثت في: v25.8.0
تعيد التاريخ والوقت الحاليين عند معالجة كل كتلة من البيانات، وذلك بالمللي ثانية. وعلى خلاف الدالة [now64](#now64)، فهي ليست تعبيرًا ثابتًا، وستكون القيمة المُعادة مختلفة من كتلة إلى أخرى في الاستعلامات طويلة التشغيل.
يُستحسن استخدام هذه الدالة لتوليد الوقت الحالي في استعلامات `INSERT SELECT` طويلة التشغيل.
**الصياغة**
```sql theme={null}
nowInBlock64([scale[, timezone]])
```
**المعاملات**
* `scale` — اختياري. حجم الـ tick (الدقة): 10^-precision ثانية. النطاق الصالح: \[0 : 9]. تُستخدم عادةً القيم: 3 (افتراضيًا) (ميلي ثانية)، 6 (ميكروثانية)، 9 (نانوثانية). [`UInt8`](/ar/reference/data-types/int-uint)
* `timezone` — اختياري. اسم المنطقة الزمنية للقيمة المعادة. [`String`](/ar/reference/data-types/string)
**القيمة المعادة**
تعيد التاريخ والوقت الحاليين عند معالجة كل كتلة من البيانات، مع دقة أقل من الثانية. [`DateTime64`](/ar/reference/data-types/datetime64)
**أمثلة**
**الفرق مع الدالة now64()**
```sql title=Query theme={null}
SELECT
now64(),
nowInBlock64(),
sleep(1)
FROM numbers(3)
SETTINGS max_block_size = 1
FORMAT PrettyCompactMonoBlock
```
```response title=Response theme={null}
┌─────────────────now64()─┬──────────nowInBlock64()─┬─sleep(1)─┐
│ 2025-07-29 17:07:29.526 │ 2025-07-29 17:07:29.534 │ 0 │
│ 2025-07-29 17:07:29.526 │ 2025-07-29 17:07:30.535 │ 0 │
│ 2025-07-29 17:07:29.526 │ 2025-07-29 17:07:31.535 │ 0 │
└─────────────────────────┴─────────────────────────┴──────────┘
```
## serverTimezone
أُضيفت في: v23.6.0
تُرجِع المنطقة الزمنية للخادم، أي قيمة إعداد [`timezone`](/ar/reference/settings/server-settings/settings#timezone).
إذا نُفِّذت الدالة في سياق جدول موزّع، فإنها تُنشئ عمودًا عاديًا بقيم تخص كل shard. وإلا، فإنها تُنتج قيمة ثابتة.
**الصيغة**
```sql theme={null}
serverTimezone()
```
**الأسماء المستعارة**: `serverTimeZone`
**الوسائط**
* لا شيء.
**القيمة المُعادة**
تُرجع المنطقة الزمنية للخادم على هيئة [`String`](/ar/reference/data-types/string)
**أمثلة**
**مثال على الاستخدام**
```sql title=Query theme={null}
SELECT serverTimeZone()
```
```response title=Response theme={null}
┌─serverTimeZone()─┐
│ UTC │
└──────────────────┘
```
## subDate
أُضيف في: v23.9.0
يطرح الفاصل الزمني من التاريخ أو التاريخ والوقت المُقدَّمين، أو من تاريخ أو تاريخ ووقت مُرمَّزين كسلسلة.
إذا نتج عن الطرح قيمة تقع خارج حدود نوع البيانات، فالنتيجة غير معرّفة.
**البنية**
```sql theme={null}
subDate(datetime, interval)
```
**الوسيطات**
* `datetime` — التاريخ أو التاريخ والوقت الذي يُطرَح منه `interval`. [`Date`](/ar/reference/data-types/date) أو [`Date32`](/ar/reference/data-types/date32) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
* `interval` — الفاصل الزمني المراد طرحه. [`Interval`](/ar/reference/data-types/int-uint)
**القيمة المُعادة**
يعيد تاريخًا أو تاريخًا ووقتًا ناتجًا عن طرح `interval` من `datetime`. [`Date`](/ar/reference/data-types/date) أو [`Date32`](/ar/reference/data-types/date32) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
**أمثلة**
**طرح فاصل زمني من تاريخ**
```sql title=Query theme={null}
SELECT subDate(toDate('2018-01-01'), INTERVAL 3 YEAR)
```
```response title=Response theme={null}
┌─subDate(toDate('2018-01-01'), toIntervalYear(3))─┐
│ 2015-01-01 │
└──────────────────────────────────────────────────┘
```
## subtractDays
أُضيفت في: v1.1.0
يطرح عددًا محددًا من الأيام من تاريخ، أو تاريخ ووقت، أو تاريخ أو تاريخ ووقت مُرمَّزَين كسلسلة نصية.
**البنية**
```sql theme={null}
subtractDays(datetime, num)
```
**الوسيطات**
* `datetime` — تاريخ أو تاريخ يتضمن وقتًا، يُطرح منه العدد المحدد من الأيام. [`Date`](/ar/reference/data-types/date) أو [`Date32`](/ar/reference/data-types/date32) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64) أو [`String`](/ar/reference/data-types/string)
* `num` — عدد الأيام المطلوب طرحها. [`(U)Int*`](/ar/reference/data-types/int-uint) أو [`Float*`](/ar/reference/data-types/float)
**القيمة المعادة**
يعيد `datetime` بعد طرح `num` يومًا منه. [`Date`](/ar/reference/data-types/date) أو [`Date32`](/ar/reference/data-types/date32) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
**أمثلة**
**طرح الأيام من أنواع التاريخ المختلفة**
```sql title=Query theme={null}
WITH
toDate('2024-01-01') AS date,
toDateTime('2024-01-01 00:00:00') AS date_time,
'2024-01-01 00:00:00' AS date_time_string
SELECT
subtractDays(date, 31) AS subtract_days_with_date,
subtractDays(date_time, 31) AS subtract_days_with_date_time,
subtractDays(date_time_string, 31) AS subtract_days_with_date_time_string
```
```response title=Response theme={null}
┌─subtract_days_with_date─┬─subtract_days_with_date_time─┬─subtract_days_with_date_time_string─┐
│ 2023-12-01 │ 2023-12-01 00:00:00 │ 2023-12-01 00:00:00.000 │
└─────────────────────────┴──────────────────────────────┴─────────────────────────────────────┘
```
**استخدام صيغة INTERVAL البديلة**
```sql title=Query theme={null}
SELECT dateSub('1998-06-16'::Date, INTERVAL 10 day)
```
```response title=Response theme={null}
┌─minus(CAST('⋯valDay(10))─┐
│ 1998-06-06 │
└──────────────────────────┘
```
## subtractHours
قُدِّمت في: v1.1.0
تطرح عددًا محددًا من الساعات من تاريخ، أو تاريخ ووقت، أو تاريخ مُمثَّل كسلسلة نصية، أو تاريخ ووقت مُمثَّل كسلسلة نصية.
**البنية**
```sql theme={null}
subtractHours(datetime, num)
```
**الوسيطات**
* `datetime` — `Date` أو تاريخ أو تاريخ مع وقت يُطرح منه العدد المحدد من الساعات. [`Date`](/ar/reference/data-types/date) أو [`Date32`](/ar/reference/data-types/date32) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64) أو [`String`](/ar/reference/data-types/string)
* `num` — عدد الساعات المراد طرحه. [`(U)Int*`](/ar/reference/data-types/int-uint) أو [`Float*`](/ar/reference/data-types/float)
**القيمة المعادة**
يُرجع `datetime` بعد طرح `num` ساعة منه [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64(3)`](/ar/reference/data-types/datetime64)
**أمثلة**
**طرح الساعات من أنواع تاريخ مختلفة**
```sql title=Query theme={null}
WITH
toDate('2024-01-01') AS date,
toDateTime('2024-01-01 00:00:00') AS date_time,
'2024-01-01 00:00:00' AS date_time_string
SELECT
subtractHours(date, 12) AS subtract_hours_with_date,
subtractHours(date_time, 12) AS subtract_hours_with_date_time,
subtractHours(date_time_string, 12) AS subtract_hours_with_date_time_string
```
```response title=Response theme={null}
┌─subtract_hours_with_date─┬─subtract_hours_with_date_time─┬─subtract_hours_with_date_time_string─┐
│ 2023-12-31 12:00:00 │ 2023-12-31 12:00:00 │ 2023-12-31 12:00:00.000 │
└──────────────────────────┴───────────────────────────────┴──────────────────────────────────────┘
```
**استخدام الصياغة البديلة لـ INTERVAL**
```sql title=Query theme={null}
SELECT dateSub('1998-06-16'::Date, INTERVAL 10 hour)
```
```response title=Response theme={null}
┌─minus(CAST('⋯alHour(10))─┐
│ 1998-06-15 14:00:00 │
└──────────────────────────┘
```
## subtractInterval
أُضيف في: v22.11.0
يضيف قيمة interval سالبة إلى interval أخرى أو إلى tuple من قيم interval.
ملاحظة: ستُدمج قيم interval من النوع نفسه في قيمة interval واحدة. على سبيل المثال، إذا تم تمرير `toIntervalDay(2)` و `toIntervalDay(1)`
فستكون النتيجة `(1)` بدلًا من `(2,1)`.
**الصياغة**
```sql theme={null}
subtractInterval(interval_1, interval_2)
```
**الوسائط**
* `interval_1` — الفاصل الزمني الأول أو Tuple من الفواصل الزمنية. [`Interval`](/ar/reference/data-types/int-uint) أو [`Tuple(Interval)`](/ar/reference/data-types/tuple)
* `interval_2` — الفاصل الزمني الثاني المراد عكس إشارته. [`Interval`](/ar/reference/data-types/int-uint)
**القيمة المعادة**
تعيد Tuple من الفواصل الزمنية [`Tuple(T)`](/ar/reference/data-types/tuple)
**أمثلة**
**طرح الفواصل الزمنية**
```sql title=Query theme={null}
SELECT subtractInterval(INTERVAL 1 DAY, INTERVAL 1 MONTH);
SELECT subtractInterval((INTERVAL 1 DAY, INTERVAL 1 YEAR), INTERVAL 1 MONTH);
SELECT subtractInterval(INTERVAL 2 DAY, INTERVAL 1 DAY);
```
```response title=Response theme={null}
┌─subtractInterval(toIntervalDay(1), toIntervalMonth(1))─┐
│ (1,-1) │
└────────────────────────────────────────────────────────┘
┌─subtractInterval((toIntervalDay(1), toIntervalYear(1)), toIntervalMonth(1))─┐
│ (1,1,-1) │
└─────────────────────────────────────────────────────────────────────────────┘
┌─subtractInterval(toIntervalDay(2), toIntervalDay(1))─┐
│ (1) │
└──────────────────────────────────────────────────────┘
```
## subtractMicroseconds
أُضيف في: v22.6.0
يطرح عددًا محددًا من الميكروثواني من قيمة تاريخ ووقت أو من قيمة تاريخ ووقت مُرمَّزة كسلسلة نصية.
**الصياغة**
```sql theme={null}
subtractMicroseconds(datetime, num)
```
**الوسائط**
* `datetime` — قيمة تاريخ ووقت يُطرح منها العدد المحدد من الميكروثواني. [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64) أو [`String`](/ar/reference/data-types/string)
* `num` — عدد الميكروثواني المراد طرحه. [`(U)Int*`](/ar/reference/data-types/int-uint) أو [`Float*`](/ar/reference/data-types/float)
**القيمة المُعادة**
تعيد `datetime` بعد طرح `num` ميكروثانية منه [`DateTime64`](/ar/reference/data-types/datetime64)
**أمثلة**
**طرح الميكروثواني من أنواع مختلفة من قيم التاريخ والوقت**
```sql title=Query theme={null}
WITH
toDateTime('2024-01-01 00:00:00') AS date_time,
'2024-01-01 00:00:00' AS date_time_string
SELECT
subtractMicroseconds(date_time, 1000000) AS subtract_microseconds_with_date_time,
subtractMicroseconds(date_time_string, 1000000) AS subtract_microseconds_with_date_time_string
```
```response title=Response theme={null}
┌─subtract_microseconds_with_date_time─┬─subtract_microseconds_with_date_time_string─┐
│ 2023-12-31 23:59:59.000000 │ 2023-12-31 23:59:59.000000 │
└──────────────────────────────────────┴─────────────────────────────────────────────┘
```
**استخدام الصياغة البديلة لـ INTERVAL**
```sql title=Query theme={null}
SELECT dateSub('1998-06-16'::DateTime, INTERVAL 10 microsecond)
```
```response title=Response theme={null}
┌─minus(CAST('1⋯osecond(10))─┐
│ 1998-06-15 23:59:59.999990 │
└────────────────────────────┘
```
## subtractMilliseconds
أُضيفت في: v22.6.0
تطرح عددًا محددًا من المللي ثانية من قيمة تاريخ ووقت أو من قيمة تاريخ ووقت مُرمَّزة كسلسلة نصية.
**الصياغة**
```sql theme={null}
subtractMilliseconds(datetime, num)
```
**الوسيطات**
* `datetime` — قيمة تاريخ ووقت يُطرح منها العدد المحدد من المللي ثانية. [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64) أو [`String`](/ar/reference/data-types/string)
* `num` — عدد المللي ثوانٍ المراد طرحه. [`(U)Int*`](/ar/reference/data-types/int-uint) أو [`Float*`](/ar/reference/data-types/float)
**القيمة المعادة**
تعيد `datetime` بعد طرح `num` مللي ثانية منه [`DateTime64`](/ar/reference/data-types/datetime64)
**أمثلة**
**طرح المللي ثانية من أنواع مختلفة من التاريخ والوقت**
```sql title=Query theme={null}
WITH
toDateTime('2024-01-01 00:00:00') AS date_time,
'2024-01-01 00:00:00' AS date_time_string
SELECT
subtractMilliseconds(date_time, 1000) AS subtract_milliseconds_with_date_time,
subtractMilliseconds(date_time_string, 1000) AS subtract_milliseconds_with_date_time_string
```
```response title=Response theme={null}
┌─subtract_milliseconds_with_date_time─┬─subtract_milliseconds_with_date_time_string─┐
│ 2023-12-31 23:59:59.000 │ 2023-12-31 23:59:59.000 │
└──────────────────────────────────────┴─────────────────────────────────────────────┘
```
**استخدام الصياغة البديلة لـ INTERVAL**
```sql title=Query theme={null}
SELECT dateSub('1998-06-16'::DateTime, INTERVAL 10 millisecond)
```
```response title=Response theme={null}
┌─minus(CAST('⋯second(10))─┐
│ 1998-06-15 23:59:59.990 │
└──────────────────────────┘
```
## subtractMinutes
أُضيف في: v1.1.0
يطرح عددًا محددًا من الدقائق من تاريخ، أو تاريخ ووقت، أو تاريخ أو تاريخ ووقت مُرمَّز كسلسلة.
**الصيغة**
```sql theme={null}
subtractMinutes(datetime, num)
```
**الوسيطات**
* `datetime` — تاريخ أو تاريخ ووقت يُطرح منهما العدد المحدد من الدقائق. [`Date`](/ar/reference/data-types/date) أو [`Date32`](/ar/reference/data-types/date32) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64) أو [`String`](/ar/reference/data-types/string)
* `num` — عدد الدقائق المطلوب طرحه. [`(U)Int*`](/ar/reference/data-types/int-uint) أو [`Float*`](/ar/reference/data-types/float)
**القيمة المعادة**
تعيد `datetime` بعد طرح `num` دقيقة منه من النوع [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64(3)`](/ar/reference/data-types/datetime64)
**أمثلة**
**طرح الدقائق من أنواع تاريخ مختلفة**
```sql title=Query theme={null}
WITH
toDate('2024-01-01') AS date,
toDateTime('2024-01-01 00:00:00') AS date_time,
'2024-01-01 00:00:00' AS date_time_string
SELECT
subtractMinutes(date, 30) AS subtract_minutes_with_date,
subtractMinutes(date_time, 30) AS subtract_minutes_with_date_time,
subtractMinutes(date_time_string, 30) AS subtract_minutes_with_date_time_string
```
```response title=Response theme={null}
┌─subtract_minutes_with_date─┬─subtract_minutes_with_date_time─┬─subtract_minutes_with_date_time_string─┐
│ 2023-12-31 23:30:00 │ 2023-12-31 23:30:00 │ 2023-12-31 23:30:00.000 │
└────────────────────────────┴─────────────────────────────────┴────────────────────────────────────────┘
```
**استخدام صيغة INTERVAL البديلة**
```sql title=Query theme={null}
SELECT dateSub('1998-06-16'::Date, INTERVAL 10 minute)
```
```response title=Response theme={null}
┌─minus(CAST('⋯Minute(10))─┐
│ 1998-06-15 23:50:00 │
└──────────────────────────┘
```
## subtractMonths
أُضيف في: v1.1.0
يطرح عددًا محددًا من الأشهر من تاريخ، أو تاريخ ووقت، أو تاريخ مُرمَّز كسلسلة نصية، أو تاريخ ووقت مُرمَّز كسلسلة نصية.
**الصيغة**
```sql theme={null}
subtractMonths(datetime, num)
```
**الوسيطات**
* `datetime` — تاريخ أو تاريخ مع وقت يُطرح منه عدد الأشهر المحدد. [`Date`](/ar/reference/data-types/date) أو [`Date32`](/ar/reference/data-types/date32) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64) أو [`String`](/ar/reference/data-types/string)
* `num` — عدد الأشهر المراد طرحه. [`(U)Int*`](/ar/reference/data-types/int-uint) أو [`Float*`](/ar/reference/data-types/float)
**القيمة المعادة**
تعيد `datetime` بعد طرح `num` شهرًا منه [`Date`](/ar/reference/data-types/date) أو [`Date32`](/ar/reference/data-types/date32) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
**أمثلة**
**طرح الأشهر من أنواع تاريخ مختلفة**
```sql title=Query theme={null}
WITH
toDate('2024-01-01') AS date,
toDateTime('2024-01-01 00:00:00') AS date_time,
'2024-01-01 00:00:00' AS date_time_string
SELECT
subtractMonths(date, 1) AS subtract_months_with_date,
subtractMonths(date_time, 1) AS subtract_months_with_date_time,
subtractMonths(date_time_string, 1) AS subtract_months_with_date_time_string
```
```response title=Response theme={null}
┌─subtract_months_with_date─┬─subtract_months_with_date_time─┬─subtract_months_with_date_time_string─┐
│ 2023-12-01 │ 2023-12-01 00:00:00 │ 2023-12-01 00:00:00.000 │
└───────────────────────────┴────────────────────────────────┴───────────────────────────────────────┘
```
**استخدام الصياغة البديلة لـ INTERVAL**
```sql title=Query theme={null}
SELECT dateSub('1998-06-16'::Date, INTERVAL 10 month)
```
```response title=Response theme={null}
┌─minus(CAST('⋯lMonth(10))─┐
│ 1997-08-16 │
└──────────────────────────┘
```
## subtractNanoseconds
أُضيف في: v20.1.0
يطرح عددًا محددًا من النانوثواني من قيمة تاريخ ووقت أو من تاريخ ووقت مُرمَّز كسلسلة نصية.
**البنية**
```sql theme={null}
subtractNanoseconds(datetime, num)
```
**الوسيطات**
* `datetime` — تاريخ ووقت يُطرح منه عدد محدد من النانوثواني. [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64) أو [`String`](/ar/reference/data-types/string)
* `num` — عدد النانوثواني المطلوب طرحه. [`(U)Int*`](/ar/reference/data-types/int-uint) أو [`Float*`](/ar/reference/data-types/float)
**القيمة المعادة**
تعيد القيمة `datetime` بعد طرح `num` نانوثانية منها، من النوع [`DateTime64`](/ar/reference/data-types/datetime64)
**أمثلة**
**طرح النانوثواني من أنواع التاريخ والوقت المختلفة**
```sql title=Query theme={null}
WITH
toDateTime('2024-01-01 00:00:00') AS date_time,
'2024-01-01 00:00:00' AS date_time_string
SELECT
subtractNanoseconds(date_time, 1000) AS subtract_nanoseconds_with_date_time,
subtractNanoseconds(date_time_string, 1000) AS subtract_nanoseconds_with_date_time_string
```
```response title=Response theme={null}
┌─subtract_nanoseconds_with_date_time─┬─subtract_nanoseconds_with_date_time_string─┐
│ 2023-12-31 23:59:59.999999000 │ 2023-12-31 23:59:59.999999000 │
└─────────────────────────────────────┴────────────────────────────────────────────┘
```
**استخدام صيغة INTERVAL البديلة**
```sql title=Query theme={null}
SELECT dateSub('1998-06-16'::DateTime, INTERVAL 10 nanosecond)
```
```response title=Response theme={null}
┌─minus(CAST('19⋯anosecond(10))─┐
│ 1998-06-15 23:59:59.999999990 │
└───────────────────────────────┘
```
## subtractQuarters
أُضيف في: v20.1.0
يطرح عددًا محددًا من أرباع السنة من تاريخ، أو تاريخ ووقت، أو تاريخ مُرمَّز كسلسلة نصية، أو تاريخ ووقت مُرمَّز كسلسلة نصية.
**الصيغة**
```sql theme={null}
subtractQuarters(datetime, num)
```
**الوسائط**
* `datetime` — تاريخ أو تاريخ مع وقت يُطرح منه العدد المحدد من أرباع السنة. [`Date`](/ar/reference/data-types/date) أو [`Date32`](/ar/reference/data-types/date32) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64) أو [`String`](/ar/reference/data-types/string)
* `num` — عدد أرباع السنة المراد طرحه. [`(U)Int*`](/ar/reference/data-types/int-uint) أو [`Float*`](/ar/reference/data-types/float)
**القيمة المعادة**
يعيد `datetime` بعد طرح `num` من أرباع السنة. [`Date`](/ar/reference/data-types/date) أو [`Date32`](/ar/reference/data-types/date32) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
**أمثلة**
**طرح أرباع السنة من أنواع تاريخ مختلفة**
```sql title=Query theme={null}
WITH
toDate('2024-01-01') AS date,
toDateTime('2024-01-01 00:00:00') AS date_time,
'2024-01-01 00:00:00' AS date_time_string
SELECT
subtractQuarters(date, 1) AS subtract_quarters_with_date,
subtractQuarters(date_time, 1) AS subtract_quarters_with_date_time,
subtractQuarters(date_time_string, 1) AS subtract_quarters_with_date_time_string
```
```response title=Response theme={null}
┌─subtract_quarters_with_date─┬─subtract_quarters_with_date_time─┬─subtract_quarters_with_date_time_string─┐
│ 2023-10-01 │ 2023-10-01 00:00:00 │ 2023-10-01 00:00:00.000 │
└─────────────────────────────┴──────────────────────────────────┴─────────────────────────────────────────┘
```
**استخدام بنية INTERVAL البديلة**
```sql title=Query theme={null}
SELECT dateSub('1998-06-16'::Date, INTERVAL 10 quarter)
```
```response title=Response theme={null}
┌─minus(CAST('1⋯Quarter(10))─┐
│ 1996-09-16 │
└───────────────────────────┘
```
## subtractSeconds
أُضيف في: v1.1.0
يطرح عددًا محددًا من الثواني من تاريخ، أو تاريخ ووقت، أو تاريخ أو تاريخ ووقت مُرمَّزَين كسلسلة نصية.
**الصيغة**
```sql theme={null}
subtractSeconds(datetime, num)
```
**الوسائط**
* `datetime` — تاريخ أو تاريخ مع وقت يُطرح منه العدد المحدد من الثواني. [`Date`](/ar/reference/data-types/date) أو [`Date32`](/ar/reference/data-types/date32) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64) أو [`String`](/ar/reference/data-types/string)
* `num` — عدد الثواني المطلوب طرحها. [`(U)Int*`](/ar/reference/data-types/int-uint) أو [`Float*`](/ar/reference/data-types/float)
**القيمة المُعادة**
يعيد `datetime` بعد طرح `num` ثانية منه [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64(3)`](/ar/reference/data-types/datetime64)
**أمثلة**
**طرح الثواني من أنواع تاريخ مختلفة**
```sql title=Query theme={null}
WITH
toDate('2024-01-01') AS date,
toDateTime('2024-01-01 00:00:00') AS date_time,
'2024-01-01 00:00:00' AS date_time_string
SELECT
subtractSeconds(date, 60) AS subtract_seconds_with_date,
subtractSeconds(date_time, 60) AS subtract_seconds_with_date_time,
subtractSeconds(date_time_string, 60) AS subtract_seconds_with_date_time_string
```
```response title=Response theme={null}
┌─subtract_seconds_with_date─┬─subtract_seconds_with_date_time─┬─subtract_seconds_with_date_time_string─┐
│ 2023-12-31 23:59:00 │ 2023-12-31 23:59:00 │ 2023-12-31 23:59:00.000 │
└────────────────────────────┴─────────────────────────────────┴────────────────────────────────────────┘
```
**استخدام صيغة INTERVAL البديلة**
```sql title=Query theme={null}
SELECT dateSub('1998-06-16'::Date, INTERVAL 10 second)
```
```response title=Response theme={null}
┌─minus(CAST('⋯Second(10))─┐
│ 1998-06-15 23:59:50 │
└──────────────────────────┘
```
## subtractTupleOfIntervals
قُدِّم في: v22.11.0
يطرح بالتتابع مجموعة مرتبة من الفواصل الزمنية من تاريخ أو من تاريخ ووقت.
**البنية**
```sql theme={null}
subtractTupleOfIntervals(datetime, intervals)
```
**الوسيطات**
* `datetime` — تاريخ أو تاريخ ووقت تُطرح منه الفواصل الزمنية. [`Date`](/ar/reference/data-types/date) أو [`Date32`](/ar/reference/data-types/date32) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
* `intervals` — Tuple من الفواصل الزمنية تُطرح من `datetime`. [`Tuple(Interval)`](/ar/reference/data-types/tuple)
**القيمة المُعادة**
يُرجع `date` بعد طرح `intervals` منه [`Date`](/ar/reference/data-types/date) أو [`Date32`](/ar/reference/data-types/date32) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
**أمثلة**
**طرح Tuple من الفواصل الزمنية من التاريخ**
```sql title=Query theme={null}
WITH toDate('2018-01-01') AS date SELECT subtractTupleOfIntervals(date, (INTERVAL 1 DAY, INTERVAL 1 YEAR))
```
```response title=Response theme={null}
┌─subtractTupl⋯alYear(1)))─┐
│ 2016-12-31 │
└──────────────────────────┘
```
## subtractWeeks
أُضيفت في: v1.1.0
تطرح عددًا محددًا من الأسابيع من تاريخ، أو تاريخ ووقت، أو تاريخ أو تاريخ ووقت مُرمَّز كسلسلة نصية.
**البنية**
```sql theme={null}
subtractWeeks(datetime, num)
```
**الوسيطات**
* `datetime` — `Date` أو تاريخ مع وقت يُطرح منه العدد المحدد من الأسابيع. [`Date`](/ar/reference/data-types/date) أو [`Date32`](/ar/reference/data-types/date32) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64) أو [`String`](/ar/reference/data-types/string)
* `num` — عدد الأسابيع المطلوب طرحه. [`(U)Int*`](/ar/reference/data-types/int-uint) أو [`Float*`](/ar/reference/data-types/float)
**القيمة المعادة**
تعيد `datetime` بعد طرح `num` أسبوعًا منه [`Date`](/ar/reference/data-types/date) أو [`Date32`](/ar/reference/data-types/date32) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
**أمثلة**
**طرح أسابيع من أنواع تاريخ مختلفة**
```sql title=Query theme={null}
WITH
toDate('2024-01-01') AS date,
toDateTime('2024-01-01 00:00:00') AS date_time,
'2024-01-01 00:00:00' AS date_time_string
SELECT
subtractWeeks(date, 1) AS subtract_weeks_with_date,
subtractWeeks(date_time, 1) AS subtract_weeks_with_date_time,
subtractWeeks(date_time_string, 1) AS subtract_weeks_with_date_time_string
```
```response title=Response theme={null}
┌─subtract_weeks_with_date─┬─subtract_weeks_with_date_time─┬─subtract_weeks_with_date_time_string─┐
│ 2023-12-25 │ 2023-12-25 00:00:00 │ 2023-12-25 00:00:00.000 │
└──────────────────────────┴───────────────────────────────┴──────────────────────────────────────┘
```
**استخدام صياغة INTERVAL البديلة**
```sql title=Query theme={null}
SELECT dateSub('1998-06-16'::Date, INTERVAL 10 week)
```
```response title=Response theme={null}
┌─minus(CAST('⋯alWeek(10))─┐
│ 1998-04-07 │
└──────────────────────────┘
```
## subtractYears
أُضيف في: v1.1.0
يطرح عددًا محددًا من السنوات من تاريخ، أو تاريخ ووقت، أو تاريخ أو تاريخ ووقت مُمثَّلَين كسلسلة نصية.
**بناء الجملة**
```sql theme={null}
subtractYears(datetime, num)
```
**الوسيطات**
* `datetime` — تاريخ أو تاريخ مع وقت يُطرح منه عدد السنوات المحدد. [`Date`](/ar/reference/data-types/date) أو [`Date32`](/ar/reference/data-types/date32) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64) أو [`String`](/ar/reference/data-types/string)
* `num` — عدد السنوات المطلوب طرحه. [`(U)Int*`](/ar/reference/data-types/int-uint) أو [`Float*`](/ar/reference/data-types/float)
**القيمة المُعادة**
تعيد `datetime` بعد طرح `num` سنة منه. [`Date`](/ar/reference/data-types/date) أو [`Date32`](/ar/reference/data-types/date32) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
**أمثلة**
**طرح السنوات من أنواع تاريخ مختلفة**
```sql title=Query theme={null}
WITH
toDate('2024-01-01') AS date,
toDateTime('2024-01-01 00:00:00') AS date_time,
'2024-01-01 00:00:00' AS date_time_string
SELECT
subtractYears(date, 1) AS subtract_years_with_date,
subtractYears(date_time, 1) AS subtract_years_with_date_time,
subtractYears(date_time_string, 1) AS subtract_years_with_date_time_string
```
```response title=Response theme={null}
┌─subtract_years_with_date─┬─subtract_years_with_date_time─┬─subtract_years_with_date_time_string─┐
│ 2023-01-01 │ 2023-01-01 00:00:00 │ 2023-01-01 00:00:00.000 │
└──────────────────────────┴───────────────────────────────┴──────────────────────────────────────┘
```
**استخدام صيغة INTERVAL البديلة**
```sql title=Query theme={null}
SELECT dateSub('1998-06-16'::Date, INTERVAL 10 year)
```
```response title=Response theme={null}
┌─minus(CAST('⋯alYear(10))─┐
│ 1988-06-16 │
└──────────────────────────┘
```
## timeDiff
أُضيفت في: v23.4.0
تعيد الفرق بالثواني بين تاريخين أو بين قيمتَي تاريخ ووقت.
ويُحسب الفرق على النحو التالي: `enddate` - `startdate`.
هذه الدالة مكافئة لـ `dateDiff('second', startdate, enddate)`.
لحساب الفروق الزمنية بوحدات أخرى (مثل الساعات والأيام والأشهر وما إلى ذلك)، استخدم الدالة [`dateDiff`](#dateDiff) بدلًا من ذلك.
**البنية**
```sql theme={null}
timeDiff(startdate, enddate)
```
**المعاملات**
* `startdate` — أول قيمة زمنية تُطرَح (المطروح). [`Date`](/ar/reference/data-types/date) أو [`Date32`](/ar/reference/data-types/date32) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
* `enddate` — ثاني قيمة زمنية يُطرَح منها (المطروح منه). [`Date`](/ar/reference/data-types/date) أو [`Date32`](/ar/reference/data-types/date32) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
**القيمة المُعادة**
تعيد الفرق بين `enddate` و`startdate` معبَّرًا عنه بالثواني. [`Int64`](/ar/reference/data-types/int-uint)
**أمثلة**
**حساب الفرق الزمني بالثواني**
```sql title=Query theme={null}
SELECT timeDiff(toDateTime('2018-01-01 22:00:00'), toDateTime('2018-01-02 23:00:00')) AS res
```
```response title=Response theme={null}
┌───res─┐
│ 90000 │
└───────┘
```
**احسب الفرق الزمني وحوّله إلى ساعات**
```sql title=Query theme={null}
SELECT timeDiff(toDateTime('2018-01-01 22:00:00'), toDateTime('2018-01-02 23:00:00')) / 3600 AS hours
```
```response title=Response theme={null}
┌─hours─┐
│ 25 │
└───────┘
```
**يعادل dateDiff بالثواني**
```sql title=Query theme={null}
SELECT
timeDiff(toDateTime('2021-12-29'), toDateTime('2022-01-01')) AS time_diff_result,
dateDiff('second', toDateTime('2021-12-29'), toDateTime('2022-01-01')) AS date_diff_result
```
```response title=Response theme={null}
┌─time_diff_result─┬─date_diff_result─┐
│ 259200 │ 259200 │
└──────────────────┴──────────────────┘
```
## timeSlot
أُضيف في: v1.1.0
قرّب الوقت إلى بداية فترة زمنية مدتها نصف ساعة.
على الرغم من أن هذه الدالة يمكن أن تأخذ قيماً من النوعين الموسّعين `Date32` و`DateTime64` كوسيط،
فإن تمرير قيمة وقت تقع خارج النطاق المعتاد إليها (من عام 1970 إلى 2149 بالنسبة إلى `Date` / وحتى 2106 بالنسبة إلى `DateTime`) سيؤدي إلى نتائج غير صحيحة.
**الصياغة**
```sql theme={null}
timeSlot(time[, time_zone])
```
**الوسيطات**
* `time` — الوقت المطلوب تقريبه إلى بداية فاصل زمني مدته نصف ساعة. [`DateTime`](/ar/reference/data-types/datetime) أو [`Date32`](/ar/reference/data-types/date32) أو [`DateTime64`](/ar/reference/data-types/datetime64)
* `time_zone` — اختياري. قيمة ثابتة من نوع String أو تعبير يمثّل المنطقة الزمنية. [`String`](/ar/reference/data-types/string)
**القيمة المعادة**
يعيد الوقت بعد تقريبه إلى بداية فاصل زمني مدته نصف ساعة. [`DateTime`](/ar/reference/data-types/datetime)
**أمثلة**
**تقريب الوقت إلى فاصل زمني مدته نصف ساعة**
```sql title=Query theme={null}
SELECT timeSlot(toDateTime('2000-01-02 03:04:05', 'UTC'))
```
```response title=Response theme={null}
┌─timeSlot(toDateTime('2000-01-02 03:04:05', 'UTC'))─┐
│ 2000-01-02 03:00:00 │
└────────────────────────────────────────────────────┘
```
## timeSlots
أُضيف في: v1.1.0
لفترة زمنية تبدأ عند `StartTime` وتستمر لمدة `Duration` ثانية، تُرجِع الدالة مصفوفة من اللحظات الزمنية تتكوّن من نقاط ضمن هذه الفترة بعد تقريبها نزولًا إلى `Size` بالثواني. `Size` وسيط اختياري مضبوط افتراضيًا على 1800 (30 دقيقة).
وهذا ضروري، على سبيل المثال، عند البحث عن مرات عرض الصفحة في الجلسة المقابلة.
بالنسبة إلى `DateTime64`، قد يختلف المقياس الخاص بالقيمة المُعادة عن مقياس `StartTime`. ويُؤخذ أعلى مقياس من بين جميع الوسيطات المُعطاة.
**البنية**
```sql theme={null}
timeSlots(StartTime, Duration[, Size])
```
**الوسيطات**
* `StartTime` — وقت بدء الفاصل الزمني. [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
* `Duration` — مدة الفاصل الزمني بالثواني. [`UInt32`](/ar/reference/data-types/int-uint) أو [`DateTime64`](/ar/reference/data-types/datetime64)
* `Size` — اختياري. حجم الفترات الزمنية بالثواني. القيمة الافتراضية هي 1800 (30 دقيقة). [`UInt32`](/ar/reference/data-types/int-uint) أو [`DateTime64`](/ar/reference/data-types/datetime64)
**القيمة المُعادة**
يعيد مصفوفة من قيم DateTime/DateTime64 (نوع الإرجاع يطابق نوع `StartTime`). بالنسبة إلى DateTime64، قد يختلف مقياس القيمة المُعادة عن مقياس `StartTime` — إذ يُعتمد أعلى مقياس بين جميع الوسيطات المُعطاة. [`Array(DateTime)`](/ar/reference/data-types/array) أو [`Array(DateTime64)`](/ar/reference/data-types/array)
**أمثلة**
**إنشاء فترات زمنية لفاصل زمني**
```sql title=Query theme={null}
SELECT timeSlots(toDateTime('2012-01-01 12:20:00'), toUInt32(600));
SELECT timeSlots(toDateTime('1980-12-12 21:01:02', 'UTC'), toUInt32(600), 299);
SELECT timeSlots(toDateTime64('1980-12-12 21:01:02.1234', 4, 'UTC'), toDecimal64(600.1, 1), toDecimal64(299, 0))
```
```response title=Response theme={null}
┌─timeSlots(toDateTime('2012-01-01 12:20:00'), toUInt32(600))─┐
│ ['2012-01-01 12:00:00','2012-01-01 12:30:00'] │
└─────────────────────────────────────────────────────────────┘
┌─timeSlots(toDateTime('1980-12-12 21:01:02', 'UTC'), toUInt32(600), 299)─┐
│ ['1980-12-12 20:56:13','1980-12-12 21:01:12','1980-12-12 21:06:11'] │
└─────────────────────────────────────────────────────────────────────────┘
┌─timeSlots(toDateTime64('1980-12-12 21:01:02.1234', 4, 'UTC'), toDecimal64(600.1, 1), toDecimal64(299, 0))─┐
│ ['1980-12-12 20:56:13.0000','1980-12-12 21:01:12.0000','1980-12-12 21:06:11.0000'] │
└───────────────────────────────────────────────────────────────────────────────────────────────────────────┘
```
## timestamp
أُضيف في: v23.9.0
يحوّل الوسيط الأول `expr` إلى النوع [`DateTime64(6)`](/ar/reference/data-types/datetime64).
إذا تم توفير وسيط ثانٍ `expr_time`، فإنه يضيف الوقت المحدد إلى القيمة بعد تحويلها.
**البنية**
```sql theme={null}
timestamp(expr[, expr_time])
```
**الوسيطات**
* `expr` — تاريخ أو تاريخ متضمّن للوقت. [`String`](/ar/reference/data-types/string)
* `expr_time` — اختياري. الوقت المراد إضافته إلى القيمة المُحوَّلة. [`String`](/ar/reference/data-types/string)
**القيمة المعادة**
تُعيد القيمة المُحوَّلة لـ `expr`، أو `expr` بعد إضافة وقت إليه [`DateTime64(6)`](/ar/reference/data-types/datetime64)
**أمثلة**
**تحويل سلسلة تاريخ إلى DateTime64(6)**
```sql title=Query theme={null}
SELECT timestamp('2023-12-31') AS ts;
```
```response title=Response theme={null}
┌─────────────────────────ts─┐
│ 2023-12-31 00:00:00.000000 │
└────────────────────────────┘
```
**إضافة الوقت إلى سلسلة نصية للتاريخ**
```sql title=Query theme={null}
SELECT timestamp('2023-12-31 12:00:00', '12:00:00.11') AS ts;
```
```response title=Response theme={null}
┌─────────────────────────ts─┐
│ 2024-01-01 00:00:00.110000 │
└────────────────────────────┘
```
## timezone
أُضيفت في: v21.4.0
تعيد اسم المنطقة الزمنية للجلسة الحالية، أو تحوّل إزاحة منطقة زمنية
أو اسمها إلى الاسم القياسي للمنطقة الزمنية.
**الصيغة**
```sql theme={null}
timezone()
```
**الأسماء البديلة**: `timeZone`
**الوسائط**
* لا توجد.
**القيمة المُعادة**
يُرجع اسم المنطقة الزمنية المعياري على هيئة [`String`](/ar/reference/data-types/string)
**أمثلة**
**مثال على الاستخدام**
```sql title=Query theme={null}
SELECT timezone()
```
```response title=Response theme={null}
┌─timezone()───────┐
│ Europe/Amsterdam │
└──────────────────┘
```
## timezoneOf
أُضيف في: v21.4.0
يعيد اسم المنطقة الزمنية لقيمة من النوع [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64).
**الصياغة**
```sql theme={null}
timezoneOf(datetime)
```
**الأسماء البديلة**: `timeZoneOf`
**الوسائط**
* `datetime` — قيمة من النوع [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
* `timezone` — اختياري. اسم المنطقة الزمنية المطلوب تحويل قيمة `datetime` إليها. [`String`](/ar/reference/data-types/string)
**القيمة المعادة**
يرجع اسم المنطقة الزمنية لـ `datetime` من النوع [`String`](/ar/reference/data-types/string)
**أمثلة**
**مثال للاستخدام**
```sql title=Query theme={null}
SELECT timezoneOf(now());
```
```response title=Response theme={null}
┌─timezoneOf(now())─┐
│ Europe/Amsterdam │
└───────────────────┘
```
## timezoneOffset
أُضيفت في: v21.6.0
تُرجع فرق المنطقة الزمنية عن [UTC](https://en.wikipedia.org/wiki/Coordinated_Universal_Time) بالثواني.
وتأخذ الدالة في الحسبان التوقيت الصيفي والتغيّرات التاريخية في المنطقة الزمنية عند التاريخ والوقت المحددين.
**الصيغة**
```sql theme={null}
timezoneOffset(datetime)
```
**الأسماء البديلة**: `timeZoneOffset`
**الوسائط**
* `datetime` — قيمة `DateTime` المطلوب الحصول على إزاحة المنطقة الزمنية الخاصة بها. [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
**القيمة المُعادة**
تعيد إزاحة UTC بالثواني [`Int32`](/ar/reference/data-types/int-uint)
**أمثلة**
**مثال على الاستخدام**
```sql title=Query theme={null}
SELECT toDateTime('2021-04-21 10:20:30', 'America/New_York') AS Time,
toTypeName(Time) AS Type,
timezoneOffset(Time) AS Offset_in_seconds,
(Offset_in_seconds / 3600) AS Offset_in_hours;
```
```response title=Response theme={null}
┌────────────────Time─┬─Type─────────────────────────┬─Offset_in_seconds─┬─Offset_in_hours─┐
│ 2021-04-21 10:20:30 │ DateTime('America/New_York') │ -14400 │ -4 │
└─────────────────────┴──────────────────────────────┴───────────────────┴─────────────────┘
```
## toDayOfMonth
أُضيفت في: v1.1.0
تعيد يوم الشهر (1-31) لقيمة من النوع `Date` أو `DateTime`.
**البنية**
```sql theme={null}
toDayOfMonth(datetime)
```
**الأسماء البديلة**: `DAY`, `DAYOFMONTH`
**الوسائط**
* `datetime` — قيمة من نوع Date أو تاريخ مع وقت لاستخراج يوم الشهر منها. [`Date`](/ar/reference/data-types/date) أو [`Date32`](/ar/reference/data-types/date32) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
**القيمة المعادة**
تعيد يوم الشهر من التاريخ/الوقت المحدد [`UInt8`](/ar/reference/data-types/int-uint)
**أمثلة**
**مثال على الاستخدام**
```sql title=Query theme={null}
SELECT toDayOfMonth(toDateTime('2023-04-21 10:20:30'))
```
```response title=Response theme={null}
┌─toDayOfMonth(toDateTime('2023-04-21 10:20:30'))─┐
│ 21 │
└─────────────────────────────────────────────────┘
```
## toDayOfWeek
أُضيفت في: v1.1.0
تعيد رقم اليوم في الأسبوع لقيمة من النوع `Date` أو `DateTime`.
تتيح لك الصيغة ذات الوسيطتين للدالة `toDayOfWeek()` تحديد ما إذا كان الأسبوع يبدأ يوم الاثنين أو يوم الأحد،
وما إذا كانت القيمة المعادة يجب أن تكون ضمن النطاق من 0 إلى 6 أو من 1 إلى 7.
| الوضع | أول يوم في الأسبوع | النطاق |
| ----- | ------------------ | ---------------------------------------------- |
| 0 | الاثنين | 1-7: الاثنين = 1، الثلاثاء = 2، ...، الأحد = 7 |
| 1 | الاثنين | 0-6: الاثنين = 0، الثلاثاء = 1، ...، الأحد = 6 |
| 2 | الأحد | 0-6: الأحد = 0، الاثنين = 1، ...، السبت = 6 |
| 3 | الأحد | 1-7: الأحد = 1، الاثنين = 2، ...، السبت = 7 |
**الصيغة**
```sql theme={null}
toDayOfWeek(datetime[, mode[, timezone]])
```
**الأسماء البديلة**: `DAYOFWEEK`
**الوسيطات**
* `datetime` — تاريخ أو تاريخ مع وقت لاستخراج يوم الأسبوع منه. [`Date`](/ar/reference/data-types/date) أو [`Date32`](/ar/reference/data-types/date32) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
* `mode` — اختياري. عدد صحيح يحدد وضع الأسبوع (0-3). تكون القيمة الافتراضية 0 إذا لم يتم تحديده. [`UInt8`](/ar/reference/data-types/int-uint)
* `timezone` — اختياري. المنطقة الزمنية المستخدمة في التحويل. [`String`](/ar/reference/data-types/string)
**القيمة المعادة**
تعيد يوم الأسبوع للقيمة `Date` أو `DateTime` المحددة. [`UInt8`](/ar/reference/data-types/int-uint)
**أمثلة**
**مثال على الاستخدام**
```sql title=Query theme={null}
-- The following date is April 21, 2023, which was a Friday:
SELECT
toDayOfWeek(toDateTime('2023-04-21')),
toDayOfWeek(toDateTime('2023-04-21'), 1)
```
```response title=Response theme={null}
┌─toDayOfWeek(toDateTime('2023-04-21'))─┬─toDayOfWeek(toDateTime('2023-04-21'), 1)─┐
│ 5 │ 4 │
└───────────────────────────────────────┴──────────────────────────────────────────┘
```
## toDayOfYear
قُدِّمت في: v18.4.0
تُرجِع رقم اليوم ضمن السنة (1-366) لقيمة من النوع `Date` أو `DateTime`.
**الصياغة**
```sql theme={null}
toDayOfYear(datetime)
```
**الأسماء المستعارة**: `DAYOFYEAR`
**الوسيطات**
* `datetime` — تاريخ أو تاريخ مع وقت لاستخراج يوم السنة منه. [`Date`](/ar/reference/data-types/date) أو [`Date32`](/ar/reference/data-types/date32) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
**القيمة المعادة**
تعيد يوم السنة لقيمة `Date` أو `DateTime` المُعطاة [`UInt16`](/ar/reference/data-types/int-uint)
**أمثلة**
**مثال على الاستخدام**
```sql title=Query theme={null}
SELECT toDayOfYear(toDateTime('2023-04-21 10:20:30'))
```
```response title=Response theme={null}
┌─toDayOfYear(toDateTime('2023-04-21 10:20:30'))─┐
│ 111 │
└────────────────────────────────────────────────┘
```
## toDaysInMonth
أُضيفت في: v26.3.0
تعيد عدد الأيام في شهر قيمة من النوع `Date` أو `DateTime`.
تكون القيمة المُعادة ضمن النطاق من 28 إلى 31.
**البنية**
```sql theme={null}
toDaysInMonth(datetime)
```
**الوسائط**
* `datetime` — تاريخ أو تاريخ مع وقت يُستخرج منه عدد أيام الشهر. [`Date`](/ar/reference/data-types/date) أو [`Date32`](/ar/reference/data-types/date32) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
**القيمة المُعادة**
تعيد عدد الأيام في شهر التاريخ/الوقت المحدد. [`UInt8`](/ar/reference/data-types/int-uint)
**أمثلة**
**مثال على الاستخدام**
```sql title=Query theme={null}
SELECT toDaysInMonth(toDate('2023-02-01')), toDaysInMonth(toDate('2024-02-01')), toDaysInMonth(toDate('2023-01-01'))
```
```response title=Response theme={null}
┌─toDaysInMonth(toDate('2023-02-01'))─┬─toDaysInMonth(toDate('2024-02-01'))─┬─toDaysInMonth(toDate('2023-01-01'))─┐
│ 28 │ 29 │ 31 │
└─────────────────────────────────────┴─────────────────────────────────────┴─────────────────────────────────────┘
```
## toDaysSinceYearZero
أُضيفت في: v23.9.0
بالنسبة إلى تاريخ معيّن، تُرجع عدد الأيام المنقضية منذ [1 January 0000](https://en.wikipedia.org/wiki/Year_zero) وفق
[التقويم الغريغوري الممتد المعرّف في ISO 8601](https://en.wikipedia.org/wiki/Gregorian_calendar#Proleptic_Gregorian_calendar).
هذا الحساب مطابق للحساب المستخدم في الدالة [`TO_DAYS`](https://dev.mysql.com/doc/refman/8.0/en/date-and-time-functions.html#function_to-days) في MySQL.
**البنية**
```sql theme={null}
toDaysSinceYearZero(date[, time_zone])
```
**الأسماء البديلة**: `TO_DAYS`
**الوسيطات**
* `date` — التاريخ أو التاريخ والوقت المراد حساب عدد الأيام منذ السنة صفر له. [`Date`](/ar/reference/data-types/date) أو [`Date32`](/ar/reference/data-types/date32) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
* `time_zone` — المنطقة الزمنية. [`String`](/ar/reference/data-types/string)
**القيمة المُعادة**
تعيد عدد الأيام المنقضية منذ التاريخ `0000-01-01`. [`UInt32`](/ar/reference/data-types/int-uint)
**أمثلة**
**احسب الأيام منذ السنة صفر**
```sql title=Query theme={null}
SELECT toDaysSinceYearZero(toDate('2023-09-08'))
```
```response title=Response theme={null}
┌─toDaysSinceYearZero(toDate('2023-09-08')))─┐
│ 713569 │
└────────────────────────────────────────────┘
```
## toHour
أُضيفت في: v1.1.0
يعيد مكوّن الساعة (0-23) من قيمة `DateTime` أو `DateTime64`.
**البنية**
```sql theme={null}
toHour(datetime)
```
**الأسماء البديلة**: `HOUR`
**الوسائط**
* `datetime` — تاريخ ووقت لاستخراج الساعة منه. [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
**القيمة المُعادة**
تُرجِع قيمة الساعة (0-23) من `datetime`. [`UInt8`](/ar/reference/data-types/int-uint)
**أمثلة**
**مثال للاستخدام**
```sql title=Query theme={null}
SELECT toHour(toDateTime('2023-04-21 10:20:30'))
```
```response title=Response theme={null}
┌─toHour(toDateTime('2023-04-21 10:20:30'))─┐
│ 10 │
└───────────────────────────────────────────┘
```
## toISOWeek
أُضيفت في: v20.1.0
تُرجع رقم أسبوع ISO لتاريخ أو تاريخ ووقت.
هذه دالة توافقية وتكافئ `toWeek(date, 3)`.
تبدأ أسابيع ISO يوم الاثنين، ويشمل الأسبوع الأول من السنة يوم 4 يناير.
وفقًا للمعيار ISO 8601، تتراوح أرقام الأسابيع من 1 إلى 53.
لاحظ أن التواريخ القريبة من بداية السنة أو نهايتها قد تُرجع رقم أسبوع من السنة السابقة أو التالية. على سبيل المثال،
يعيد 29 ديسمبر 2025 الأسبوع 1 لأنه يقع ضمن أول أسبوع يشمل 4 يناير 2026.
**الصيغة**
```sql theme={null}
toISOWeek(datetime[, timezone])
```
**المعاملات**
* `datetime` — تاريخ أو تاريخ مع وقت لاستخراج رقم أسبوع ISO منه. [`Date`](/ar/reference/data-types/date) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`Date32`](/ar/reference/data-types/date32) أو [`DateTime64`](/ar/reference/data-types/datetime64)
* `timezone` — اختياري. المنطقة الزمنية. [`String`](/ar/reference/data-types/string)
**القيمة المعادة**
يعيد رقم أسبوع ISO وفقًا للمعيار ISO 8601. ويكون رقمًا بين 1 و53. [`UInt8`](/ar/reference/data-types/int-uint)
**أمثلة**
**الحصول على أرقام أسابيع ISO**
```sql title=Query theme={null}
SELECT toDate('2016-12-27') AS date, toISOWeek(date) AS isoWeek
```
```response title=Response theme={null}
┌───────date─┬─isoWeek─┐
│ 2016-12-27 │ 52 │
└────────────┴─────────┘
```
**قد يقع أسبوع ISO في سنة مختلفة**
```sql title=Query theme={null}
SELECT toDate('2025-12-29') AS date, toISOWeek(date) AS isoWeek, toYear(date) AS year
```
```response title=Response theme={null}
┌───────date─┬─isoWeek─┬─year─┐
│ 2025-12-29 │ 1 │ 2025 │
└────────────┴─────────┴──────┘
```
## toISOYear
أُضيف في: v18.4.0
يحوِّل تاريخًا أو تاريخًا مع وقت إلى رقم السنة وفق معيار ISO.
**البنية**
```sql theme={null}
toISOYear(datetime)
```
**الوسائط**
* `datetime` — قيمة من نوع تاريخ أو تاريخ مع وقت. [`Date`](/ar/reference/data-types/date) أو [`Date32`](/ar/reference/data-types/date32) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
**القيمة المُعادة**
تعيد قيمة الإدخال بعد تحويلها إلى رقم سنة وفق معيار ISO. [`UInt16`](/ar/reference/data-types/int-uint)
**أمثلة**
**استخراج سنة ISO من قيم التاريخ**
```sql title=Query theme={null}
SELECT
toISOYear(toDate('2024/10/02')) as year1,
toISOYear(toDateTime('2024-10-02 01:30:00')) as year2
```
```response title=Response theme={null}
┌─week1─┬─week2─┐
│ 40 │ 40 │
└───────┴───────┘
```
## toLastDayOfMonth
أُضيف في: v1.1.0
يُقرِّب قيمة من نوع تاريخ أو تاريخ مع وقت إلى آخر يوم في الشهر.
يمكن تهيئة نوع الإرجاع من خلال الإعداد [`enable_extended_results_for_datetime_functions`](/ar/reference/settings/session-settings#enable_extended_results_for_datetime_functions).
**الصياغة**
```sql theme={null}
toLastDayOfMonth(value)
```
**الأسماء المستعارة**: `LAST_DAY`
**الوسائط**
* `value` — التاريخ أو التاريخ مع الوقت المطلوب تقريبه للأعلى إلى آخر يوم من الشهر. [`Date`](/ar/reference/data-types/date) أو [`Date32`](/ar/reference/data-types/date32) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
**القيمة المعادة**
يعيد تاريخ آخر يوم من الشهر للتاريخ أو التاريخ مع الوقت المحدد. [`Date`](/ar/reference/data-types/date)
**أمثلة**
**التقريب للأعلى إلى آخر يوم من الشهر**
```sql title=Query theme={null}
SELECT toLastDayOfMonth(toDateTime('2023-04-21 10:20:30'))
```
```response title=Response theme={null}
┌─toLastDayOfMonth(toDateTime('2023-04-21 10:20:30'))─┐
│ 2023-04-30 │
└─────────────────────────────────────────────────────┘
```
## toLastDayOfWeek
أُضيف في: v23.5.0
يُقرِّب تاريخًا أو تاريخًا ووقتًا إلى أقرب يوم سبت أو أحد.
يمكن تهيئة نوع الإرجاع عبر ضبط [`enable_extended_results_for_datetime_functions`](/ar/reference/settings/session-settings#enable_extended_results_for_datetime_functions).
**البنية**
```sql theme={null}
toLastDayOfWeek(datetime[, mode[, timezone]])
```
**الوسيطات**
* `datetime` — تاريخ أو تاريخ ووقت لتحويله. [`Date`](/ar/reference/data-types/date) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`Date32`](/ar/reference/data-types/date32) أو [`DateTime64`](/ar/reference/data-types/datetime64)
* `mode` — يحدد أول يوم في الأسبوع كما هو موضح في الدالة `toWeek()`. القيمة الافتراضية `0`. [`UInt8`](/ar/reference/data-types/int-uint)
* `timezone` — اختياري. المنطقة الزمنية المستخدمة في التحويل. إذا لم يتم تحديدها، تُستخدم المنطقة الزمنية الخاصة بالخادم. [`String`](/ar/reference/data-types/string)
**القيمة المعادة**
تعيد تاريخ أقرب يوم سبت أو أحد، في يوم التاريخ المحدد نفسه أو بعده، وذلك حسب الوضع. [`Date`](/ar/reference/data-types/date) أو [`Date32`](/ar/reference/data-types/date32)
**أمثلة**
**التقريب للأعلى إلى أقرب يوم سبت أو أحد**
```sql title=Query theme={null}
SELECT
toLastDayOfWeek(toDateTime('2023-04-21 10:20:30')), /* a Friday */
toLastDayOfWeek(toDateTime('2023-04-21 10:20:30'), 1), /* a Friday */
toLastDayOfWeek(toDate('2023-04-23')), /* a Sunday */
toLastDayOfWeek(toDate('2023-04-23'), 1) /* a Sunday */
FORMAT Vertical
```
```response title=Response theme={null}
Row 1:
──────
toLastDayOfWeek(toDateTime('2023-04-21 10:20:30')): 2023-04-23
toLastDayOfWeek(toDateTime('2023-04-21 10:20:30'), 1): 2023-04-22
toLastDayOfWeek(toDate('2023-04-23')): 2023-04-23
toLastDayOfWeek(toDate('2023-04-23'), 1): 2023-04-23
```
## toMicrosecond
أُضيفت في: v25.7.0
تعيد مكوّن الميكروثانية (0-999999) من قيمة `DateTime64`.
**الصياغة**
```sql theme={null}
toMicrosecond(datetime)
```
**الأسماء المستعارة**: `MICROSECOND`
**الوسيطات**
* `datetime` — تاريخ ووقت لاستخراج الميكروثانية منه. [`DateTime64`](/ar/reference/data-types/datetime64)
**القيمة المُعادة**
تعيد قيمة الميكروثانية ضمن الثانية (0 - 999999) في `datetime`. [`UInt32`](/ar/reference/data-types/int-uint)
**أمثلة**
**مثال على الاستخدام**
```sql title=Query theme={null}
SELECT toMicrosecond(toDateTime64('2023-04-21 10:20:30.456789', 6));
```
```response title=Response theme={null}
┌─toMicrosecond(toDateTime64('2023-04-21 10:20:30.456789', 6))─┐
│ 456789 │
└──────────────────────────────────────────────────────────────┘
```
## toMillisecond
أُضيف في: v24.2.0
يعيد مكوّن الملّي ثانية (0-999) من قيمة `DateTime` أو `DateTime64`.
**البنية**
```sql theme={null}
toMillisecond(datetime)
```
**الأسماء البديلة**: `MILLISECOND`
**الوسيطات**
* `datetime` — تاريخ ووقت يُستخرج منه جزء الملّي ثانية. [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
**القيمة المُعادة**
تعيد قيمة الملّي ثانية ضمن الدقيقة (0 - 59) من `datetime`. [`UInt16`](/ar/reference/data-types/int-uint)
**أمثلة**
**مثال على الاستخدام**
```sql title=Query theme={null}
SELECT toMillisecond(toDateTime64('2023-04-21 10:20:30.456', 3));
```
```response title=Response theme={null}
┌──toMillisecond(toDateTime64('2023-04-21 10:20:30.456', 3))─┐
│ 456 │
└────────────────────────────────────────────────────────────┘
```
## toMinute
أُضيفت في: v1.1.0
تعيد مكوّن الدقيقة (0-59) من قيمة `Date` أو `DateTime`.
**البنية**
```sql theme={null}
toMinute(datetime)
```
**الأسماء البديلة**: `MINUTE`
**الوسائط**
* `datetime` — قيمة تاريخ ووقت لاستخراج الدقيقة منها. [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
**القيمة المُعادة**
يُرجع دقيقة الساعة (0 - 59) من `datetime`. [`UInt8`](/ar/reference/data-types/int-uint)
**أمثلة**
**مثال على الاستخدام**
```sql title=Query theme={null}
SELECT toMinute(toDateTime('2023-04-21 10:20:30'))
```
```response title=Response theme={null}
┌─toMinute(toDateTime('2023-04-21 10:20:30'))─┐
│ 20 │
└─────────────────────────────────────────────┘
```
## toModifiedJulianDay
ظهر في: v21.1.0
يحوّل تاريخًا بصيغة نصية `YYYY-MM-DD` وفق [التقويم الغريغوري الاستباقي](https://en.wikipedia.org/wiki/Proleptic_Gregorian_calendar) إلى رقم [اليوم اليولياني المعدّل](https://en.wikipedia.org/wiki/Julian_day#Variants) من النوع `Int32`. تدعم هذه الدالة التواريخ من `0000-01-01` إلى `9999-12-31`. وتُثير استثناءً إذا تعذّر تحليل الوسيطة كتاريخ، أو كان التاريخ غير صالح.
**الصياغة**
```sql theme={null}
toModifiedJulianDay(date)
```
**الوسيطات**
* `date` — التاريخ على هيئة String. [`String`](/ar/reference/data-types/string) أو [`FixedString`](/ar/reference/data-types/fixedstring)
**القيمة المعادة**
يُرجع رقم اليوم اليولياني المعدّل. [`Int32`](/ar/reference/data-types/int-uint)
**أمثلة**
**تحويل التاريخ إلى رقم اليوم اليولياني المعدّل**
```sql title=Query theme={null}
SELECT toModifiedJulianDay('2020-01-01')
```
```response title=Response theme={null}
┌─toModifiedJulianDay('2020-01-01')─┐
│ 58849 │
└───────────────────────────────────┘
```
## toModifiedJulianDayOrNull
أُضيفت في: v21.1.0
مشابهة لـ [`toModifiedJulianDay()`](#toModifiedJulianDay)، ولكن بدلًا من إطلاق استثناءات، تُرجع `NULL`.
**البنية**
```sql theme={null}
toModifiedJulianDayOrNull(date)
```
**الوسيطات**
* `date` — تاريخ بصيغة نصية. [`String`](/ar/reference/data-types/string) أو [`FixedString`](/ar/reference/data-types/fixedstring)
**القيمة المعادة**
تعيد رقم اليوم اليولياني المعدّل إذا كانت قيمة `date` صالحة، وإلا تُعيد `null`. [`Nullable(Int32)`](/ar/reference/data-types/nullable)
**أمثلة**
**تحويل التاريخ إلى رقم اليوم اليولياني المعدّل مع معالجة null**
```sql title=Query theme={null}
SELECT toModifiedJulianDayOrNull('2020-01-01');
SELECT toModifiedJulianDayOrNull('0000-00-00'); -- invalid date, returns NULL
```
```response title=Response theme={null}
┌─toModifiedJu⋯020-01-01')─┐
│ 58849 │
└──────────────────────────┘
┌─toModifiedJu⋯000-00-00')─┐
│ ᴺᵁᴸᴸ │
└──────────────────────────┘
```
## toMonday
أُضيف في: v1.1.0
يُقرِّب التاريخ أو التاريخ مع الوقت نزولًا إلى يوم الاثنين من الأسبوع نفسه. ويُرجع التاريخ.
يمكن تهيئة نوع الإرجاع عبر تعيين [`enable_extended_results_for_datetime_functions`](/ar/reference/settings/session-settings#enable_extended_results_for_datetime_functions).
**البنية**
```sql theme={null}
toMonday(value)
```
**المعاملات**
* `value` — تاريخ أو تاريخ متضمّن لوقت، لتقريبه إلى يوم الاثنين من ذلك الأسبوع. [`Date`](/ar/reference/data-types/date) أو [`Date32`](/ar/reference/data-types/date32) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
**القيمة المعادة**
تاريخ يوم الاثنين من الأسبوع نفسه للتاريخ أو التاريخ المتضمّن لوقت المُعطى. [`Date`](/ar/reference/data-types/date)
**أمثلة**
**التقريب إلى يوم الاثنين من الأسبوع**
```sql title=Query theme={null}
SELECT
toMonday(toDateTime('2023-04-21 10:20:30')), -- A Friday
toMonday(toDate('2023-04-24')); -- Already a Monday
```
```response title=Response theme={null}
┌─toMonday(toDateTime('2023-04-21 10:20:30'))─┬─toMonday(toDate('2023-04-24'))─┐
│ 2023-04-17 │ 2023-04-24 │
└─────────────────────────────────────────────┴────────────────────────────────┘
```
## toMonth
أُضيفت في: v1.1.0
تعيد مكوّن الشهر (1-12) من قيمة `Date` أو `DateTime`.
**الصيغة**
```sql theme={null}
toMonth(datetime)
```
**الأسماء البديلة**: `MONTH`
**الوسائط**
* `datetime` — تاريخ أو تاريخ مع وقت لاستخراج الشهر منه. [`Date`](/ar/reference/data-types/date) أو [`Date32`](/ar/reference/data-types/date32) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
**القيمة المعادة**
تعيد رقم شهر التاريخ/الوقت المحدد من النوع [`UInt8`](/ar/reference/data-types/int-uint)
**أمثلة**
**مثال على الاستخدام**
```sql title=Query theme={null}
SELECT toMonth(toDateTime('2023-04-21 10:20:30'))
```
```response title=Response theme={null}
┌─toMonth(toDateTime('2023-04-21 10:20:30'))─┐
│ 4 │
└────────────────────────────────────────────┘
```
## toMonthNumSinceEpoch
استُحدث في: v25.3.0
يعيد عدد الأشهر منذ عام 1970
**الصيغة**
```sql theme={null}
toMonthNumSinceEpoch(date)
```
**المعاملات**
* `date` — تاريخ أو تاريخ ووقت. [`Date`](/ar/reference/data-types/date) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
**القيمة المُعادة**
عدد صحيح موجب
**أمثلة**
**مثال**
```sql title=Query theme={null}
SELECT toMonthNumSinceEpoch(toDate('2024-10-01'))
```
```response title=Response theme={null}
657
```
## toNanosecond
قُدِّم في: v25.7.0
يعيد مكوّن النانوثانية (0-999999999) من قيمة `DateTime64`.
**الصياغة**
```sql theme={null}
toNanosecond(datetime)
```
**الأسماء البديلة**: `NANOSECOND`
**الوسيطات**
* `datetime` — قيمة تاريخ ووقت يُستخرج منها جزء النانوثانية. [`DateTime64`](/ar/reference/data-types/datetime64)
**القيمة المعادة**
تُرجع النانوثانية ضمن الثانية (0 - 999999999) من `datetime`. [`UInt32`](/ar/reference/data-types/int-uint)
**أمثلة**
**مثال على الاستخدام**
```sql title=Query theme={null}
SELECT toNanosecond(toDateTime64('2023-04-21 10:20:30.123456789', 9));
```
```response title=Response theme={null}
┌─toNanosecond(toDateTime64('2023-04-21 10:20:30.123456789', 9))─┐
│ 123456789 │
└────────────────────────────────────────────────────────────────┘
```
## toQuarter
أُضيفت في: v1.1.0
تُرجِع ربع السنة (1-4) لقيمة `Date` أو `DateTime` معيّنة.
**الصياغة**
```sql theme={null}
toQuarter(datetime)
```
**الأسماء البديلة**: `QUARTER`
**الوسيطات**
* `datetime` — تاريخ أو تاريخ مع وقت لاستخراج ربع السنة منه. [`Date`](/ar/reference/data-types/date) أو [`Date32`](/ar/reference/data-types/date32) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
**القيمة المعادة**
تعيد ربع السنة للتاريخ/الوقت المحدد [`UInt8`](/ar/reference/data-types/int-uint)
**أمثلة**
**مثال على الاستخدام**
```sql title=Query theme={null}
SELECT toQuarter(toDateTime('2023-04-21 10:20:30'))
```
```response title=Response theme={null}
┌─toQuarter(toDateTime('2023-04-21 10:20:30'))─┐
│ 2 │
└──────────────────────────────────────────────┘
```
## toRelativeDayNum
أُضيفت في: v1.1.0
تحوِّل قيمة من نوع تاريخ أو تاريخ ووقت إلى عدد الأيام المنقضية منذ نقطة ثابتة معيّنة في الماضي.
أما النقطة الزمنية الدقيقة فهي تفصيل متعلق بالتنفيذ، ولذلك فهذه الدالة غير مخصّصة للاستخدام بشكل مستقل.
والغرض الرئيسي من هذه الدالة هو حساب الفرق بالأيام بين تاريخين أو قيمتين من نوع تاريخ ووقت، مثل: `toRelativeDayNum(dt1) - toRelativeDayNum(dt2)`.
**البنية**
```sql theme={null}
toRelativeDayNum(date)
```
**الوسائط**
* `date` — تاريخ أو تاريخ ووقت. [`Date`](/ar/reference/data-types/date) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
**القيمة المعادة**
يعيد عدد الأيام بدءًا من نقطة مرجعية ثابتة في الماضي. [`UInt32`](/ar/reference/data-types/int-uint)
**أمثلة**
**الحصول على أرقام الأيام النسبية**
```sql title=Query theme={null}
SELECT toRelativeDayNum(toDate('2023-04-01')) - toRelativeDayNum(toDate('2023-01-01'))
```
```response title=Response theme={null}
┌─minus(toRela⋯3-01-01')))─┐
│ 90 │
└──────────────────────────┘
```
## toRelativeHourNum
أُضيفت في: v1.1.0
تحوّل تاريخًا أو تاريخًا ووقتًا إلى عدد الساعات المنقضية منذ نقطة ثابتة معيّنة في الماضي.
تمثّل النقطة الزمنية الدقيقة تفصيلًا تنفيذيًا، لذلك لا يُقصد استخدام هذه الدالة بشكل مستقل.
الغرض الرئيسي من هذه الدالة هو حساب الفرق بالساعات بين تاريخين أو بين قيمتَي تاريخ ووقت، على سبيل المثال: `toRelativeHourNum(dt1) - toRelativeHourNum(dt2)`.
**البنية**
```sql theme={null}
toRelativeHourNum(date)
```
**الوسائط**
* `date` — تاريخ أو تاريخ مع وقت. [`Date`](/ar/reference/data-types/date) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
**القيمة المُعادة**
يُرجع عدد الساعات منذ نقطة مرجعية ثابتة في الماضي. [`UInt32`](/ar/reference/data-types/int-uint)
**أمثلة**
**استخراج أرقام الساعات النسبية**
```sql title=Query theme={null}
SELECT toRelativeHourNum(toDateTime('2023-01-01 12:00:00')) - toRelativeHourNum(toDateTime('2023-01-01 00:00:00')) AS hours_difference
```
```response title=Response theme={null}
┌─hours_difference─┐
│ 12 │
└──────────────────┘
```
## toRelativeMinuteNum
أُضيفت في: v1.1.0
تحوّل تاريخًا أو تاريخًا مع وقت إلى عدد الدقائق المنقضية منذ نقطة ثابتة معيّنة في الماضي.
النقطة الزمنية الدقيقة هي تفصيل متعلق بالتنفيذ، ولذلك لا يُقصد استخدام هذه الدالة بمفردها.
الغرض الرئيسي من هذه الدالة هو حساب الفرق بالدقائق بين تاريخين أو بين قيمتَي تاريخ مع وقت، مثل `toRelativeMinuteNum(dt1) - toRelativeMinuteNum(dt2)`.
**الصيغة**
```sql theme={null}
toRelativeMinuteNum(date)
```
**الوسيطات**
* `date` — تاريخ أو تاريخ مع وقت. [`Date`](/ar/reference/data-types/date) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
**القيمة المُعادة**
يعيد عدد الدقائق منذ نقطة مرجعية ثابتة في الماضي. [`UInt32`](/ar/reference/data-types/int-uint)
**أمثلة**
**الحصول على أرقام الدقائق النسبية**
```sql title=Query theme={null}
SELECT toRelativeMinuteNum(toDateTime('2023-01-01 00:30:00')) - toRelativeMinuteNum(toDateTime('2023-01-01 00:00:00')) AS minutes_difference
```
```response title=Response theme={null}
┌─minutes_difference─┐
│ 30 │
└────────────────────┘
```
## toRelativeMonthNum
قُدِّمت في: v1.1.0
تحوّل تاريخًا أو تاريخًا مع وقت إلى عدد الأشهر المنقضية منذ نقطة ثابتة معيّنة في الماضي.
النقطة الزمنية الدقيقة هي تفصيل متعلق بالتنفيذ، لذلك لا يُقصد استخدام هذه الدالة بشكل مستقل.
الغرض الرئيسي من هذه الدالة هو حساب الفرق بالأشهر بين تاريخين أو تاريخين مع وقت، على سبيل المثال: `toRelativeMonthNum(dt1) - toRelativeMonthNum(dt2)`.
**الصياغة**
```sql theme={null}
toRelativeMonthNum(date)
```
**الوسائط**
* `date` — تاريخ أو تاريخ ووقت. [`Date`](/ar/reference/data-types/date) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
**القيمة المعادة**
يُرجع عدد الأشهر منذ نقطة مرجعية ثابتة في الماضي. [`UInt32`](/ar/reference/data-types/int-uint)
**أمثلة**
**الحصول على أرقام الأشهر النسبية**
```sql title=Query theme={null}
SELECT toRelativeMonthNum(toDate('2023-04-01')) - toRelativeMonthNum(toDate('2023-01-01')) AS months_difference
```
```response title=Response theme={null}
┌─months_difference─┐
│ 3 │
└───────────────────┘
```
## toRelativeQuarterNum
أُضيفت في: v1.1.0
تحوِّل تاريخًا أو تاريخًا مصحوبًا بوقت إلى عدد الأرباع المنقضية منذ نقطة ثابتة معيّنة في الماضي.
النقطة الزمنية الدقيقة هي من تفاصيل التنفيذ، لذلك لا يُقصد استخدام هذه الدالة بشكل مستقل.
والغرض الرئيسي من هذه الدالة هو حساب الفرق في الأرباع بين تاريخين أو بين قيمتَي تاريخ مصحوب بوقت، على سبيل المثال: `toRelativeQuarterNum(dt1) - toRelativeQuarterNum(dt2)`.
**الصيغة**
```sql theme={null}
toRelativeQuarterNum(date)
```
**الوسائط**
* `date` — تاريخ أو تاريخ مع وقت. [`Date`](/ar/reference/data-types/date) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
**القيمة المعادة**
تُرجع عدد أرباع السنة من نقطة مرجعية ثابتة في الماضي. [`UInt32`](/ar/reference/data-types/int-uint)
**أمثلة**
**الحصول على أرقام أرباع السنة النسبية**
```sql title=Query theme={null}
SELECT toRelativeQuarterNum(toDate('2023-04-01')) - toRelativeQuarterNum(toDate('2023-01-01')) AS quarters_difference
```
```response title=Response theme={null}
┌─quarters_difference─┐
│ 1 │
└─────────────────────┘
```
## toRelativeSecondNum
أُضيفت في: v1.1.0
تحوِّل تاريخًا أو تاريخًا يتضمّن وقتًا إلى عدد الثواني المنقضية منذ نقطة ثابتة معيّنة في الماضي.
النقطة الزمنية الدقيقة هي تفصيل خاص بالتنفيذ، ولذلك لا يُقصد استخدام هذه الدالة بصورة مستقلة.
الغرض الأساسي من هذه الدالة هو حساب الفرق بالثواني بين تاريخين أو بين قيمتَي تاريخ مع وقت، على سبيل المثال `toRelativeSecondNum(dt1) - toRelativeSecondNum(dt2)`.
**الصياغة**
```sql theme={null}
toRelativeSecondNum(date)
```
**المعاملات**
* `date` — تاريخ أو تاريخ مع وقت. [`Date`](/ar/reference/data-types/date) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
**القيمة المُعادة**
يعيد عدد الثواني منذ نقطة مرجعية ثابتة في الماضي. [`UInt32`](/ar/reference/data-types/int-uint)
**أمثلة**
**الحصول على أرقام الثواني النسبية**
```sql title=Query theme={null}
SELECT toRelativeSecondNum(toDateTime('2023-01-01 00:01:00')) - toRelativeSecondNum(toDateTime('2023-01-01 00:00:00')) AS seconds_difference
```
```response title=Response theme={null}
┌─seconds_difference─┐
│ 60 │
└────────────────────┘
```
## toRelativeWeekNum
قُدِّمت في: v1.1.0
تحوِّل قيمة تاريخ أو تاريخ مع وقت إلى عدد الأسابيع المنقضية منذ نقطة ثابتة معيّنة في الماضي.
أما النقطة الزمنية الدقيقة فهي من تفاصيل التنفيذ، لذلك فهذه الدالة غير مخصّصة للاستخدام بمفردها.
والغرض الرئيسي من هذه الدالة هو حساب الفرق بالأسابيع بين تاريخين أو قيمتي تاريخ مع وقت، على سبيل المثال: `toRelativeWeekNum(dt1) - toRelativeWeekNum(dt2)`.
**البنية**
```sql theme={null}
toRelativeWeekNum(date)
```
**الوسيطات**
* `date` — تاريخ أو تاريخ ووقت. [`Date`](/ar/reference/data-types/date) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
**القيمة المعادة**
تعيد عدد الأسابيع بدءًا من نقطة مرجعية ثابتة في الماضي. [`UInt32`](/ar/reference/data-types/int-uint)
**أمثلة**
**الحصول على أرقام الأسابيع النسبية**
```sql title=Query theme={null}
SELECT toRelativeWeekNum(toDate('2023-01-08')) - toRelativeWeekNum(toDate('2023-01-01')) AS weeks_difference
```
```response title=Response theme={null}
┌─weeks_difference─┐
│ 1 │
└──────────────────┘
```
## toRelativeYearNum
أُضيفت في: v1.1.0
تحوِّل تاريخًا أو تاريخًا يتضمّن وقتًا إلى عدد السنوات المنقضية منذ نقطة ثابتة معيّنة في الماضي.
والنقطة الزمنية الدقيقة هي من تفاصيل التنفيذ، لذلك لا يُقصد استخدام هذه الدالة
بشكل مستقل. والغرض الرئيسي من هذه الدالة هو حساب الفرق بالسنوات بين تاريخين أو تاريخين يتضمّنان وقتًا، على سبيل المثال: `toRelativeYearNum(dt1) - toRelativeYearNum(dt2)`.
**البنية**
```sql theme={null}
toRelativeYearNum(date)
```
**الوسائط**
* `date` — تاريخ أو تاريخ مع وقت. [`Date`](/ar/reference/data-types/date) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
**القيمة المُعادة**
يعيد عدد السنوات بدءًا من نقطة مرجعية ثابتة في الماضي. [`UInt16`](/ar/reference/data-types/int-uint)
**أمثلة**
**الحصول على أرقام السنوات النسبية**
```sql title=Query theme={null}
SELECT toRelativeYearNum('2010-10-01'::DateTime) - toRelativeYearNum('2000-01-01'::DateTime)
```
```response title=Response theme={null}
┌─minus(toRela⋯ateTime')))─┐
│ 10 │
└──────────────────────────┘
```
## toSecond
أُضيف في: v1.1.0
يعيد مكوّن الثواني (0-59) من قيمة `DateTime` أو `DateTime64`.
**البنية**
```sql theme={null}
toSecond(datetime)
```
**الأسماء البديلة**: `SECOND`
**الوسائط**
* `datetime` — تاريخ ووقت لاستخراج الثواني منه. [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
**القيمة المُعادة**
تُرجع الثانية ضمن الدقيقة (0 - 59) من `datetime`. [`UInt8`](/ar/reference/data-types/int-uint)
**أمثلة**
**مثال على الاستخدام**
```sql title=Query theme={null}
SELECT toSecond(toDateTime('2023-04-21 10:20:30'))
```
```response title=Response theme={null}
┌─toSecond(toDateTime('2023-04-21 10:20:30'))─┐
│ 30 │
└─────────────────────────────────────────────┘
```
## toStartOfDay
أُضيف في: v1.1.0
يقرّب قيمة تاريخ ووقت نزولًا إلى بداية اليوم.
يمكن تهيئة نوع الإرجاع عبر تعيين [`enable_extended_results_for_datetime_functions`](/ar/reference/settings/session-settings#enable_extended_results_for_datetime_functions).
**الصيغة**
```sql theme={null}
toStartOfDay(datetime)
```
**الوسائط**
* `datetime` — تاريخ أو تاريخ مع وقت لتقريبه. [`Date`](/ar/reference/data-types/date) أو [`DateTime`](/ar/reference/data-types/datetime)
**القيمة المعادة**
يُرجع تاريخًا مع وقت بعد تقريبه نزولًا إلى بداية اليوم. [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
**أمثلة**
**التقريب نزولًا إلى بداية اليوم**
```sql title=Query theme={null}
SELECT toStartOfDay(toDateTime('2023-04-21 10:20:30'))
```
```response title=Response theme={null}
┌─toStartOfDay(toDateTime('2023-04-21 10:20:30'))─┐
│ 2023-04-21 00:00:00 │
└─────────────────────────────────────────────────┘
```
## toStartOfFifteenMinutes
أُضيفت في: v1.1.0
تُنزِّل قيمة التاريخ والوقت إلى بداية الفاصل الزمني البالغ خمس عشرة دقيقة.
يمكن تهيئة نوع الإرجاع عبر تعيين [`enable_extended_results_for_datetime_functions`](/ar/reference/settings/session-settings#enable_extended_results_for_datetime_functions).
**الصياغة**
```sql theme={null}
toStartOfFifteenMinutes(datetime)
```
**المعاملات**
* `datetime` — تاريخ أو تاريخ ووقت مطلوب تقريبه. [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
**القيمة المُعادة**
يعيد التاريخ والوقت بعد تقريبهما إلى بداية أقرب فاصل زمني مدته خمس عشرة دقيقة. [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
**أمثلة**
**مثال**
```sql title=Query theme={null}
SELECT
toStartOfFifteenMinutes(toDateTime('2023-04-21 10:17:00')),
toStartOfFifteenMinutes(toDateTime('2023-04-21 10:20:00')),
toStartOfFifteenMinutes(toDateTime('2023-04-21 10:23:00'))
FORMAT Vertical
```
```response title=Response theme={null}
Row 1:
──────
toStartOfFifteenMinutes(toDateTime('2023-04-21 10:17:00')): 2023-04-21 10:15:00
toStartOfFifteenMinutes(toDateTime('2023-04-21 10:20:00')): 2023-04-21 10:15:00
toStartOfFifteenMinutes(toDateTime('2023-04-21 10:23:00')): 2023-04-21 10:15:00
```
## toStartOfFiveMinutes
أُضيفت في: v22.6.0
تُقرِّب قيمة تاريخ ووقت نزولًا إلى بداية فترة الخمس دقائق الأقرب.
يمكن تهيئة نوع الإرجاع من خلال الإعداد [`enable_extended_results_for_datetime_functions`](/ar/reference/settings/session-settings#enable_extended_results_for_datetime_functions).
**البنية**
```sql theme={null}
toStartOfFiveMinutes(datetime)
```
**الأسماء البديلة**: `toStartOfFiveMinute`
**الوسيطات**
* `datetime` — تاريخ ووقت المطلوب تقريبهما. [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
**القيمة المُعادة**
تعيد التاريخ والوقت بعد تقريبهما إلى بداية أقرب فاصل زمني مدته خمس دقائق. [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
**أمثلة**
**مثال**
```sql title=Query theme={null}
SELECT
toStartOfFiveMinutes(toDateTime('2023-04-21 10:17:00')),
toStartOfFiveMinutes(toDateTime('2023-04-21 10:20:00')),
toStartOfFiveMinutes(toDateTime('2023-04-21 10:23:00'))
FORMAT Vertical
```
```response title=Response theme={null}
Row 1:
──────
toStartOfFiveMinutes(toDateTime('2023-04-21 10:17:00')): 2023-04-21 10:15:00
toStartOfFiveMinutes(toDateTime('2023-04-21 10:20:00')): 2023-04-21 10:20:00
toStartOfFiveMinutes(toDateTime('2023-04-21 10:23:00')): 2023-04-21 10:20:00
```
## toStartOfHour
تم تقديمه في: v1.1.0
يقرّب تاريخًا ووقتًا نزولًا إلى بداية الساعة.
يمكن تهيئة نوع الإرجاع من خلال ضبط [`enable_extended_results_for_datetime_functions`](/ar/reference/settings/session-settings#enable_extended_results_for_datetime_functions).
**الصيغة**
```sql theme={null}
toStartOfHour(datetime)
```
**الوسيطات**
* `datetime` — قيمة تاريخية تتضمن وقتًا لتقريبها. [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
**القيمة المُعادة**
يعيد القيمة التاريخية بعد تقريبها نزولًا إلى بداية الساعة. [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
**أمثلة**
**التقريب نزولًا إلى بداية الساعة**
```sql title=Query theme={null}
SELECT
toStartOfHour(toDateTime('2023-04-21 10:20:30'));
```
```response title=Response theme={null}
┌─────────────────res─┬─toTypeName(res)─┐
│ 2023-04-21 10:00:00 │ DateTime │
└─────────────────────┴─────────────────┘
```
## toStartOfISOYear
أُضيفت في: v1.1.0
يُنزل تاريخًا أو تاريخًا يتضمن وقتًا إلى اليوم الأول من سنة ISO، والتي قد تختلف عن السنة الميلادية العادية. راجع [ISO week date](https://en.wikipedia.org/wiki/ISO_week_date).
يمكن تهيئة نوع الإرجاع عن طريق ضبط [`enable_extended_results_for_datetime_functions`](/ar/reference/settings/session-settings#enable_extended_results_for_datetime_functions).
**البنية**
```sql theme={null}
toStartOfISOYear(value)
```
**الوسائط**
* `value` — التاريخ أو التاريخ مع وقت المراد تقريبُه نزولًا إلى اليوم الأول من سنة ISO. [`Date`](/ar/reference/data-types/date) أو [`Date32`](/ar/reference/data-types/date32) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
**القيمة المعادة**
يعيد اليوم الأول من سنة ISO للتاريخ أو التاريخ مع وقت المحدد. [`Date`](/ar/reference/data-types/date)
**أمثلة**
**التقريب نزولًا إلى اليوم الأول من سنة ISO**
```sql title=Query theme={null}
SELECT toStartOfISOYear(toDateTime('2023-04-21 10:20:30'))
```
```response title=Response theme={null}
┌─toStartOfISOYear(toDateTime('2023-04-21 10:20:30'))─┐
│ 2023-01-02 │
└─────────────────────────────────────────────────────┘
```
## toStartOfInterval
أُضيفت في: v20.1.0
تُعمِّم هذه الدالة دوال `toStartOf*()` الأخرى باستخدام البنية `toStartOfInterval(date_or_date_with_time, INTERVAL x unit [, time_zone])`.
على سبيل المثال،
* تُرجع `toStartOfInterval(t, INTERVAL 1 YEAR)` النتيجة نفسها التي تُرجعها `toStartOfYear(t)`,
* تُرجع `toStartOfInterval(t, INTERVAL 1 MONTH)` النتيجة نفسها التي تُرجعها `toStartOfMonth(t)`,
* تُرجع `toStartOfInterval(t, INTERVAL 1 DAY)` النتيجة نفسها التي تُرجعها `toStartOfDay(t)`,
* تُرجع `toStartOfInterval(t, INTERVAL 15 MINUTE)` النتيجة نفسها التي تُرجعها `toStartOfFifteenMinutes(t)`.
يُجرى الحساب بالاستناد إلى نقاط زمنية محددة:
| Interval | Start |
| ------------------------------------------------------------------------------------------------------------------------- | --------------------------- |
| YEAR | السنة 0 |
| QUARTER | 1900 Q1 |
| MONTH | يناير 1900 |
| WEEK | 1970، الأسبوع الأول (01-05) |
| DAY | 1970-01-01 |
| HOUR | (\*) |
| MINUTE | 1970-01-01 00:00:00 |
| SECOND | 1970-01-01 00:00:00 |
| MILLISECOND | 1970-01-01 00:00:00 |
| MICROSECOND | 1970-01-01 00:00:00 |
| NANOSECOND | 1970-01-01 00:00:00 |
| (\*) فترات الساعات حالة خاصة: يُجرى الحساب دائمًا بالاستناد إلى 00:00:00 (منتصف الليل) من اليوم الحالي. ونتيجةً لذلك، فإن | |
| قيم الساعات من 1 إلى 23 فقط هي المفيدة. | |
إذا جرى تحديد الوحدة `WEEK`، فإن `toStartOfInterval` يفترض أن الأسابيع تبدأ يوم الاثنين. لاحظ أن هذا السلوك يختلف عن سلوك الدالة `toStartOfWeek`، حيث تبدأ الأسابيع افتراضيًا يوم الأحد.
تحاكي صيغة التحميل الزائد الثانية الدالة `time_bucket()` في TimescaleDB، وكذلك الدالة `date_bin()` في PostgreSQL.
**البنية**
```sql theme={null}
toStartOfInterval(value, INTERVAL x unit[, time_zone])
toStartOfInterval(value, INTERVAL x unit[, origin[, time_zone]])
```
**الأسماء البديلة**: `time_bucket`, `date_bin`
**المعاملات**
* `value` — قيمة تاريخ أو تاريخ مع وقت تُقرَّب نزولًا. [`Date`](/ar/reference/data-types/date) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
* `x` — رقم يمثّل طول الفاصل الزمني. - `unit` — وحدة الفاصل الزمني: YEAR, QUARTER, MONTH, WEEK, DAY, HOUR, MINUTE, SECOND, MILLISECOND, MICROSECOND, NANOSECOND. - `time_zone` — اختياري. اسم المنطقة الزمنية كسلسلة نصية. - `origin` — اختياري. نقطة بدء الحساب (في التوقيع الثاني فقط).
**القيمة المُعادة**
تعيد بداية الفاصل الزمني الذي تقع ضمنه قيمة الإدخال. [`DateTime`](/ar/reference/data-types/datetime)
**أمثلة**
**تقريب الفاصل الزمني الأساسي**
```sql title=Query theme={null}
SELECT toStartOfInterval(toDateTime('2023-01-15 14:30:00'), INTERVAL 1 MONTH)
```
```response title=Response theme={null}
┌─toStartOfInt⋯alMonth(1))─┐
│ 2023-01-01 │
└──────────────────────────┘
```
**استخدام نقطة الأصل**
```sql title=Query theme={null}
SELECT toStartOfInterval(toDateTime('2023-01-01 14:45:00'), INTERVAL 1 MINUTE, toDateTime('2023-01-01 14:35:30'))
```
```response title=Response theme={null}
┌─toStartOfInt⋯14:35:30'))─┐
│ 2023-01-01 14:44:30 │
└──────────────────────────┘
```
## toStartOfMicrosecond
أُضيفت في: v22.6.0
تُقرِّب قيمة تاريخ ووقت نزولًا إلى بداية الميكروثانية.
**الصيغة**
```sql theme={null}
toStartOfMicrosecond(datetime[, timezone])
```
**الوسائط**
* `datetime` — التاريخ والوقت. [`DateTime64`](/ar/reference/data-types/datetime64)
* `timezone` — اختياري. المنطقة الزمنية للقيمة المُعادة. إذا لم يتم تحديدها، تستخدم الدالة المنطقة الزمنية للمعامل `value`. [`String`](/ar/reference/data-types/string)
**القيمة المُعادة**
قيمة الإدخال بعد إزالة الأجزاء الأقل من الميكروثانية [`DateTime64`](/ar/reference/data-types/datetime64)
**أمثلة**
**استعلام من دون منطقة زمنية**
```sql title=Query theme={null}
WITH toDateTime64('2020-01-01 10:20:30.999999999', 9) AS dt64
SELECT toStartOfMicrosecond(dt64);
```
```response title=Response theme={null}
┌────toStartOfMicrosecond(dt64)─┐
│ 2020-01-01 10:20:30.999999000 │
└───────────────────────────────┘
```
**استعلام مع تحديد المنطقة الزمنية**
```sql title=Query theme={null}
WITH toDateTime64('2020-01-01 10:20:30.999999999', 9) AS dt64
SELECT toStartOfMicrosecond(dt64, 'Asia/Istanbul');
```
```response title=Response theme={null}
┌─toStartOfMicrosecond(dt64, 'Asia/Istanbul')─┐
│ 2020-01-01 12:20:30.999999000 │
└─────────────────────────────────────────────┘
```
## toStartOfMillisecond
أُضيف في: v22.6.0
يقرّب تاريخًا مع وقت نزولًا إلى بداية الملّي ثانية.
**البنية**
```sql theme={null}
toStartOfMillisecond(datetime[, timezone])
```
**الوسائط**
* `datetime` — التاريخ والوقت. [`DateTime64`](/ar/reference/data-types/datetime64)
* `timezone` — اختياري. المنطقة الزمنية للقيمة المُعادة. إذا لم يتم تحديدها، تستخدم الدالة المنطقة الزمنية للمعلَمة `value`. [`String`](/ar/reference/data-types/string)
**القيمة المُعادة**
قيمة الإدخال مع أجزاء أصغر من المللي ثانية. [`DateTime64`](/ar/reference/data-types/datetime64)
**أمثلة**
**استعلام بدون منطقة زمنية**
```sql title=Query theme={null}
WITH toDateTime64('2020-01-01 10:20:30.999999999', 9) AS dt64
SELECT toStartOfMillisecond(dt64);
```
```response title=Response theme={null}
┌────toStartOfMillisecond(dt64)─┐
│ 2020-01-01 10:20:30.999000000 │
└───────────────────────────────┘
```
**استعلام مع تحديد المنطقة الزمنية**
```sql title=Query theme={null}
WITH toDateTime64('2020-01-01 10:20:30.999999999', 9) AS dt64
SELECT toStartOfMillisecond(dt64, 'Asia/Istanbul');
```
```response title=Response theme={null}
┌─toStartOfMillisecond(dt64, 'Asia/Istanbul')─┐
│ 2020-01-01 12:20:30.999000000 │
└─────────────────────────────────────────────┘
```
## toStartOfMinute
أُضيفت في: v1.1.0
تُقرِّب قيمة تاريخية تتضمن وقتًا نزولًا إلى بداية الدقيقة.
يمكن تهيئة نوع الإرجاع عن طريق ضبط [`enable_extended_results_for_datetime_functions`](/ar/reference/settings/session-settings#enable_extended_results_for_datetime_functions).
**الصياغة**
```sql theme={null}
toStartOfMinute(datetime)
```
**الوسائط**
* `datetime` — تاريخ ووقت يُراد تقريبهما. [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
**القيمة المُعادة**
يعيد تاريخًا ووقتًا بعد تقريبهما نزولًا إلى بداية الدقيقة. [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
**أمثلة**
**التقريب نزولًا إلى بداية الدقيقة**
```sql title=Query theme={null}
SELECT
toStartOfMinute(toDateTime('2023-04-21 10:20:30')),
toStartOfMinute(toDateTime64('2023-04-21 10:20:30.5300', 8))
FORMAT Vertical
```
```response title=Response theme={null}
Row 1:
──────
toStartOfMinute(toDateTime('2023-04-21 10:20:30')): 2023-04-21 10:20:00
toStartOfMinute(toDateTime64('2023-04-21 10:20:30.5300', 8)): 2023-04-21 10:20:00
```
## toStartOfMonth
أُضيف في: v1.1.0
يقرّب تاريخًا أو تاريخًا مع وقت إلى اليوم الأول من الشهر.
يمكن تهيئة نوع الإرجاع من خلال إعداد [`enable_extended_results_for_datetime_functions`](/ar/reference/settings/session-settings#enable_extended_results_for_datetime_functions).
**الصيغة**
```sql theme={null}
toStartOfMonth(value)
```
**المعاملات**
* `value` — التاريخ أو التاريخ والوقت المراد تقريبُه نزولًا إلى اليوم الأول من الشهر. [`Date`](/ar/reference/data-types/date) أو [`Date32`](/ar/reference/data-types/date32) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
**القيمة المُعادة**
تُرجِع اليوم الأول من الشهر للتاريخ أو التاريخ والوقت المحدد. [`Date`](/ar/reference/data-types/date)
**أمثلة**
**التقريب نزولًا إلى اليوم الأول من الشهر**
```sql title=Query theme={null}
SELECT toStartOfMonth(toDateTime('2023-04-21 10:20:30'))
```
```response title=Response theme={null}
┌─toStartOfMonth(toDateTime('2023-04-21 10:20:30'))─┐
│ 2023-04-01 │
└───────────────────────────────────────────────────┘
```
## toStartOfNanosecond
تم تقديمه في: v22.6.0
يقرّب قيمة تاريخ مع وقت نزولًا إلى بداية النانوثانية.
**البنية**
```sql theme={null}
toStartOfNanosecond(datetime[, timezone])
```
**الوسيطات**
* `datetime` — التاريخ والوقت. [`DateTime64`](/ar/reference/data-types/datetime64)
* `timezone` — اختياري. المنطقة الزمنية للقيمة المعادة. إذا لم يتم تحديدها، تستخدم الدالة المنطقة الزمنية للمعامل `value`. [`String`](/ar/reference/data-types/string)
**القيمة المعادة**
قيمة الإدخال بدقة النانوثانية. [`DateTime64`](/ar/reference/data-types/datetime64)
**أمثلة**
**استعلام بدون منطقة زمنية**
```sql title=Query theme={null}
WITH toDateTime64('2020-01-01 10:20:30.999999999', 9) AS dt64
SELECT toStartOfNanosecond(dt64);
```
```response title=Response theme={null}
┌─────toStartOfNanosecond(dt64)─┐
│ 2020-01-01 10:20:30.999999999 │
└───────────────────────────────┘
```
**استعلام مع تحديد المنطقة الزمنية**
```sql title=Query theme={null}
WITH toDateTime64('2020-01-01 10:20:30.999999999', 9) AS dt64
SELECT toStartOfNanosecond(dt64, 'Asia/Istanbul');
```
```response title=Response theme={null}
┌─toStartOfNanosecond(dt64, 'Asia/Istanbul')─┐
│ 2020-01-01 12:20:30.999999999 │
└────────────────────────────────────────────┘
```
## toStartOfQuarter
أُضيف في: v1.1.0
يقرّب تاريخًا أو قيمة تاريخ ووقت نزولًا إلى اليوم الأول من الربع. ويكون اليوم الأول من الربع أحد التواريخ التالية: 1 يناير، أو 1 أبريل، أو 1 يوليو، أو 1 أكتوبر.
يمكن ضبط نوع الإرجاع عن طريق تعيين [`enable_extended_results_for_datetime_functions`](/ar/reference/settings/session-settings#enable_extended_results_for_datetime_functions).
**الصيغة**
```sql theme={null}
toStartOfQuarter(value)
```
**الوسيطات**
* `value` — التاريخ أو التاريخ والوقت المراد تقريبه نزولًا إلى اليوم الأول من الربع. [`Date`](/ar/reference/data-types/date) أو [`Date32`](/ar/reference/data-types/date32) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
**القيمة المُعادة**
يعيد اليوم الأول من الربع للتاريخ أو التاريخ والوقت المُعطى. [`Date`](/ar/reference/data-types/date)
**أمثلة**
**التقريب نزولًا إلى اليوم الأول من الربع**
```sql title=Query theme={null}
SELECT toStartOfQuarter(toDateTime('2023-04-21 10:20:30'))
```
```response title=Response theme={null}
┌─toStartOfQuarter(toDateTime('2023-04-21 10:20:30'))─┐
│ 2023-04-01 │
└─────────────────────────────────────────────────────┘
```
## toStartOfSecond
أُضيفت في: v20.5.0
يُنزِّل قيمة تاريخ مع وقت إلى بداية الثانية.
**الصيغة**
```sql theme={null}
toStartOfSecond(datetime[, timezone])
```
**الوسائط**
* `datetime` — التاريخ والوقت المراد حذف الأجزاء من الثانية منه. [`DateTime64`](/ar/reference/data-types/datetime64)
* `timezone` — اختياري. المنطقة الزمنية للقيمة المُعادة. إذا لم يتم تحديدها، تستخدم الدالة المنطقة الزمنية الخاصة بالمعامل `value`. [`String`](/ar/reference/data-types/string)
**القيمة المُعادة**
تعيد قيمة الإدخال من دون الأجزاء من الثانية. [`DateTime64`](/ar/reference/data-types/datetime64)
**أمثلة**
**استعلام بدون منطقة زمنية**
```sql title=Query theme={null}
WITH toDateTime64('2020-01-01 10:20:30.999', 3) AS dt64
SELECT toStartOfSecond(dt64);
```
```response title=Response theme={null}
┌───toStartOfSecond(dt64)─┐
│ 2020-01-01 10:20:30.000 │
└─────────────────────────┘
```
**استعلام مع تحديد المنطقة الزمنية**
```sql title=Query theme={null}
WITH toDateTime64('2020-01-01 10:20:30.999', 3) AS dt64
SELECT toStartOfSecond(dt64, 'Asia/Istanbul');
```
```response title=Response theme={null}
┌─toStartOfSecond(dt64, 'Asia/Istanbul')─┐
│ 2020-01-01 13:20:30.000 │
└────────────────────────────────────────┘
```
## toStartOfTenMinutes
أُضيف في: v20.1.0
يقرّب قيمة تاريخ مع وقت بالتنزيل إلى بداية أقرب فترة من عشر دقائق.
يمكن تهيئة نوع القيمة المعادة عن طريق تعيين [`enable_extended_results_for_datetime_functions`](/ar/reference/settings/session-settings#enable_extended_results_for_datetime_functions).
**البنية**
```sql theme={null}
toStartOfTenMinutes(datetime)
```
**الوسيطات**
* `datetime` — تاريخ ووقت. [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
**القيمة المُعادة**
تعيد التاريخ والوقت بعد تقريبهما إلى بداية أقرب فاصل زمني مدته عشر دقائق. [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
**أمثلة**
**مثال**
```sql title=Query theme={null}
SELECT
toStartOfTenMinutes(toDateTime('2023-04-21 10:17:00')),
toStartOfTenMinutes(toDateTime('2023-04-21 10:20:00')),
toStartOfTenMinutes(toDateTime('2023-04-21 10:23:00'))
FORMAT Vertical
```
```response title=Response theme={null}
Row 1:
──────
toStartOfTenMinutes(toDateTime('2023-04-21 10:17:00')): 2023-04-21 10:10:00
toStartOfTenMinutes(toDateTime('2023-04-21 10:20:00')): 2023-04-21 10:20:00
toStartOfTenMinutes(toDateTime('2023-04-21 10:23:00')): 2023-04-21 10:20:00
```
## toStartOfWeek
أُضيف في: v20.1.0
يُقرِّب قيمة من نوع تاريخ أو تاريخ مع وقت نزولًا إلى أقرب يوم أحد أو اثنين.
يمكن تهيئة نوع الإرجاع من خلال ضبط [`enable_extended_results_for_datetime_functions`](/ar/reference/settings/session-settings#enable_extended_results_for_datetime_functions).
**الصيغة**
```sql theme={null}
toStartOfWeek(datetime[, mode[, timezone]])
```
**الوسيطات**
* `datetime` — تاريخ أو تاريخ ووقت للتحويل. [`Date`](/ar/reference/data-types/date) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`Date32`](/ar/reference/data-types/date32) أو [`DateTime64`](/ar/reference/data-types/datetime64)
* `mode` — يحدد أول يوم في الأسبوع كما هو موضح في الدالة `toWeek()`. القيمة الافتراضية `0`. [`UInt8`](/ar/reference/data-types/int-uint)
* `timezone` — المنطقة الزمنية المستخدمة في التحويل. إذا لم يتم تحديدها، فستُستخدم المنطقة الزمنية الخاصة بـ الخادم. [`String`](/ar/reference/data-types/string)
**القيمة المعادة**
يعيد تاريخ أقرب يوم أحد أو اثنين يوافق التاريخ المحدد أو يسبقه، وذلك حسب الوضع. [`Date`](/ar/reference/data-types/date) أو [`Date32`](/ar/reference/data-types/date32)
**أمثلة**
**التقريب لأسفل إلى أقرب يوم أحد أو اثنين**
```sql title=Query theme={null}
SELECT
toStartOfWeek(toDateTime('2023-04-21 10:20:30')), /* a Friday */
toStartOfWeek(toDateTime('2023-04-21 10:20:30'), 1), /* a Friday */
toStartOfWeek(toDate('2023-04-24')), /* a Monday */
toStartOfWeek(toDate('2023-04-24'), 1) /* a Monday */
FORMAT Vertical
```
```response title=Response theme={null}
Row 1:
──────
toStartOfWeek(toDateTime('2023-04-21 10:20:30')): 2023-04-17
toStartOfWeek(toDateTime('2023-04-21 10:20:30'), 1): 2023-04-17
toStartOfWeek(toDate('2023-04-24')): 2023-04-24
toStartOfWeek(toDate('2023-04-24'), 1): 2023-04-24
```
## toStartOfYear
قُدِّمت في: v1.1.0
تُنزِّل قيمة من نوع تاريخ أو تاريخ مع وقت إلى اليوم الأول من السنة. وتُرجِع التاريخ ككائن `Date`.
يمكن تهيئة نوع الإرجاع عبر ضبط [`enable_extended_results_for_datetime_functions`](/ar/reference/settings/session-settings#enable_extended_results_for_datetime_functions).
**البنية**
```sql theme={null}
toStartOfYear(value)
```
**المعاملات**
* `value` — التاريخ أو التاريخ مع الوقت المراد تقريبه لأسفل. [`Date`](/ar/reference/data-types/date) أو [`Date32`](/ar/reference/data-types/date32) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
**القيمة المعادة**
اليوم الأول من السنة للتاريخ/الوقت المحدد [`Date`](/ar/reference/data-types/date)
**أمثلة**
**التقريب لأسفل إلى أول يوم من السنة**
```sql title=Query theme={null}
SELECT toStartOfYear(toDateTime('2023-04-21 10:20:30'))
```
```response title=Response theme={null}
┌─toStartOfYear(toDateTime('2023-04-21 10:20:30'))─┐
│ 2023-01-01 │
└──────────────────────────────────────────────────┘
```
## toTimeWithFixedDate
أُضيفت في: v1.1.0
تستخرج مكوّن الوقت من تاريخ أو تاريخ ووقت.
النتيجة المُعادة هي إزاحة إلى نقطة زمنية ثابتة، وهي حاليًا `1970-01-02`،
لكن النقطة الزمنية الدقيقة هي تفصيل تنفيذي قد يتغير مستقبلًا.
لذلك، لا ينبغي استخدام `toTime` بشكل مستقل.
الغرض الرئيسي من هذه الدالة هو حساب فرق الوقت بين تاريخين أو قيمتين من نوع تاريخ ووقت، مثل: `toTime(dt1) - toTime(dt2)`.
**البنية**
```sql theme={null}
toTimeWithFixedDate(date[, timezone])
```
**الوسائط**
* `date` — التاريخ المراد تحويله إلى وقت. [`Date`](/ar/reference/data-types/date) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
* `timezone` — اختياري. المنطقة الزمنية للقيمة المُعادة. [`String`](/ar/reference/data-types/string)
**القيمة المُعادة**
يعيد مكوّن الوقت من قيمة تاريخ أو تاريخ ووقت، على هيئة إزاحة بالنسبة إلى نقطة زمنية ثابتة (المحددة حاليًا بـ 1970-01-02). [`DateTime`](/ar/reference/data-types/datetime)
**أمثلة**
**احسب الفرق الزمني بين تاريخين**
```sql title=Query theme={null}
SELECT toTimeWithFixedDate('2025-06-15 12:00:00'::DateTime) - toTimeWithFixedDate('2024-05-10 11:00:00'::DateTime) AS result, toTypeName(result)
```
```response title=Response theme={null}
┌─result─┬─toTypeName(result)─┐
│ 3600 │ Int32 │
└────────┴────────────────────┘
```
## toTimezone
أُضيف في: v1.1.0
يحوّل `DateTime` أو `DateTime64` إلى المنطقة الزمنية المحددة.
لا تتغير القيمة الداخلية للبيانات (عدد ثواني Unix).
يتغير فقط سِمة المنطقة الزمنية للقيمة وتمثيلها النصي.
**البنية**
```sql theme={null}
toTimezone(datetime, timezone)
```
**الأسماء البديلة**: `toTimeZone`
**المعاملات**
* `date` — القيمة المراد تحويلها. [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
* `timezone` — اسم المنطقة الزمنية المستهدفة. [`String`](/ar/reference/data-types/string)
**القيمة المُعادة**
تُرجع نفس الطابع الزمني المُدخل، ولكن مع المنطقة الزمنية المحددة [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
**أمثلة**
**مثال على الاستخدام**
```sql title=Query theme={null}
SELECT toDateTime('2019-01-01 00:00:00', 'UTC') AS time_utc,
toTypeName(time_utc) AS type_utc,
toInt32(time_utc) AS int32utc,
toTimezone(time_utc, 'Asia/Yekaterinburg') AS time_yekat,
toTypeName(time_yekat) AS type_yekat,
toInt32(time_yekat) AS int32yekat,
toTimezone(time_utc, 'US/Samoa') AS time_samoa,
toTypeName(time_samoa) AS type_samoa,
toInt32(time_samoa) AS int32samoa
FORMAT Vertical;
```
```response title=Response theme={null}
Row 1:
──────
time_utc: 2019-01-01 00:00:00
type_utc: DateTime('UTC')
int32utc: 1546300800
time_yekat: 2019-01-01 05:00:00
type_yekat: DateTime('Asia/Yekaterinburg')
int32yekat: 1546300800
time_samoa: 2018-12-31 13:00:00
type_samoa: DateTime('US/Samoa')
int32samoa: 1546300800
```
## toUTCTimestamp
أُضيفت في: v23.8.0
تحوِّل قيمة تاريخ أو تاريخ ووقت من منطقة زمنية إلى طابع زمني بتوقيت UTC. تُضمَّن هذه الدالة أساسًا للتوافق مع Apache Spark وأطر العمل المشابهة.
**الصيغة**
```sql theme={null}
toUTCTimestamp(datetime, time_zone)
```
**الأسماء البديلة**: `to_utc_timestamp`
**المعاملات**
* `datetime` — قيمة ثابتة من نوع تاريخ أو تاريخ ووقت، أو تعبير. [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
* `time_zone` — قيمة ثابتة من نوع String أو تعبير يمثّل المنطقة الزمنية. [`String`](/ar/reference/data-types/string)
**القيمة المُعادة**
تعيد قيمة تاريخ أو تاريخ ووقت في المنطقة الزمنية UTC. [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
**أمثلة**
**تحويل المنطقة الزمنية إلى UTC**
```sql title=Query theme={null}
SELECT toUTCTimestamp(toDateTime('2023-03-16'), 'Asia/Shanghai')
```
```response title=Response theme={null}
┌─toUTCTimestamp(toDateTime('2023-03-16'), 'Asia/Shanghai')─┐
│ 2023-03-15 16:00:00 │
└─────────────────────────────────────────────────────────┘
```
## toUnixTimestamp
قُدِّمت في: v1.1.0
يحوّل قيمة من النوع `String` أو `Date` أو `DateTime` إلى طابع زمني Unix (عدد الثواني منذ `1970-01-01 00:00:00 UTC`) بصيغة `UInt32`.
**الصياغة**
```sql theme={null}
toUnixTimestamp(date[, timezone])
```
**الوسيطات**
* `date` — القيمة المراد تحويلها. [`Date`](/ar/reference/data-types/date) أو [`Date32`](/ar/reference/data-types/date32) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64) أو [`String`](/ar/reference/data-types/string)
* `timezone` — اختياري. المنطقة الزمنية المستخدمة للتحويل. إذا لم يتم تحديدها، تُستخدم المنطقة الزمنية للخادم. [`String`](/ar/reference/data-types/string)
**القيمة المعادة**
تُرجع الطابع الزمني لـ Unix. [`UInt32`](/ar/reference/data-types/int-uint)
**أمثلة**
**مثال على الاستخدام**
```sql title=Query theme={null}
SELECT
'2017-11-05 08:07:47' AS dt_str,
toUnixTimestamp(dt_str) AS from_str,
toUnixTimestamp(dt_str, 'Asia/Tokyo') AS from_str_tokyo,
toUnixTimestamp(toDateTime(dt_str)) AS from_datetime,
toUnixTimestamp(toDateTime64(dt_str, 0)) AS from_datetime64,
toUnixTimestamp(toDate(dt_str)) AS from_date,
toUnixTimestamp(toDate32(dt_str)) AS from_date32
FORMAT Vertical;
```
```response title=Response theme={null}
Row 1:
──────
dt_str: 2017-11-05 08:07:47
from_str: 1509869267
from_str_tokyo: 1509836867
from_datetime: 1509869267
from_datetime64: 1509869267
from_date: 1509840000
from_date32: 1509840000
```
## toWeek
أُضيفت في: v20.1.0
تعيد هذه الدالة رقم الأسبوع لتاريخ أو قيمة تاريخ ووقت. يتيح لك الشكل ذو الوسيطتين للدالة `toWeek()` تحديد ما إذا كان الأسبوع يبدأ
يوم الأحد أو يوم الاثنين، وما إذا كانت القيمة المُعادة يجب أن تكون ضمن النطاق من `0` إلى `53` أو من `1` إلى `53`.
تُعد [`toISOWeek()`](#toWeek) دالة توافقية مكافئة لـ `toWeek(date,3)`.
يوضح الجدول التالي كيفية عمل وسيطة mode.
| Mode | اليوم الأول من الأسبوع | النطاق | الأسبوع 1 هو أول أسبوع ... |
| ---- | ---------------------- | ------ | ------------------------------------- |
| 0 | الأحد | 0-53 | يحتوي على يوم أحد في هذه السنة |
| 1 | الاثنين | 0-53 | يحتوي على 4 أيام أو أكثر في هذه السنة |
| 2 | الأحد | 1-53 | يحتوي على يوم أحد في هذه السنة |
| 3 | الاثنين | 1-53 | يحتوي على 4 أيام أو أكثر في هذه السنة |
| 4 | الأحد | 0-53 | يحتوي على 4 أيام أو أكثر في هذه السنة |
| 5 | الاثنين | 0-53 | يحتوي على يوم اثنين في هذه السنة |
| 6 | الأحد | 1-53 | يحتوي على 4 أيام أو أكثر في هذه السنة |
| 7 | الاثنين | 1-53 | يحتوي على يوم اثنين في هذه السنة |
| 8 | الأحد | 1-53 | يتضمن 1 يناير |
| 9 | الاثنين | 1-53 | يتضمن 1 يناير |
بالنسبة إلى قيم mode التي يكون معناها "يحتوي على 4 أيام أو أكثر في هذه السنة"، تُرقَّم الأسابيع وفقًا للمعيار ISO 8601:1988:
* إذا كان الأسبوع الذي يتضمن 1 يناير يحتوي على 4 أيام أو أكثر في السنة الجديدة، فهو الأسبوع 1.
* وإلا، فهو الأسبوع الأخير من السنة السابقة، ويكون الأسبوع التالي هو الأسبوع 1.
بالنسبة إلى قيم mode التي يكون معناها "يتضمن 1 يناير"، فإن الأسبوع الذي يتضمن 1 يناير هو الأسبوع 1.
ولا يهم عدد الأيام من السنة الجديدة التي يتضمنها ذلك الأسبوع، حتى لو كان يتضمن يومًا واحدًا فقط.
أي إذا كان الأسبوع الأخير من ديسمبر يتضمن 1 يناير من السنة التالية، فسيكون هو الأسبوع 1 من السنة التالية.
يمكن أيضًا تحديد الوسيطة الأولى على أنها [`String`](/ar/reference/data-types/string) بتنسيق تدعمه [`parseDateTime64BestEffort()`](/ar/reference/functions/regular-functions/type-conversion-functions#parseDateTime64BestEffort). يوجد دعم لوسائط السلاسل النصية فقط لأسباب تتعلق بالتوافق مع MySQL، كما تتطلبه بعض أدوات الجهات الخارجية. ونظرًا إلى أن دعم وسائط السلاسل النصية قد يصبح في المستقبل معتمدًا على إعدادات جديدة للتوافق مع MySQL، ولأن تحليل السلاسل النصية بطيء عمومًا، يُوصى بعدم استخدامه.
**الصياغة**
```sql theme={null}
toWeek(datetime[, mode[, time_zone]])
```
**الأسماء البديلة**: `week`
**الوسيطات**
* `datetime` — `Date` أو تاريخ مع وقت لاستخراج رقم الأسبوع منه. [`Date`](/ar/reference/data-types/date) أو [`DateTime`](/ar/reference/data-types/datetime)
* `mode` — اختياري. يحدد النمط من `0` إلى `9` اليوم الأول من الأسبوع ونطاق رقم الأسبوع. القيمة الافتراضية هي `0`. - `time_zone` — اختياري. المنطقة الزمنية. [`String`](/ar/reference/data-types/string)
**القيمة المُعادة**
يعيد رقم الأسبوع وفقًا للنمط المحدد. [`UInt32`](/ar/reference/data-types/int-uint)
**أمثلة**
**الحصول على أرقام الأسابيع باستخدام أنماط مختلفة**
```sql title=Query theme={null}
SELECT toDate('2016-12-27') AS date, toWeek(date) AS week0, toWeek(date,1) AS week1, toWeek(date,9) AS week9
```
```response title=Response theme={null}
┌───────date─┬─week0─┬─week1─┬─week9─┐
│ 2016-12-27 │ 52 │ 52 │ 1 │
└────────────┴───────┴───────┴───────┘
```
## toYYYYMM
أُضيفت في: v1.1.0
تحوّل تاريخًا أو تاريخًا ووقتًا إلى رقم `UInt32` يحتوي على السنة ورقم الشهر (YYYY \* 100 + MM).
وتقبل وسيطة ثانية اختيارية للمنطقة الزمنية. وإذا قُدِّمت، فيجب أن تكون قيمة المنطقة الزمنية ثابتًا نصيًا.
هذه الدالة هي عكس الدالة `YYYYMMDDToDate()`.
**الصيغة**
```sql theme={null}
toYYYYMM(datetime[, timezone])
```
**الوسيطات**
* `datetime` — تاريخ أو تاريخ يتضمن وقتًا لتحويله. [`Date`](/ar/reference/data-types/date) أو [`Date32`](/ar/reference/data-types/date32) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
* `timezone` — اختياري. المنطقة الزمنية للتحويل. إذا جرى توفيرها، فيجب أن تكون المنطقة الزمنية ثابتًا نصيًا. [`String`](/ar/reference/data-types/string)
**القيمة المُعادة**
يعيد رقمًا من النوع UInt32 يحتوي على رقمَي السنة والشهر (YYYY \* 100 + MM). [`UInt32`](/ar/reference/data-types/int-uint)
**أمثلة**
**تحويل التاريخ الحالي إلى تنسيق YYYYMM**
```sql title=Query theme={null}
SELECT toYYYYMM(now(), 'US/Eastern')
```
```response title=Response theme={null}
┌─toYYYYMM(now(), 'US/Eastern')─┐
│ 202303 │
└───────────────────────────────┘
```
## toYYYYMMDD
أُضيف في: v1.1.0
يحوّل قيمة تاريخ أو تاريخ ووقت إلى عدد `UInt32` يحتوي على السنة والشهر واليوم (YYYY \* 10000 + MM \* 100 + DD). ويقبل وسيطة ثانية اختيارية هي `timezone`. وإذا تم توفيرها، فيجب أن تكون `timezone` قيمة `string constant`.
**البنية**
```sql theme={null}
toYYYYMMDD(datetime[, timezone])
```
**الوسيطات**
* `datetime` — تاريخ أو تاريخ ووقت للتحويل. [`Date`](/ar/reference/data-types/date) أو [`Date32`](/ar/reference/data-types/date32) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
* `timezone` — اختياري. المنطقة الزمنية المستخدمة في التحويل. إذا تم تحديدها، فيجب أن تكون المنطقة الزمنية ثابتًا نصيًا. [`String`](/ar/reference/data-types/string)
**القيمة المعادة**
يعيد قيمة من النوع `UInt32` تحتوي على السنة والشهر واليوم (YYYY \* 10000 + MM \* 100 + DD). [`UInt32`](/ar/reference/data-types/int-uint)
**أمثلة**
**حوّل التاريخ الحالي إلى تنسيق YYYYMMDD**
```sql title=Query theme={null}
SELECT toYYYYMMDD(now(), 'US/Eastern')
```
```response title=Response theme={null}
┌─toYYYYMMDD(now(), 'US/Eastern')─┐
│ 20230302 │
└─────────────────────────────────┘
```
## toYYYYMMDDhhmmss
أُضيفت في: v1.1.0
تحوِّل قيمة من نوع تاريخ أو تاريخ ووقت إلى رقم `UInt64` يحتوي على السنة ورقم الشهر (YYYY \* 10000000000 + MM \* 100000000 + DD \* 1000000 + hh \* 10000 + mm \* 100 + ss).
تقبل وسيطًا اختياريًا ثانيًا للمنطقة الزمنية. وإذا تم توفيره، فيجب أن تكون المنطقة الزمنية ثابتًا نصيًا.
**البنية**
```sql theme={null}
toYYYYMMDDhhmmss(datetime[, timezone])
```
**الوسيطات**
* `datetime` — `Date` أو تاريخ أو تاريخ مع وقت للتحويل. [`Date`](/ar/reference/data-types/date) أو [`Date32`](/ar/reference/data-types/date32) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
* `timezone` — اختياري. المنطقة الزمنية للتحويل. إذا تم توفيرها، فيجب أن تكون المنطقة الزمنية ثابتًا نصيًا. [`String`](/ar/reference/data-types/string)
**القيمة المُعادة**
يعيد عددًا من النوع `UInt64` يحتوي على السنة والشهر واليوم والساعة والدقيقة والثانية (YYYY \* 10000000000 + MM \* 100000000 + DD \* 1000000 + hh \* 10000 + mm \* 100 + ss). [`UInt64`](/ar/reference/data-types/int-uint)
**أمثلة**
**حوّل التاريخ والوقت الحاليين إلى تنسيق YYYYMMDDhhmmss**
```sql title=Query theme={null}
SELECT toYYYYMMDDhhmmss(now(), 'US/Eastern')
```
```response title=Response theme={null}
┌─toYYYYMMDDhhmmss(now(), 'US/Eastern')─┐
│ 20230302112209 │
└───────────────────────────────────────┘
```
## toYear
أُضيفت في: v1.1.0
تُرجع مكوّن السنة (ميلادي) من قيمة `Date` أو `DateTime`.
**البنية**
```sql theme={null}
toYear(datetime)
```
**الأسماء البديلة**: `YEAR`
**الوسيطات**
* `datetime` — تاريخ أو تاريخ مع وقت لاستخراج السنة منه. [`Date`](/ar/reference/data-types/date) أو [`Date32`](/ar/reference/data-types/date32) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
**القيمة المُعادة**
تعيد سنة قيمة `Date` أو `DateTime` المُعطاة [`UInt16`](/ar/reference/data-types/int-uint)
**أمثلة**
**مثال على الاستخدام**
```sql title=Query theme={null}
SELECT toYear(toDateTime('2023-04-21 10:20:30'))
```
```response title=Response theme={null}
┌─toYear(toDateTime('2023-04-21 10:20:30'))─┐
│ 2023 │
└───────────────────────────────────────────┘
```
## toYearNumSinceEpoch
استُحدثت في: v25.3.0
تعيد عدد السنوات المنقضية منذ عام 1970
**الصياغة**
```sql theme={null}
toYearNumSinceEpoch(date)
```
**الوسائط**
* `date` — تاريخ أو تاريخ ووقت لتحويله. [`Date`](/ar/reference/data-types/date) أو [`DateTime`](/ar/reference/data-types/datetime) أو [`DateTime64`](/ar/reference/data-types/datetime64)
**القيمة المُعادة**
عدد صحيح موجب
**أمثلة**
**مثال**
```sql title=Query theme={null}
SELECT toYearNumSinceEpoch(toDate('2024-10-01'))
```
```response title=Response theme={null}
54
```
## toYearWeek
أُضيف في: v20.1.0
تعيد هذه الدالة السنة ورقم الأسبوع لتاريخٍ ما. وقد تختلف السنة في النتيجة عن السنة في وسيطة التاريخ في الأسبوع الأول والأسبوع الأخير من السنة.
تعمل الوسيطة mode بالطريقة نفسها التي تعمل بها الوسيطة mode في [`toWeek()`](/ar/reference/functions/regular-functions/date-time-functions#toWeek).
تحذير: قد يختلف رقم الأسبوع الذي تُعيده `toYearWeek()` عن الرقم الذي تُعيده `toWeek()`. إذ تُعيد `toWeek()` دائمًا رقم الأسبوع ضمن سياق السنة المحددة، وإذا أعادت `toWeek()` القيمة `0`، فإن `toYearWeek()` تُعيد القيمة المقابلة لآخر أسبوع من السنة السابقة. راجع `prev_yearWeek` في المثال أدناه.
يمكن أيضًا تحديد الوسيطة الأولى على أنها [`String`](/ar/reference/data-types/string) بتنسيق تدعمه [`parseDateTime64BestEffort()`](/ar/reference/functions/regular-functions/type-conversion-functions#parseDateTime64BestEffort). ولا يوجد دعم لوسيطات السلاسل النصية إلا لأسباب تتعلق بالتوافق مع MySQL، كما تتطلبه بعض الأدوات الخارجية. ونظرًا إلى أن دعم وسائط السلاسل النصية قد يصبح في المستقبل معتمدًا على إعدادات جديدة للتوافق مع MySQL، ولأن تحليل السلاسل النصية بطيء عمومًا، يُوصى بعدم استخدامها.
**الصياغة**
```sql theme={null}
toYearWeek(datetime[, mode[, timezone]])
```
**الأسماء المستعارة**: `yearweek`
**الوسائط**
* `datetime` — التاريخ أو التاريخ مع الوقت المراد استخراج السنة ورقم الأسبوع منه. [`Date`](/ar/reference/data-types/date) أو [`DateTime`](/ar/reference/data-types/datetime)
* `mode` — اختياري. يحدد النمط من `0` إلى `9` اليوم الأول من الأسبوع ونطاق رقم الأسبوع. القيمة الافتراضية `0`. - `timezone` — اختياري. المنطقة الزمنية. [`String`](/ar/reference/data-types/string)
**القيمة المعادة**
تعيد السنة ورقم الأسبوع كقيمة عددية صحيحة مدمجة. [`UInt32`](/ar/reference/data-types/int-uint)
**أمثلة**
**الحصول على تركيبات السنة-الأسبوع باستخدام أنماط مختلفة**
```sql title=Query theme={null}
SELECT toDate('2016-12-27') AS date, toYearWeek(date) AS yearWeek0, toYearWeek(date,1) AS yearWeek1, toYearWeek(date,9) AS yearWeek9, toYearWeek(toDate('2022-01-01')) AS prev_yearWeek
```
```response title=Response theme={null}
┌───────date─┬─yearWeek0─┬─yearWeek1─┬─yearWeek9─┬─prev_yearWeek─┐
│ 2016-12-27 │ 201652 │ 201652 │ 201701 │ 202152 │
└────────────┴───────────┴───────────┴───────────┴───────────────┘
```
## today
أُضيف في: v1.1.0
يعيد التاريخ الحالي وقت تحليل الاستعلام. وهو مطابق لـ `toDate(now())`.
**الصياغة**
```sql theme={null}
today()
```
**الأسماء البديلة**: `curdate`, `current_date`
**المعاملات**
* لا توجد.
**القيمة المُعادة**
تعيد التاريخ الحالي [`Date`](/ar/reference/data-types/date)
**أمثلة**
**مثال على الاستخدام**
```sql title=Query theme={null}
SELECT today() AS today, curdate() AS curdate, current_date() AS current_date FORMAT Pretty
```
```response title=Response theme={null}
┏━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━━┓
┃ today ┃ curdate ┃ current_date ┃
┡━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━━┩
│ 2025-03-03 │ 2025-03-03 │ 2025-03-03 │
└────────────┴────────────┴──────────────┘
```
**صياغة SQL القياسية بدون أقواس**
```sql title=Query theme={null}
SELECT TODAY, CURDATE,CURRENT_DATE
```
```response title=Response theme={null}
┏━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━━┓
┃ TODAY ┃ CURDATE ┃ CURRENT_DATE ┃
┡━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━━┩
│ 2025-03-04 │ 2025-03-04 │ 2025-03-04 │
└────────────┴────────────┴──────────────┘
```
## yesterday
أُضيفت في: v1.1.0
لا تقبل أي وسيطات وتُرجِع تاريخ الأمس في إحدى مراحل تحليل الاستعلام.
**البنية**
```sql theme={null}
yesterday()
```
**المعاملات**
* لا شيء.
**القيمة المُعادة**
يُرجع تاريخ الأمس. [`Date`](/ar/reference/data-types/date)
**أمثلة**
**الحصول على تاريخ الأمس**
```sql title=Query theme={null}
SELECT yesterday();
SELECT today() - 1;
```
```response title=Response theme={null}
┌─yesterday()─┐
│ 2025-06-09 │
└─────────────┘
┌─minus(today(), 1)─┐
│ 2025-06-09 │
└───────────────────┘
```