Milvusについて
スタート
コンセプト
ユーザーガイド
データインポート
管理ガイド
ツール
統合
チュートリアル
よくあるご質問
API Reference

Home
Docs
ユーザーガイド
スキーマとデータフィールド
TIMESTAMPTZフィールド

TIMESTAMPTZフィールドCompatible with Milvus 2.6.6+

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

TIMESTAMPTZフィールドとは？

TIMESTAMPTZ フィールドはMilvusのスキーマ定義データ型(DataType.TIMESTAMPTZ)であり、タイムゾーンを考慮した入力を処理し、内部的に全てのタイムポイントをUTC絶対時間として格納します：

入力フォーマット：入力フォーマット:ISO 8601文字列にタイムゾーンのオフセット (例えば、"2025-05-01T23:59:59+08:00" は UTC+08:00 の 11:59:59 PM を表す)。
内部ストレージ：TIMESTAMPTZ の値はすべて正規化され、協定世界時（UTC）に保存されます。
比較とフィルタリング：すべてのフィルタリングと順序付け操作はUTCで実行され、異なるタイムゾーン間で一貫性のある予測可能な結果を保証します。

TIMESTAMPTZ フィールドにnullable=True を設定し、欠損値を許容することができます。
ISO 8601形式のdefault_value 属性を用いて、デフォルトのタイムスタンプ値を指定することができます。

詳しくはNullable & Defaultを参照してください。

基本操作

TIMESTAMPTZ フィールドを使用する際の基本的なワークフローは、milvusの他のスカラーフィールドと同様です：フィールドの定義 → データの挿入 → クエリ/フィルタ.

ステップ1: TIMESTAMPTZフィールドの定義

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

Python Java NodeJS Go cURL

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次元ベクトル

Python Java NodeJS Go cURL

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 フィールドに対してフィルタリング操作を行う前に、以下を確認してください：

各ベクトル・フィールドにインデックスが作成されている。
コレクションがメモリにロードされている。

コード例を示す。

Python Java NodeJS Go cURL

# 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 と等しくないエンティティをフィルタリングしています：

cURL Java NodeJS Go cURL

# 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) に 0 日を足した値が2025-01-03T00:00:00+08:00 と等しくないエンティティをフィルタリングします：

Python Java NodeJS Go cURL

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

Python Java NodeJS Go cURL

# 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

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

高度な使用法

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

異なるレベルでのタイムゾーンの管理

データベース、コレクション、クエリ/検索レベルで、TIMESTAMPTZ フィールドのタイムゾーンを管理できます。

レベル	パラメータ	範囲	優先度
データベース	`timezone`	データベース内のすべてのコレクションのデフォルト	最も低い
コレクション	`timezone`	そのコレクションのデータベースのデフォルトのタイムゾーン設定を上書きします。	ミディアム
クエリ/検索/ハイブリッド検索	`timezone`	特定の操作に対する一時的なオーバーライド	最高

ステップバイステップの説明とコードサンプルについては、専用ページを参照してください：

クエリの高速化

デフォルトでは、インデックスのないTIMESTAMPTZ フィールドに対するクエリは、すべての行のフルスキャンを実行します。タイムスタンプ・クエリを高速化するには、TIMESTAMPTZ フィールドにSTL_SORT インデックスを作成します。

詳細はSTL_SORTを参照。

TIMESTAMPTZフィールドCompatible with Milvus 2.6.6+
TIMESTAMPTZフィールドとは？
基本操作
ステップ1: TIMESTAMPTZフィールドの定義
ステップ 2: データの挿入
ステップ3：フィルタリング操作
高度な使用法
異なるレベルでのタイムゾーンの管理
クエリの高速化

Try Managed Milvus for Free

Zilliz Cloud is hassle-free, powered by Milvus and 10x faster.

Get Started

フィードバック

このページは役に立ちましたか？

TIMESTAMPTZフィールドCompatible with Milvus 2.6.6+

TIMESTAMPTZフィールドとは？

基本操作

ステップ1: TIMESTAMPTZフィールドの定義

ステップ 2: データの挿入

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

タイムスタンプ・フィルタリングによるクエリー

区間演算

タイムスタンプ・フィルタリングによる検索

高度な使用法

異なるレベルでのタイムゾーンの管理

クエリの高速化

目次

Try Managed Milvus for Free

フィードバック