JSON 인덱싱
JSON 필드는 Milvus에 구조화된 메타데이터를 저장하는 유연한 방법을 제공합니다. 인덱싱이 없으면 JSON 필드에 대한 쿼리는 전체 컬렉션 스캔이 필요하며, 데이터 세트가 증가함에 따라 속도가 느려집니다. JSON 인덱싱은 JSON 데이터 내에 인덱스를 생성하여 빠른 조회를 가능하게 합니다.
JSON 인덱싱은 다음과 같은 경우에 이상적입니다:
일관되고 알려진 키가 있는 구조화된 스키마
특정 JSON 경로에 대한 같음 및 범위 쿼리
색인되는 키를 정밀하게 제어해야 하는 시나리오
타깃 쿼리의 스토리지 효율적인 가속화
다양한 쿼리 패턴을 가진 복잡한 JSON 문서의 경우, JSON 파쇄를 대안으로 고려하세요.
JSON 색인 구문
JSON 인덱스를 생성할 때 다음을 지정합니다:
JSON 경로: 색인하려는 데이터의 정확한 위치
데이터 캐스트 유형: 인덱싱된 값을 해석하고 저장하는 방법
선택적 유형 변환: 필요한 경우 색인하는 동안 데이터 변환
다음은 JSON 필드를 색인하는 구문입니다:
# Prepare index params
index_params = MilvusClient.prepare_index_params()
index_params.add_index(
field_name="<json_field_name>", # Name of the JSON field
index_type="AUTOINDEX", # Must be AUTOINDEX or INVERTED
index_name="<unique_index_name>", # Index name
params={
"json_path": "<path_to_json_key>", # Specific key to be indexed within JSON data
"json_cast_type": "<data_type>", # Data type to use when interpreting and indexing the value
# "json_cast_function": "<cast_function>" # Optional: convert key values into a target type at index time
}
)
매개변수 |
설명 |
값/예시 |
|---|---|---|
|
컬렉션 스키마에 있는 JSON 필드의 이름입니다. |
|
|
JSON 인덱싱의 경우 |
|
|
이 인덱스의 고유 식별자입니다. |
|
|
JSON 객체 내에서 색인하려는 키의 경로입니다. |
|
|
값을 해석하고 색인할 때 사용할 데이터 유형입니다. 키의 실제 데이터 유형과 일치해야 합니다. 사용 가능한 형 변환 유형 목록은 아래에서 지원되는 형 변환 유형을 참조하세요. |
|
|
(선택 사항) 색인 시점에 원본 키 값을 대상 유형으로 변환합니다. 이 구성은 키 값이 잘못된 형식으로 저장되어 있고 인덱싱 중에 데이터 유형을 변환하려는 경우에만 필요합니다. 사용 가능한 형 변환 함수 목록은 아래의 지원되는 형 변환 함수를 참조하세요. |
|
지원되는 형 변환 유형
Milvus는 인덱싱 시 형 변환을 위해 다음과 같은 데이터 유형을 지원합니다. 이러한 유형은 효율적인 필터링을 위해 데이터가 올바르게 해석되도록 보장합니다.
형 변환 유형 |
설명 |
예제 JSON 값 |
|---|---|---|
|
부울 값을 인덱싱하는 데 사용되며, 참/거짓 조건에 따라 필터링하는 쿼리를 가능하게 합니다. |
|
|
정수 및 부동 소수점 숫자를 포함한 숫자 값에 사용됩니다. 범위 또는 같음을 기준으로 필터링할 수 있습니다(예: |
|
|
이름, 카테고리 또는 ID와 같은 텍스트 기반 데이터에 일반적으로 사용되는 문자열 값을 색인하는 데 사용됩니다. |
|
|
부울 값 배열을 인덱싱하는 데 사용됩니다. |
|
|
숫자 값 배열을 인덱싱하는 데 사용됩니다. |
|
|
태그나 키워드 목록에 이상적인 문자열 배열을 색인하는 데 사용됩니다. |
|
|
자동 유형 추론 및 플랫화 기능을 갖춘 전체 JSON 객체 또는 하위 객체. 전체 JSON 개체를 색인하면 색인 크기가 증가합니다. 키가 많은 시나리오의 경우, JSON 파쇄를 고려하세요. |
모든 JSON 객체 |
배열은 최적의 인덱싱을 위해 동일한 유형의 요소를 포함해야 합니다. 자세한 내용은 배열 필드를 참조하세요.
지원되는 형 변환 함수
JSON 필드 키에 잘못된 형식의 값(예: 문자열로 저장된 숫자)이 포함된 경우 json_cast_function 인수에 형 변환 함수를 전달하여 색인 시점에 이러한 값을 변환할 수 있습니다.
형 변환 함수는 대소문자를 구분하지 않습니다. 지원되는 함수는 다음과 같습니다:
형 변환 함수 |
에서 → 으로 변환 |
사용 사례 |
|---|---|---|
|
문자열 → 숫자(더블) |
|
변환에 실패하면(예: 숫자가 아닌 문자열) 해당 값은 건너뛰고 인덱싱되지 않습니다.
JSON 인덱스 만들기
이 섹션에서는 실제 예제를 사용하여 다양한 유형의 JSON 데이터에 대한 인덱스를 만드는 방법을 설명합니다. 모든 예제에서는 아래에 표시된 샘플 JSON 구조를 사용하며, 적절하게 정의된 컬렉션 스키마로 MilvusClient에 이미 연결이 설정되어 있다고 가정합니다.
샘플 JSON 구조
{
"metadata": {
"category": "electronics",
"brand": "BrandA",
"in_stock": true,
"price": 99.99,
"string_price": "99.99",
"tags": ["clearance", "summer_sale"],
"supplier": {
"name": "SupplierX",
"country": "USA",
"contact": {
"email": "support@supplierx.com",
"phone": "+1-800-555-0199"
}
}
}
}
기본 설정
JSON 인덱스를 생성하기 전에 인덱스 매개변수를 준비하세요:
# Prepare index params
index_params = MilvusClient.prepare_index_params()
예 1: 간단한 JSON 키 인덱싱하기
category 필드에 인덱스를 생성하여 제품 카테고리별로 빠르게 필터링할 수 있도록 합니다:
index_params.add_index(
field_name="metadata",
index_type="AUTOINDEX", # Must be set to AUTOINDEX or INVERTED for JSON path indexing
index_name="category_index", # Unique index name
params={
"json_path": 'metadata["category"]', # Path to the JSON key
"json_cast_type": "varchar" # Data cast type
}
)
예 2: 중첩된 키 색인 생성
공급업체 연락처 검색을 위해 깊게 중첩된 email 필드에 색인을 생성합니다:
# Index the nested key
index_params.add_index(
field_name="metadata",
index_type="AUTOINDEX", # Must be set to AUTOINDEX or INVERTED for JSON path indexing
index_name="email_index", # Unique index name
params={
"json_path": 'metadata["supplier"]["contact"]["email"]', # Path to the nested JSON key
"json_cast_type": "varchar" # Data cast type
}
)
예 3: 색인 시 데이터 유형 변환하기
숫자 데이터가 실수로 문자열로 저장되는 경우가 있습니다. STRING_TO_DOUBLE 캐스트 함수를 사용하여 올바르게 변환하고 색인을 생성하세요:
# Convert string numbers to double for indexing
index_params.add_index(
field_name="metadata",
index_type="AUTOINDEX", # Must be set to AUTOINDEX or INVERTED for JSON path indexing
index_name="string_to_double_index", # Unique index name
params={
"json_path": 'metadata["string_price"]', # Path to the JSON key to be indexed
"json_cast_type": "double", # Data cast type
"json_cast_function": "STRING_TO_DOUBLE" # Cast function; case insensitive
}
)
중요: 어떤 문서(예: "invalid" 과 같은 숫자가 아닌 문자열)에 대해 변환에 실패하면 해당 문서의 값은 색인에서 제외되고 필터링된 결과에 표시되지 않습니다.
예 4: 전체 개체 색인하기
전체 JSON 객체를 색인하여 그 안의 모든 필드에 대한 쿼리를 활성화합니다. json_cast_type="JSON" 을 사용하면 시스템이 자동으로 색인을 생성합니다:
JSON 구조를 플랫화합니다: 효율적인 인덱싱을 위해 중첩된 개체가 플랫 경로로 변환됩니다.
데이터 유형을 추론합니다: 각 값은 콘텐츠에 따라 숫자, 문자열, 부울, 날짜로 자동 분류됩니다.
포괄적인 범위를 생성합니다: 개체 내의 모든 키와 중첩된 경로를 검색할 수 있습니다.
위의 샘플 JSON 구조의 경우, metadata 객체 전체를 색인합니다:
# Index the entire JSON object
index_params.add_index(
field_name="metadata",
index_type="AUTOINDEX",
index_name="metadata_full_index",
params={
"json_path": "metadata",
"json_cast_type": "JSON"
}
)
모든 supplier 정보와 같이 JSON 구조의 일부만 색인할 수도 있습니다:
# Index a sub-object
index_params.add_index(
field_name="metadata",
index_type="AUTOINDEX",
index_name="supplier_index",
params={
"json_path": 'metadata["supplier"]',
"json_cast_type": "JSON"
}
)
인덱스 구성 적용
모든 인덱스 매개변수를 정의한 후 컬렉션에 적용합니다:
# Apply all index configurations to the collection
MilvusClient.create_index(
collection_name="your_collection_name",
index_params=index_params
)
인덱싱이 완료되면 JSON 필드 쿼리가 자동으로 이 인덱스를 사용하므로 성능이 더욱 빨라집니다.
FAQ
쿼리의 필터 표현식이 인덱싱된 캐스트 유형과 다른 유형을 사용하면 어떻게 되나요?
필터 표현식이 인덱스의 json_cast_type 와 다른 유형을 사용하는 경우 Milvus는 인덱스를 사용하지 않으며 데이터가 허용하는 경우 느린 무차별 대입 검색으로 돌아갈 수 있습니다. 최상의 성능을 위해 항상 필터 표현식을 인덱스의 형 변환 유형에 맞춰 정렬하세요. 예를 들어 json_cast_type="double" 로 숫자 인덱스를 만들면 숫자 필터 조건만 인덱스를 활용하게 됩니다.
JSON 인덱스를 만들 때 JSON 키의 데이터 유형이 여러 엔티티에 걸쳐 일관되지 않으면 어떻게 해야 하나요?
일관되지 않은 유형은 부분 인덱싱으로 이어질 수 있습니다. 예를 들어 metadata["price"] 필드가 숫자(99.99)와 문자열("99.99")로 저장되어 있는데 json_cast_type="double" 으로 인덱스를 생성하면 숫자 값만 색인됩니다. 문자열 형식의 항목은 건너뛰고 필터 결과에 표시되지 않습니다.
동일한 JSON 키에 여러 개의 인덱스를 만들 수 있나요?
아니요, 각 JSON 키는 하나의 인덱스만 지원합니다. 데이터와 일치하는 하나의 json_cast_type 를 선택해야 합니다. 그러나 전체 JSON 객체에 대한 인덱스와 해당 객체 내의 중첩된 키에 대한 인덱스를 만들 수는 있습니다.
JSON 필드에서 기본값 설정을 지원하나요?
아니요, JSON 필드는 기본값을 지원하지 않습니다. 그러나 필드를 정의할 때 nullable=True 을 설정하여 빈 항목을 허용할 수 있습니다. 자세한 내용은 Null 가능 및 기본값을 참조하세요.