פונקציות של חותמות זמן

פונקציות של חותמות זמן

שם תיאור
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 ‫"second" לא צוין 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" 2001-03-23 17:00:00 UTC
2026-01-24 20:00:00 UTC ‫"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. הפונקציה מחזירה 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

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 UTC
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 UTC
‫60L 1970-01-01 00:01:00 UTC
‫-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 UTC ‫"minute" ‫2L 2025-02-20 00:02:00 UTC
2025-02-20 00:00:00 UTC ‫"hour" (שעה) ‫‎-4L 2025-02-19 20:00:00 UTC
2025-02-20 00:00:00 UTC ‫"day" ‫5L 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
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 UTC ‫"minute" 40L ‫2026-07-03 23:20:00 UTC
2026-07-04 00:00:00 UTC ‫"hour" (שעה) ‫-24L 2026-07-05 00:00:00 UTC
2026-07-04 00:00:00 UTC ‫"day" ‫3L 2026-07-01 00:00:00 UTC

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 UTC 0L
1970-01-01 00:06:40.123456 UTC 400123456L
1969-12-31 23:59:59 UTC ‎-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 UTC 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 UTC 0L
1970-01-01 00:01:00 UTC ‫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