دوال الطابع الزمني

دوال الطابع الزمني

الاسم الوصف
CURRENT_TIMESTAMP يتم إنشاء TIMESTAMP يتوافق مع وقت الطلب.
TIMESTAMP_TRUNC يتم اقتطاع TIMESTAMP إلى درجة دقة معيّنة.
UNIX_MICROS_TO_TIMESTAMP تحوّل هذه الدالة عدد الميكروثانية منذ ‎1970-01-01 00:00:00 UTC إلى TIMESTAMP
UNIX_MILLIS_TO_TIMESTAMP تحوّل هذه الدالة عدد الملّي ثانية منذ 1970-01-01 00:00:00 UTC إلى TIMESTAMP
UNIX_SECONDS_TO_TIMESTAMP تحوّل هذه الدالة عدد الثواني منذ 1970-01-01 00:00:00 UTC إلى TIMESTAMP
TIMESTAMP_ADD تضيف هذه الدالة فاصلاً زمنيًا إلى TIMESTAMP.
TIMESTAMP_SUB تطرح هذه الدالة فاصلاً زمنيًا من TIMESTAMP
TIMESTAMP_TO_UNIX_MICROS تحوّل TIMESTAMP إلى عدد الميكروثانية منذ 1970-01-01 00:00:00 UTC
TIMESTAMP_TO_UNIX_MILLIS تحوّل TIMESTAMP إلى عدد المللي ثانية منذ 1970-01-01 00:00:00 UTC
TIMESTAMP_TO_UNIX_SECONDS تحوّل TIMESTAMP إلى عدد الثواني منذ 1970-01-01 00:00:00 UTC
TIMESTAMP_DIFF تعرض هذه الدالة العدد الصحيح للفواصل الزمنية المحدّدة لـ unit بين قيمتَي TIMESTAMP.
TIMESTAMP_EXTRACT تستخرج هذه الدالة part محدّدًا (مثل السنة أو الشهر أو اليوم) من TIMESTAMP.

CURRENT_TIMESTAMP

البنية:

current_timestamp() -> TIMESTAMP

الوصف:

تحصل على الطابع الزمني في بداية وقت الطلب input (يتم تفسيره على أنّه عدد الميكروثانية منذ 1970-01-01 00:00:00 UTC).

تكون هذه الدالة ثابتة ضمن طلب البحث، وسيتم دائمًا حلّها بالقيمة نفسها إذا تم استدعاؤها عدة مرات.

TIMESTAMP_TRUNC

البنية:

timestamp_trunc(timestamp: TIMESTAMP | BSON_TIMESTAMP, granularity: STRING[, timezone: STRING]) -> TIMESTAMP

الوصف:

يتم اقتطاع طابع زمني إلى مستوى دقة معيّن.

يجب أن تكون الوسيطة granularity سلسلة وإحدى القيم التالية:

  • microsecond
  • millisecond
  • second
  • minute
  • hour
  • day
  • week
  • week([weekday])
  • month
  • quarter
  • year
  • isoyear

في حال تقديم الوسيطة timezone، سيستند الاقتطاع إلى حدود التقويم في المنطقة الزمنية المحدّدة (على سبيل المثال، سيتم اقتطاع اليوم إلى منتصف الليل في المنطقة الزمنية المحدّدة). سيتم اقتطاع الوقت وفقًا لنظام التوقيت الصيفي.

إذا لم يتم توفير timezone، سيتم الاقتطاع استنادًا إلى حدود التقويم UTC.

يجب أن تكون الوسيطة timezone تمثيلاً نصيًا لمنطقة زمنية من قاعدة بيانات tz، على سبيل المثال America/New_York. يمكن أيضًا استخدام إزاحة زمنية مخصّصة من خلال تحديد إزاحة من GMT.

أمثلة:

