メインコンテンツまでスキップ

TIMESTAMPTZ フィールド

電子商取引システム、コラボレーションツール、分散ロギングなど、地域をまたいで時間を追跡するアプリケーションでは、タイムゾーン付きタイムスタンプを正確に処理する必要があります。Zilliz Cloud の TIMESTAMPTZ データ型は、タイムスタンプを関連付けられたタイムゾーンとともに保存することで、この機能を提供します。

TIMESTAMPTZ フィールドとは​

TIMESTAMPTZ フィールドは、Zilliz Cloud のスキーマ定義データ型(DataType.TIMESTAMPTZ)であり、タイムゾーンを考慮した入力を受け付けて、すべての時点を内部的に UTC の絶対時刻として保存します:

  • 受け入れられる入力形式:TIMESTAMPTZ フィールドは、次を含む ISO 8601 互換のタイムスタンプ文字列を受け入れます:

    • "2024-12-31 22:00:00"

    • "2024-12-31T22:00:00"

    • "2024-12-31T22:00:00+08:00"

    • "2024-12-31T22:00:00Z"

  • タイムスタンプ解析ルール:タイムスタンプの解釈方法は、入力文字列がタイムゾーンを明示的に指定しているかどうかによって異なります:

    • 入力にタイムゾーンオフセット(+08:00 や Z など)が含まれている場合は、絶対的な時点として扱われます。

    • 入力にタイムゾーンオフセットが含まれていない場合は、コレクションに設定されたタイムゾーンを使用して解釈されます。たとえば、コレクションのタイムゾーンが Asia/Shanghai: である場合、次のようになります。

      • "2024-12-31 22:00:00" は 2024-12-31T22:00:00+08:00 として解釈されます

      • "2024-12-31T22:00:00" は 2024-12-31T22:00:00Z として解釈され、2025-01-01T06:00:00+08:00 に相当します

  • 内部ストレージ:すべての TIMESTAMPTZ 値は正規化され、Coordinated Universal Time(UTC)で保存されます。

  • 比較とフィルタリング:TIMESTAMPTZ フィールドに対するすべての比較、フィルタリング、並べ替え操作は UTC に正規化された値に対して実行され、異なるタイムゾーン間で一貫した動作を保証します。

Notes
  • TIMESTAMPTZ フィールドに nullable=True を設定すると、欠損値を許可できます。

  • ISO 8601 形式の default_value 属性を使用して、デフォルトのタイムスタンプ値を指定できます。

詳細については、Nullable & Default を参照してください。

基本操作​

TIMESTAMPTZ フィールドを使用する基本的なワークフローは、Zilliz Cloud の他のスカラーフィールドと同じです:フィールドを定義 → データを挿入 → query/filter.

ステップ 1: TIMESTAMPTZ フィールドを定義する​

TIMESTAMPTZ フィールドを使用するには、コレクションの作成時にコレクションのスキーマで明示的に定義します。次の例では、DataType.TIMESTAMPTZ 型の tsz フィールドを持つコレクションを作成する方法を示します。

python
import time
from pymilvus import MilvusClient, DataType
import datetime
import pytz

server_address = "YOUR_CLUSTER_ENDPOINT"
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.")

ステップ 2: データを挿入する​

タイムゾーンオフセットを含む ISO 8601 文字列を含むエンティティを挿入します。

次の例では、8,193 行のサンプルデータをコレクションに挿入します。各行には次が含まれます:

  • 一意の ID

  • タイムゾーンを考慮したタイムスタンプ(上海時間)

  • 単純な 4 次元ベクトル

python
data_size = 10

# 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 _ in range(4)],
}
for i in range(data_size)
]

client.insert(collection_name, data)
print("Data inserted successfully.")

ステップ 3: フィルタリング操作​

TIMESTAMPTZ は、スカラー比較、間隔演算、および時間コンポーネントの抽出をサポートします。

TIMESTAMPTZ フィールドに対するフィルタリング操作を実行する前に、次のことを確認してください:

  • 各ベクトルフィールドにインデックスを作成していること。

  • コレクションがメモリにロードされていること。

サンプルコードを表示する
python
# 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.")

