Funzioni di timestamp

Funzioni di timestamp

Nome Descrizione
CURRENT_TIMESTAMP Genera un TIMESTAMP corrispondente all'ora della richiesta.
TIMESTAMP_TRUNC Tronca un TIMESTAMP in base a una granularità specificata.
UNIX_MICROS_TO_TIMESTAMP Converte il numero di microsecondi a partire dal 1970-01-01 00:00:00 UTC in un TIMESTAMP
UNIX_MILLIS_TO_TIMESTAMP Converte il numero di millisecondi trascorsi dal 1970-01-01 00:00:00 UTC in un TIMESTAMP
UNIX_SECONDS_TO_TIMESTAMP Converte il numero di secondi trascorsi dal 1970-01-01 00:00:00 UTC in un TIMESTAMP
TIMESTAMP_ADD Aggiunge un intervallo di tempo a un TIMESTAMP
TIMESTAMP_SUB Sottrae un intervallo di tempo a TIMESTAMP
TIMESTAMP_TO_UNIX_MICROS Converte un valore TIMESTAMP nel numero di microsecondi trascorsi dal 1970-01-01 00:00:00 UTC
TIMESTAMP_TO_UNIX_MILLIS Converte un valore TIMESTAMP nel numero di millisecondi trascorsi dal giorno 1970-01-01 00:00:00 UTC
TIMESTAMP_TO_UNIX_SECONDS Converte un valore TIMESTAMP nel numero di secondi trascorsi dal giorno 1970-01-01 00:00:00 UTC

CURRENT_TIMESTAMP

Sintassi:

current_timestamp() -> TIMESTAMP

Descrizione:

Recupera il timestamp all'inizio dell'ora della richiesta input (interpretato come il numero di microsecondi trascorsi dal 1970-01-01 00:00:00 UTC).

Questo valore è stabile all'interno di una query e verrà sempre risolto nello stesso valore se chiamato più volte.

TIMESTAMP_TRUNC

Sintassi:

timestamp_trunc(timestamp: TIMESTAMP, granularity: STRING[, timezone: STRING]) -> TIMESTAMP

Descrizione:

Tronca un timestamp in base a una granularità specificata.

L'argomento granularity deve essere una stringa e uno dei seguenti:

  • microsecond
  • millisecond
  • second
  • minute
  • hour
  • day
  • week
  • week([weekday])
  • month
  • quarter
  • year
  • isoyear

Se viene fornito l'argomento timezone, il troncamento si baserà sui limiti del calendario del fuso orario specificato (ad es. il troncamento giornaliero troncherà fino a mezzanotte nel fuso orario specificato). Il troncamento rispetterà l'ora legale.

Se timezone non viene fornito, il troncamento si baserà sui limiti del calendario UTC.

L'argomento timezone deve essere una rappresentazione stringa di un fuso orario del database tz, ad esempio America/New_York. È possibile utilizzare anche un offset temporale personalizzato specificando un offset da GMT.

Esempi:

timestamp granularity timezone timestamp_trunc(timestamp, granularity, timezone)
2000-01-01 10:20:30:123456 UTC "secondo" Non fornito 2001-01-01 10:20:30 UTC
1997-05-31 04:30:30 UTC "day" Non fornito 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) Non fornito 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

Sintassi:

unix_micros_to_timestamp(input: INT64) -> TIMESTAMP

Descrizione:

Converte input (interpretato come il numero di microsecondi a partire dal 1970-01-01 00:00:00 UTC) in un TIMESTAMP. Genera un error se input non può essere convertito in un TIMESTAMP valido.

Esempi:

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

Sintassi:

unix_millis_to_timestamp(input: INT64) -> TIMESTAMP

Descrizione:

Converte input (interpretato come il numero di millisecondi a partire dal 1970-01-01 00:00:00 UTC) in un TIMESTAMP. Genera un error se input non può essere convertito in un TIMESTAMP valido.

Esempi:

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

Sintassi:

unix_seconds_to_timestamp(input: INT64) -> TIMESTAMP

Descrizione:

Converte input (interpretato come il numero di secondi trascorsi dal 1970-01-01 00:00:00 UTC) in un TIMESTAMP. Genera un error se input non può essere convertito in un TIMESTAMP valido.

Esempi:

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

Sintassi:

timestamp_add(timestamp: TIMESTAMP, unit: STRING, amount: INT64) -> TIMESTAMP

Descrizione:

Aggiunge un amount di unit da timestamp. L'argomento amount può essere negativo, nel qual caso è equivalente a TIMESTAMP_SUB.

L'argomento unit deve essere una stringa e uno dei seguenti:

  • microsecond
  • millisecond
  • second
  • minute
  • hour
  • day

Genera un errore se il timestamp risultante non rientra nell'intervallo TIMESTAMP.

Esempi:

timestamp unit amount timestamp_add(timestamp, unit, amount)
2025-02-20 00:00:00 UTC "minuto" 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

Sintassi:

timestamp_sub(timestamp: TIMESTAMP, unit: STRING, amount: INT64) -> TIMESTAMP

Descrizione:

Sottrae un amount di unit da timestamp. L'argomento amount può essere negativo, nel qual caso è equivalente a TIMESTAMP_ADD.

L'argomento unit deve essere una stringa e uno dei seguenti:

  • microsecond
  • millisecond
  • second
  • minute
  • hour
  • day

Genera un errore se il timestamp risultante non rientra nell'intervallo TIMESTAMP.

Esempi:

timestamp unit amount timestamp_sub(timestamp, unit, amount)
2026-07-04 00:00:00 UTC "minuto" 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

Sintassi:

timestamp_to_unix_micros(input: TIMESTAMP) -> INT64

Descrizione:

Converte input nel numero di microsecondi trascorsi dal 1970-01-01 00:00:00 UTC. Tronca i livelli di precisione più elevati arrotondando per difetto all'inizio del microsecondo.

Esempi:

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

Sintassi:

timestamp_to_unix_millis(input: TIMESTAMP) -> INT64

Descrizione:

Converte input nel numero di millisecondi trascorsi dal 1970-01-01 00:00:00 UTC. Tronca i livelli di precisione più elevati arrotondando per difetto all'inizio del millisecondo.

Esempi:

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

Sintassi:

timestamp_to_unix_seconds(input: TIMESTAMP) -> INT64

Descrizione:

Converte input nel numero di secondi trascorsi dal giorno 1970-01-01 00:00:00 UTC. Tronca i livelli di precisione più elevati arrotondando per difetto all'inizio del secondo.

Esempi:

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