توابع مهر زمانی

توابع مهر زمانی

نام توضیحات
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() -> TIMESTAMP

شرح:

مهر زمانی را در ابتدای input زمان درخواست دریافت می‌کند (که به صورت تعداد میکروثانیه‌ها از 1970-01-01 00:00:00 UTC تفسیر می‌شود).

این در یک پرس و جو پایدار است و اگر چندین بار فراخوانی شود، همیشه به همان مقدار برمی‌گردد.

مهر زمانی_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)
‎۲۰۰۰-۰۱-۰۱ ۱۰:۲۰:۳۰:۱۲۳۴۵۶ UTC «دوم» ارائه نشده است ۲۰۰۱-۰۱-۰۱ ۱۰:۲۰:۳۰ UTC
‏۳۱-۰۵-۱۹۹۷‏ ساعت ۰۴:۳۰:۳۰ به وقت جهانی «روز» ارائه نشده است ‎۱۹۹۷-۰۵-۳۱ ۰۰:۰۰:۰۰ UTC‎
‏۳۱-۰۵-۱۹۹۷‏ ساعت ۰۴:۳۰:۳۰ به وقت جهانی «روز» «آمریکا/لس‌آنجلس» ‎۱۹۹۷-۰۵-۳۰ ۰۷:۰۰:۰۰ UTC‎
‏‎2001-03-16‎‏ ساعت ‏04:00:00 UTC‎‏ "هفته (جمعه) ارائه نشده است ‏‎2001-03-16‎‏ ساعت ‏۰۰:۰۰:۰۰ UTC‎‏
‏۲۳ مارس ۲۰۰۱‏ ساعت ‏۰۴:۰۰:۰۰ به وقت جهانی "هفته (جمعه) «آمریکا/لس‌آنجلس» ‏۲۳ مارس ۲۰۰۱‏ ۱۷:۰۰:۰۰ به وقت جهانی
‎۲۴-۰۱-۲۰۲۶ ساعت ۲۰:۰۰:۰۰ به وقت جهانی‎ «ماه» «به وقت گرینویچ+۰۶:۳۲:۴۳» ‎۲۰۲۶-۰۱-۰۱T۰۶:۳۲:۴۳ UTC‎

UNIX_MICROS_TO_TIMESTAMP

نحو:

unix_micros_to_timestamp(input: INT64) -> TIMESTAMP

شرح:

input (که به صورت تعداد میکروثانیه‌ها از 1970-01-01 00:00:00 UTC تفسیر می‌شود) را به یک TIMESTAMP تبدیل می‌کند. اگر input نتواند به یک TIMESTAMP معتبر تبدیل شود، error می‌دهد.

مثال‌ها:

input unix_micros_to_timestamp(input)
0 لیتر ۱۹۷۰-۰۱-۰۱ ۰۰:۰۰:۰۰ UTC
۴۰۰۱۲۳۴۵۶L ۱۹۷۰-۰۱-۰۱ ۰۰:۰۶:۴۰.۱۲۳۴۵۶ UTC
-1000000 لیتر ‏۱۹۶۹-۱۲-۳۱ ۲۳:۵۹:۵۹ UTC‏

Web 

const result = await execute(db.pipeline()
  .collection("documents")
  .select(
    field("createdAtMicros").unixMicrosToTimestamp().as("createdAtString")
  )
);
test.firestore.js
سویفت 
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
پایتون 
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 تبدیل می‌کند. اگر input نتواند به یک TIMESTAMP معتبر تبدیل شود، error می‌دهد.

مثال‌ها:

input unix_millis_to_timestamp(input)
0 لیتر ۱۹۷۰-۰۱-۰۱ ۰۰:۰۰:۰۰ UTC
۴۰۰۰۱۲۳ لیتر ۱۹۷۰-۰۱-۰۱ ۰۱:۰۶:۴۰.۱۲۳ UTC
-1000000 لیتر ‏۱۹۶۹-۱۲-۳۱ ۲۳:۴۳:۲۰ UTC‏

Web 

const result = await execute(db.pipeline()
  .collection("documents")
  .select(
    field("createdAtMillis").unixMillisToTimestamp().as("createdAtString")
  )
);
test.firestore.js
سویفت 
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
پایتون 
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 تبدیل می‌کند. اگر input نتواند به یک TIMESTAMP معتبر تبدیل شود، error می‌دهد.

مثال‌ها:

input unix_seconds_to_timestamp(input)
0 لیتر ۱۹۷۰-۰۱-۰۱ ۰۰:۰۰:۰۰ UTC
۶۰ لیتر ۱۹۷۰-۰۱-۰۱ ۰۰:۰۱:۰۰ UTC
-300 لیتر ‎۱۹۶۹-۱۲-۳۱ ۲۳:۵۵:۰۰ UTC‎

Web 

