TIMESTAMPTZ 필드Compatible with Milvus 2.6.6+

전자상거래 시스템, 협업 도구 또는 분산 로깅과 같이 여러 지역에 걸쳐 시간을 추적하는 애플리케이션은 시간대를 고려한 타임스탬프를 정밀하게 처리해야 합니다. Milvus의 TIMESTAMPTZ 데이터 유형은 타임스탬프를 해당 시간대와 함께 저장함으로써 이러한 기능을 제공합니다.

TIMESTAMPTZ 필드란 무엇인가요?

TIMESTAMPTZ 필드는 Milvus의 스키마 정의 데이터 유형(DataType.TIMESTAMPTZ)으로, 시간대를 고려한 입력을 처리하고 모든 시간 지점을 내부적으로 UTC 절대 시간으로 저장합니다.

• 허용되는 입력 형식: 시간대 오프셋이 포함된 ISO 8601 문자열(예: "2025-05-01T23:59:59+08:00" 는 2025년 5월 1일 오후 11시 59분 59초(UTC+08:00)를 나타냅니다).

• 내부 저장: 모든 TIMESTAMPTZ 값은 정규화되어 협정 세계시 (UTC)로 저장됩니다.

• 비교 및 필터링: 모든 필터링 및 정렬 작업은 UTC 기준으로 수행되므로, 서로 다른 시간대에서도 일관되고 예측 가능한 결과를 보장합니다.

기본 작업

TIMESTAMPTZ 필드를 사용하는 기본 워크플로는 Milvus의 다른 스칼라 필드와 동일합니다. 필드 정의 → 데이터 삽입 → 쿼리/필터링.

1단계: TIMESTAMPTZ 필드 정의

TIMESTAMPTZ 필드를 사용하려면 컬렉션을 생성할 때 컬렉션 스키마에 해당 필드를 명시적으로 정의해야 합니다. 다음 예제는 ` DataType.TIMESTAMPTZ` 유형의 ` tsz ` 필드가 포함된 컬렉션을 생성하는 방법을 보여줍니다.

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 형식의 타임스탬프 리터럴입니다.

• != 는 필드 값을 해당 리터럴과 비교합니다. 지원되는 다른 연산자로는 ==, <, <=, > 및 >= 가 있습니다.

간격 연산

ISO 8601 기간 형식의 INTERVAL 값을 사용하여 TIMESTAMPTZ 필드에 대한 산술 연산을 수행할 수 있습니다. 이를 통해 데이터를 필터링할 때 타임스탬프에서 일, 시간 또는 분과 같은 기간을 더하거나 뺄 수 있습니다.

예를 들어, 다음 쿼리는 타임스탬프(tsz)에 0일을 더한 값이 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 ` 필드에 대한 쿼리는 모든 행을 전체 스캔하므로, 대규모 데이터 세트에서는 처리 속도가 느려질 수 있습니다. 타임스탬프 쿼리 속도를 높이려면 ` TIMESTAMPTZ ` 필드에 ` STL_SORT ` 인덱스를 생성하십시오.

자세한 내용은 STL_SORT를 참조하십시오.