Campo TIMESTAMPTZCompatible with Milvus 2.6.6+

As aplicações que controlam o tempo entre regiões, como os sistemas de comércio eletrónico, as ferramentas de colaboração ou o registo distribuído, necessitam de um tratamento preciso dos carimbos de data/hora com os fusos horários. O tipo de dados TIMESTAMPTZ em Milvus fornece esta capacidade ao armazenar carimbos de data/hora com o seu fuso horário associado.

O que é um campo TIMESTAMPTZ?

Um campo TIMESTAMPTZ é um tipo de dados definido por um esquema (DataType.TIMESTAMPTZ) em Milvus que processa a entrada sensível ao 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" representa 11:59:59 PM em UTC+08:00).

• Armazenamento interno: Todos os valores de 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 reflecte 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 seu esquema de coleção ao criar a coleção. O exemplo a seguir 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

Etapa 2: Inserir dados

Insira entidades contendo cadeias de caracteres ISO 8601 com deslocamentos de fuso horário.

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

• um ID exclusivo

• um carimbo de data/hora sensível ao 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 O site suporta comparações escalares, aritmética de intervalos e extração de componentes de tempo.

Antes de poder efetuar operações de filtragem nos campos TIMESTAMPTZ, certifique-se de que:

• Criou um índice em cada campo de vetor.

• 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 de 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 e hora (tsz) que não são 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 de data/hora no formato ISO 8601, incluindo seu deslocamento de fuso horário.

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

Operações de intervalo

Pode efetuar aritmética nos campos TIMESTAMPTZ utilizando valores de INTERVALO no formato de duração ISO 8601. Isto permite-lhe adicionar ou subtrair durações, tais como dias, horas ou minutos, de um carimbo de data/hora ao filtrar dados.

Por exemplo, a consulta a seguir 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 de carimbo de data/hora

Você pode combinar a filtragem TIMESTAMPTZ com a pesquisa de similaridade de vetor para restringir os resultados por tempo e 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

Uso avançado

Para uso avançado, você pode gerenciar fusos horários em diferentes níveis (por exemplo, banco de dados, coleção ou consulta) ou acelerar consultas em TIMESTAMPTZ campos usando índices.

Gerir fusos horários a diferentes níveis

É possível controlar o fuso horário dos campos TIMESTAMPTZ 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 de vários vetores

Acelerar as consultas

Por predefinição, as consultas nos campos TIMESTAMPTZ sem um índice efectuam uma pesquisa completa de todas as linhas, o que pode ser lento em grandes conjuntos de dados. Para acelerar as consultas de carimbo de data/hora, crie um índice STL_SORT no seu campo TIMESTAMPTZ.

Para obter detalhes, consulte STL_SORT.