timestamp granularity timezone timestamp_trunc(timestamp, granularity, timezone)
‫2000-01-01 10:20:30:123456 بالتوقيت العالمي المنسّق "second" غير متوفر ‫2001-01-01 10:20:30 بالتوقيت العالمي المنسَّق
‫1997-05-31 04:30:30 بالتوقيت العالمي المنسّق "day" غير متوفر ‫1997-05-31 00:00:00 بالتوقيت العالمي المنسق
‫1997-05-31 04:30:30 بالتوقيت العالمي المنسّق "day" "America/Los_Angeles" ‫1997-05-30 07:00:00 بالتوقيت العالمي المنسّق
‫2001-03-16 04:00:00 بالتوقيت العالمي المنسّق "week(friday) غير متوفر ‫2001-03-16 00:00:00 بالتوقيت العالمي المنسّق
‫2001-03-23 04:00:00 بالتوقيت العالمي المنسّق "week(friday) "America/Los_Angeles" ‫2001-03-23 17:00:00 بالتوقيت العالمي المنسّق
‫24 يناير 2026، الساعة 8:00 مساءً بالتوقيت العالمي المنسّق "month" "GMT+06:32:43" ‫2026-01-01T06:32:43 بالتوقيت العالمي المنسق

UNIX_MICROS_TO_TIMESTAMP

البنية:

unix_micros_to_timestamp(input: INT64) -> TIMESTAMP

الوصف:

تحوّل هذه الدالة input (التي يتم تفسيرها على أنّها عدد الميكروثانية منذ 1970-01-01 00:00:00 UTC) إلى TIMESTAMP. يتم عرض error إذا تعذّر تحويل input إلى TIMESTAMP صالح.

أمثلة:

input unix_micros_to_timestamp(input)
0 لتر ‫1970-01-01 00:00:00 بالتوقيت العالمي المنسق
400123456L 1970-01-01 00:06:40.123456 UTC
-1000000L ‫31/12/1969 الساعة 11:59:59 مساءً بالتوقيت العالمي المنسّق
Node.js
const result = await db.pipeline()
  .collection("documents")
  .select(
    field("createdAtMicros").unixMicrosToTimestamp().as("createdAtString")
  )
  .execute();

Web

const result = await execute(db.pipeline()
  .collection("documents")
  .select(
    field("createdAtMicros").unixMicrosToTimestamp().as("createdAtString")
  )
);
Swift
let result = try await db.pipeline()
  .collection("documents")
  .select([
    Field("createdAtMicros").unixMicrosToTimestamp().as("createdAtString")
  ])
  .execute()

Kotlin

val result = db.pipeline()
    .collection("documents")
    .select(
        field("createdAtMicros").unixMicrosToTimestamp().alias("createdAtString")
    )
    .execute()

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("documents")
    .select(
        field("createdAtMicros").unixMicrosToTimestamp().alias("createdAtString")
    )
    .execute();
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("documents")
    .select(
        Field.of("createdAtMicros")
        .unix_micros_to_timestamp()
        .as_("createdAtString")
    )
    .execute()
)
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("documents")
        .select(unixMicrosToTimestamp(field("createdAtMicros")).as("createdAtString"))
        .execute()
        .get();
متابعة
snapshot := client.Pipeline().
	Collection("documents").
	Select(firestore.Fields(
		firestore.UnixMicrosToTimestamp(firestore.FieldOf("createdAtMicros")).As("createdAtString"),
	)).
	Execute(ctx)

UNIX_MILLIS_TO_TIMESTAMP

البنية:

unix_millis_to_timestamp(input: INT64) -> TIMESTAMP

الوصف:

تحوّل هذه الدالة input (التي يتم تفسيرها على أنّها عدد المللي ثانية منذ 1970-01-01 00:00:00 UTC) إلى TIMESTAMP. يتم عرض error إذا تعذّر تحويل input إلى TIMESTAMP صالح.

أمثلة:

