Inserir dados nos campos StructArray

Insira dados num campo StructArray quando cada entidade contiver uma lista ordenada de elementos estruturados. Na carga útil de inserção, um campo StructArray é representado como uma matriz de objetos. Cada objeto representa um elemento Struct e utiliza os nomes dos subcampos Struct definidos no esquema da coleção.

Esta página utiliza a coleção « tech_articles » da secção «Criar um campo StructArray». Cada entidade é um artigo técnico e o campo « chunks » armazena partes do artigo como elementos Struct.

Antes de começar

Certifique-se de que o esquema da coleção já contém o campo StructArray « chunks ».

Campo	Tipo	Valor de inserção
doc_id	INT64	ID do artigo.
title	VARCHAR	Título do artigo.
category	VARCHAR	Categoria do artigo.
title_vector	FLOAT_VECTOR	Incorporação ao nível do artigo.
chunks	ARRAY	Uma lista de objetos «chunk».

Cada objeto em « chunks » deve seguir o esquema Struct.

Subcampo	Tipo	Valor a inserir
text	VARCHAR	Texto do chunk.
section	VARCHAR	Nome da secção, como index, search ou filter.
page	INT64	Número da página ou posição lógica.
quality_score	FLOAT	Pontuação ao nível do bloco.
has_code	BOOL	Se o fragmento contém código.
emb_list_vector	FLOAT_VECTOR	Vetor criado para a pesquisa EmbeddingList.
emb	FLOAT_VECTOR	Vetor criado para pesquisa ao nível do elemento.

Compreender a estrutura da carga útil de inserção

O valor de ` chunks ` é uma matriz de elementos `Struct`. Cada elemento é um objeto cujas chaves são nomes 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 e emb são subcampos vetoriais separados, uma vez que suportam modos de pesquisa diferentes. A pesquisa EmbeddingList trata todos os vetores num campo StructArray como uma única lista de incorporações e devolve resultados ao nível da entidade com métricas MAX_SIM*. A pesquisa ao nível do elemento pesquisa cada elemento Struct de forma independente e pode devolver o deslocamento do elemento correspondente. Este exemplo armazena os mesmos valores vetoriais em ambos os campos por uma questão de simplicidade. Numa aplicação de produção, pode armazenar as mesmas incorporações em ambos os subcampos quando ambos os modos de pesquisa utilizam a mesma incorporação de blocos, ou armazenar incorporações diferentes quando os dois modos de pesquisa utilizam representações diferentes.

Inserir linhas

Utilize « client.insert() » para inserir linhas que contenham 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)

Inserir em campos StructArray nulos

Se o campo ` chunks ` for nulo, uma entidade pode definir todo o campo ` chunks ` como nulo. Em Python, utilize ` None ` para representar um 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,
        }
    ],
)

Quando um campo StructArray nulo contém um valor StructArray válido, todos os subcampos desse valor devem ser nulos ou ter valores válidos. A inserção de uma entidade com alguns subcampos definidos como nulos e outros com valores válidos resulta num erro.

Validar dados inseridos

Pode consultar a coleção e devolver o campo StructArray ou os subcampos selecionados.

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)

Utilize caminhos de campo StructArray, tais como chunks[text], apenas quando consultar, pesquisar, filtrar ou criar índices. As cargas de inserção devem continuar a utilizar objetos aninhados em chunks.

Regras de inserção

Regra	Explicação
Utilize uma matriz de objetos para um campo StructArray.	O valor de chunks é uma lista, e cada item da lista é um elemento Struct.
Utilize nomes de subcampos dentro de cada elemento Struct.	Insira « {"text": "...", "emb": [...]} » dentro de « chunks », e não em « {"chunks[text]": "..."} ».
Respeite o esquema da Struct.	Cada elemento Struct deve utilizar os subcampos definidos no esquema Struct.
Respeite as dimensões do vetor.	Os valores dos vetores devem corresponder aos « dim » configurados para os seus subcampos vetoriais.
Respeitar o « max_capacity ».	O número de elementos Struct numa entidade não deve exceder o max_capacity do campo StructArray.
Utilize subcampos vetoriais separados para modos de pesquisa distintos.	Se forem necessárias tanto a pesquisa EmbeddingList como a pesquisa ao nível do elemento, escreva os valores do vetor em ambos os subcampos do vetor.
Utilize o parâmetro « null » apenas quando o campo for nulo.	Os campos StructArray não nulos exigem valores StructArray válidos.

Erros comuns

• Utilizar caminhos de campo como « chunks[text] » em cargas de inserção.

• Omitir subcampos obrigatórios de um elemento Struct.

• Inserir vetores com a dimensão errada.

• Inserir mais elementos Struct do que o permitido por max_capacity.

• Definir apenas um subcampo como « null », enquanto outros subcampos no mesmo valor «StructArray» são válidos.

• Gravar vetores apenas em ` emb_list_vector ` e, em seguida, tentar executar uma pesquisa ao nível do elemento em ` chunks[emb]`.

• Gravar vetores apenas em « emb » e, em seguida, tentar executar uma pesquisa «EmbeddingList» em « chunks[emb_list_vector] ».

Próximos passos

1. Para criar índices para chunks[emb_list_vector], chunks[emb] e subcampos escalares, consulte «Indexar campos StructArray».

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

3. Para rever o comportamento dos valores nulos e as limitações específicas de cada versão, consulte «Limites do StructArray».