Crear un campo StructArray

Crea un campo StructArray cuando una entidad deba contener una lista ordenada de elementos estructurados. Un campo StructArray es un campo Array cuyo tipo de elemento es Struct. Cada elemento Struct sigue el mismo esquema y puede contener subcampos escalares, subcampos vectoriales o ambos.

En esta página se explica cómo definir un esquema Struct, añadirlo como campo StructArray, seleccionar subcampos para su posterior búsqueda y filtrado, y comprender las reglas del esquema que se aplican antes de insertar o indexar datos.

Antes de empezar

Esta página utiliza una colección denominada « tech_articles ». Cada entidad representa un artículo técnico, y el campo « chunks » almacena datos a nivel de fragmento como elementos Struct.

Campo	Tipo	Finalidad
doc_id	INT64	Clave primaria del artículo.
title	VARCHAR	Título del artículo.
category	VARCHAR	Categoría a nivel de artículo.
title_vector	FLOAT_VECTOR	Campo vectorial a nivel de artículo, que se utilizará más adelante en los ejemplos de búsqueda híbrida.
chunks	ARRAY	Campo StructArray que almacena texto a nivel de fragmento, metadatos e incrustaciones.

El campo StructArray « chunks » contiene los siguientes subcampos.

Subcampo	Tipo	Finalidad
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 del fragmento.
quality_score	FLOAT	Puntuación a nivel de fragmento utilizada en el filtrado escalar y en los ejemplos de rango.
has_code	BOOL	Si el fragmento contiene código.
emb_list_vector	FLOAT_VECTOR	Subcampo vectorial para la búsqueda en EmbeddingList con métricas de « MAX_SIM* ».
emb	FLOAT_VECTOR	Subcampo vectorial para la búsqueda a nivel de elemento con métricas vectoriales habituales.

Tipos de datos admitidos para los subcampos

Un campo StructArray almacena un valor de matriz para cada subcampo Struct. Al definir un esquema Struct, elija los tipos de subcampo de entre las familias escalares y vectoriales compatibles.

Tipo físico de subcampo Struct	Compatibilidad	Notas
Array	Compatible	Defina el subcampo como « DataType.BOOL ».
Array	Compatible	Defina el subcampo como « DataType.INT8 », « DataType.INT16 », « DataType.INT32 » o « DataType.INT64 ».
Array	Compatible	Defina el subcampo como DataType.FLOAT o DataType.DOUBLE.
Array	Compatible	Defina el subcampo como « DataType.VARCHAR » y establezca « max_length ».
ArrayOfVector	Compatible	Defina el subcampo como « DataType.FLOAT_VECTOR » y establezca « dim ».
ArrayOfVector	Compatible	Defina el subcampo como « DataType.FLOAT16_VECTOR » y establezca « dim ».
ArrayOfVector	Compatible	Defina el subcampo como « DataType.BFLOAT16_VECTOR » y establezca « dim ».
ArrayOfVector	Compatible	Defina el subcampo como « DataType.INT8_VECTOR » y establezca « dim ».
ArrayOfVector	Compatible	Defina el subcampo como « DataType.BINARY_VECTOR » y establezca « dim ».
ArrayOfVector	No compatible	Los subcampos de vectores dispersos no son compatibles con los campos StructArray.
Array	No compatible	Utilice « VARCHAR », no « String ».
Array	No compatible	Los subcampos JSON no son compatibles con los campos StructArray.
Array	No compatible	Los subcampos de geometría y las funciones SIG no son compatibles con los campos StructArray.
Array	No compatible	Los subcampos de texto no son compatibles con los campos StructArray.
Array	No compatible	Los subcampos «timestamptz» y las expresiones específicas de tiempo no son compatibles con los campos StructArray.
Array, ArrayOfVector, Struct o ArrayOfStruct	No compatible	Un campo StructArray no puede contener matrices anidadas, matrices vectoriales anidadas, campos Struct anidados ni campos Array-of-Struct anidados.

Para obtener información sobre la compatibilidad específica de cada versión, el comportamiento de los valores nulos y otras restricciones, consulta Restricciones de StructArray.

Crear una colección con un campo StructArray

Para crear un campo StructArray, defina primero el esquema Struct utilizado por cada elemento. A continuación, añada un campo Array y establezca su tipo de elemento en Struct.

1. Crea el esquema de la colección.

2. Añade campos a nivel de colección, como la clave principal y los campos a nivel de artículo.

3. Crea un esquema Struct para los elementos almacenados dentro del campo StructArray.

4. Añade subcampos escalares y vectoriales al esquema Struct.

