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 值均會進行標準化處理，並以協調世界時（UTC）儲存。

• 比較與篩選：所有篩選和排序操作均以 UTC 為基準進行，確保在不同時區間能獲得一致且可預測的結果。

基本操作

使用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

使用時間戳記篩選進行搜尋

您可以將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。