Cloud Firestore Enterprise edition in Native mode is now available! Learn more.

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

معاينة: تخضع خدمة 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`

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 UTC
‫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"	‫2001-03-23 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 UTC
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 UTC
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 UTC
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();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 UTC	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 UTC	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 UTC	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();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

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