Campo TIMESTAMPTZCompatible with Milvus 2.6.6+

Las aplicaciones que realizan un seguimiento del tiempo en distintas regiones, como los sistemas de comercio electrónico, las herramientas de colaboración o el registro distribuido, necesitan gestionar con precisión las marcas de tiempo con zonas horarias. El tipo de datos « TIMESTAMPTZ » de Milvus ofrece esta capacidad al almacenar las marcas de tiempo junto con su zona horaria asociada.

¿Qué es un campo TIMESTAMPTZ?

Un campo « TIMESTAMPTZ » es un tipo de datos definido por el esquema (DataType.TIMESTAMPTZ) en Milvus que procesa entradas que tienen en cuenta la zona horaria y almacena internamente todos los puntos temporales como hora absoluta UTC:

• Formato de entrada aceptado: cadenas ISO 8601 con un desfase horario (por ejemplo, "2025-05-01T23:59:59+08:00" indica las 11:59:59 p. m. del 1 de mayo de 2025 (UTC+08:00)).

• Almacenamiento interno: Todos los valores « TIMESTAMPTZ » se normalizan y se almacenan en tiempo universal coordinado (UTC).

• Comparación y filtrado: Todas las operaciones de filtrado y ordenación se realizan en UTC, lo que garantiza resultados coherentes y predecibles en diferentes zonas horarias.

Operaciones básicas

El flujo de trabajo básico para utilizar un campo « TIMESTAMPTZ » es similar al de otros campos escalares en Milvus: definir el campo → insertar datos → consultar/filtrar.

Paso 1: Definir un campo TIMESTAMPTZ

Para utilizar un campo « TIMESTAMPTZ », defínelo explícitamente en el esquema de la colección al crearla. El siguiente ejemplo muestra cómo crear una colección con un campo « tsz » de tipo « 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

Paso 2: Insertar datos

Inserta entidades que contengan cadenas ISO 8601 con diferencias horarias.

El ejemplo siguiente inserta 8.193 filas de datos de muestra en la colección. Cada fila incluye:

• un ID único

• una marca de tiempo que tiene en cuenta la zona horaria (hora de Shanghái)

• un vector simple de 4 dimensiones

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

Paso 3: Operaciones de filtrado

TIMESTAMPTZ Admite comparaciones escalares, aritmética de intervalos y extracción de componentes temporales.

Antes de poder realizar operaciones de filtrado en los campos de un TIMESTAMPTZ, asegúrate de que:

• Has creado un índice en cada campo vectorial.

• La colección esté cargada en memoria.

# 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

Consulta con filtrado por marca de tiempo

Utiliza operadores aritméticos como ==, !=, <, >, <= y >=. Para ver la lista completa de operadores aritméticos disponibles en Milvus, consulta Operadores aritméticos.

El siguiente ejemplo filtra las entidades con marcas de tiempo (tsz) que no sean iguales a 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

En el ejemplo anterior,

• tsz « TIMESTAMPTZ » es el nombre del campo definido en el esquema.

• ISO '2025-01-03T00:00:00+08:00' es un literal de marca de tiempo en formato ISO 8601, que incluye su desfase horario.

• != compara el valor del campo con ese literal. Otros operadores admitidos son « == », « < », « <= », « > » y « >= ».

Operaciones con intervalos

Se pueden realizar operaciones aritméticas en campos de tipo « TIMESTAMPTZ » utilizando valores de INTERVAL en el formato de duración ISO 8601. Esto permite sumar o restar duraciones, como días, horas o minutos, a una marca de tiempo al filtrar datos.

Por ejemplo, la siguiente consulta filtra las entidades en las que la marca de tiempo (tsz) más cero días no es igual a 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

Búsqueda con filtrado por marca de tiempo

Puedes combinar el filtrado de « TIMESTAMPTZ » con la búsqueda por similitud vectorial para acotar los resultados tanto por tiempo como por similitud.

# 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

Uso avanzado

Para un uso avanzado, puede gestionar las zonas horarias en diferentes niveles (por ejemplo, base de datos, colección o consulta) o acelerar las consultas en campos de « TIMESTAMPTZ » utilizando índices.

Gestionar zonas horarias en diferentes niveles

Puede controlar la zona horaria de los campos « TIMESTAMPTZ » a nivel de base de datos, colección o consulta/búsqueda.

Para obtener instrucciones paso a paso y ejemplos de código, consulta las páginas específicas:

• Modificar colección

• Base de datos

• Consulta

• Búsqueda vectorial básica

• Búsqueda híbrida multivectorial

Acelerar consultas

Por defecto, las consultas en campos de tipo « TIMESTAMPTZ » que no tengan un índice realizarán un escaneo completo de todas las filas, lo que puede resultar lento en conjuntos de datos de gran tamaño. Para acelerar las consultas con marcas de tiempo, crea un índice « STL_SORT » en tu campo « TIMESTAMPTZ ».

Para obtener más información, consulta STL_SORT.