Insertar datos en campos StructArray

Inserta datos en un campo StructArray cuando cada entidad contenga una lista ordenada de elementos estructurados. En la carga útil de inserción, un campo StructArray se representa como una matriz de objetos. Cada objeto representa un elemento Struct y utiliza los nombres de los subcampos Struct definidos en el esquema de la colección.

Esta página utiliza la colección « tech_articles » de «Crear un campo StructArray». Cada entidad es un artículo técnico, y el campo « chunks » almacena fragmentos del artículo como elementos Struct.

Antes de empezar

Asegúrate de que el esquema de la colección ya contiene el campo StructArray « chunks ».

Campo	Tipo	Valor de inserción
doc_id	INT64	ID del artículo.
title	VARCHAR	Título del artículo.
category	VARCHAR	Categoría del artículo.
title_vector	FLOAT_VECTOR	Incrustación a nivel de artículo.
chunks	ARRAY	Una lista de objetos «chunk».

Cada objeto de « chunks » debe seguir el esquema «Struct».

Subcampo	Tipo	Valor de inserción
text	VARCHAR	Texto del fragmento.
section	VARCHAR	Nombre de la sección, como « index », « search » o « filter ».
page	INT64	Número de página o posición lógica.
quality_score	FLOAT	Puntuación a nivel de fragmento.
has_code	BOOL	Si el fragmento contiene código.
emb_list_vector	FLOAT_VECTOR	Vector escrito para la búsqueda en EmbeddingList.
emb	FLOAT_VECTOR	Vector escrito para la búsqueda a nivel de elemento.

Comprender la estructura de la carga útil de inserción

El valor de ` chunks ` es una matriz de elementos `Struct`. Cada elemento es un objeto cuyas claves son nombres de subcampos.

{
  "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 y emb son subcampos vectoriales independientes, ya que admiten modos de búsqueda diferentes. La búsqueda de EmbeddingList trata todos los vectores de un campo StructArray como una única lista de incrustaciones y devuelve resultados a nivel de entidad con métricas de MAX_SIM*. La búsqueda a nivel de elemento busca cada elemento Struct de forma independiente y puede devolver el desplazamiento del elemento coincidente. En este ejemplo, para simplificar, se almacenan los mismos valores vectoriales en ambos campos. En una aplicación de producción, se pueden almacenar las mismas representaciones en ambos subcampos cuando ambos modos de búsqueda utilizan la misma representación de fragmentos, o bien almacenar representaciones diferentes cuando los dos modos de búsqueda utilizan representaciones distintas.

Insertar filas

Utiliza « client.insert() » para insertar filas que contengan valores de 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)

Insertar en campos StructArray nulos

Si el campo ` chunks ` es nulo, una entidad puede establecer todo el campo ` chunks ` en nulo. En Python, utilice ` None ` para representar un valor nulo.

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,
        }
    ],
)

Cuando un campo StructArray nulo contiene un valor StructArray válido, todos los subcampos de ese valor deben ser nulos o tener valores válidos. Insertar una entidad con algunos subcampos establecidos en nulo y otros en valores válidos da lugar a un error.

Validar los datos insertados

Puede consultar la colección y obtener el campo StructArray o los subcampos seleccionados.

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)

Utilice rutas de campos StructArray, como chunks[text], únicamente al consultar, buscar, filtrar o crear índices. Las cargas útiles de inserción deben seguir utilizando objetos anidados bajo chunks.

Reglas de inserción

Regla	Explicación
Utilice una matriz de objetos para un campo StructArray.	El valor de chunks es una lista, y cada elemento de la lista es un elemento Struct.
Utiliza nombres de subcampos dentro de cada elemento Struct.	Inserta « {"text": "...", "emb": [...]} » dentro de « chunks », no en « {"chunks[text]": "..."} ».
Cumpla con el esquema de Struct.	Cada elemento de Struct debe utilizar los subcampos definidos en el esquema de Struct.
Las dimensiones de los vectores deben coincidir.	Los valores de los vectores deben coincidir con los « dim » configurados para sus subcampos vectoriales.
Respetar el « max_capacity ».	El número de elementos Struct en una entidad no debe superar el número de elementos max_capacity del campo StructArray.
Utilice subcampos vectoriales independientes para los distintos modos de búsqueda.	Si se requieren tanto la búsqueda en EmbeddingList como la búsqueda a nivel de elemento, escriba los valores vectoriales en ambos subcampos vectoriales.
Utilice « null » solo cuando el campo sea nulo.	Los campos StructArray no nulos requieren valores StructArray válidos.

Errores comunes

• Utilizar rutas de campo como « chunks[text] » en las cargas útiles de inserción.

• Omitir subcampos obligatorios de un elemento Struct.

• Insertar vectores con una dimensión incorrecta.

• Insertar más elementos Struct de los que permite max_capacity.

• Establecer solo un subcampo como « null », mientras que otros subcampos del mismo valor de StructArray son válidos.

• Escribir vectores únicamente en ` emb_list_vector ` y, a continuación, intentar ejecutar una búsqueda a nivel de elemento en ` chunks[emb]`.

• Escribir vectores únicamente en « emb » y, a continuación, intentar realizar una búsqueda en «EmbeddingList» en « chunks[emb_list_vector] ».

Próximos pasos

1. Para crear índices para los subcampos « chunks[emb_list_vector] », « chunks[emb] » y los subcampos escalares, consulta «Indexar campos de StructArray».

2. Para realizar búsquedas en subcampos vectoriales de StructArray, consulte «Búsqueda vectorial básica con StructArray».

3. Para revisar el comportamiento de los valores nulos y las limitaciones específicas de cada versión, consulta «Límites de StructArray».