TIMESTAMPTZ-FeldCompatible with Milvus 2.6.6+

Anwendungen, die die Zeit über Regionen hinweg verfolgen, wie z. B. E-Commerce-Systeme, Tools für die Zusammenarbeit oder verteilte Protokollierung, benötigen eine präzise Handhabung von Zeitstempeln mit Zeitzonen. Der Datentyp TIMESTAMPTZ in Milvus bietet diese Möglichkeit, indem er Zeitstempel mit ihrer zugehörigen Zeitzone speichert.

Was ist ein TIMESTAMPTZ-Feld?

Ein TIMESTAMPTZ -Feld ist ein schema-definierter Datentyp (DataType.TIMESTAMPTZ) in Milvus, der zeitzonenkonforme Eingaben verarbeitet und alle Zeitpunkte intern als absolute UTC-Zeit speichert:

• Akzeptiertes Eingabeformat: ISO 8601-Strings mit einem Zeitzonen-Offset (z. B. bedeutet "2025-05-01T23:59:59+08:00" 11:59:59 PM am 1. Mai 2025 (UTC+08:00)).

• Interne Speicherung: Alle TIMESTAMPTZ Werte werden normalisiert und in koordinierter Weltzeit (UTC) gespeichert.

• Vergleich und Filterung: Alle Filter- und Bestellvorgänge werden in UTC durchgeführt, um konsistente und vorhersehbare Ergebnisse in verschiedenen Zeitzonen zu gewährleisten.

Grundlegende Vorgänge

Der grundlegende Arbeitsablauf bei der Verwendung eines TIMESTAMPTZ Feldes spiegelt andere skalare Felder in Milvus wider: Feld definieren → Daten einfügen → Abfrage/Filter.

Schritt 1: Definieren Sie ein TIMESTAMPTZ-Feld

Um ein TIMESTAMPTZ Feld zu verwenden, definieren Sie es explizit in Ihrem Sammlungsschema, wenn Sie die Sammlung erstellen. Das folgende Beispiel zeigt, wie Sie eine Sammlung mit einem tsz Feld vom Typ DataType.TIMESTAMPTZ erstellen.

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

Schritt 2: Daten einfügen

Fügen Sie Entitäten ein, die ISO 8601-Strings mit Zeitzonen-Offsets enthalten.

Das folgende Beispiel fügt 8.193 Zeilen mit Beispieldaten in die Sammlung ein. Jede Zeile enthält:

• eine eindeutige ID

• einen zeitzonenkonformen Zeitstempel (Shanghai-Zeit)

• einen einfachen 4-dimensionalen Vektor

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

Schritt 3: Filterungsoperationen

TIMESTAMPTZ unterstützt skalare Vergleiche, Intervallarithmetik und die Extraktion von Zeitkomponenten.

Bevor Sie Filteroperationen auf TIMESTAMPTZ Feldern durchführen können, stellen Sie sicher, dass:

• Sie haben einen Index für jedes Vektorfeld erstellt.

• Die Sammlung ist in den Speicher geladen.

# 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

Abfrage mit Zeitstempel-Filterung

Verwenden Sie arithmetische Operatoren wie ==, !=, <, >, <=, >=. Eine vollständige Liste der arithmetischen Operatoren, die in Milvus verfügbar sind, finden Sie unter Arithmetische Operatoren.

Das folgende Beispiel filtert Entitäten mit Zeitstempeln (tsz), die nicht gleich 2025-01-03T00:00:00+08:00 sind:

# 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

Im obigen Beispiel,

• tsz ist der im Schema definierte Feldname TIMESTAMPTZ.

• ISO '2025-01-03T00:00:00+08:00' ist ein Zeitstempel-Literal im ISO 8601-Format, einschließlich seines Zeitzonen-Offsets.

• != vergleicht den Feldwert mit diesem Literal. Andere unterstützte Operatoren sind ==, <, <=, > und >=.

Intervalloperationen

Sie können mit TIMESTAMPTZ Feldern arithmetische Operationen durchführen, indem Sie INTERVAL-Werte im ISO 8601-Dauerformat verwenden. So können Sie beim Filtern von Daten Zeiträume wie Tage, Stunden oder Minuten zu einem Zeitstempel addieren oder davon subtrahieren.

Zum Beispiel filtert die folgende Abfrage Entitäten, bei denen der Zeitstempel (tsz) plus null Tage nicht gleich 2025-01-03T00:00:00+08:00 ist:

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

Suche mit Zeitstempel-Filterung

Sie können die TIMESTAMPTZ Filterung mit der Vektorähnlichkeitssuche kombinieren, um die Ergebnisse sowohl nach Zeit als auch nach Ähnlichkeit einzugrenzen.

# 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

Erweiterte Verwendung

Für die erweiterte Nutzung können Sie Zeitzonen auf verschiedenen Ebenen verwalten (z. B. Datenbank, Sammlung oder Abfrage) oder Abfragen auf TIMESTAMPTZ Feldern mit Indizes beschleunigen.

Verwalten von Zeitzonen auf verschiedenen Ebenen

Sie können die Zeitzone für TIMESTAMPTZ Felder auf der Ebene der Datenbank, der Sammlung oder der Abfrage/Suche steuern.

Schritt-für-Schritt-Anweisungen und Codebeispiele finden Sie auf den entsprechenden Seiten:

• Sammlung modifizieren

• Datenbank

• Abfrage

• Einfache Vektorsuche

• Hybride Multivektorsuche

Abfragen bescheunigen

Standardmäßig führen Abfragen auf TIMESTAMPTZ Felder ohne Index einen vollständigen Scan aller Zeilen durch, was bei großen Datensätzen langsam sein kann. Um Zeitstempelabfragen zu beschleunigen, erstellen Sie einen STL_SORT Index für Ihr TIMESTAMPTZ Feld.

Einzelheiten finden Sie unter STL_SORT.