input unix_millis_to_timestamp(input)
0 لتر ‫1970-01-01 00:00:00 بالتوقيت العالمي المنسق
4000123L ‫1970-01-01 01:06:40.123 بالتوقيت العالمي المنسق
-1000000L ‫1969-12-31 23:43:20 بالتوقيت العالمي المنسّق
Node.js
const result = await db.pipeline()
  .collection("documents")
  .select(
    field("createdAtMillis").unixMillisToTimestamp().as("createdAtString")
  )
  .execute();

Web

const result = await execute(db.pipeline()
  .collection("documents")
  .select(
    field("createdAtMillis").unixMillisToTimestamp().as("createdAtString")
  )
);
Swift
let result = try await db.pipeline()
  .collection("documents")
  .select([
    Field("createdAtMillis").unixMillisToTimestamp().as("createdAtString")
  ])
  .execute()

Kotlin

val result = db.pipeline()
    .collection("documents")
    .select(
        field("createdAtMillis").unixMillisToTimestamp().alias("createdAtString")
    )
    .execute()

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("documents")
    .select(
        field("createdAtMillis").unixMillisToTimestamp().alias("createdAtString")
    )
    .execute();
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("documents")
    .select(
        Field.of("createdAtMillis")
        .unix_millis_to_timestamp()
        .as_("createdAtString")
    )
    .execute()
)
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("documents")
        .select(unixMillisToTimestamp(field("createdAtMillis")).as("createdAtString"))
        .execute()
        .get();
متابعة
snapshot := client.Pipeline().
	Collection("documents").
	Select(firestore.Fields(
		firestore.UnixMillisToTimestamp(firestore.FieldOf("createdAtMillis")).As("createdAtString"),
	)).
	Execute(ctx)

UNIX_SECONDS_TO_TIMESTAMP

البنية:

unix_seconds_to_timestamp(input: INT64) -> TIMESTAMP

الوصف:

تحوّل هذه الدالة input (التي يتم تفسيرها على أنّها عدد الثواني منذ 1970-01-01 00:00:00 UTC) إلى TIMESTAMP. يتم عرض error إذا تعذّر تحويل input إلى TIMESTAMP صالح.

أمثلة:

input unix_seconds_to_timestamp(input)
0 لتر ‫1970-01-01 00:00:00 بالتوقيت العالمي المنسق
60 لتر ‫1970-01-01 00:01:00 بالتوقيت العالمي المنسق
-300L ‫31-12-1969 الساعة 11:55 مساءً بالتوقيت العالمي المنسّق
Node.js
const result = await db.pipeline()
  .collection("documents")
  .select(
    field("createdAtSeconds").unixSecondsToTimestamp().as("createdAtString")
  )
  .execute();

Web

const result = await execute(db.pipeline()
  .collection("documents")
  .select(
    field("createdAtSeconds").unixSecondsToTimestamp().as("createdAtString")
  )
);
Swift
let result = try await db.pipeline()
  .collection("documents")
  .select([
    Field("createdAtSeconds").unixSecondsToTimestamp().as("createdAtString")
  ])
  .execute()

Kotlin

val result = db.pipeline()
    .collection("documents")
    .select(
        field("createdAtSeconds").unixSecondsToTimestamp().alias("createdAtString")
    )
    .execute()

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("documents")
    .select(
        field("createdAtSeconds").unixSecondsToTimestamp().alias("createdAtString")
    )
    .execute();
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("documents")
    .select(
        Field.of("createdAtSeconds")
        .unix_seconds_to_timestamp()
        .as_("createdAtString")
    )
    .execute()
)
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("documents")
        .select(unixSecondsToTimestamp(field("createdAtSeconds")).as("createdAtString"))
        .execute()
        .get();
متابعة
snapshot := client.Pipeline().
	Collection("documents").
	Select(firestore.Fields(
		firestore.UnixSecondsToTimestamp(firestore.FieldOf("createdAtSeconds")).As("createdAtString"),
	)).
	Execute(ctx)

