Campo TIMESTAMPTZCompatible with Milvus 2.6.6+

As aplicações que monitorizam o tempo em várias regiões, tais como sistemas de comércio eletrónico, ferramentas de colaboração ou registo distribuído, necessitam de um tratamento preciso dos carimbos de data e hora com fusos horários. O tipo de dados « TIMESTAMPTZ » no Milvus proporciona esta capacidade, armazenando carimbos de data e hora com o fuso horário associado.

O que é um campo TIMESTAMPTZ?

Um campo TIMESTAMPTZ é um tipo de dados definido pelo esquema (DataType.TIMESTAMPTZ) no Milvus que processa entradas que têm em conta o fuso horário e armazena todos os pontos temporais internamente como hora absoluta UTC:

• Formato de entrada aceite: cadeias de caracteres ISO 8601 com um desvio de fuso horário (por exemplo, "2025-05-01T23:59:59+08:00" indica 23:59:59 do dia 1 de maio de 2025 (UTC+08:00)).

• Armazenamento interno: Todos os valores « TIMESTAMPTZ » são normalizados e armazenados em Tempo Universal Coordenado (UTC).

• Comparação e filtragem: Todas as operações de filtragem e ordenação são realizadas em UTC, garantindo resultados consistentes e previsíveis em diferentes fusos horários.

Operações básicas

O fluxo de trabalho básico da utilização de um campo « TIMESTAMPTZ » é semelhante ao de outros campos escalares no Milvus: definir o campo → inserir dados → consultar/filtrar.

Passo 1: Definir um campo TIMESTAMPTZ

Para utilizar um campo « TIMESTAMPTZ », defina-o explicitamente no esquema da sua coleção ao criar a coleção. O exemplo seguinte demonstra como criar uma coleção com um campo « tsz » do 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

Passo 2: Inserir dados

Insira entidades que contenham cadeias de caracteres ISO 8601 com desvios de fuso horário.

O exemplo abaixo insere 8 193 linhas de dados de amostra na coleção. Cada linha inclui:

• um ID único

• um carimbo de data/hora com consideração do fuso horário (hora de Xangai)

• um vetor simples de 4 dimensões

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

Passo 3: Operações de filtragem

TIMESTAMPTZ suporta comparações escalares, aritmética de intervalos e extração de componentes temporais.

Antes de poder realizar operações de filtragem em campos d TIMESTAMPTZ, certifique-se de que:

• Que tenha criado um índice em cada campo vetorial.

• A coleção está carregada na memória.

# 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 com filtragem por carimbo de data/hora

Utilize operadores aritméticos como ==, !=, <, >, <=, >=. Para obter uma lista completa dos operadores aritméticos disponíveis no Milvus, consulte Operadores aritméticos.

O exemplo abaixo filtra entidades com carimbos de data/hora (tsz) que não sejam iguais 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

No exemplo acima,

• tsz é o nome do campo « TIMESTAMPTZ » definido no esquema.

• ISO '2025-01-03T00:00:00+08:00' é um literal de carimbo temporal no formato ISO 8601, incluindo o desvio do fuso horário.

• != compara o valor do campo com esse literal. Outros operadores suportados incluem ==, <, <=, > e >=.

Operações com intervalos

É possível realizar operações aritméticas em campos « TIMESTAMPTZ » utilizando valores «INTERVAL» no formato de duração ISO 8601. Isto permite-lhe somar ou subtrair durações, tais como dias, horas ou minutos, a um carimbo de data/hora ao filtrar dados.

Por exemplo, a consulta seguinte filtra entidades em que o carimbo de data/hora (tsz) mais zero dias não é 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

Pesquisa com filtragem por carimbo de data/hora

Pode combinar a filtragem de « TIMESTAMPTZ » com a pesquisa de similaridade vetorial para restringir os resultados tanto por tempo como por similaridade.

# 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

Utilização avançada

Para utilização avançada, pode gerir fusos horários a diferentes níveis (por exemplo, base de dados, coleção ou consulta) ou acelerar consultas em campos de « TIMESTAMPTZ » utilizando índices.

Gerir fusos horários em diferentes níveis

Pode controlar o fuso horário para campos TIMESTAMPTZ es ao nível da base de dados, da coleção ou da consulta/pesquisa.

Para obter instruções passo a passo e exemplos de código, consulte as páginas dedicadas:

• Modificar coleção

• Base de dados

• Consulta

• Pesquisa vetorial básica

• Pesquisa híbrida multivetor

Acelerar consultas

Por predefinição, as consultas em campos « TIMESTAMPTZ » sem um índice realizam uma varredura completa de todas as linhas, o que pode ser lento em conjuntos de dados de grande dimensão. Para acelerar as consultas com carimbos de data/hora, crie um índice « STL_SORT » no seu campo « TIMESTAMPTZ ».

Para mais detalhes, consulte STL_SORT.