Вставка данных в поля StructArray

Вставьте данные в поле StructArray, если каждая сущность содержит упорядоченный список структурированных элементов. В полезной нагрузке вставки поле StructArray представлено в виде массива объектов. Каждый объект представляет один элемент Struct и использует имена подполей Struct, определенные в схеме коллекции.

На этой странице используется коллекция « tech_articles » из раздела «Создание поля StructArray». Каждая сущность представляет собой техническую статью, а поле « chunks » хранит фрагменты статьи в виде элементов Struct.

Перед началом

Убедитесь, что схема коллекции уже содержит поле StructArray « chunks ».

Поле	Тип	Значение при вставке
doc_id	INT64	Идентификатор статьи.
title	VARCHAR	Название статьи.
category	VARCHAR	Категория статьи.
title_vector	FLOAT_VECTOR	Встраивание на уровне статьи.
chunks	ARRAY	Список объектов фрагментов.

Каждый объект в « chunks » должен соответствовать схеме Struct.

Поле	Тип	Значение
text	VARCHAR	Текст фрагмента.
section	VARCHAR	Название раздела, например index, search или filter.
page	INT64	Номер страницы или логическое положение.
quality_score	FLOAT	Оценка на уровне фрагмента.
has_code	BOOL	Содержит ли фрагмент код.
emb_list_vector	FLOAT_VECTOR	Вектор, написанный для поиска по EmbeddingList.
emb	FLOAT_VECTOR	Вектор, записанный для поиска на уровне элементов.

Понимание структуры данных вставки

Значение chunks представляет собой массив элементов Struct. Каждый элемент — это объект, ключи которого являются именами подполей.

{
  "doc_id": 1,
  "title": "StructArray indexing patterns",
  "category": "index",
  "title_vector": [0.12, 0.08, 0.32, 0.48],
  "chunks": [
    {
      "text": "Create one index for each vector subfield.",
      "section": "index",
      "page": 1,
      "quality_score": 0.96,
      "has_code": false,
      "emb_list_vector": [0.10, 0.20, 0.30, 0.40],
      "emb": [0.10, 0.20, 0.30, 0.40]
    },
    {
      "text": "Use MAX_SIM metrics for EmbeddingList search.",
      "section": "index",
      "page": 2,
      "quality_score": 0.91,
      "has_code": true,
      "emb_list_vector": [0.16, 0.24, 0.35, 0.45],
      "emb": [0.16, 0.24, 0.35, 0.45]
    }
  ]
}

emb_list_vector и emb являются отдельными подполями векторного типа, поскольку поддерживают разные режимы поиска. Поиск по EmbeddingList рассматривает все векторы в поле StructArray как один список вложений и возвращает результаты на уровне сущностей с метриками MAX_SIM*. Поиск на уровне элементов выполняет поиск по каждому элементу Struct независимо и может возвращать смещение найденного элемента. В данном примере для простоты в обоих полях хранятся одинаковые векторные значения. В производственном приложении можно хранить одинаковые вложения в обоих подполях, если оба режима поиска используют одно и то же вложение блоков, или хранить разные вложения, если эти два режима поиска используют разные представления.

Вставка строк

Используйте оператор ` client.insert() ` для вставки строк, содержащих значения StructArray.

from pymilvus import MilvusClient

client = MilvusClient(
    uri="http://localhost:19530",
    token="root:Milvus",
)

data = [
    {
        "doc_id": 1,
        "title": "StructArray indexing patterns",
        "category": "index",
        "title_vector": [0.12, 0.08, 0.32, 0.48],
        "chunks": [
            {
                "text": "Create one index for each vector subfield.",
                "section": "index",
                "page": 1,
                "quality_score": 0.96,
                "has_code": False,
                "emb_list_vector": [0.10, 0.20, 0.30, 0.40],
                "emb": [0.10, 0.20, 0.30, 0.40],
            },
            {
                "text": "Use MAX_SIM metrics for EmbeddingList search.",
                "section": "index",
                "page": 2,
                "quality_score": 0.91,
                "has_code": True,
                "emb_list_vector": [0.16, 0.24, 0.35, 0.45],
                "emb": [0.16, 0.24, 0.35, 0.45],
            },
        ],
    },
    {
        "doc_id": 2,
        "title": "Filtered StructArray search",
        "category": "filter",
        "title_vector": [0.20, 0.18, 0.22, 0.40],
        "chunks": [
            {
                "text": "Use element_filter to match scalar conditions within the same Struct element.",
                "section": "filter",
                "page": 1,
                "quality_score": 0.93,
                "has_code": True,
                "emb_list_vector": [0.21, 0.18, 0.33, 0.44],
                "emb": [0.21, 0.18, 0.33, 0.44],
            },
            {
                "text": "MATCH_LEAST checks how many elements satisfy a predicate.",
                "section": "filter",
                "page": 2,
                "quality_score": 0.88,
                "has_code": False,
                "emb_list_vector": [0.24, 0.22, 0.31, 0.39],
                "emb": [0.24, 0.22, 0.31, 0.39],
            },
        ],
    },
    {
        "doc_id": 3,
        "title": "Element-level search with offsets",
        "category": "search",
        "title_vector": [0.33, 0.11, 0.29, 0.37],
        "chunks": [
            {
                "text": "Element-level search can return the offset of the matched Struct element.",
                "section": "search",
                "page": 1,
                "quality_score": 0.95,
                "has_code": False,
                "emb_list_vector": [0.32, 0.14, 0.28, 0.41],
                "emb": [0.32, 0.14, 0.28, 0.41],
            }
        ],
    },
]

