تابع‌های مُهر زمان

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

نام شرح
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 | BSON_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 UTC
‫1997-05-31 04:30:30 UTC «day» "America/Los_Angeles" ‫1997-05-30 07:00:00 UTC
‫2001-03-16 04:00:00 UTC "week(friday) ارائه نشده است ‫2001-03-16 00:00:00 UTC
‫2001-03-23 04:00:00 UTC "week(friday) "America/Los_Angeles" ‫۲۰۰۱-۰۳-۲۳ ۱۷:۰۰:۰۰ ساعت هماهنگ جهانی
‫۲۰۲۶-۰۱-۲۴ ۲۰:۰۰:۰۰ ساعت هماهنگ جهانی "month" «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 تبدیل می‌کند. اگر input نتواند به TIMESTAMP معتبری تبدیل شود، error را برمی‌گرداند.

نمونه:

input unix_micros_to_timestamp(input)
‫۰ لیتر ‫۱۹۷۰-۰۱-۰۱ ۰۰:۰۰:۰۰ ساعت هماهنگ جهانی
400123456L ‫1970-01-01 00:06:40.123456 UTC
-1000000L ‫۱۹۶۹-۱۲-۳۱ ۲۳:۵۹:۵۹ ساعت هماهنگ جهانی
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();
پایتون
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()
)
جاوا
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 تبدیل می‌کند. اگر input نتواند به TIMESTAMP معتبری تبدیل شود، error را برمی‌گرداند.

نمونه:

input unix_millis_to_timestamp(input)
‫۰ لیتر ‫۱۹۷۰-۰۱-۰۱ ۰۰:۰۰:۰۰ ساعت هماهنگ جهانی
4000123L ‫1970-01-01 01:06:40.123 UTC
-1000000L ‫۱۹۶۹-۱۲-۳۱ ۲۳:۴۳:۲۰ ساعت هماهنگ جهانی
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();
پایتون
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()
)
جاوا
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 تبدیل می‌کند. اگر input نتواند به TIMESTAMP معتبری تبدیل شود، error را برمی‌گرداند.

نمونه:

input unix_seconds_to_timestamp(input)
‫۰ لیتر ‫۱۹۷۰-۰۱-۰۱ ۰۰:۰۰:۰۰ ساعت هماهنگ جهانی
۶۰ لیتر ‫۱۹۷۰-۰۱-۰۱ ۰۰:۰۱:۰۰ به‌وقت ساعت هماهنگ جهانی
-300L ‫۱۹۶۹-۱۲-۳۱ ۲۳:۵۵:۰۰ ساعت هماهنگ جهانی
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();
پایتون
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()
)
جاوا
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 | BSON_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)
‫۲۰۲۵-۰۲-۲۰ ۰۰:۰۰:۰۰ ساعت هماهنگ جهانی «دقیقه» 2L ‫۲۰۲۵-۰۲-۲۰ ۰۰:۰۲:۰۰ ساعت هماهنگ جهانی
‫۲۰۲۵-۰۲-۲۰ ۰۰:۰۰:۰۰ ساعت هماهنگ جهانی «ساعت» -4L ‫۲۰۲۵-۰۲-۱۹ ساعت ۲۰:۰۰:۰۰ به‌وقت ساعت هماهنگ جهانی
‫۲۰۲۵-۰۲-۲۰ ۰۰:۰۰:۰۰ ساعت هماهنگ جهانی «day» ‫۵ لیتر ‫۲۰۲۵-۰۲-۲۵ 00:00:00 UTC
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();
پایتون
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()
)
جاوا
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 | BSON_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)
‫۲۰۲۶-۰۷-۰۴ ۰۰:۰۰:۰۰ UTC «دقیقه» ۴۰ لیتر ‫۲۰۲۶-۰۷-۰۳ ۲۳:۲۰:۰۰ ساعت هماهنگ جهانی
‫۲۰۲۶-۰۷-۰۴ ۰۰:۰۰:۰۰ UTC «ساعت» ‫-۲۴ لیتر ‫۲۰۲۶-۰۷-۰۵ ۰۰:۰۰:۰۰ UTC
‫۲۰۲۶-۰۷-۰۴ ۰۰:۰۰:۰۰ UTC «day» 3L ‫۲۰۲۶-۰۷-۰۱ ۰۰:۰۰:۰۰ UTC
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();
پایتون
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()
)
جاوا
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 | BSON_TIMESTAMP) -> INT64

