Champ TIMESTAMPTZCompatible with Milvus 2.6.6+
Les applications qui suivent l'évolution du temps dans différentes régions, telles que les systèmes de commerce électronique, les outils de collaboration ou la journalisation distribuée, nécessitent un traitement précis des horodatages tenant compte des fuseaux horaires. Le type de données « TIMESTAMPTZ » de Milvus offre cette fonctionnalité en stockant les horodatages avec le fuseau horaire associé.
Qu'est-ce qu'un champ TIMESTAMPTZ ?
Un champ TIMESTAMPTZ est un type de données défini par le schéma (DataType.TIMESTAMPTZ) dans Milvus qui traite les données d’entrée tenant compte du fuseau horaire et stocke en interne tous les instants sous forme d’heure absolue UTC :
Format d’entrée accepté: chaînes de caractères au format ISO 8601 avec un décalage de fuseau horaire (par exemple,
"2025-05-01T23:59:59+08:00"correspond à 23 h 59 min 59 s le 1er mai 2025 (UTC+08:00)).Stockage interne: toutes les valeurs de type «
TIMESTAMPTZ» sont normalisées et stockées en temps universel coordonné (UTC).Comparaison et filtrage: toutes les opérations de filtrage et de tri sont effectuées en UTC, ce qui garantit des résultats cohérents et prévisibles quel que soit le fuseau horaire.
Vous pouvez définir l’attribut «
nullable=True» pour les champs «TIMESTAMPTZ» afin d’autoriser les valeurs manquantes.Vous pouvez spécifier une valeur d’horodatage par défaut à l’aide de l’attribut «
default_value» au format ISO 8601.
Voir « Nullable & Default » pour plus de détails.
Opérations de base
Le workflow de base pour l’utilisation d’un champ « TIMESTAMPTZ » est similaire à celui des autres champs scalaires dans Milvus : définir le champ → insérer des données → interroger/filtrer.
Étape 1 : Définir un champ TIMESTAMPTZ
Pour utiliser un champ « TIMESTAMPTZ », définissez-le explicitement dans le schéma de votre collection lors de la création de celle-ci. L’exemple suivant montre comment créer une collection avec un champ « tsz » de type « 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
Étape 2 : Insérer des données
Insérez des entités contenant des chaînes ISO 8601 avec des décalages horaires.
L’exemple ci-dessous insère 8 193 lignes de données d’exemple dans la collection. Chaque ligne comprend :
un identifiant unique
un horodatage tenant compte du fuseau horaire (heure de Shanghai)
un vecteur simple à 4 dimensions
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
Étape 3 : Opérations de filtrage
TIMESTAMPTZ Prend en charge les comparaisons scalaires, l'arithmétique d'intervalles et l'extraction de composantes temporelles.
Avant de pouvoir effectuer des opérations de filtrage sur les champs d'TIMESTAMPTZ, assurez-vous que :
Vous avez créé un index sur chaque champ vectoriel.
La collection est chargée en mémoire.
# 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
Requête avec filtrage par horodatage
Utilisez des opérateurs arithmétiques tels que ==, !=, <, >, <=, >=. Pour obtenir la liste complète des opérateurs arithmétiques disponibles dans Milvus, consultez la section Opérateurs arithmétiques.
L'exemple ci-dessous filtre les entités dont l'horodatage (tsz) n'est pas égal à 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
Dans l’exemple ci-dessus,
tszest le nom du champ «TIMESTAMPTZ» défini dans le schéma.ISO '2025-01-03T00:00:00+08:00'est un littéral d’horodatage au format ISO 8601, incluant son décalage horaire.!=compare la valeur du champ à ce littéral. Les autres opérateurs pris en charge sont notamment==,<,<=,>et>=.
Opérations sur les intervalles
Vous pouvez effectuer des opérations arithmétiques sur les champs de type « TIMESTAMPTZ » à l’aide de valeurs INTERVAL au format de durée ISO 8601. Cela vous permet d’ajouter ou de soustraire des durées, telles que des jours, des heures ou des minutes, à un horodatage lors du filtrage des données.
Par exemple, la requête suivante filtre les entités pour lesquelles l’horodatage (tsz) plus zéro jour n’ est pas égal à 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
INTERVAL Les valeurs respectent la syntaxe de durée ISO 8601. Par exemple :
P1D→ 1 jourPT3H→ 3 heuresP2DT6H→ 2 jours et 6 heures
Vous pouvez utiliser directement l'arithmétique d'INTERVAL s dans les expressions de filtrage, comme par exemple :
tsz + INTERVAL 'P3D'→ Ajoute 3 jourstsz - INTERVAL 'PT2H'→ Soustrait 2 heures
Recherche avec filtrage par horodatage
Vous pouvez combiner le filtrage par horodat TIMESTAMPTZ s avec la recherche par similarité vectorielle pour affiner les résultats à la fois en fonction de l'heure et de la similarité.
# 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
Si votre collection comporte au moins deux champs vectoriels, vous pouvez effectuer des opérations de recherche hybride avec filtrage par horodatage. Pour plus de détails, consultez la section Recherche hybride multi-vecteurs.
Utilisation avancée
Pour une utilisation avancée, vous pouvez gérer les fuseaux horaires à différents niveaux (par exemple, base de données, collection ou requête) ou accélérer les requêtes sur les champs d'TIMESTAMPTZ s à l'aide d'index.
Gérer les fuseaux horaires à différents niveaux
Vous pouvez contrôler le fuseau horaire des champs « TIMESTAMPTZ » au niveau de la base de données, de la collection ou de la requête/recherche.
Niveau |
Paramètre |
Portée |
Priorité |
|---|---|---|---|
Base de données |
|
Valeur par défaut pour toutes les collections de la base de données |
La plus faible |
Collection |
|
Remplace le paramètre de fuseau horaire par défaut de la base de données pour cette collection |
Moyen |
Requête/recherche/recherche hybride |
|
Remplacement temporaire pour une opération spécifique |
Max |
Pour obtenir des instructions étape par étape et des exemples de code, consultez les pages dédiées :
Accélérer les requêtes
Par défaut, les requêtes sur les champs de type « TIMESTAMPTZ » ne disposant pas d’index effectuent un balayage complet de toutes les lignes, ce qui peut s’avérer lent sur des ensembles de données volumineux. Pour accélérer les requêtes sur les horodatages, créez un index « STL_SORT » sur votre champ « TIMESTAMPTZ ».
Pour plus de détails, reportez-vous à STL_SORT.