JSON 索引

在 Milvus 中，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
    }
)

參數	說明	值/範例
field_name	收集模式中 JSON 欄位的名稱。	"metadata"
index_type	對於 JSON 索引，必須是"AUTOINDEX" 或"INVERTED" 。	"AUTOINDEX"
index_name	此索引的唯一識別碼。	"category_index"
json_path	您要在 JSON 物件中建立索引的關鍵路徑。	頂層鍵：'metadata["category"]' 巢狀鍵：'metadata["supplier"]["contact"]["email"]' 整個 JSON 物件："metadata" 子物件：'metadata["supplier"]'
json_cast_type	解釋和索引值時要使用的資料類型。必須與 key 的實際資料類型相符。 如需可用的轉換類型清單，請參閱 下面 支援的轉換類型。	"VARCHAR"
json_cast_function	(可選）在編制索引時，將原始關鍵值轉換為目標類型。只有當鍵值以錯誤的格式儲存，且您想要在索引期間轉換資料類型時，才需要此設定。 如需可用的轉換函數清單，請參閱下面的支援轉換函數。	"STRING_TO_DOUBLE"

支援的轉換類型

Milvus 支援下列資料類型在索引時轉換。這些類型可確保您的資料被正確詮釋，以進行有效的篩選。

轉換類型	說明	範例 JSON 值
BOOL /bool	用於索引布林值，使查詢可以篩選真/假條件。	true,false
DOUBLE /double	用於數值，包括整數和浮點數。它可以根據範圍或等值進行篩選（例如：>,<,== ）。	42,99.99
VARCHAR /varchar	用於索引字串值，常用於以文字為基礎的資料，例如名稱、類別或 ID。	"electronics","BrandA"
ARRAY_BOOL /array_bool	用於索引布林值陣列。	[true, false, true]
ARRAY_DOUBLE /array_double	用於索引數值陣列。	[1.2, 3.14, 42]
ARRAY_VARCHAR /array_varchar	用於索引字串陣列，非常適合標籤或關鍵字清單。	["tag1", "tag2", "tag3"]
JSON /json	整個 JSON 物件或子物件，具有自動類型推斷和扁平化功能。 索引整個 JSON 物件會增加索引大小。對於多 key 的情況，請考慮JSON Shredding。	任何 JSON 物件

支援的轉換函數

如果您的 JSON 欄位 key 包含格式不正確的值 (例如，以字串形式儲存的數字)，您可以傳送一個 cast 函數到json_cast_function 參數，以便在建立索引時轉換這些值。

轉換函數不區分大小寫。支援下列函數：

轉換函數	轉換自 → 轉換為	使用範例
STRING_TO_DOUBLE /string_to_double	字串 → 數字 (雙數)	轉換"99.99" 為99.99

建立 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"
    }
)

您也可以只索引 JSON 結構的一部分，例如所有supplier 資訊：

# 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 欄位查詢將會自動使用這些索引，以獲得更快的效能。

常見問題

如果查詢的篩選表達式使用的類型與索引的鑄模類型不同，會發生什麼情況？

如果您的篩選表達式使用的類型與索引的json_cast_type 不同，Milvus 將不會使用索引，如果資料允許的話，可能會退回到較慢的強制掃描。為了獲得最佳效能，請務必使您的篩選表達式與索引的類型一致。例如，如果使用json_cast_type="double" 建立數值索引，則只有數值篩選條件會使用該索引。

在建立 JSON 索引時，如果不同實體的 JSON key 具有不一致的資料類型，該怎麼辦？

不一致的類型可能會導致部分索引。例如，如果metadata["price"] 欄位同時以數字 (99.99) 和字串 ("99.99") 儲存，而您以json_cast_type="double" 建立索引，則只有數字值會被索引。字串形式的項目將會被跳過，並且不會出現在篩選結果中。

我可以在同一個 JSON key 上建立多個索引嗎？

不可以，每個 JSON key 只支援一個索引。您必須選擇符合您資料的單一json_cast_type 。但是，您可以在整個 JSON 物件上建立索引，也可以在該物件中的巢狀關鍵上建立索引。

JSON 欄位是否支援設定預設值？

不，JSON 欄位不支援預設值。但是，您可以在定義欄位時設定nullable=True ，以允許空項目。如需詳細資訊，請參閱Nullable & Default。