タイムスタンプフィルタリングを使用したクエリ​

==、!=、<、>、<=、>= などの算術演算子を使用します。Zilliz Cloud で使用可能な算術演算子の完全な一覧については、Arithmetic Operators を参照してください。

Notes

連鎖した範囲式(たとえば、lower_bound < tsz < upper_bound)はサポートされていません。

代わりに論理積を使用してください:tsz > lower_bound AND tsz < upper_bound。

次の例では、タイムスタンプ(tsz)が 2025-01-03T00:00:00+08:00 と等しくないエンティティをフィルタリングします:

python
# 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'}"]

上記の例について説明します。

  • tsz は、スキーマで定義された TIMESTAMPTZ フィールド名です。

  • ISO '2025-01-03T00:00:00+08:00' は、タイムゾーンオフセットを含む ISO 8601 形式のタイムスタンプリテラルです。

  • != はフィールド値をそのリテラルと比較します。サポートされている他の演算子には、==、<、<=、>、>= があります。

間隔演算​

ISO 8601 期間形式の INTERVAL 値を使用して、TIMESTAMPTZ フィールドに対して算術演算を実行できます。これにより、データのフィルタリング時に、タイムスタンプから日、時間、分などの期間を加算または減算できます。

たとえば、次のクエリは、タイムスタンプ(tsz)に 0 日を加算した値が 2025-01-03T00:00:00+08:00 と等しくないエンティティをフィルタリングします:

python
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'}"]
Notes

INTERVAL 値は ISO 8601 期間構文に従います。例:

  • P1D → 1 日

  • PT3H → 3 時間

  • P2DT6H → 2 日と 6 時間

次のように、フィルター式内で INTERVAL 演算を直接使用できます:

  • tsz + INTERVAL 'P3D' → 3 日を加算する

  • tsz - INTERVAL 'PT2H' → 2 時間を減算する

タイムスタンプフィルタリングを使用した検索​

TIMESTAMPTZ フィルタリングとベクトル類似検索を組み合わせて、時間と類似度の両方で結果を絞り込むことができます。

python
# 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': 6, 'distance': 0.9128709435462952, 'entity': {'tsz': '2025-01-05T16:00:00Z', 'id': 6}}, {'id': 7, 'distance': 0.9128709435462952, 'entity': {'tsz': '2025-01-06T16:00:00Z', 'id': 7}}, {'id': 8, 'distance': 0.9128709435462952, 'entity': {'tsz': '2025-01-07T16:00:00Z', 'id': 8}}, {'id': 10, 'distance': 0.9128709435462952, 'entity': {'tsz': '2025-01-09T16:00:00Z', 'id': 10}}, {'id': 9, 'distance': 0.9128708839416504, 'entity': {'tsz': '2025-01-08T16:00:00Z', 'id': 9}}]]
Notes

コレクションに 2 つ以上のベクトルフィールドがある場合は、タイムスタンプフィルタリングを使用したハイブリッド検索操作を実行できます。詳細については、Multi-ベクトル Hybrid Search を参照してください。

高度な使用方法​

高度な使用方法として、さまざまなレベル(データベース、コレクション、クエリなど)でタイムゾーンを管理したり、インデックスを使用して TIMESTAMPTZ フィールドのクエリを高速化したりできます。

さまざまなレベルでタイムゾーンを管理する​

TIMESTAMPTZ フィールドのタイムゾーンは、コレクションレベルまたはquery/search レベルで制御できます。

レベルパラメータースコープ優先度
コレクションtimezoneそのコレクションのデータベースデフォルトタイムゾーン設定を上書きします中
Query/search/hybrid searchtimezone特定の 1 回の操作に対する一時的な上書きです最高

手順とコードサンプルについては、専用のページを参照してください:

クエリを高速化する​

デフォルトでは、インデックスのない TIMESTAMPTZ フィールドに対するクエリはすべての行のフルスキャンを実行するため、大規模なデータセットでは遅くなる可能性があります。タイムスタンプクエリを高速化するには、TIMESTAMPTZ フィールドに AUTOINDEX インデックスを作成します。

詳細については、STL_SORT を参照してください。