Criar um campo StructArray

Crie um campo StructArray quando uma entidade precisar de conter uma lista ordenada de elementos estruturados. Um campo StructArray é um campo Array cujo tipo de elemento é Struct. Cada elemento Struct segue o mesmo esquema e pode conter subcampos escalares, subcampos vetoriais ou ambos.

Esta página mostra como definir um esquema Struct, adicioná-lo como um campo StructArray, selecionar subcampos para pesquisa e filtragem posteriores e compreender as regras do esquema aplicáveis antes de inserir ou indexar dados.

Antes de começar

Esta página utiliza uma coleção denominada « tech_articles ». Cada entidade representa um artigo técnico, e o campo « chunks » armazena dados ao nível de fragmentos como elementos Struct.

Campo	Tipo	Finalidade
doc_id	INT64	Chave primária do artigo.
title	VARCHAR	Título do artigo.
category	VARCHAR	Categoria ao nível do artigo.
title_vector	FLOAT_VECTOR	Campo vetorial ao nível do artigo, utilizado posteriormente em exemplos de pesquisa híbrida.
chunks	ARRAY	Campo StructArray que armazena texto ao nível do fragmento, metadados e incorporações.

O campo StructArray « chunks » contém os seguintes subcampos.

Subcampo	Tipo	Finalidade
text	VARCHAR	Texto do bloco.
section	VARCHAR	Nome da secção, como « index », « search » ou « filter ».
page	INT64	Número da página ou posição lógica do fragmento.
quality_score	FLOAT	Pontuação ao nível do fragmento utilizada na filtragem escalar e nos exemplos de intervalo.
has_code	BOOL	Se o fragmento contém código.
emb_list_vector	FLOAT_VECTOR	Subcampo de vetor para pesquisa na EmbeddingList com métricas de MAX_SIM*.
emb	FLOAT_VECTOR	Subcampo vetorial para pesquisa ao nível do elemento com métricas vetoriais regulares.

Tipos de dados de subcampos suportados

Um campo StructArray armazena um valor de matriz para cada subcampo Struct. Ao definir um esquema Struct, escolha os tipos de subcampo entre as famílias escalares e vetoriais suportadas.

Tipo físico do subcampo Struct	Suporte	Notas
Array	Suportado	Defina o subcampo como « DataType.BOOL ».
Array	Compatível	Defina o subcampo como « DataType.INT8 », « DataType.INT16 », « DataType.INT32 » ou « DataType.INT64 ».
Array	Compatível	Defina o subcampo como DataType.FLOAT ou DataType.DOUBLE.
Array	Compatível	Defina o subcampo como « DataType.VARCHAR » e defina « max_length ».
ArrayOfVector	Compatível	Defina o subcampo como « DataType.FLOAT_VECTOR » e defina « dim ».
ArrayOfVector	Compatível	Defina o subcampo como « DataType.FLOAT16_VECTOR » e defina « dim ».
ArrayOfVector	Compatível	Defina o subcampo como « DataType.BFLOAT16_VECTOR » e defina « dim ».
ArrayOfVector	Compatível	Defina o subcampo como « DataType.INT8_VECTOR » e defina « dim ».
ArrayOfVector	Compatível	Defina o subcampo como « DataType.BINARY_VECTOR » e defina « dim ».
ArrayOfVector	Não suportado	Os subcampos de vetores esparsos não são suportados nos campos StructArray.
Array	Não suportado	Utilize « VARCHAR », e não « String ».
Array	Não suportado	Os subcampos JSON não são suportados nos campos StructArray.
Array	Não suportado	Os subcampos de geometria e as funções GIS não são suportados nos campos StructArray.
Array	Não suportado	Os subcampos de texto não são suportados nos campos StructArray.
Array	Não suportado	Os subcampos «Timestamptz» e as expressões específicas de hora não são suportados nos campos StructArray.
Array, ArrayOfVector, Struct ou ArrayOfStruct	Não suportado	Um campo StructArray não pode conter matrizes aninhadas, matrizes vetoriais aninhadas, campos Struct aninhados ou campos Array-of-Struct aninhados.

Para obter informações sobre suporte específico por versão, comportamento de valores nulos e outros limites, consulte Limites do StructArray.

Criar uma coleção com um campo StructArray

Para criar um campo StructArray, defina primeiro o esquema Struct utilizado por cada elemento. Em seguida, adicione um campo Array e defina o seu tipo de elemento como Struct.

1. Crie o esquema da coleção.

2. Adicione campos ao nível da coleção, tais como a chave primária e campos ao nível do artigo.

3. Crie um esquema Struct para os elementos armazenados no campo StructArray.

4. Adicione subcampos escalares e vetoriais ao esquema Struct.

5. Adicione um campo «Array» com « element_type=DataType.STRUCT ».

6. Defina ` struct_schema ` para o esquema `Struct`.

7. Defina « max_capacity » para limitar o número de elementos «Struct» que cada entidade pode armazenar no 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,
)

Compreender os caminhos do campo StructArray

Depois de criar um campo «StructArray», refira-se aos seus subcampos utilizando a sintaxe de caminho « structArray[subfield] ». Utilize esta sintaxe ao criar índices, pesquisar subcampos vetoriais, gerar subcampos ou criar filtros escalares.

