Inserir ou atualizar um documento em uma coleção usando o SDK Python - DashVector: Central de Documentação do Alibaba Cloud

A operação upsert insere um novo documento na coleção se o ID não existir. Caso o ID já exista, o sistema executa uma atualização.

Se nenhum Doc ID for especificado, o DashVector gera um automaticamente e o retorna na resposta.

Pré-requisitos

Antes de começar, verifique se você tem:

Um cluster
Uma API key
A versão mais recente do DashVector SDK

Definição da API

Collection.upsert(
    docs: Union[Doc, List[Doc], Tuple, List[Tuple]],
    partition: Optional[str] = None,
    async_req: False
) -> DashVectorResponse

Exemplos

Todos os exemplos usam a seguinte configuração de cliente e coleção:

import dashvector
from dashvector import Doc
import numpy as np

# Replace with your actual credentials
client = dashvector.Client(
    api_key='YOUR_API_KEY',
    endpoint='YOUR_CLUSTER_ENDPOINT'
)

# Use an existing collection named 'quickstart'.
# To create one, see: https://www.alibabacloud.com/help/en/vrs/latest/new-collection#hivl6
collection = client.get(name='quickstart')

Substitua os placeholders abaixo pelos seus valores:

Placeholder	Descrição
`YOUR_API_KEY`	Chave de API para autenticação
`YOUR_CLUSTER_ENDPOINT`	URL do endpoint do cluster

Inserir ou atualizar um único documento

# Upsert using a Doc object
ret = collection.upsert(
    Doc(
        id='1',
        vector=[0.1, 0.2, 0.3, 0.4]
    )
)
assert ret

# Upsert using a tuple (shorthand)
ret = collection.upsert(
    ('2', [0.1, 0.1, 0.1, 0.1])               # (id, vector)
)

Inserir ou atualizar um documento com campos

# Upsert with predefined and schema-free fields
ret = collection.upsert(
    Doc(
        id='3',
        vector=np.random.rand(4),
        fields={
            # Predefined fields (types must match the collection schema)
            'name': 'zhangsan', 'weight': 70.0, 'age': 30,
            # Schema-free fields (str, int, bool, or float)
            'anykey1': 'str-value', 'anykey2': 1,
            'anykey3': True, 'anykey4': 3.1415926
        }
    )
)

# Upsert with fields using a tuple
ret = collection.upsert(
    ('4', np.random.rand(4), {'foo': 'bar'})  # (id, vector, fields)
)

Inserir ou atualizar vários documentos

# Batch upsert 10 documents using Doc objects
ret = collection.upsert(
    [
        Doc(id=str(i+5), vector=np.random.rand(4)) for i in range(10)
    ]
)

# Batch upsert 3 documents using tuples
ret = collection.upsert(
    [
        ('15', [0.2, 0.7, 0.8, 1.3], {'age': 20}),
        ('16', [0.3, 0.6, 0.9, 1.2], {'age': 30}),
        ('17', [0.4, 0.5, 1.0, 1.1], {'age': 40})
    ]                                         # List[(id, vector, fields)]
)

assert ret

Inserir ou atualizar documentos de forma assíncrona

Defina async_req=True para enviar a operação de upsert como uma chamada não bloqueante. Chame .get() no future retornado para obter o resultado.

# Asynchronously upsert 10 documents
ret_funture = collection.upsert(
    [
        Doc(id=str(i+18), vector=np.random.rand(4), fields={'name': 'foo' + str(i)}) for i in range(10)
    ],
    async_req=True
)

# Block until the operation completes
ret = ret_funture.get()

Inserir ou atualizar um documento com vetor esparso

Forneça um dicionário sparse_vector que mapeia índices a valores:

ret = collection.upsert(
    Doc(
        id='28',
        vector=[0.1, 0.2, 0.3, 0.4],
        sparse_vector={1: 0.4, 10000: 0.6, 222222: 0.8}
    )
)

Parâmetros da solicitação

Parâmetro	Tipo	Padrão	Descrição
`docs`	`Union[Doc, List[Doc], Tuple, List[Tuple]]`	-	Um ou mais documentos para inserir ou atualizar. Obrigatório.
`partition`	`Optional[str]`	`None`	Nome da partição de destino.
`async_req`	`bool`	`False`	Ativa o modo assíncrono.

Formato de tupla:

Ao usar uma tupla em vez de um objeto Doc, os elementos devem seguir esta ordem: (id, vector) ou (id, vector, fields).

Restrições de campos:

Cada campo em um objeto Doc é um par chave-valor em que:

A chave deve ser do tipo str.
O valor deve ser str, int, bool ou float.
Se a chave foi predefinida durante a criação da coleção, o tipo do valor deve corresponder ao tipo predefinido.
Chaves não predefinidas são schema-free e aceitam qualquer um dos tipos de valor compatíveis.

Parâmetros da resposta

O método retorna um objeto DashVectorResponse:

Parâmetro	Tipo	Descrição	Exemplo
`code`	`int`	Código de status. `0` indica sucesso. Consulte Códigos de status.	`0`
`message`	`str`	Mensagem de resultado.	`success`
`request_id`	`str`	Identificador exclusivo da solicitação.	`19215409-ea66-4db9-8764-26ce2eb5bb99`