شرح:

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

نمونه:

input timestamp_to_unix_micros(input)
‫۱۹۷۰-۰۱-۰۱ ۰۰:۰۰:۰۰ ساعت هماهنگ جهانی ‫۰ لیتر
‫1970-01-01 00:06:40.123456 UTC 400123456L
‫۱۹۶۹-۱۲-۳۱ ۲۳:۵۹:۵۹ ساعت هماهنگ جهانی -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();
پایتون
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()
)
جاوا
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 | BSON_TIMESTAMP) -> INT64

شرح:

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

نمونه:

input timestamp_to_unix_millis(input)
‫۱۹۷۰-۰۱-۰۱ ۰۰:۰۰:۰۰ ساعت هماهنگ جهانی ‫۰ لیتر
‫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();
پایتون
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()
)
جاوا
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 | BSON_TIMESTAMP) -> INT64

شرح:

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

نمونه:

input timestamp_to_unix_seconds(input)
‫۱۹۷۰-۰۱-۰۱ ۰۰:۰۰:۰۰ ساعت هماهنگ جهانی ‫۰ لیتر
‫۱۹۷۰-۰۱-۰۱ ۰۰:۰۱:۰۰ به‌وقت ساعت هماهنگ جهانی ۶۰ لیتر
‫۱۹۶۹-۱۲-۳۱ ۲۳:۵۵:۰۰ ساعت هماهنگ جهانی -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();
پایتون
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()
)
جاوا
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 | BSON_TIMESTAMP, start: TIMESTAMP | BSON_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)
‫۲۰۲۶-۰۷-۰۴ ۰۰:۰۱:۰۰ UTC ‫۲۰۲۶-۰۷-۰۴ ۰۰:۰۰:۰۰ UTC «ثانیه» ۶۰ لیتر
‫۲۰۲۶-۰۷-۰۴ ۰۰:۰۰:۰۰ UTC ‫۲۰۲۶-۰۷-۰۵ ۰۰:۰۰:۰۰ UTC «day» ‫-۱ لیتر
‫۲۰۲۶-۰۷-۰۴ ۰۰:۰۰:۵۹ ساعت هماهنگ جهانی ‫۲۰۲۶-۰۷-۰۴ ۰۰:۰۰:۰۰ UTC «دقیقه» ‫۰ لیتر

TIMESTAMP_EXTRACT

نحو:

timestamp_extract(timestamp: TIMESTAMP | BSON_TIMESTAMP, part: STRING[, timezone: STRING]) -> INT64

شرح:

part خاصی (مثلاً سال، ماه، روز) را از timestamp استخراج می‌کند.

آرگومان part باید رشته و یکی از موارد زیر باشد:

  • microsecond
  • millisecond
  • second
  • minute
  • hour
  • day
  • dayofweek: مقداری بین ۱ (یکشنبه) و ۷ (شنبه) برمی‌گرداند.
  • dayofyear
  • week: شماره هفته سال را برمی‌گرداند، که از ۱ برای اولین یکشنبه سال شروع می‌شود.
  • 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 UTC "year" ارائه نشده است ۲۰۲۵
‫2025-02-20 10:20:30 UTC «day» ارائه نشده است 20
‫۲۰۲۵-۱۲-۳۱ ساعت ۲۳:۵۹:۵۹ به‌وقت ساعت هماهنگ جهانی "year" «آسیا/توکیو» 2026