Feld „TIMESTAMPTZ“Compatible with Milvus 2.6.6+

Anwendungen, die Zeitangaben über verschiedene Regionen hinweg erfassen, wie beispielsweise E-Commerce-Systeme, Tools für die Zusammenarbeit oder verteilte Protokollierung, erfordern eine präzise Verarbeitung von Zeitstempeln unter Berücksichtigung von Zeitzonen. Der Datentyp „ TIMESTAMPTZ “ in Milvus bietet diese Funktion, indem er Zeitstempel zusammen mit der zugehörigen Zeitzone speichert.

Was ist ein TIMESTAMPTZ-Feld?

Ein „ TIMESTAMPTZ “-Feld ist ein schemadefinierter Datentyp (DataType.TIMESTAMPTZ) in Milvus, der zeitzonenbezogene Eingaben verarbeitet und alle Zeitpunkte intern als absolute UTC-Zeit speichert:

• Akzeptiertes Eingabeformat: ISO-8601-Zeichenfolgen mit einem Zeitzonen-Offset (beispielsweise steht „ "2025-05-01T23:59:59+08:00" “ für 23:59:59 Uhr am 1. Mai 2025 (UTC+08:00)).

• Interne Speicherung: Alle „ TIMESTAMPTZ “-Werte werden normalisiert und in der koordinierten Weltzeit (UTC) gespeichert.

• Vergleich und Filterung: Alle Filter- und Sortiervorgänge werden in UTC durchgeführt, wodurch konsistente und vorhersehbare Ergebnisse über verschiedene Zeitzonen hinweg gewährleistet sind.

Grundlegende Vorgänge

Der grundlegende Arbeitsablauf bei der Verwendung eines „ TIMESTAMPTZ “-Feldes entspricht dem anderer Skalarfelder in Milvus: Feld definieren → Daten einfügen → Abfrage/Filterung.

Schritt 1: Definieren eines TIMESTAMPTZ-Feldes

Um ein „ TIMESTAMPTZ “-Feld zu verwenden, definieren Sie es beim Erstellen der Sammlung explizit in Ihrem Sammlungsschema. 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-Zeichenfolgen 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 zeitzonenabhängigen 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: Filteroperationen

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

Bevor Sie Filteroperationen auf „ TIMESTAMPTZ “-Feldern durchführen können, stellen Sie Folgendes sicher:

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

• Die Sammlung ist in den Arbeitsspeicher 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 „ == “, „ != “, „ < “, „ > “, „ <= “ und „ >= “. Eine vollständige Liste der in Milvus verfügbaren arithmetischen Operatoren finden Sie unter „Arithmetische Operatoren“.

Das folgende Beispiel filtert Entitäten mit Zeitstempeln (tsz), die nicht dem Wert „2025-01-03T00:00:00+08:00“ entsprechen:

# 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 „ TIMESTAMPTZ “ der im Schema definierte Feldname.

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

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

Intervalloperationen

Sie können arithmetische Operationen auf TIMESTAMPTZ -Feldern unter Verwendung von INTERVAL- Werten im ISO 8601-Dauerformat durchführen. Auf diese Weise können Sie beim Filtern von Daten Zeiträume wie Tage, Stunden oder Minuten zu einem Zeitstempel addieren oder von diesem subtrahieren.

Die folgende Abfrage filtert beispielsweise Entitäten heraus, 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 Filterung nach „ TIMESTAMPTZ “ 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 fortgeschrittene Anwendungen können Sie Zeitzonen auf verschiedenen Ebenen (z. B. Datenbank, Sammlung oder Abfrage) verwalten oder Abfragen auf „ TIMESTAMPTZ “-Feldern mithilfe von Indizes beschleunigen.

Zeitzonen auf verschiedenen Ebenen verwalten

Sie können die Zeitzone für „ TIMESTAMPTZ “-Felder auf Datenbank-, Kollektions- oder Abfrage-/Suchebene steuern.

Schritt-für-Schritt-Anleitungen und Code-Beispiele finden Sie auf den entsprechenden Seiten:

• Sammlung bearbeiten

• Datenbank

• Abfrage

• Einfache Vektorsuche

• Hybride Suche mit mehreren Vektoren

Abfragen beschleunigen

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

Weitere Informationen finden Sie unter STL_SORT.