時間戳記函式參考資料

時間戳記函式參考資料

時間戳記函式

名稱	說明
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	傳回兩個TIMESTAMP之間指定unit間隔的整數。
TIMESTAMP_EXTRACT	從 TIMESTAMP 擷取特定 part (例如年、月、日)。

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	"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。如果 input 無法轉換為有效的 TIMESTAMP，則會擲回 error。

範例：

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();
test.firestore.js

網頁

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
Android

val result = db.pipeline()
    .collection("documents")
    .select(
        field("createdAtMicros").unixMicrosToTimestamp().alias("createdAtString")
    )
    .execute()
DocSnippets.kt

Java
Android

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

Java

Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("documents")
        .select(unixMicrosToTimestamp(field("createdAtMicros")).as("createdAtString"))
        .execute()
        .get();
PipelineSnippets.java

Go

snapshot := client.Pipeline().
	Collection("documents").
	Select(firestore.Fields(
		firestore.UnixMicrosToTimestamp(firestore.FieldOf("createdAtMicros")).As("createdAtString"),
	)).
	Execute(ctx)
pipeline_snippets_date_timestamp.go

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)
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();
test.firestore.js

網頁

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
Android

val result = db.pipeline()
    .collection("documents")
    .select(
        field("createdAtMillis").unixMillisToTimestamp().alias("createdAtString")
    )
    .execute()
DocSnippets.kt

Java
Android

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

Java

Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("documents")
        .select(unixMillisToTimestamp(field("createdAtMillis")).as("createdAtString"))
        .execute()
        .get();
PipelineSnippets.java

Go

snapshot := client.Pipeline().
	Collection("documents").
	Select(firestore.Fields(
		firestore.UnixMillisToTimestamp(firestore.FieldOf("createdAtMillis")).As("createdAtString"),
	)).
	Execute(ctx)
pipeline_snippets_date_timestamp.go

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)
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();
test.firestore.js

網頁

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
Android

val result = db.pipeline()
    .collection("documents")
    .select(
        field("createdAtSeconds").unixSecondsToTimestamp().alias("createdAtString")
    )
    .execute()
DocSnippets.kt

Java
Android

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

Java

Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("documents")
        .select(unixSecondsToTimestamp(field("createdAtSeconds")).as("createdAtString"))
        .execute()
        .get();
PipelineSnippets.java

Go

snapshot := client.Pipeline().
	Collection("documents").
	Select(firestore.Fields(
		firestore.UnixSecondsToTimestamp(firestore.FieldOf("createdAtSeconds")).As("createdAtString"),
	)).
	Execute(ctx)
pipeline_snippets_date_timestamp.go

TIMESTAMP_ADD

語法：

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

說明：

從 timestamp 新增 unit 的 amount。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	「小時」	-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();
test.firestore.js

網頁

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
Android

val result = db.pipeline()
    .collection("documents")
    .select(
        field("createdAt")
          .timestampAdd("day", 3653)
          .alias("expiresAt")
    )
    .execute()
DocSnippets.kt

Java
Android

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

Java

Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("documents")
        .select(timestampAdd(field("createdAt"), "day", 3653).as("expiresAt"))
        .execute()
        .get();
PipelineSnippets.java

Go

snapshot := client.Pipeline().
	Collection("documents").
	Select(firestore.Fields(
		firestore.TimestampAdd(firestore.FieldOf("createdAt"), "day", 3653).As("expiresAt"),
	)).
	Execute(ctx)
pipeline_snippets_date_timestamp.go

TIMESTAMP_SUB

語法：

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

說明：

從 timestamp 減去 unit 的 amount。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	「小時」	-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();
test.firestore.js

網頁

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
Android

val result = db.pipeline()
    .collection("documents")
    .select(
        field("expiresAt")
          .timestampSubtract("day", 14)
          .alias("sendWarningTimestamp")
    )
    .execute()
DocSnippets.kt

Java
Android

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

Java

Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("documents")
        .select(timestampSubtract(field("expiresAt"), "day", 14).as("sendWarningTimestamp"))
        .execute()
        .get();
PipelineSnippets.java

Go

snapshot := client.Pipeline().
	Collection("documents").
	Select(firestore.Fields(
		firestore.TimestampSubtract(firestore.FieldOf("expiresAt"), "day", 14).As("sendWarningTimestamp"),
	)).
	Execute(ctx)
pipeline_snippets_date_timestamp.go

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: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();
test.firestore.js

網頁

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
Android

val result = db.pipeline()
    .collection("documents")
    .select(
        field("dateString").timestampToUnixMicros().alias("unixMicros")
    )
    .execute()
DocSnippets.kt

Java
Android

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

Java

Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("documents")
        .select(timestampToUnixMicros(field("dateString")).as("unixMicros"))
        .execute()
        .get();
PipelineSnippets.java

Go

snapshot := client.Pipeline().
	Collection("documents").
	Select(firestore.Fields(
		firestore.TimestampToUnixMicros(firestore.FieldOf("dateString")).As("unixMicros"),
	)).
	Execute(ctx)
pipeline_snippets_date_timestamp.go

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 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();
test.firestore.js

網頁

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
Android

val result = db.pipeline()
    .collection("documents")
    .select(
        field("dateString").timestampToUnixMillis().alias("unixMillis")
    )
    .execute()
DocSnippets.kt

Java
Android

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

Java

Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("documents")
        .select(timestampToUnixMillis(field("dateString")).as("unixMillis"))
        .execute()
        .get();
PipelineSnippets.java

Go

snapshot := client.Pipeline().
	Collection("documents").
	Select(firestore.Fields(
		firestore.TimestampToUnixMillis(firestore.FieldOf("dateString")).As("unixMillis"),
	)).
	Execute(ctx)
pipeline_snippets_date_timestamp.go

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)
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();
test.firestore.js

網頁

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
Android

val result = db.pipeline()
    .collection("documents")
    .select(
        field("dateString").timestampToUnixSeconds().alias("unixSeconds")
    )
    .execute()
DocSnippets.kt

Java
Android

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

Java

Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("documents")
        .select(timestampToUnixSeconds(field("dateString")).as("unixSeconds"))
        .execute()
        .get();
PipelineSnippets.java

Go

snapshot := client.Pipeline().
	Collection("documents").
	Select(firestore.Fields(
		firestore.TimestampToUnixSeconds(firestore.FieldOf("dateString")).As("unixSeconds"),
	)).
	Execute(ctx)
pipeline_snippets_date_timestamp.go

TIMESTAMP_DIFF

語法：

timestamp_diff(end: TIMESTAMP | BSON_TIMESTAMP, start: TIMESTAMP | BSON_TIMESTAMP, unit: STRING) -> INT64

說明：

傳回兩個TIMESTAMP之間指定unit間隔的整數。

• 如果 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)
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

語法：

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

說明：

從 timestamp 擷取特定 part (例如年、月、日)。

part 引數必須是字串，且為下列其中一項：

• microsecond
• millisecond
• second
• minute
• hour
• day
• dayofweek：傳回介於 1 (星期日) 和 7 (星期六) 之間的值。
• dayofyear
• week：傳回一年中的週數，從當年的第一個星期日開始，以 1 表示。
• 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
2025-02-20 10:20:30 UTC	"day"	未提供	20
2025-12-31 23:59:59 UTC	"year"	"Asia/Tokyo"	2026

後續步驟

• 請參閱「管道查詢總覽」