TIMESTAMP_ADD

البنية:

timestamp_add(timestamp: TIMESTAMP | BSON_TIMESTAMP, unit: STRING, amount: INT64) -> TIMESTAMP

الوصف:

يضيف amount من unit من timestamp. يمكن أن تكون الوسيطة amount سالبة، وفي هذه الحالة تكون مكافئة لـ TIMESTAMP_SUB.

يجب أن تكون الوسيطة unit سلسلة وإحدى القيم التالية:

  • microsecond
  • millisecond
  • second
  • minute
  • hour
  • day

يتم عرض خطأ إذا لم يكن الطابع الزمني الناتج ضمن نطاق TIMESTAMP.

أمثلة:

timestamp unit amount timestamp_add(timestamp, unit, amount)
‫2025-02-20‎ 00:00:00 بالتوقيت العالمي المنسق "minute" ‫2 لتر ‫2025-02-20 00:02:00 بالتوقيت العالمي المنسق
‫2025-02-20‎ 00:00:00 بالتوقيت العالمي المنسق "hour" -4L ‫19-02-2025‎ 20:00:00 بالتوقيت العالمي المنسق
‫2025-02-20‎ 00:00:00 بالتوقيت العالمي المنسق "day" ‫5 لتر ‫25 فبراير 2025، الساعة 12:00 صباحًا بالتوقيت العالمي المنسَّق
Node.js
const result = await db.pipeline()
  .collection("documents")
  .select(
    field("createdAt").timestampAdd("day", 3653).as("expiresAt")
  )
  .execute();

Web

const result = await execute(db.pipeline()
  .collection("documents")
  .select(
    field("createdAt").timestampAdd("day", 3653).as("expiresAt")
  )
);
Swift
let result = try await db.pipeline()
  .collection("documents")
  .select([
    Field("createdAt").timestampAdd(3653, .day).as("expiresAt")
  ])
  .execute()

Kotlin

val result = db.pipeline()
    .collection("documents")
    .select(
        field("createdAt")
          .timestampAdd("day", 3653)
          .alias("expiresAt")
    )
    .execute()

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("documents")
    .select(
        field("createdAt").timestampAdd("day", 3653).alias("expiresAt")
    )
    .execute();
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("documents")
    .select(Field.of("createdAt").timestamp_add("day", 3653).as_("expiresAt"))
    .execute()
)
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("documents")
        .select(timestampAdd(field("createdAt"), "day", 3653).as("expiresAt"))
        .execute()
        .get();
متابعة
snapshot := client.Pipeline().
	Collection("documents").
	Select(firestore.Fields(
		firestore.TimestampAdd(firestore.FieldOf("createdAt"), "day", 3653).As("expiresAt"),
	)).
	Execute(ctx)

TIMESTAMP_SUB

البنية:

timestamp_sub(timestamp: TIMESTAMP | BSON_TIMESTAMP, unit: STRING, amount: INT64) -> TIMESTAMP

الوصف:

تطرح هذه الدالة amount من unit من timestamp. يمكن أن تكون الوسيطة amount سالبة، وفي هذه الحالة تكون مكافئة لـ TIMESTAMP_ADD.

يجب أن تكون الوسيطة unit سلسلة وإحدى القيم التالية:

  • microsecond
  • millisecond
  • second
  • minute
  • hour
  • day

يتم عرض خطأ إذا لم يكن الطابع الزمني الناتج ضمن نطاق TIMESTAMP.

أمثلة:

