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

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

الاسم الوصف
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, 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 UTC "ثانية" غير متوفر ‫2001-01-01 10:20:30 UTC
1997-05-31 04:30:30 UTC "day" غير متوفر ‫1997-05-31 00:00:00 بالتوقيت العالمي المتّفق عليه
1997-05-31 04:30:30 UTC "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 UTC "week(friday) "America/Los_Angeles" ‫23 مارس 2001، الساعة 17:00:00 بالتوقيت العالمي المتّفق عليه
‫2026-01-24 20:00:00 بالتوقيت العالمي المتفق عليه "شهر" "GMT+06:32:43" ‫2026-01-01T06:32:43 UTC

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)
0L ‫1970-01-01 00:00:00 بالتوقيت العالمي المتّفق عليه
400123456L 1970-01-01 00:06:40.123456 UTC
-1000000L 1969-12-31 23:59:59 UTC
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)
0L ‫1970-01-01 00:00:00 بالتوقيت العالمي المتّفق عليه
4000123L 1970-01-01 01:06:40.123 UTC
-1000000L 1969-12-31 23:43:20 UTC
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)
0L ‫1970-01-01 00:00:00 بالتوقيت العالمي المتّفق عليه
60L ‫1970-01-01 00:01:00 بالتوقيت العالمي المتفق عليه
‎-300L 1969-12-31 23:55:00 UTC
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, 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 بالتوقيت العالمي المتفق عليه "دقيقة" 2L ‫2025-02-20 00:02:00 بالتوقيت العالمي المتفق عليه
‫2025-02-20 00:00:00 بالتوقيت العالمي المتفق عليه "ساعة" ‫-4L ‫2025-02-19 20:00:00 بالتوقيت العالمي المتفق عليه
‫2025-02-20 00:00:00 بالتوقيت العالمي المتفق عليه "day" 5L ‫2025-02-25 00:00: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, 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 بالتوقيت العالمي المتفق عليه "دقيقة" 40L ‫2026-07-03 23:20:00 بالتوقيت العالمي المتّفق عليه
‫2026-07-04 00:00:00 بالتوقيت العالمي المتفق عليه "ساعة" ‫-24L ‫2026-07-05 00:00:00 بالتوقيت العالمي المتفق عليه
‫2026-07-04 00:00:00 بالتوقيت العالمي المتفق عليه "day" 3L ‫2026-07-01 00:00:00 بالتوقيت العالمي المتفق عليه
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) -> INT64

الوصف:

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

أمثلة:

input timestamp_to_unix_micros(input)
‫1970-01-01 00:00:00 بالتوقيت العالمي المتّفق عليه 0L
1970-01-01 00:06:40.123456 UTC 400123456L
1969-12-31 23:59:59 UTC -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) -> INT64

الوصف:

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

أمثلة:

input timestamp_to_unix_millis(input)
‫1970-01-01 00:00:00 بالتوقيت العالمي المتّفق عليه 0L
1970-01-01 01:06:40.123 UTC 4000123L
1969-12-31 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) -> INT64

الوصف:

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

أمثلة:

input timestamp_to_unix_seconds(input)
‫1970-01-01 00:00:00 بالتوقيت العالمي المتّفق عليه 0L
‫1970-01-01 00:01:00 بالتوقيت العالمي المتفق عليه 60L
1969-12-31 23:55:00 UTC ‎-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, start: 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 بالتوقيت العالمي المتفق عليه "ثانية" 60L
‫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 بالتوقيت العالمي المتفق عليه "دقيقة" 0L

TIMESTAMP_EXTRACT

البنية:

timestamp_extract(timestamp: 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
‫2025-12-31 23:59:59 بالتوقيت العالمي المتفق عليه "year" "Asia/Tokyo" 2026