Caminho	Significado	Utilização comum
chunks[text]	O subcampo « text » dentro de cada elemento Struct.	Campo de saída ou filtragem escalar.
chunks[section]	O rótulo da secção para cada bloco.	Filtragem escalar.
chunks[quality_score]	A pontuação de qualidade ao nível do bloco.	Filtragem escalar ou índice escalar.
chunks[emb_list_vector]	O subcampo vetorial utilizado como lista de incorporação.	Pesquisa na EmbeddingList com ` MAX_SIM*`.
chunks[emb]	O subcampo vetorial utilizado por cada elemento Struct de forma independente.	Pesquisa vetorial ao nível do elemento.

Tornar um campo StructArray nulo

O Milvus v3.0.x suporta campos StructArray nulos. Um campo StructArray nulo permite que uma entidade armazene valores do tipo « null » para todo o campo StructArray.

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

Adicionar um campo StructArray a uma coleção existente

O Milvus v3.0.x suporta a adição de um campo StructArray a uma coleção existente. O campo StructArray adicionado deve ser nulo, uma vez que as entidades que já existem na coleção não têm valores para o novo campo.

Para adicionar um campo StructArray a uma coleção existente, defina primeiro o esquema Struct. Em seguida, chame ` add_collection_struct_field() ` e defina ` 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,
)

Após a adição do campo StructArray, as entidades existentes devolvem ` null ` para o novo campo em todos os seus subcampos.

Após a criação de um campo StructArray, não é possível adicionar novos subcampos a esse campo StructArray existente. Se, posteriormente, necessitar de atributos de elemento adicionais, chame drop_collection_field() para eliminar o campo StructArray e, em seguida, adicione um novo campo StructArray com o esquema Struct atualizado.

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

Regras do esquema

Regra	Explicação
O Struct é utilizado como tipo de elemento Array.	Crie um campo StructArray como um campo Array com ` element_type=STRUCT`. Não crie Struct como um campo de coleção de nível superior.
Todos os elementos partilham um único esquema.	Cada elemento Struct no mesmo campo StructArray segue o esquema Struct definido para esse campo.
max_capacity é obrigatório.	Limita o número de elementos Struct que cada entidade pode armazenar no campo StructArray.
Apenas são permitidos os tipos de subcampos suportados.	Utilize tipos de subcampos escalares e vetoriais suportados pelo StructArray. Não defina subcampos JSON, Geometry, Text, Timestamptz, SparseFloatVector ou subcampos Struct / Array aninhados.
Os subcampos vetoriais necessitam de índices antes da pesquisa.	Crie índices em percursos como chunks[emb_list_vector] ou chunks[emb] antes de executar a pesquisa vetorial.
Cada subcampo vetorial tem um índice.	Se precisar tanto da pesquisa EmbeddingList como da pesquisa ao nível do elemento, crie dois subcampos vetoriais separados.
Os subcampos StructArray existentes são fixos.	Após criar um campo StructArray, não espere poder adicionar mais subcampos a esse mesmo campo StructArray.
As funções não são suportadas dentro de Struct.	Não defina funções para campos ou subcampos dentro de um campo StructArray.
Os subcampos escalares devem corresponder às necessidades de filtragem.	Adicione campos como section, quality_score ou has_code apenas quando precisar de os filtrar, agrupar ou apresentar posteriormente.

Erros comuns

• Criar « DataType.STRUCT » como um campo de coleção de nível superior, em vez de o utilizar como o tipo de elemento de um campo «Array».

• Esquecer-se de definir « max_capacity » no campo «StructArray».

• Definir tipos de subcampos não suportados, tais como JSON, Geometry, Text, Timestamptz, SparseFloatVector, Array aninhado, Struct aninhado ou Array-of-Struct.

• Utilizar « String » como tipo de subcampo. Utilize « VARCHAR » e defina « max_length ».

• Utilizar um único subcampo vetorial tanto para a pesquisa na EmbeddingList como para a pesquisa ao nível dos elementos.

• Adicionar apenas subcampos vetoriais e esquecer os subcampos escalares necessários para a filtragem, tais como section, quality_score ou has_code.

• Tratar os subcampos vetoriais como entradas de predicados escalares $[...]. Utilizar subcampos vetoriais para a pesquisa vetorial e subcampos escalares para predicados escalares.

• Partir do princípio de que é possível adicionar novos subcampos a um campo StructArray existente após a criação do campo.

• Utilizar chunks.emb ou chunks.emb_list_vector em vez da sintaxe de caminho obrigatória chunks[emb] ou chunks[emb_list_vector].

• Tratar o comportamento do StructArray nulo como se estivesse disponível em todas as versões de destino.

Próximos passos

1. Para inserir dados aninhados no campo StructArray, consulte Inserir dados em campos StructArray.

2. Para criar índices vetoriais e escalares, consulte «Indexar campos StructArray».

3. Para pesquisar subcampos vetoriais do StructArray, consulte «Pesquisa vetorial básica com StructArray».

4. Para consultar os tipos de dados suportados, o comportamento nulo e as limitações específicas de cada versão, leia «Limites do StructArray».