5. Añade un campo «Array» con « element_type=DataType.STRUCT ».

6. Establece ` struct_schema ` en el esquema `Struct`.

7. Establece « max_capacity » para limitar el número de elementos «Struct» que cada entidad puede almacenar en el campo.

from pymilvus import MilvusClient, DataType

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

schema = client.create_schema(
    auto_id=False,
    enable_dynamic_field=False,
)

# Collection-level fields.
schema.add_field(
    field_name="doc_id",
    datatype=DataType.INT64,
    is_primary=True,
)
schema.add_field(
    field_name="title",
    datatype=DataType.VARCHAR,
    max_length=512,
)
schema.add_field(
    field_name="category",
    datatype=DataType.VARCHAR,
    max_length=128,
)
schema.add_field(
    field_name="title_vector",
    datatype=DataType.FLOAT_VECTOR,
    dim=4,
)

# Struct schema used by each element in the StructArray field.
chunk_schema = client.create_struct_field_schema()
chunk_schema.add_field(
    field_name="text",
    datatype=DataType.VARCHAR,
    max_length=65535,
)
chunk_schema.add_field(
    field_name="section",
    datatype=DataType.VARCHAR,
    max_length=128,
)
chunk_schema.add_field(
    field_name="page",
    datatype=DataType.INT64,
)
chunk_schema.add_field(
    field_name="quality_score",
    datatype=DataType.FLOAT,
)
chunk_schema.add_field(
    field_name="has_code",
    datatype=DataType.BOOL,
)

# Vector subfield for EmbeddingList search.
chunk_schema.add_field(
    field_name="emb_list_vector",
    datatype=DataType.FLOAT_VECTOR,
    dim=4,
)

# Vector subfield for element-level search.
chunk_schema.add_field(
    field_name="emb",
    datatype=DataType.FLOAT_VECTOR,
    dim=4,
)

# Add the StructArray field.
schema.add_field(
    field_name="chunks",
    datatype=DataType.ARRAY,
    element_type=DataType.STRUCT,
    struct_schema=chunk_schema,
    max_capacity=1000,
)

client.create_collection(
    collection_name="tech_articles",
    schema=schema,
)

Comprender las rutas de los campos StructArray

Una vez creado un campo StructArray, haz referencia a sus subcampos utilizando la sintaxis de ruta « structArray[subfield] ». Utiliza esta sintaxis al crear índices, buscar en subcampos vectoriales, generar subcampos de salida o crear filtros escalares.

Ruta	Significado	Uso habitual
chunks[text]	El subcampo « text » dentro de cada elemento Struct.	Campo de salida o filtrado escalar.
chunks[section]	La etiqueta de sección de cada fragmento.	Filtrado escalar.
chunks[quality_score]	La puntuación de calidad a nivel de fragmento.	Filtrado escalar o índice escalar.
chunks[emb_list_vector]	El subcampo vectorial utilizado como lista de incrustaciones.	Búsqueda en EmbeddingList con « MAX_SIM* ».
chunks[emb]	El subcampo vectorial utilizado por cada elemento de Struct de forma independiente.	Búsqueda vectorial a nivel de elemento.

Hacer que un campo StructArray sea nulo

Milvus v3.0.x admite campos StructArray nulos. Un campo StructArray nulo permite que una entidad almacene valores de tipo « null » para todo el campo StructArray.

schema.add_field(
    field_name="chunks",
    datatype=DataType.ARRAY,
    element_type=DataType.STRUCT,
    struct_schema=chunk_schema,
    max_capacity=1000,
    nullable=True,
)

Añadir un campo StructArray a una colección existente

Milvus v3.0.x permite añadir un campo StructArray a una colección existente. El campo StructArray añadido debe ser nulo, ya que las entidades que ya existen en la colección no tienen valores para el nuevo campo.

Para añadir un campo StructArray a una colección existente, defina primero el esquema Struct. A continuación, llame a ` add_collection_struct_field() ` y establezca ` nullable=True`.

chunk_schema = client.create_struct_field_schema()
chunk_schema.add_field(
    field_name="text",
    datatype=DataType.VARCHAR,
    max_length=65535,
)
chunk_schema.add_field(
    field_name="section",
    datatype=DataType.VARCHAR,
    max_length=128,
)
chunk_schema.add_field(
    field_name="page",
    datatype=DataType.INT64,
)
chunk_schema.add_field(
    field_name="quality_score",
    datatype=DataType.FLOAT,
)
chunk_schema.add_field(
    field_name="has_code",
    datatype=DataType.BOOL,
)
chunk_schema.add_field(
    field_name="emb_list_vector",
    datatype=DataType.FLOAT_VECTOR,
    dim=4,
)
chunk_schema.add_field(
    field_name="emb",
    datatype=DataType.FLOAT_VECTOR,
    dim=4,
)

