TIMESTAMPTZ 領域Compatible with Milvus 2.6.6+
跨區域追蹤時間的應用程式，例如電子商務系統、協作工具或分散式日誌，需要精確處理帶有時區的時間戳。Milvus 中的TIMESTAMPTZ 資料類型透過儲存帶有相關時區的時間戳來提供此功能。
什麼是 TIMESTAMPTZ 欄位？
TIMESTAMPTZ 欄位是 Milvus 中一個模式定義的資料類型 (DataType.TIMESTAMPTZ) ，它處理時區感應輸入，並在內部將所有時間點儲存為 UTC 絕對時間：
接受的輸入格式：帶有時區偏移的ISO 8601字串（例如，
"2025-05-01T23:59:59+08:00"表示 2025 年 5 月 1 日晚上 11:59:59 (UTC+08:00)）。內部儲存：所有
TIMESTAMPTZ值均以統一時間 (Coordinated Universal Time, UTC) 標準化和儲存。比較與篩選：所有篩選和排序作業都以 UTC 執行，確保不同時區的結果一致且可預測。
您可以為
TIMESTAMPTZ欄位設定nullable=True，以允許缺失值。您可以使用
default_value屬性以ISO 8601格式指定預設時間戳值。
詳情請參閱Nullable & Default。
基本操作
使用TIMESTAMPTZ 欄位的基本工作流程與 Milvus 中的其他標量欄位相同：定義欄位 → 插入資料 → 查詢/篩選。
步驟 1：定義 TIMESTAMPTZ 欄位
要使用TIMESTAMPTZ 欄位，請在建立集合時，在集合模式中明確定義。以下範例示範如何建立一個具有tsz 欄位類型DataType.TIMESTAMPTZ 的集合。
import time
from pymilvus import MilvusClient, DataType
import datetime
import pytz
server_address = "http://localhost:19530"
collection_name = "timestamptz_test123"
client = MilvusClient(uri=server_address)
if client.has_collection(collection_name):
client.drop_collection(collection_name)
schema = client.create_schema()
# Add a primary key field
schema.add_field("id", DataType.INT64, is_primary=True)
# Add a TIMESTAMPTZ field that allows null values
schema.add_field("tsz", DataType.TIMESTAMPTZ, nullable=True)
# Add a vector field
schema.add_field("vec", DataType.FLOAT_VECTOR, dim=4)
client.create_collection(collection_name, schema=schema, consistency_level="Session")
print(f"Collection '{collection_name}' with a TimestampTz field created successfully.")
// java
// nodejs
// go
# restful
步驟 2：插入資料
插入包含 ISO 8601 字串與時區偏移的實體。
下面的範例會插入 8,193 行樣本資料到集合中。每一行包括
一個唯一的 ID
感知時區的時間戳 (上海時間)
一個簡單的 4 維向量
data_size = 8193
# Get the Asia/Shanghai time zone using the pytz library
# You can use any valid IANA time zone identifier such as:
# "Asia/Tokyo", "America/New_York", "Europe/London", "UTC", etc.
# To view all available values:
# import pytz; print(pytz.all_timezones)
# Reference:
# IANA database – https://www.iana.org/time-zones
# Wikipedia – https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
shanghai_tz = pytz.timezone("Asia/Shanghai")
data = [
{
"id": i + 1,
"tsz": shanghai_tz.localize(
datetime.datetime(2025, 1, 1, 0, 0, 0) + datetime.timedelta(days=i)
).isoformat(),
"vec": [float(i) / 10 for i in range(4)],
}
for i in range(data_size)
]
client.insert(collection_name, data)
print("Data inserted successfully.")
// java
// nodejs
// go
# restful
步驟 3：篩選操作
TIMESTAMPTZ...支援標量比較、區間運算和提取時間元件。
在對TIMESTAMPTZ 欄位執行篩選操作之前，請確定
您已為每個向量欄位建立索引。
集合已載入記憶體。
# Create index on vector field
index_params = client.prepare_index_params()
index_params.add_index(
field_name="vec",
index_type="AUTOINDEX",
index_name="vec_index",
metric_type="COSINE"
)
client.create_index(collection_name, index_params)
print("Index created successfully.")
# Load the collection
client.load_collection(collection_name)
print(f"Collection '{collection_name}' loaded successfully.")
// java
// nodejs
// go
# restful
使用時間戳過濾查詢
使用算術運算符如==,!=,<,>,<=,>= 。如需 Milvus 中可用的算術運算符的完整清單，請參閱算術運算符。
以下範例過濾時間戳 (tsz) 不等於2025-01-03T00:00:00+08:00 的實體：
# Query for entities where tsz is not equal to '2025-01-03T00:00:00+08:00'
expr = "tsz != ISO '2025-01-03T00:00:00+08:00'"
results = client.query(
collection_name=collection_name,
filter=expr,
output_fields=["id", "tsz"],
limit=10
)
print("Query result: ", results)
# Expected output:
# Query result: data: ["{'id': 1, 'tsz': '2024-12-31T16:00:00Z'}", "{'id': 2, 'tsz': '2025-01-01T16:00:00Z'}", "{'id': 4, 'tsz': '2025-01-03T16:00:00Z'}", "{'id': 5, 'tsz': '2025-01-04T16:00:00Z'}", "{'id': 6, 'tsz': '2025-01-05T16:00:00Z'}", "{'id': 7, 'tsz': '2025-01-06T16:00:00Z'}", "{'id': 8, 'tsz': '2025-01-07T16:00:00Z'}", "{'id': 9, 'tsz': '2025-01-08T16:00:00Z'}", "{'id': 10, 'tsz': '2025-01-09T16:00:00Z'}", "{'id': 11, 'tsz': '2025-01-10T16:00:00Z'}"]
// java
// nodejs
// go
# restful
在上面的範例中
tsz是模式中定義的TIMESTAMPTZ欄位名稱。ISO '2025-01-03T00:00:00+08:00'是ISO 8601格式的時間戳文字，包括其時區偏移。!=將字段值與字面意義比較。其他支援的操作符包括==,<,<=,>, 和>=。
間隔運算
您可以使用ISO 8601 長度格式中的INTERVAL值對TIMESTAMPTZ 欄位執行算術運算。這可讓您在篩選資料時，從時間戳記中加入或減去持續時間，例如天、小時或分鐘。
例如，以下查詢會篩選時間戳記 (tsz) 加上零天不等於2025-01-03T00:00:00+08:00 的實體：
expr = "tsz + INTERVAL 'P0D' != ISO '2025-01-03T00:00:00+08:00'"
results = client.query(
collection_name,
filter=expr,
output_fields=["id", "tsz"],
limit=10
)
print("Query result: ", results)
# Expected output:
# Query result: data: ["{'id': 1, 'tsz': '2024-12-31T16:00:00Z'}", "{'id': 2, 'tsz': '2025-01-01T16:00:00Z'}", "{'id': 4, 'tsz': '2025-01-03T16:00:00Z'}", "{'id': 5, 'tsz': '2025-01-04T16:00:00Z'}", "{'id': 6, 'tsz': '2025-01-05T16:00:00Z'}", "{'id': 7, 'tsz': '2025-01-06T16:00:00Z'}", "{'id': 8, 'tsz': '2025-01-07T16:00:00Z'}", "{'id': 9, 'tsz': '2025-01-08T16:00:00Z'}", "{'id': 10, 'tsz': '2025-01-09T16:00:00Z'}", "{'id': 11, 'tsz': '2025-01-10T16:00:00Z'}"]
// java
// nodejs
// go
# restful
INTERVAL 值遵循ISO 8601 期限語法。例如
P1D→ 1 天PT3H→ 3 小時P2DT6H→ 2 天 6 小時
您可以在篩選表達式中直接使用INTERVAL 算術，例如
tsz + INTERVAL 'P3D'→ 增加 3 天tsz - INTERVAL 'PT2H'→ 減去 2 小時
使用時間戳過濾搜尋
您可以將TIMESTAMPTZ 過濾與向量相似性搜尋結合，以時間和相似性兩種方式縮小搜尋結果的範圍。
# Define a time-based filter expression
filter = "tsz > ISO '2025-01-05T00:00:00+08:00'"
res = client.search(
collection_name=collection_name, # Collection name
data=[[0.1, 0.2, 0.3, 0.4]], # Query vector (must match collection's vector dim)
limit=5, # Max. number of results to return
filter=filter, # Filter expression using TIMESTAMPTZ
output_fields=["id", "tsz"], # Fields to include in the search results
)
print("Search result: ", res)
# Expected output:
# Search result: data: [[{'id': 10, 'distance': 0.9759000539779663, 'entity': {'tsz': '2025-01-09T16:00:00Z', 'id': 10}}, {'id': 9, 'distance': 0.9759000539779663, 'entity': {'tsz': '2025-01-08T16:00:00Z', 'id': 9}}, {'id': 8, 'distance': 0.9759000539779663, 'entity': {'tsz': '2025-01-07T16:00:00Z', 'id': 8}}, {'id': 7, 'distance': 0.9759000539779663, 'entity': {'tsz': '2025-01-06T16:00:00Z', 'id': 7}}, {'id': 6, 'distance': 0.9759000539779663, 'entity': {'tsz': '2025-01-05T16:00:00Z', 'id': 6}}]]
// java
// nodejs
// go
# restful
如果您的集合有兩個或更多向量欄位，您可以使用時間戳過濾執行混合搜尋作業。如需詳細資訊，請參閱多向量混合搜尋。
進階用法
對於進階用法，您可以在不同層級 (例如資料庫、集合或查詢) 管理時區，或使用索引加速對TIMESTAMPTZ 欄位的查詢。
管理不同層級的時區
您可以在資料庫、資料集或查詢/搜尋層級控制TIMESTAMPTZ 欄位的時區。
層級 |
參數 |
範圍 |
優先順序 |
|---|---|---|---|
資料庫 |
|
資料庫中所有收藏集的預設值 |
最低 |
收藏集 |
|
覆寫該收藏集的資料庫預設時區設定 |
中 |
查詢/搜尋/混合搜尋 |
|
針對一個特定作業的臨時覆寫 |
最高 |
如需逐步說明和程式碼範例，請參閱專用頁面：
加速查詢
預設情況下，在沒有索引的TIMESTAMPTZ 欄位上進行查詢時，會對所有行執行完整掃描，這在大型資料集上可能會很慢。若要加速時間戳查詢，請在TIMESTAMPTZ 欄位上建立STL_SORT 索引。
詳情請參閱STL_SORT。