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 un manejo preciso de las marcas de tiempo con zonas horarias. El tipo de datos TIMESTAMPTZ en Milvus proporciona esta capacidad mediante el almacenamiento de marcas de tiempo con su zona horaria asociada.

¿Qué es un campo TIMESTAMPTZ?

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

• Formato de entrada aceptado: Cadenas ISO 8601 con un desfase de zona horaria (por ejemplo, "2025-05-01T23:59:59+08:00" indica las 23:59:59 del 1 de mayo de 2025 (UTC+08:00)).

• Almacenamiento interno: Todos los valores de TIMESTAMPTZ se normalizan y 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 distintas zonas horarias.

Operaciones básicas

El flujo de trabajo básico del uso de un campo TIMESTAMPTZ refleja otros campos escalares en Milvus: definir el campo → insertar datos → consulta/filtro.

Paso 1: Definir un campo TIMESTAMPTZ

Para utilizar un campo TIMESTAMPTZ, defínalo explícitamente en el esquema de su colección al crear la colección. 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

Inserte entidades que contengan cadenas ISO 8601 con desfases horarios.

El siguiente ejemplo 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 Shanghai)

• 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 TIMESTAMPTZ, asegúrese de:

• 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 de fecha y hora

Utilice operadores aritméticos como ==, !=, <, >, <=, >=. Para obtener una lista completa de los operadores aritméticos disponibles en Milvus, consulte Operadores aritméticos.

El siguiente ejemplo filtra entidades con marcas de tiempo (tsz) que no son 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 es el nombre del campo TIMESTAMPTZ definido en el esquema.

• ISO '2025-01-03T00:00:00+08:00' es un literal de fecha y hora en formato ISO 8601, incluido su desfase horario.

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

Operaciones de intervalo

Puede realizar operaciones aritméticas en los campos TIMESTAMPTZ utilizando valores de INTERVALO en el formato de duración ISO 8601. Esto le permite sumar o restar duraciones, como días, horas o minutos, de 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 de marcas de tiempo

Puedes combinar el filtrado TIMESTAMPTZ con la búsqueda de 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 los campos TIMESTAMPTZ utilizando índices.

Gestión de zonas horarias a distintos 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, consulte las páginas correspondientes:

• Modificar colección

• Base de datos

• Consulta

• Búsqueda vectorial básica

• Búsqueda híbrida multivectorial

Acelerar las consultas

Por defecto, las consultas en campos TIMESTAMPTZ sin un índice realizarán un escaneo completo de todas las filas, lo que puede ser lento en grandes conjuntos de datos. Para acelerar las consultas de fecha y hora, cree un índice STL_SORT en el campo TIMESTAMPTZ.

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