타임스탬프 필드Compatible with Milvus 2.6.6+

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

타임스탬프 필드란 무엇인가요?

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

• 허용되는 입력 형식입니다: 표준 시간대 오프셋이 있는 ISO 8601 문자열(예: "2025-05-01T23:59:59+08:00" 은 UTC+08:00 기준 11:59:59 PM을 나타냄).

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

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

기본 작업

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

1단계: 타임스탬프 필드 정의하기

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를 참조하세요.