const result = await execute(db.pipeline()
  .collection("documents")
  .select(
    field("createdAtSeconds").unixSecondsToTimestamp().as("createdAtString")
  )
);
test.firestore.js
سویفت 
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
پایتون 
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: 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)
۲۰۲۵-۰۲-۲۰ ساعت ۰۰:۰۰:۰۰ به وقت جهانی "دقیقه" ۲ لیتر ۲۰۲۵-۰۲-۲۰ ساعت ۰۰:۰۲:۰۰ به وقت جهانی
۲۰۲۵-۰۲-۲۰ ساعت ۰۰:۰۰:۰۰ به وقت جهانی «ساعت» -4 لیتر ۲۰۲۵-۰۲-۱۹ ساعت ۲۰:۰۰:۰۰ به وقت جهانی
۲۰۲۵-۰۲-۲۰ ساعت ۰۰:۰۰:۰۰ به وقت جهانی «روز» ۵ لیتر ‎2025-02-25 00:00:00 UTC‎

Web 

const result = await execute(db.pipeline()
  .collection("documents")
  .select(
    field("createdAt").timestampAdd("day", 3653).as("expiresAt")
  )
);
test.firestore.js
سویفت 
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
پایتون 
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: 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 UTC‎ "دقیقه" ۴۰ لیتر ‎2026-07-03 23:20:00 UTC
‎2026-07-04 00:00:00 UTC‎ «ساعت» -24 لیتر ‎2026-07-05 00:00:00 UTC‎
‎2026-07-04 00:00:00 UTC‎ «روز» ۳ لیتر ‎۲۰۲۶-۰۷-۰۱ ۰۰:۰۰:۰۰ UTC‎

Web 

const result = await execute(db.pipeline()
  .collection("documents")
  .select(
    field("expiresAt").timestampSubtract("day", 14).as("sendWarningTimestamp")
  )
);
test.firestore.js
سویفت 
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
پایتون 
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(input: TIMESTAMP) -> INT64

شرح:

input به تعداد میکروثانیه‌ها از 1970-01-01 00:00:00 UTC تبدیل می‌کند. سطوح بالاتر دقت را با گرد کردن به ابتدای میکروثانیه، کوتاه می‌کند.

مثال‌ها:

input timestamp_to_unix_micros(input)
۱۹۷۰-۰۱-۰۱ ۰۰:۰۰:۰۰ UTC 0 لیتر
۱۹۷۰-۰۱-۰۱ ۰۰:۰۶:۴۰.۱۲۳۴۵۶ UTC ۴۰۰۱۲۳۴۵۶L
‏۱۹۶۹-۱۲-۳۱ ۲۳:۵۹:۵۹ UTC‏ -1000000 لیتر

Web 

const result = await execute(db.pipeline()
  .collection("documents")
  .select(
    field("dateString").timestampToUnixMicros().as("unixMicros")
  )
);
test.firestore.js
سویفت 
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
پایتون 
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(input: TIMESTAMP) -> INT64

شرح:

input به تعداد میلی‌ثانیه‌ها از 1970-01-01 00:00:00 UTC تبدیل می‌کند. سطوح بالاتر دقت را با گرد کردن به ابتدای میلی‌ثانیه، کوتاه می‌کند.

مثال‌ها:

input timestamp_to_unix_millis(input)
۱۹۷۰-۰۱-۰۱ ۰۰:۰۰:۰۰ UTC 0 لیتر
۱۹۷۰-۰۱-۰۱ ۰۱:۰۶:۴۰.۱۲۳ UTC ۴۰۰۰۱۲۳ لیتر
۱۹۶۹-۱۲-۳۱ ۲۳:۴۳:۲۰ -1000000 لیتر

Web 

const result = await execute(db.pipeline()
  .collection("documents")
  .select(
    field("dateString").timestampToUnixMillis().as("unixMillis")
  )
);
test.firestore.js
سویفت 
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
پایتون 
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(input: TIMESTAMP) -> INT64

شرح:

input به تعداد ثانیه‌ها از 1970-01-01 00:00:00 UTC تبدیل می‌کند. سطوح بالاتر دقت را با گرد کردن به ابتدای ثانیه به پایین، کوتاه می‌کند.

مثال‌ها:

input timestamp_to_unix_seconds(input)
۱۹۷۰-۰۱-۰۱ ۰۰:۰۰:۰۰ UTC 0 لیتر
۱۹۷۰-۰۱-۰۱ ۰۰:۰۱:۰۰ UTC ۶۰ لیتر
‎۱۹۶۹-۱۲-۳۱ ۲۳:۵۵:۰۰ UTC‎ -300 لیتر

Web 

const result = await execute(db.pipeline()
  .collection("documents")
  .select(
    field("dateString").timestampToUnixSeconds().as("unixSeconds")
  )
);
test.firestore.js
سویفت 
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
پایتون 
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