Поле TIMESTAMPTZCompatible with Milvus 2.6.6+

Приложения, отслеживающие время в разных регионах, такие как системы электронной коммерции, инструменты для совместной работы или распределенное ведение журналов, требуют точной обработки временных меток с учетом часовых поясов. Тип данных « TIMESTAMPTZ » в Milvus обеспечивает эту возможность, храня временные метки вместе с соответствующими часовыми поясами.

Что такое поле TIMESTAMPTZ?

Поле TIMESTAMPTZ — это тип данных, определённый в схеме (DataType.TIMESTAMPTZ) в Milvus, который обрабатывает входные данные с учётом часовых поясов и хранит все временные точки внутренне в виде абсолютного времени UTC:

• Допустимый формат входных данных: строки в формате ISO 8601 со смещением часового пояса (например, "2025-05-01T23:59:59+08:00" обозначает 11:59:59 вечера 1 мая 2025 года (UTC+08:00)).

• Внутреннее хранение: все значения TIMESTAMPTZ нормализуются и хранятся в универсальном координированном времени (UTC).

• Сравнение и фильтрация: все операции фильтрации и сортировки выполняются в формате UTC, что обеспечивает согласованные и предсказуемые результаты в разных часовых поясах.

Основные операции

Основной рабочий процесс использования поля « TIMESTAMPTZ » аналогичен работе с другими скалярными полями в Milvus: определение поля → вставка данных → запрос/фильтрация.

Шаг 1: Определение поля TIMESTAMPTZ

Чтобы использовать поле ` TIMESTAMPTZ `, явно определите его в схеме коллекции при создании коллекции. В следующем примере показано, как создать коллекцию с полем ` tsz ` типа ` 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

Шаг 2: Вставка данных

Вставьте сущности, содержащие строки в формате ISO 8601 со смещениями часовых поясов.

В приведенном ниже примере в коллекцию вставляется 8 193 строки примерных данных. Каждая строка содержит:

• уникальный ID

• метку времени с учетом часового пояса (по шанхайскому времени)

• простой 4-мерный вектор

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

Шаг 3: Операции фильтрации

TIMESTAMPTZ поддерживает скалярные сравнения, арифметику интервалов и извлечение временных компонентов.

Прежде чем выполнять операции фильтрации над полями TIMESTAMPTZ, убедитесь, что:

• Вы создали индекс для каждого векторного поля.

• Коллекция загружена в память.

# 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

Запрос с фильтрацией по временным меткам

Используйте арифметические операторы, такие как ==, !=, <, >, <=, >=. Полный список арифметических операторов, доступных в Milvus, см. в разделе «Арифметические операторы».

В приведенном ниже примере выполняется фильтрация сущностей с метками времени (tsz), которые не равны 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

В приведенном выше примере

• tsz TIMESTAMPTZ — это имя поля, определённое в схеме.

• ISO '2025-01-03T00:00:00+08:00' — это литерал временной метки в формате ISO 8601, включая смещение часового пояса.

• != проводит сравнение значения поля с этим литералом. Другие поддерживаемые операторы включают ==, <, <=, > и >=.

Операции с интервалами

Вы можете выполнять арифметические операции над полями TIMESTAMPTZ, используя значения INTERVAL в формате продолжительности ISO 8601. Это позволяет при фильтрации данных складывать или вычитать из временной метки продолжительности, такие как дни, часы или минуты.

Например, следующий запрос фильтрует сущности, у которых временная метка (tsz) плюс ноль дней не равна 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

Поиск с фильтрацией по временным меткам

Вы можете сочетать фильтрацию по формату « TIMESTAMPTZ » с векторным поиском по схожести, чтобы сузить результаты как по времени, так и по степени схожести.

# 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

Расширенное использование

Для расширенного использования вы можете управлять часовыми поясами на разных уровнях (например, на уровне базы данных, коллекции или запроса) или ускорять запросы по полям « TIMESTAMPTZ » с помощью индексов.

Управление часовыми поясами на разных уровнях

Вы можете контролировать часовой пояс для полей TIMESTAMPTZ на уровне базы данных, коллекции или запроса/поиска.

Пошаговые инструкции и примеры кода см. на соответствующих страницах:

• Изменение коллекции

• База данных

• Запрос

• Базовый векторный поиск

• Гибридный поиск по нескольким векторам

Ускорение запросов

По умолчанию запросы по полям типа « TIMESTAMPTZ » без индекса выполняют полное сканирование всех строк, что может замедлять работу при работе с большими наборами данных. Чтобы ускорить запросы по временным меткам, создайте индекс типа « STL_SORT » для поля типа « TIMESTAMPTZ ».

Подробности см. в разделе STL_SORT.