Insert documents into a collection using Python SDK - DashVector

Insert one or more documents into a DashVector collection using the Python SDK.

If a document ID already exists in the collection, the insert operation skips that document without overwriting it. To update an existing document, use the upsert method instead. If you omit the document ID, DashVector automatically generates one and returns it in the response.

Prerequisites

Before you begin, make sure that you have:

A DashVector cluster. For details, see Create a cluster
An API key. For details, see Manage API keys
The latest DashVector SDK for Python. For details, see Install DashVector SDK

API definition

Python

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

Examples

All examples use an existing collection named quickstart. Replace YOUR_API_KEY with your API key and YOUR_CLUSTER_ENDPOINT with the endpoint of your cluster before running the code.

Python

import dashvector
from dashvector import Doc
import numpy as np

client = dashvector.Client(
    api_key='YOUR_API_KEY',
    endpoint='YOUR_CLUSTER_ENDPOINT'
)
collection = client.get(name='quickstart')

Note

Create the quickstart collection before running these examples. For details, see the example section in Create a collection.

Insert a single document

Python

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

# Shorthand: use a tuple instead of a Doc object
ret = collection.insert(
    ('2', [0.1, 0.1, 0.1, 0.1])               # (id, vector)
)

Insert a document with fields

Attach metadata as key-value pairs through the fields parameter. Fields defined during collection creation must match their predefined types. Additional fields are schema-free and accept str, int, bool, or float values. For more information, see Schema-free.

Python

# Insert a document with predefined and schema-free fields
ret = collection.insert(
    Doc(
        id='3',
        vector=np.random.rand(4),
        fields={
            # Predefined fields (types must match collection schema)
            # name:str, weight:float, age:int, id:dashvector.long
            'name': 'zhangsan', 'weight':70.0, 'age':30, 'id':1234567890,
            # Schema-free fields (no predefinition required)
            'anykey1': 'str-value', 'anykey2': 1,
            'anykey3': True, 'anykey4': 3.1415926
        }
    )
)

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

Insert multiple documents

Python

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

# Batch insert using tuples with fields
ret = collection.insert(
    [
        ('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

Insert documents asynchronously

Set async_req=True to perform non-blocking inserts. Call .get() on the returned future to retrieve the result.

Python

# Asynchronously insert 10 documents
ret_funture = collection.insert(
    [
        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 asynchronous insert completes
ret = ret_funture.get()

Insert a document with a sparse vector

Use the sparse_vector parameter to store sparse representations alongside dense vectors.

Python

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

Parameters

Request parameters

Parameter	Type	Default	Description
`docs`	`Union[Doc, List[Doc], Tuple, List[Tuple]]`	Required	One or more documents to insert
`partition`	`Optional[str]`	`None`	Target partition name
`async_req`	`bool`	`False`	Enable asynchronous mode

Parameter notes:

Tuple format: Elements must follow the order (id, vector) or (id, vector, fields). A tuple is equivalent to a Doc object.
Field keys and values: Each field key must be a str. Values accept str, int, bool, or float.
- If a field key is predefined during collection creation, the value must match the predefined type.
- If a field key is not predefined, it is treated as a schema-free field and accepts any supported value type.
For more information about predefined fields, see Schema-free.

Response

The method returns a DashVectorResponse object with the following properties:

Property	Type	Description	Example
`code`	`int`	Status code. `0` indicates success. See Status codes.	`0`
`message`	`str`	Result message	`success`
`request_id`	`str`	Unique request identifier	`19215409-ea66-4db9-8764-26ce2eb5bb99`