Cloud Firestore Enterprise edition in Native mode is now available! Learn more.

ฟังก์ชันการประทับเวลา

เวอร์ชันตัวอย่าง: Firestore ในโหมด Native (พร้อมการดำเนินการแบบไปป์ไลน์) สำหรับ Enterprise Edition อยู่ภายใต้ "ข้อกำหนดเกี่ยวกับข้อเสนอก่อนเวอร์ชันสำหรับผู้ใช้ทั่วไป" ในส่วนข้อกำหนดในการให้บริการทั่วไป ของข้อกำหนดเฉพาะของบริการ คุณสามารถประมวลผลข้อมูลส่วนตัวสำหรับฟีเจอร์นี้ได้ตามที่ระบุไว้ในเอกสารแนบท้ายการประมวลผลข้อมูลระบบคลาวด์ โดยขึ้นอยู่กับภาระหน้าที่และข้อจำกัดที่อธิบายไว้ในข้อตกลงที่คุณใช้เข้าถึง Google Cloud ฟีเจอร์ก่อนเวอร์ชันสำหรับผู้ใช้ทั่วไปพร้อมใช้งาน "ตามที่เป็น" และอาจมีการสนับสนุนที่จำกัด ดูข้อมูลเพิ่มเติมได้ที่คำอธิบาย ระยะการเปิดตัว

ฟังก์ชันการประทับเวลา

ชื่อ	คำอธิบาย
`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	"วินาที"	ไม่ได้ระบุข้อมูล	01-01-2001 10:20:30 UTC
1997-05-31 04:30:30 UTC	"วัน"	ไม่ได้ระบุข้อมูล	1997-05-31 00:00:00 UTC
1997-05-31 04:30:30 UTC	"วัน"	"America/Los_Angeles"	1997-05-30 07:00:00 UTC
16-03-2001 04:00:00 UTC	"week(friday)	ไม่ได้ระบุข้อมูล	16-03-2001 00:00:00 UTC
23-03-2001 04:00:00 UTC	"week(friday)	"America/Los_Angeles"	23-03-2001 17:00:00 UTC
24-01-2026 20:00:00 UTC	"เดือน"	"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	"นาที"	2L	2025-02-20 00:02:00 UTC
2025-02-20 00:00:00 UTC	"ชั่วโมง"	-4L	2025-02-19 20:00:00 UTC
2025-02-20 00:00:00 UTC	"วัน"	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	"นาที"	40L	2026-07-03 23:20:00 UTC
2026-07-04 00:00:00 UTC	"ชั่วโมง"	-24L	2026-07-05 00:00:00 UTC
2026-07-04 00:00:00 UTC	"วัน"	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