client.add_collection_struct_field(
    collection_name="tech_articles",
    field_name="chunks",
    struct_schema=chunk_schema,
    max_capacity=1000,
    nullable=True,
)

Una vez añadido el campo StructArray, las entidades existentes devuelven ` null ` para el nuevo campo en todos sus subcampos.

Una vez creado un campo StructArray, no se pueden añadir nuevos subcampos a ese campo StructArray ya existente. Si más adelante necesitas atributos de elemento adicionales, llama a ` drop_collection_field() ` para eliminar el campo StructArray y, a continuación, añade un nuevo campo StructArray con el esquema Struct actualizado.

client.drop_collection_field(
    collection_name="tech_articles",
    field_name="chunks",
)

client.add_collection_struct_field(
    collection_name="tech_articles",
    field_name="chunks",
    struct_schema=updated_chunk_schema,
    max_capacity=1000,
    nullable=True,
)

Reglas del esquema

Regla	Explicación
Struct se utiliza como tipo de elemento Array.	Crea un campo StructArray como un campo Array con ` element_type=STRUCT`. No crees Struct como un campo de colección de nivel superior.
Todos los elementos comparten un mismo esquema.	Cada elemento «Struct» del mismo campo «StructArray» sigue el esquema «Struct» definido para ese campo.
max_capacity es obligatorio.	Limita el número de elementos Struct que cada entidad puede almacenar en el campo StructArray.
Solo se permiten los tipos de subcampos compatibles.	Utilice los tipos de subcampos escalares y vectoriales compatibles con StructArray. No defina subcampos JSON, Geometry, Text, Timestamptz, SparseFloatVector ni subcampos Struct / Array anidados.
Los subcampos vectoriales necesitan índices antes de la búsqueda.	Crea índices en rutas como chunks[emb_list_vector] o chunks[emb] antes de ejecutar una búsqueda vectorial.
Cada subcampo vectorial tiene un índice.	Si necesitas tanto la búsqueda en EmbeddingList como la búsqueda a nivel de elemento, crea dos subcampos vectoriales independientes.
Los subcampos StructArray existentes son fijos.	Una vez creado un campo StructArray, no se pueden añadir más subcampos a ese mismo campo StructArray.
No se admiten funciones dentro de Struct.	No definas funciones para campos o subcampos dentro de un campo StructArray.
Los subcampos escalares deben ajustarse a las necesidades de filtrado.	Añade campos como « section », « quality_score » o « has_code » solo cuando necesites filtrarlos, agruparlos o mostrarlos posteriormente.

Errores comunes

• Crear « DataType.STRUCT » como un campo de colección de nivel superior en lugar de utilizarlo como tipo de elemento de un campo «Array».

• Olvidarse de establecer « max_capacity » en el campo «StructArray».

• Definir tipos de subcampos no admitidos, como JSON, Geometry, Text, Timestamptz, SparseFloatVector, Array anidado, Struct anidado o Array-of-Struct.

• Utilizar « String » como tipo de subcampo. Utiliza « VARCHAR » y establece « max_length ».

• Utilizar un único subcampo vectorial tanto para la búsqueda en EmbeddingList como para la búsqueda a nivel de elemento.

• Añadir únicamente subcampos vectoriales y omitir los subcampos escalares necesarios para el filtrado, como section, quality_score o has_code.

• Tratar los subcampos vectoriales como entradas de predicados escalares de tipo $[...]. Utilizar los subcampos vectoriales para la búsqueda vectorial y los subcampos escalares para los predicados escalares.

• Suponer que se pueden añadir nuevos subcampos a un campo StructArray existente una vez creado dicho campo.

• Utilizar chunks.emb o chunks.emb_list_vector en lugar de la sintaxis de ruta requerida chunks[emb] o chunks[emb_list_vector].

• Tratar el comportamiento de los StructArray nulos como si estuviera disponible en todas las versiones de destino.

Próximos pasos

1. Para insertar datos anidados en el campo StructArray, consulta Insertar datos en campos StructArray.

2. Para crear índices vectoriales y escalares, consulta «Indexar campos StructArray».

3. Para buscar en los subcampos vectoriales de StructArray, consulta «Búsqueda vectorial básica con StructArray».

4. Para consultar los tipos de datos admitidos, el comportamiento de los valores nulos y las limitaciones específicas de cada versión, consulta «Límites de StructArray».