result = client.insert(
    collection_name="tech_articles",
    data=data,
)

print(result)

Вставка в поля StructArray, допускающие значение null

Если поле ` chunks ` допускает значение `null`, сущность может установить для всего поля ` chunks ` значение `null`. В Python для представления нулевого значения используйте ` None `.

client.insert(
    collection_name="tech_articles",
    data=[
        {
            "doc_id": 10,
            "title": "Article without chunks yet",
            "category": "draft",
            "title_vector": [0.05, 0.10, 0.15, 0.20],
            "chunks": None,
        }
    ],
)

Если поле StructArray, допускающее значение null, содержит допустимое значение StructArray, все подполя в этом значении должны либо быть равны null, либо иметь допустимые значения. Вставка сущности, в которой некоторые подполя установлены в null, а другие — в допустимые значения, приводит к ошибке.

Проверка вставленных данных

Вы можете выполнить запрос к коллекции и получить поле StructArray или выбранные подполя.

rows = client.query(
    collection_name="tech_articles",
    filter="doc_id in [1, 2, 3]",
    output_fields=[
        "doc_id",
        "title",
        "chunks[text]",
        "chunks[section]",
        "chunks[quality_score]",
    ],
)

for row in rows:
    print(row)

Используйте пути к полям StructArray, например chunks[text], только при запросах, поиске, фильтрации или создании индексов. В данных для вставки по-прежнему следует использовать вложенные объекты в формате chunks.

Правила вставки

Правило	Объяснение
Используйте массив объектов для поля StructArray.	Значение chunks представляет собой список, и каждый элемент в этом списке является элементом Struct.
Используйте имена подполей внутри каждого элемента Struct.	Вставьте ` {"text": "...", "emb": [...]} ` внутрь ` chunks`, а не ` {"chunks[text]": "..."}`.
Соблюдайте схему Struct.	Каждый элемент Struct должен использовать подполя, определенные в схеме Struct.
Размеры векторов должны совпадать.	Значения векторов должны соответствовать параметрам « dim », настроенным для их подполей вектора.
Соблюдайте ограничения на размеры ( max_capacity).	Количество элементов Struct в одной сущности не должно превышать значение параметра « max_capacity » поля StructArray.
Используйте отдельные подполя вектора для отдельных режимов поиска.	Если требуется как поиск по EmbeddingList, так и поиск на уровне элементов, записывайте значения вектора в оба подполя вектора.
Используйте null только в том случае, если поле допускает нулевые значения.	Поля StructArray, не допускающие нулевых значений, требуют действительных значений StructArray.

Распространенные ошибки

• Использование путей к полям, таких как chunks[text], в данных вставки.

• Пропуск обязательных подполей в элементе Struct.

• Вставка векторов с неправильным размером.

• Вставка большего количества элементов Struct, чем допускает max_capacity.

• Установка значения null только для одного подполя, в то время как другие подполя в том же значении StructArray являются допустимыми.

• Запись векторов только в emb_list_vector, а затем попытка запустить поиск на уровне элементов в chunks[emb].

• Запись векторов только в поле « emb », а затем попытка выполнить поиск по EmbeddingList в поле « chunks[emb_list_vector] ».

Следующие шаги

1. Чтобы создать индексы для полей chunks[emb_list_vector], chunks[emb] и скалярных подполей, ознакомьтесь с разделом «Индексирование полей StructArray».

2. Чтобы выполнить поиск по векторным подполям StructArray, ознакомьтесь с разделом «Базовый поиск по векторам с помощью StructArray».

3. Чтобы ознакомиться с поведением при наличии значений null и ограничениями, связанными с конкретными версиями, ознакомьтесь с разделом «Ограничения StructArray».