timestamp unit amount timestamp_sub(timestamp, unit, amount)
‫2026-07-04 00:00:00 بالتوقيت العالمي المنسق "minute" ‫40 لتر ‫2026-07-03‎ 23:20:00 بالتوقيت العالمي المنسّق
‫2026-07-04 00:00:00 بالتوقيت العالمي المنسق "hour" -24L ‫‎2026-07-05 00:00:00 بالتوقيت العالمي المنسَّق
‫2026-07-04 00:00:00 بالتوقيت العالمي المنسق "day" 3L ‫‎2026-07-01 00:00:00 UTC
Node.js
const result = await db.pipeline()
  .collection("documents")
  .select(
    field("expiresAt").timestampSubtract("day", 14).as("sendWarningTimestamp")
  )
  .execute();

Web

const result = await execute(db.pipeline()
  .collection("documents")
  .select(
    field("expiresAt").timestampSubtract("day", 14).as("sendWarningTimestamp")
  )
);
Swift
let result = try await db.pipeline()
  .collection("documents")
  .select([
    Field("expiresAt").timestampSubtract(14, .day).as("sendWarningTimestamp")
  ])
  .execute()

Kotlin

val result = db.pipeline()
    .collection("documents")
    .select(
        field("expiresAt")
          .timestampSubtract("day", 14)
          .alias("sendWarningTimestamp")
    )
    .execute()

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("documents")
    .select(
        field("expiresAt").timestampSubtract("day", 14).alias("sendWarningTimestamp")
    )
    .execute();
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("documents")
    .select(
        Field.of("expiresAt")
        .timestamp_subtract("day", 14)
        .as_("sendWarningTimestamp")
    )
    .execute()
)
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("documents")
        .select(timestampSubtract(field("expiresAt"), "day", 14).as("sendWarningTimestamp"))
        .execute()
        .get();
متابعة
snapshot := client.Pipeline().
	Collection("documents").
	Select(firestore.Fields(
		firestore.TimestampSubtract(firestore.FieldOf("expiresAt"), "day", 14).As("sendWarningTimestamp"),
	)).
	Execute(ctx)

TIMESTAMP_TO_UNIX_MICROS

البنية:

timestamp_to_unix_micros(input: TIMESTAMP | BSON_TIMESTAMP) -> INT64

الوصف:

تحوّل input إلى عدد الميكروثانية منذ 1970-01-01 00:00:00 UTC. يتم اقتطاع المستويات الأعلى من الدقة من خلال التقريب إلى بداية الميكروثانية.

أمثلة:

input timestamp_to_unix_micros(input)
‫1970-01-01 00:00:00 بالتوقيت العالمي المنسق 0 لتر
1970-01-01 00:06:40.123456 UTC 400123456L
‫31/12/1969 الساعة 11:59:59 مساءً بالتوقيت العالمي المنسّق -1000000L
Node.js
const result = await db.pipeline()
  .collection("documents")
  .select(
    field("dateString").timestampToUnixMicros().as("unixMicros")
  )
  .execute();

Web

const result = await execute(db.pipeline()
  .collection("documents")
  .select(
    field("dateString").timestampToUnixMicros().as("unixMicros")
  )
);
Swift
let result = try await db.pipeline()
  .collection("documents")
  .select([
    Field("dateString").timestampToUnixMicros().as("unixMicros")
  ])
  .execute()

Kotlin

val result = db.pipeline()
    .collection("documents")
    .select(
        field("dateString").timestampToUnixMicros().alias("unixMicros")
    )
    .execute()

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("documents")
    .select(
        field("dateString").timestampToUnixMicros().alias("unixMicros")
    )
    .execute();
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("documents")
    .select(Field.of("dateString").timestamp_to_unix_micros().as_("unixMicros"))
    .execute()
)
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("documents")
        .select(timestampToUnixMicros(field("dateString")).as("unixMicros"))
        .execute()
        .get();
متابعة
snapshot := client.Pipeline().
	Collection("documents").
	Select(firestore.Fields(
		firestore.TimestampToUnixMicros(firestore.FieldOf("dateString")).As("unixMicros"),
	)).
	Execute(ctx)

TIMESTAMP_TO_UNIX_MILLIS

البنية:

timestamp_to_unix_millis(input: TIMESTAMP | BSON_TIMESTAMP) -> INT64

الوصف:

تحوّل هذه الدالة input إلى عدد الملّي ثانية منذ 1970-01-01 00:00:00 UTC. يتم اقتطاع المستويات الأعلى من الدقة عن طريق التقريب إلى بداية الملّي ثانية.

أمثلة:

input timestamp_to_unix_millis(input)
‫1970-01-01 00:00:00 بالتوقيت العالمي المنسق 0 لتر
‫1970-01-01 01:06:40.123 بالتوقيت العالمي المنسق 4000123L
‫31/12/1969 23:43:20 -1000000L
Node.js
const result = await db.pipeline()
  .collection("documents")
  .select(
    field("dateString").timestampToUnixMillis().as("unixMillis")
  )
  .execute();

Web

const result = await execute(db.pipeline()
  .collection("documents")
  .select(
    field("dateString").timestampToUnixMillis().as("unixMillis")
  )
);
Swift
let result = try await db.pipeline()
  .collection("documents")
  .select([
    Field("dateString").timestampToUnixMillis().as("unixMillis")
  ])
  .execute()

Kotlin

val result = db.pipeline()
    .collection("documents")
    .select(
        field("dateString").timestampToUnixMillis().alias("unixMillis")
    )
    .execute()

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("documents")
    .select(
        field("dateString").timestampToUnixMillis().alias("unixMillis")
    )
    .execute();
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("documents")
    .select(Field.of("dateString").timestamp_to_unix_millis().as_("unixMillis"))
    .execute()
)
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("documents")
        .select(timestampToUnixMillis(field("dateString")).as("unixMillis"))
        .execute()
        .get();
متابعة
snapshot := client.Pipeline().
	Collection("documents").
	Select(firestore.Fields(
		firestore.TimestampToUnixMillis(firestore.FieldOf("dateString")).As("unixMillis"),
	)).
	Execute(ctx)

TIMESTAMP_TO_UNIX_SECONDS

البنية:

timestamp_to_unix_seconds(input: TIMESTAMP | BSON_TIMESTAMP) -> INT64

الوصف:

تحوّل هذه الدالة input إلى عدد الثواني منذ 1970-01-01 00:00:00 UTC. يتم اقتطاع المستويات الأعلى من الدقة عن طريق التقريب إلى بداية الثانية.

أمثلة:

input timestamp_to_unix_seconds(input)
‫1970-01-01 00:00:00 بالتوقيت العالمي المنسق 0 لتر
‫1970-01-01 00:01:00 بالتوقيت العالمي المنسق 60 لتر
‫31-12-1969 الساعة 11:55 مساءً بالتوقيت العالمي المنسّق -300L
Node.js
const result = await db.pipeline()
  .collection("documents")
  .select(
    field("dateString").timestampToUnixSeconds().as("unixSeconds")
  )
  .execute();

Web

const result = await execute(db.pipeline()
  .collection("documents")
  .select(
    field("dateString").timestampToUnixSeconds().as("unixSeconds")
  )
);
Swift
let result = try await db.pipeline()
  .collection("documents")
  .select([
    Field("dateString").timestampToUnixSeconds().as("unixSeconds")
  ])
  .execute()

Kotlin

val result = db.pipeline()
    .collection("documents")
    .select(
        field("dateString").timestampToUnixSeconds().alias("unixSeconds")
    )
    .execute()

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("documents")
    .select(
        field("dateString").timestampToUnixSeconds().alias("unixSeconds")
    )
    .execute();
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("documents")
    .select(Field.of("dateString").timestamp_to_unix_seconds().as_("unixSeconds"))
    .execute()
)
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("documents")
        .select(timestampToUnixSeconds(field("dateString")).as("unixSeconds"))
        .execute()
        .get();
