Kolom TIMESTAMPTZCompatible with Milvus 2.6.6+

Aplikasi yang melacak waktu di berbagai wilayah, seperti sistem e-commerce, alat kolaborasi, atau pencatatan terdistribusi, memerlukan penanganan yang akurat terhadap cap waktu beserta zona waktunya. Tipe data ` TIMESTAMPTZ ` di Milvus menyediakan kemampuan ini dengan menyimpan cap waktu beserta zona waktu yang terkait.

Apa itu bidang TIMESTAMPTZ?

Kolom TIMESTAMPTZ adalah tipe data yang didefinisikan dalam skema (DataType.TIMESTAMPTZ) di Milvus yang memproses input yang menyertakan zona waktu dan menyimpan semua titik waktu secara internal sebagai waktu absolut UTC:

• Format masukan yang diterima: string ISO 8601 dengan selisih zona waktu (misalnya, "2025-05-01T23:59:59+08:00" menunjukkan pukul 11:59:59 malam pada 1 Mei 2025 (UTC+08:00)).

• Penyimpanan internal: Semua nilai TIMESTAMPTZ dinormalisasi dan disimpan dalam Waktu Universal Terkoordinasi (UTC).

• Perbandingan dan penyaringan: Semua operasi penyaringan dan pengurutan dilakukan dalam UTC, memastikan hasil yang konsisten dan dapat diprediksi di berbagai zona waktu.

Operasi dasar

Alur kerja dasar dalam menggunakan bidang ` TIMESTAMPTZ ` mirip dengan bidang skalar lainnya di Milvus: tentukan bidang → masukkan data → lakukan kueri/filter.

Langkah 1: Menentukan bidang TIMESTAMPTZ

Untuk menggunakan bidang ` TIMESTAMPTZ `, tentukan secara eksplisit dalam skema koleksi Anda saat membuat koleksi. Contoh berikut menunjukkan cara membuat koleksi dengan bidang ` tsz ` bertipe ` 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

Langkah 2: Menyisipkan data

Masukkan entitas yang berisi string ISO 8601 dengan selisih zona waktu.

Contoh di bawah ini menyisipkan 8.193 baris data sampel ke dalam koleksi. Setiap baris mencakup:

• ID unik

• cap waktu yang menyertakan zona waktu (waktu Shanghai)

• vektor 4-dimensi sederhana

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

Langkah 3: Operasi penyaringan

TIMESTAMPTZ mendukung perbandingan skalar, aritmatika interval, dan ekstraksi komponen waktu.

Sebelum Anda dapat melakukan operasi penyaringan pada bidang-bid TIMESTAMPTZ, pastikan:

• Anda telah membuat indeks pada setiap bidang vektor.

• Koleksi telah dimuat ke dalam memori.

# 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

Kueri dengan penyaringan berdasarkan cap waktu

Gunakan operator aritmatika seperti ==, !=, <, >, <=, >=. Untuk daftar lengkap operator aritmatika yang tersedia di Milvus, lihat Operator Aritmatika.

Contoh di bawah ini menyaring entitas dengan cap waktu (tsz) yang tidak sama dengan 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

Dalam contoh di atas,

• tsz adalah nama kolom ` TIMESTAMPTZ ` yang didefinisikan dalam skema.

• ISO '2025-01-03T00:00:00+08:00' adalah literal cap waktu dalam format ISO 8601, termasuk offset zona waktunya.

• != membandingkan nilai bidang dengan literal tersebut. Operator lain yang didukung meliputi ==, <, <=, >, dan >=.

Operasi interval

Anda dapat melakukan operasi aritmatika pada bidang ` TIMESTAMPTZ ` menggunakan nilai `INTERVAL ` dalam format durasi ISO 8601. Hal ini memungkinkan Anda untuk menambahkan atau mengurangkan durasi, seperti hari, jam, atau menit, dari sebuah cap waktu saat menyaring data.

Misalnya, kueri berikut menyaring entitas di mana cap waktu (tsz) ditambah nol hari tidak sama dengan 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

Pencarian dengan penyaringan berdasarkan cap waktu

Anda dapat menggabungkan penyaring TIMESTAMPTZ e dengan pencarian kesamaan vektor untuk mempersempit hasil berdasarkan waktu dan kesamaan.

# 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

Penggunaan lanjutan

Untuk penggunaan lanjutan, Anda dapat mengelola zona waktu pada berbagai tingkatan (misalnya, basis data, koleksi, atau kueri) atau mempercepat kueri pada bidang TIMESTAMPTZ menggunakan indeks.

Mengelola zona waktu pada berbagai tingkatan

Anda dapat mengontrol zona waktu untuk bidang- TIMESTAMPTZ pada tingkat basis data, koleksi, atau kueri/pencarian.

Untuk petunjuk langkah demi langkah dan contoh kode, lihat halaman khusus berikut:

• Mengubah Koleksi

• Database

• Kueri

• Pencarian Vektor Dasar

• Pencarian Hibrida Multi-Vektor

Mempercepat kueri

Secara default, kueri pada kolom ` TIMESTAMPTZ ` yang tidak memiliki indeks akan melakukan pemindaian penuh terhadap semua baris, yang dapat memakan waktu lama pada dataset besar. Untuk mempercepat kueri berdasarkan cap waktu, buatlah indeks ` STL_SORT ` pada kolom ` TIMESTAMPTZ ` Anda.

Untuk detailnya, lihat STL_SORT.