Funkcje sygnatury czasowej
| Nazwa | Opis |
CURRENT_TIMESTAMP
|
Generuje TIMESTAMP odpowiadający czasowi żądania.
|
TIMESTAMP_TRUNC
|
Skraca TIMESTAMP do podanej szczegółowości.
|
UNIX_MICROS_TO_TIMESTAMP
|
Konwertuje liczbę mikrosekund od 1970-01-01 00:00:00 UTC na TIMESTAMP
|
UNIX_MILLIS_TO_TIMESTAMP
|
Konwertuje liczbę milisekund od 1970-01-01 00:00:00 UTC na TIMESTAMP
|
UNIX_SECONDS_TO_TIMESTAMP
|
Konwertuje liczbę sekund od 1970-01-01 00:00:00 UTC na TIMESTAMP
|
TIMESTAMP_ADD
|
Dodaje przedział czasu do: TIMESTAMP
|
TIMESTAMP_SUB
|
Odejmuje przedział czasu od TIMESTAMP
|
TIMESTAMP_TO_UNIX_MICROS
|
Konwertuje TIMESTAMP na liczbę mikrosekund od 1970-01-01 00:00:00 UTC
|
TIMESTAMP_TO_UNIX_MILLIS
|
Konwertuje TIMESTAMP na liczbę milisekund od 1970-01-01 00:00:00 UTC
|
TIMESTAMP_TO_UNIX_SECONDS
|
Konwertuje TIMESTAMP na liczbę sekund od 1970-01-01 00:00:00 UTC
|
TIMESTAMP_DIFF
|
Zwraca liczbę całkowitą określonych interwałów unit między 2 TIMESTAMP.
|
TIMESTAMP_EXTRACT
|
Wyodrębnia określony element part (np. rok, miesiąc, dzień) z TIMESTAMP.
|
CURRENT_TIMESTAMP
Składnia:
current_timestamp() -> TIMESTAMP
Opis:
Pobiera sygnaturę czasową na początku czasu żądania input (interpretowaną jako liczba mikrosekund od 1970-01-01 00:00:00 UTC).
Jest ona stabilna w ramach zapytania i zawsze zwraca tę samą wartość, jeśli zostanie wywołana wielokrotnie.
TIMESTAMP_TRUNC
Składnia:
timestamp_trunc(timestamp: TIMESTAMP | BSON_TIMESTAMP, granularity: STRING[, timezone: STRING]) -> TIMESTAMP
Opis:
Skraca sygnaturę czasową do określonej szczegółowości.
Argument granularity musi być ciągiem znaków i jedną z tych wartości:
microsecondmillisecondsecondminutehourdayweekweek([weekday])monthquarteryearisoyear
Jeśli podano argument timezone, obcinanie będzie oparte na granicach kalendarza w danej strefie czasowej (np. obcinanie dnia spowoduje obcięcie do północy w danej strefie czasowej). Skracanie będzie uwzględniać czas letni.
Jeśli nie podasz parametru timezone, obcinanie będzie się odbywać na podstawie granic kalendarza UTC.
Argument timezone powinien być ciągiem znaków reprezentującym strefę czasową z bazy danych tz, na przykład America/New_York. Możesz też użyć niestandardowego przesunięcia czasu, określając przesunięcie od GMT.
Przykłady:
timestamp |
granularity |
timezone |
timestamp_trunc(timestamp, granularity, timezone) |
|---|---|---|---|
| 2000-01-01 10:20:30:123456 UTC | "second" | Nie podano | 2001-01-01 10:20:30 UTC |
| 1997-05-31 04:30:30 UTC | "day" | Nie podano | 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) | Nie podano | 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
Składnia:
unix_micros_to_timestamp(input: INT64) -> TIMESTAMP
Opis:
Konwertuje input (interpretowane jako liczba mikrosekund od 1970-01-01 00:00:00 UTC) na TIMESTAMP. Zwraca błąd error, jeśli nie można przekonwertować input na prawidłowy typ TIMESTAMP.
Przykłady:
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();
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();
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() )
Java
Pipeline.Snapshot result = firestore .pipeline() .collection("documents") .select(unixMicrosToTimestamp(field("createdAtMicros")).as("createdAtString")) .execute() .get();
Go
snapshot := client.Pipeline(). Collection("documents"). Select(firestore.Fields( firestore.UnixMicrosToTimestamp(firestore.FieldOf("createdAtMicros")).As("createdAtString"), )). Execute(ctx)
UNIX_MILLIS_TO_TIMESTAMP
Składnia:
unix_millis_to_timestamp(input: INT64) -> TIMESTAMP
Opis:
Konwertuje wartość input (interpretowaną jako liczba milisekund od 1970-01-01 00:00:00 UTC) na TIMESTAMP. Zwraca błąd error, jeśli nie można przekonwertować input na prawidłowy typ TIMESTAMP.
Przykłady:
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();
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();
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() )
Java
Pipeline.Snapshot result = firestore .pipeline() .collection("documents") .select(unixMillisToTimestamp(field("createdAtMillis")).as("createdAtString")) .execute() .get();
Go
snapshot := client.Pipeline(). Collection("documents"). Select(firestore.Fields( firestore.UnixMillisToTimestamp(firestore.FieldOf("createdAtMillis")).As("createdAtString"), )). Execute(ctx)
UNIX_SECONDS_TO_TIMESTAMP
Składnia:
unix_seconds_to_timestamp(input: INT64) -> TIMESTAMP
Opis:
Przekształca wartość input (interpretowaną jako liczba sekund od 1970-01-01 00:00:00 UTC) w TIMESTAMP. Zwraca błąd error, jeśli nie można przekonwertować input na prawidłowy typ TIMESTAMP.
Przykłady:
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 |
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();
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() )
Java
Pipeline.Snapshot result = firestore .pipeline() .collection("documents") .select(unixSecondsToTimestamp(field("createdAtSeconds")).as("createdAtString")) .execute() .get();
Go
snapshot := client.Pipeline(). Collection("documents"). Select(firestore.Fields( firestore.UnixSecondsToTimestamp(firestore.FieldOf("createdAtSeconds")).As("createdAtString"), )). Execute(ctx)
TIMESTAMP_ADD
Składnia:
timestamp_add(timestamp: TIMESTAMP | BSON_TIMESTAMP, unit: STRING, amount: INT64) -> TIMESTAMP
Opis:
Dodaje amount w kwocie unit z: timestamp. Argument amount może być ujemny. W takim przypadku jest równoważny funkcji TIMESTAMP_SUB.
Argument unit musi być ciągiem znaków i jedną z tych wartości:
microsecondmillisecondsecondminutehourday
Jeśli wynikowa sygnatura czasowa nie mieści się w zakresie TIMESTAMP, zwraca błąd.
Przykłady:
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 |
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();
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() )
Java
Pipeline.Snapshot result = firestore .pipeline() .collection("documents") .select(timestampAdd(field("createdAt"), "day", 3653).as("expiresAt")) .execute() .get();
Go
snapshot := client.Pipeline(). Collection("documents"). Select(firestore.Fields( firestore.TimestampAdd(firestore.FieldOf("createdAt"), "day", 3653).As("expiresAt"), )). Execute(ctx)
TIMESTAMP_SUB
Składnia:
timestamp_sub(timestamp: TIMESTAMP | BSON_TIMESTAMP, unit: STRING, amount: INT64) -> TIMESTAMP
Opis:
Odejmuje amount o wartości unit od timestamp. Argument amount może być ujemny. W takim przypadku jest równoważny funkcji TIMESTAMP_ADD.
Argument unit musi być ciągiem znaków i jedną z tych wartości:
microsecondmillisecondsecondminutehourday
Jeśli wynikowa sygnatura czasowa nie mieści się w zakresie TIMESTAMP, zwraca błąd.
Przykłady:
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 |
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();
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() )
Java
Pipeline.Snapshot result = firestore .pipeline() .collection("documents") .select(timestampSubtract(field("expiresAt"), "day", 14).as("sendWarningTimestamp")) .execute() .get();
Go
snapshot := client.Pipeline(). Collection("documents"). Select(firestore.Fields( firestore.TimestampSubtract(firestore.FieldOf("expiresAt"), "day", 14).As("sendWarningTimestamp"), )). Execute(ctx)
TIMESTAMP_TO_UNIX_MICROS
Składnia:
timestamp_to_unix_micros(input: TIMESTAMP | BSON_TIMESTAMP) -> INT64
Opis:
Konwertuje input na liczbę mikrosekund od 1970-01-01 00:00:00 UTC.
Obcina wyższe poziomy precyzji, zaokrąglając w dół do początku mikrosekundy.
Przykłady:
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();
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();
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() )
Java
Pipeline.Snapshot result = firestore .pipeline() .collection("documents") .select(timestampToUnixMicros(field("dateString")).as("unixMicros")) .execute() .get();
Go
snapshot := client.Pipeline(). Collection("documents"). Select(firestore.Fields( firestore.TimestampToUnixMicros(firestore.FieldOf("dateString")).As("unixMicros"), )). Execute(ctx)
TIMESTAMP_TO_UNIX_MILLIS
Składnia:
timestamp_to_unix_millis(input: TIMESTAMP | BSON_TIMESTAMP) -> INT64
Opis:
Przekształca wartość input w liczbę milisekund, które upłynęły od 1970-01-01 00:00:00 UTC.
Obcina wyższe poziomy precyzji, zaokrąglając w dół do początku milisekundy.
Przykłady:
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();
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();
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() )
Java
Pipeline.Snapshot result = firestore .pipeline() .collection("documents") .select(timestampToUnixMillis(field("dateString")).as("unixMillis")) .execute() .get();
Go
snapshot := client.Pipeline(). Collection("documents"). Select(firestore.Fields( firestore.TimestampToUnixMillis(firestore.FieldOf("dateString")).As("unixMillis"), )). Execute(ctx)
TIMESTAMP_TO_UNIX_SECONDS
Składnia:
timestamp_to_unix_seconds(input: TIMESTAMP | BSON_TIMESTAMP) -> INT64
Opis:
Przekształca wartość input w liczbę sekund od 1970-01-01 00:00:00 UTC.
Obcina wyższe poziomy precyzji, zaokrąglając w dół do początku sekundy.
Przykłady:
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 |
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();
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() )
Java
Pipeline.Snapshot result = firestore .pipeline() .collection("documents") .select(timestampToUnixSeconds(field("dateString")).as("unixSeconds")) .execute() .get();
Go
snapshot := client.Pipeline(). Collection("documents"). Select(firestore.Fields( firestore.TimestampToUnixSeconds(firestore.FieldOf("dateString")).As("unixSeconds"), )). Execute(ctx)
TIMESTAMP_DIFF
Składnia:
timestamp_diff(end: TIMESTAMP | BSON_TIMESTAMP, start: TIMESTAMP | BSON_TIMESTAMP, unit: STRING) -> INT64
Opis:
Zwraca liczbę całkowitą określonych interwałów unit między 2 TIMESTAMP.
- Zwraca wartość ujemną, jeśli
endjest przedstart. - Obcina wszystkie jednostki ułamkowe. Na przykład
timestamp_diff("2021-01-01 00:00:01", "2021-01-01 00:00:00", "minute")zwraca0.
Argument unit musi być ciągiem znaków i jedną z tych wartości:
microsecondmillisecondsecondminutehourday
Przykłady:
end |
start |
unit |
timestamp_diff(end, start, unit) |
|---|---|---|---|
| 2026-07-04 00:01:00 UTC | 2026-07-04 00:00:00 UTC | "second" | 60L |
| 2026-07-04 00:00:00 UTC | 2026-07-05 00:00:00 UTC | "day" | -1L |
| 2026-07-04 00:00:59 UTC | 2026-07-04 00:00:00 UTC | "minute" | 0L |
TIMESTAMP_EXTRACT
Składnia:
timestamp_extract(timestamp: TIMESTAMP | BSON_TIMESTAMP, part: STRING[, timezone: STRING]) -> INT64
Opis:
Wyodrębnia określony element part (np. rok, miesiąc, dzień) z timestamp.
Argument part musi być ciągiem znaków i jedną z tych wartości:
microsecondmillisecondsecondminutehourdaydayofweek: zwraca wartość od 1 (niedziela) do 7 (sobota).dayofyearweek: zwraca numer tygodnia w roku, zaczynając od 1 dla pierwszej niedzieli w roku.week([weekday]): zwraca numer tygodnia w roku, zaczynając od określonego dnia (weekday).monthquarteryearisoweek: zwraca numer tygodnia w formacie ISO 8601.isoyear: zwraca rok według numeracji tygodni ISO 8601.
Jeśli podano argument timezone, wyodrębnianie będzie oparte na kalendarzu danej strefy czasowej. Wyodrębnianie będzie uwzględniać czas letni.
Jeśli nie podasz właściwości timezone, wyodrębnianie będzie oparte na właściwości UTC.
Argument timezone powinien być ciągiem znaków reprezentującym strefę czasową z bazy danych stref czasowych, np. America/New_York. Możesz też użyć niestandardowego przesunięcia czasu, określając przesunięcie od GMT.
Przykłady:
timestamp |
part |
timezone |
timestamp_extract(timestamp, part, timezone) |
|---|---|---|---|
| 2025-02-20 10:20:30 UTC | "year" | Nie podano | 2025 |
| 2025-02-20 10:20:30 UTC | "day" | Nie podano | 20 |
| 31 grudnia 2025 r., 23:59:59 UTC | "year" | "Asia/Tokyo" | 2026 |