متابعة
snapshot := client.Pipeline().
	Collection("documents").
	Select(firestore.Fields(
		firestore.TimestampToUnixSeconds(firestore.FieldOf("dateString")).As("unixSeconds"),
	)).
	Execute(ctx)

TIMESTAMP_DIFF

البنية:

timestamp_diff(end: TIMESTAMP | BSON_TIMESTAMP, start: TIMESTAMP | BSON_TIMESTAMP, unit: STRING) -> INT64

الوصف:

تعرض هذه الدالة العدد الصحيح للفواصل الزمنية المحدّدة لـ unit بين قيمتَي TIMESTAMP.

  • تعرض قيمة سالبة إذا كان end قبل start.
  • يتم اقتطاع أي وحدة كسرية. على سبيل المثال، تعرض الدالة timestamp_diff("2021-01-01 00:00:01", "2021-01-01 00:00:00", "minute") القيمة 0.

يجب أن تكون الوسيطة unit سلسلة وإحدى القيم التالية:

  • microsecond
  • millisecond
  • second
  • minute
  • hour
  • day

أمثلة:

end start unit timestamp_diff(end, start, unit)
‫‎2026-07-04 00:01:00 بالتوقيت العالمي المنسق ‫2026-07-04 00:00:00 بالتوقيت العالمي المنسق "second" 60 لتر
‫2026-07-04 00:00:00 بالتوقيت العالمي المنسق ‫‎2026-07-05 00:00:00 بالتوقيت العالمي المنسَّق "day" -1L
‫2026-07-04‎ 00:00:59 بالتوقيت العالمي المنسَّق ‫2026-07-04 00:00:00 بالتوقيت العالمي المنسق "minute" 0 لتر

TIMESTAMP_EXTRACT

البنية:

timestamp_extract(timestamp: TIMESTAMP | BSON_TIMESTAMP, part: STRING[, timezone: STRING]) -> INT64

الوصف:

تستخرج هذه الدالة part محدّدًا (مثل السنة أو الشهر أو اليوم) من timestamp.

يجب أن تكون الوسيطة part سلسلة وإحدى القيم التالية:

  • microsecond
  • millisecond
  • second
  • minute
  • hour
  • day
  • ‫dayofweek: تعرض قيمة بين 1 (الأحد) و7 (السبت).
  • dayofyear
  • ‫week: تعرض هذه الدالة رقم الأسبوع في السنة، بدءًا من 1 لأول يوم أحد في السنة.
  • ‫week([weekday]): تعرض هذه الدالة رقم الأسبوع في السنة، بدءًا من weekday المحدّد.
  • month
  • quarter
  • year
  • ‫isoweek: تعرض رقم الأسبوع وفقًا لمعيار ISO 8601.
  • ‫isoyear: تعرض السنة المرقمة حسب الأسبوع وفقًا لمعيار ISO 8601.

إذا تم تقديم الوسيطة timezone، سيتم الاستخراج استنادًا إلى تقويم المنطقة الزمنية المحددة. ستراعي عملية الاستخراج نظام التوقيت الصيفي.

إذا لم يتم توفير السمة timezone، سيتم الاستخراج استنادًا إلى السمة UTC.

يجب أن تكون الوسيطة timezone تمثيلاً نصيًا لمنطقة زمنية من قاعدة بيانات المناطق الزمنية، مثل America/New_York. يمكن أيضًا استخدام إزاحة زمنية مخصّصة من خلال تحديد إزاحة من GMT.

أمثلة:

timestamp part timezone timestamp_extract(timestamp, part, timezone)
‫2025-02-20 10:20:30 بالتوقيت العالمي المنسّق "year" غير متوفر 2025
‫2025-02-20 10:20:30 بالتوقيت العالمي المنسّق "day" غير متوفر 20
‫31-12-2025 الساعة 11:59:59 مساءً بالتوقيت العالمي المنسَّق "year" "Asia/Tokyo" 2026