Bidang TIMESTAMPTZCompatible with Milvus 2.6.6+

Aplikasi yang melacak waktu di seluruh wilayah, seperti sistem e-commerce, alat kolaborasi, atau penebangan terdistribusi, membutuhkan penanganan stempel waktu yang tepat dengan zona waktu. Tipe data TIMESTAMPTZ di Milvus menyediakan kemampuan ini dengan menyimpan stempel waktu dengan zona waktu terkait.

Apa yang dimaksud dengan bidang TIMESTAMPTZ?

Bidang TIMESTAMPTZ adalah tipe data yang ditentukan skema (DataType.TIMESTAMPTZ) di Milvus yang memproses input yang sadar zona waktu dan menyimpan semua titik waktu secara internal sebagai waktu absolut UTC:

• Format masukan yang diterima: String ISO 8601 dengan offset zona waktu (misalnya, "2025-05-01T23:59:59+08:00" mewakili pukul 11:59:59 PM di UTC+08:00).

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

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

Operasi dasar

Alur kerja dasar penggunaan bidang TIMESTAMPTZ mencerminkan bidang skalar lainnya di Milvus: tentukan bidang → masukkan data → kueri/filter.

Langkah 1: Mendefinisikan bidang TIMESTAMPTZ

Untuk menggunakan field TIMESTAMPTZ, secara eksplisit mendefinisikannya di dalam skema koleksi Anda ketika membuat koleksi. Contoh berikut ini 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: Memasukkan data

Sisipkan entitas yang berisi string ISO 8601 dengan offset zona waktu.

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

• ID unik

• stempel waktu yang sadar 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 pemfilteran

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

Sebelum Anda dapat melakukan operasi pemfilteran pada bidang TIMESTAMPTZ, pastikan:

• Anda telah membuat indeks pada setiap bidang vektor.

• Koleksi 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 pemfilteran stempel waktu

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

Contoh di bawah ini memfilter entitas dengan stempel 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

Pada contoh di atas,

• tsz adalah nama bidang TIMESTAMPTZ yang didefinisikan dalam skema.

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

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

Operasi interval

Anda dapat melakukan aritmatika pada bidang TIMESTAMPTZ menggunakan nilai INTERVAL dalam format durasi ISO 8601. Hal ini memungkinkan Anda menambah atau mengurangi durasi, seperti hari, jam, atau menit, dari stempel waktu saat memfilter data.

Sebagai contoh, kueri berikut ini memfilter entitas dengan 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

Mencari dengan pemfilteran stempel waktu

Anda dapat menggabungkan pemfilteran TIMESTAMPTZ dengan pencarian kemiripan vektor untuk mempersempit hasil berdasarkan waktu dan kemiripan.

# 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 tingkat lanjut, Anda dapat mengelola zona waktu pada tingkat yang berbeda (misalnya basis data, koleksi, atau kueri) atau mempercepat kueri pada bidang TIMESTAMPTZ menggunakan indeks.

Mengelola zona waktu di tingkat yang berbeda

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

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

• Memodifikasi Koleksi

• Basis data

• Permintaan

• Pencarian Vektor Dasar

• Pencarian Hibrida Multi-Vektor

Mempercepat kueri

Secara default, kueri pada bidang TIMESTAMPTZ tanpa indeks akan melakukan pemindaian penuh terhadap semua baris, yang dapat berjalan lambat pada kumpulan data yang besar. Untuk mempercepat kueri stempel waktu, buat indeks STL_SORT pada bidang TIMESTAMPTZ Anda.

Untuk detailnya, lihat STL_SORT.