原生模式下的 Cloud Firestore 企业版现已推出！了解详情。

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

معاينة: يخضع Firestore في الوضع الأصلي (مع عمليات Pipeline) لإصدار Enterprise لـ "أحكام العرض لمرحلة ما قبل التوفّر للجمهور العام" في قسم "أحكام الخدمة العامة" من الأحكام الخاصة بالخدمة. يمكنك معالجة البيانات الشخصية لهذه الميزة على النحو الموضّح في ملحق معالجة البيانات في خدمات Cloud، وذلك وفقًا للالتزامات والقيود الموضّحة في الاتفاقية التي تتيح لك الوصول إلى Google Cloud. تتوفّر الميزات في مرحلة ما قبل التوفّر للجمهور العام "كما هي"، وقد يقتصر دعمها على نطاق محدود. لمزيد من المعلومات، يُرجى الاطّلاع على أوصاف مراحل الإطلاق.

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

الاسم	الوصف
`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 UTC
‫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();test.firestore.js

Web

const result = await execute(db.pipeline()
  .collection("documents")
  .select(
    field("createdAtMicros").unixMicrosToTimestamp().as("createdAtString")
  )
);test.firestore.js

Swift

let result = try await db.pipeline()
  .collection("documents")
  .select([
    Field("createdAtMicros").unixMicrosToTimestamp().as("createdAtString")
  ])
  .execute()PipelineSnippets.swift

Kotlin

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

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("documents")
    .select(
        field("createdAtMicros").unixMicrosToTimestamp().alias("createdAtString")
    )
    .execute();DocSnippets.java

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()
)firestore_pipelines.py

Java

Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("documents")
        .select(unixMicrosToTimestamp(field("createdAtMicros")).as("createdAtString"))
        .execute()
        .get();PipelineSnippets.java

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();test.firestore.js

Web

const result = await execute(db.pipeline()
  .collection("documents")
  .select(
    field("createdAtMillis").unixMillisToTimestamp().as("createdAtString")
  )
);test.firestore.js

Swift

let result = try await db.pipeline()
  .collection("documents")
  .select([
    Field("createdAtMillis").unixMillisToTimestamp().as("createdAtString")
  ])
  .execute()PipelineSnippets.swift

Kotlin

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

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("documents")
    .select(
        field("createdAtMillis").unixMillisToTimestamp().alias("createdAtString")
    )
    .execute();DocSnippets.java

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()
)firestore_pipelines.py

Java

Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("documents")
        .select(unixMillisToTimestamp(field("createdAtMillis")).as("createdAtString"))
        .execute()
        .get();PipelineSnippets.java

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 UTC
‎-300L	1969-12-31 23:55:00 UTC

Node.js

const result = await db.pipeline()
  .collection("documents")
  .select(
    field("createdAtSeconds").unixSecondsToTimestamp().as("createdAtString")
  )
  .execute();test.firestore.js

Web

const result = await execute(db.pipeline()
  .collection("documents")
  .select(
    field("createdAtSeconds").unixSecondsToTimestamp().as("createdAtString")
  )
);test.firestore.js

Swift

let result = try await db.pipeline()
  .collection("documents")
  .select([
    Field("createdAtSeconds").unixSecondsToTimestamp().as("createdAtString")
  ])
  .execute()PipelineSnippets.swift

Kotlin

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

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("documents")
    .select(
        field("createdAtSeconds").unixSecondsToTimestamp().alias("createdAtString")
    )
    .execute();DocSnippets.java

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()
)firestore_pipelines.py

Java

Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("documents")
        .select(unixSecondsToTimestamp(field("createdAtSeconds")).as("createdAtString"))
        .execute()
        .get();PipelineSnippets.java

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();test.firestore.js

Web

const result = await execute(db.pipeline()
  .collection("documents")
  .select(
    field("createdAt").timestampAdd("day", 3653).as("expiresAt")
  )
);test.firestore.js

Swift

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

Kotlin

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

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("documents")
    .select(
        field("createdAt").timestampAdd("day", 3653).alias("expiresAt")
    )
    .execute();DocSnippets.java

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()
)firestore_pipelines.py

Java

Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("documents")
        .select(timestampAdd(field("createdAt"), "day", 3653).as("expiresAt"))
        .execute()
        .get();PipelineSnippets.java

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();test.firestore.js

Web

const result = await execute(db.pipeline()
  .collection("documents")
  .select(
    field("expiresAt").timestampSubtract("day", 14).as("sendWarningTimestamp")
  )
);test.firestore.js

Swift

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

Kotlin

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

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("documents")
    .select(
        field("expiresAt").timestampSubtract("day", 14).alias("sendWarningTimestamp")
    )
    .execute();DocSnippets.java

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()
)firestore_pipelines.py

Java

Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("documents")
        .select(timestampSubtract(field("expiresAt"), "day", 14).as("sendWarningTimestamp"))
        .execute()
        .get();PipelineSnippets.java

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();test.firestore.js

Web

const result = await execute(db.pipeline()
  .collection("documents")
  .select(
    field("dateString").timestampToUnixMicros().as("unixMicros")
  )
);test.firestore.js

Swift

let result = try await db.pipeline()
  .collection("documents")
  .select([
    Field("dateString").timestampToUnixMicros().as("unixMicros")
  ])
  .execute()PipelineSnippets.swift

Kotlin

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

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("documents")
    .select(
        field("dateString").timestampToUnixMicros().alias("unixMicros")
    )
    .execute();DocSnippets.java

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()
)firestore_pipelines.py

Java

Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("documents")
        .select(timestampToUnixMicros(field("dateString")).as("unixMicros"))
        .execute()
        .get();PipelineSnippets.java

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();test.firestore.js

Web

const result = await execute(db.pipeline()
  .collection("documents")
  .select(
    field("dateString").timestampToUnixMillis().as("unixMillis")
  )
);test.firestore.js

Swift

let result = try await db.pipeline()
  .collection("documents")
  .select([
    Field("dateString").timestampToUnixMillis().as("unixMillis")
  ])
  .execute()PipelineSnippets.swift

Kotlin

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

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("documents")
    .select(
        field("dateString").timestampToUnixMillis().alias("unixMillis")
    )
    .execute();DocSnippets.java

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()
)firestore_pipelines.py

Java

Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("documents")
        .select(timestampToUnixMillis(field("dateString")).as("unixMillis"))
        .execute()
        .get();PipelineSnippets.java

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 UTC	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();test.firestore.js

Web

const result = await execute(db.pipeline()
  .collection("documents")
  .select(
    field("dateString").timestampToUnixSeconds().as("unixSeconds")
  )
);test.firestore.js

Swift

let result = try await db.pipeline()
  .collection("documents")
  .select([
    Field("dateString").timestampToUnixSeconds().as("unixSeconds")
  ])
  .execute()PipelineSnippets.swift

Kotlin

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

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("documents")
    .select(
        field("dateString").timestampToUnixSeconds().alias("unixSeconds")
    )
    .execute();DocSnippets.java

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()
)firestore_pipelines.py

Java

Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("documents")
        .select(timestampToUnixSeconds(field("dateString")).as("unixSeconds"))
        .execute()
        .get();PipelineSnippets.java

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

دوال الطابع الزمني تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.