Индексирование JSON

Поля JSON обеспечивают гибкий способ хранения структурированных метаданных в Milvus. Без индексации запросы к полям 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	Тип данных, который будет использоваться при интерпретации и индексировании значения. Должен совпадать с фактическим типом данных ключа. Список доступных типов приведения см. в разделе Поддерживаемые типы приведения ниже.	"VARCHAR"
json_cast_function	(Необязательно) Преобразование исходных значений ключа в целевой тип во время индексирования. Эта настройка требуется только в том случае, если значения ключей хранятся в неправильном формате и вы хотите преобразовать тип данных во время индексирования. Список доступных функций приведения приведен ниже в разделе Поддерживаемые функции приведения.	"STRING_TO_DOUBLE"

Поддерживаемые типы приведения

Milvus поддерживает следующие типы данных для приведения во время индексирования. Эти типы обеспечивают правильную интерпретацию данных для эффективной фильтрации.

Тип приведения	Описание	Пример JSON-значения
BOOL / bool	Используется для индексации булевых значений, позволяя выполнять запросы, фильтрующие по условиям "истина/ложь".	true, false
DOUBLE / double	Используется для числовых значений, включая целые числа и числа с плавающей точкой. Позволяет фильтровать по диапазонам или равенству (например, >, <, ==).	42, 99.99
VARCHAR / varchar	Используется для индексации строковых значений, что характерно для текстовых данных, таких как имена, категории или идентификаторы.	"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-объектов увеличивает размер индекса. Для сценариев с большим количеством ключей рассмотрите вариант измельчения JSON.	Любой объект JSON

Поддерживаемые функции приведения

Если ключ поля JSON содержит значения в неправильном формате (например, числа, хранящиеся в виде строк), вы можете передать функцию приведения в аргумент 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 cast, чтобы правильно преобразовать и проиндексировать их:

# 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 имеет несогласованные типы данных в разных сущностях?

Несогласованные типы могут привести к частичному индексированию. Например, если поле metadata["price"] хранится в виде числа (99.99) и строки ("99.99") и вы создаете индекс с json_cast_type="double", то будут проиндексированы только числовые значения. Записи в строковой форме будут пропущены и не появятся в результатах фильтрации.

Можно ли создать несколько индексов для одного и того же ключа JSON?

Нет, каждый JSON-ключ поддерживает только один индекс. Вы должны выбрать один json_cast_type, который соответствует вашим данным. Однако вы можете создать индекс для всего объекта JSON и индекс для вложенного ключа внутри этого объекта.

Поддерживает ли поле JSON установку значения по умолчанию?

Нет, поля JSON не поддерживают значения по умолчанию. Однако при определении поля можно задать значение nullable=True, чтобы разрешить пустые записи. Дополнительные сведения см. в разделе Nullable & Default.