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

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

الاسم الوصف
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 بالتوقيت العالمي المتفق عليه
‫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 بالتوقيت العالمي المتفق عليه

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

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

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

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

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

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 بالتوقيت العالمي المتفق عليه

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

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 بالتوقيت العالمي المتفق عليه

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

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 بالتوقيت العالمي المتفق عليه -1000000L

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

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

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

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

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