upsert_vectors

Use the upsert vectors operation to insert or update vectors in a table.

Upserts vectors into the specified table. If a vector with the same ID already exists, it will be updated with the new values. Otherwise, a new record is inserted.

Note: Automatic batching: When the JSON payload for an upsert_vectors request exceeds the request-size limit, the SDK automatically splits the input vector list into smaller batches. It sends each batch sequentially as a separate request. No batching configuration is required.

Performance: When automatic batching is triggered, sequential processing can degrade performance for large upserts.

Database JSON size limit: Oracle Database limits a JSON data type object to 32 MB. For details, see the Oracle Database JSON capabilities specification.

Automatic batching reduces the size of each request, but it does not change the database JSON-object limit.

ORA-40604: An upsert_vectors call can fail with the following error:

ORA-40604: exceeded maximum size for a JSON data type object

This error occurs when the serialized JSON request, including vector values and metadata, exceeds the database limit. Retrying the same oversized request does not resolve the error.

Load large vector datasets: For large vector datasets, stage the records in a CSV file in object storage and use load_vectors. The operation starts an asynchronous load job and avoids sending the complete dataset in one upsert_vectors request.

Parameters

Parameter	Type	Value Range	Required	Default	Description	Notes
table_name	str	Valid vector table identifier	Yes	No default	Name of the vector table to insert or update.	Table must exist in the database schema.
vectors	list[dict or UpsertVectorsRequestVectorsInner]	Array	Yes	No default	List of vector records to insert or update. Each item is a dictionary or vector model object.	Routed to the raw-vector or integrated embedding path based on table metadata.
debug_flags	dict	Object or NULL	No	None	Debug or tracing flags for detailed logging.	Optional; omit unless diagnostics are needed.

vectors fields

Field	Type	Value Range	Required	Description	Notes
id	str	Scalar value	Conditional	Vector record ID. Omit this field when the table has automatic ID generation enabled.	Required unless table_params.auto_generate_id is enabled for the table.
dense_vector	list	Array	Conditional	Precomputed dense vector values. Required for bring-your-own-vector tables and omitted for integrated embedding vector tables.	Required for bring-your-own-vector tables.
metadata	dict	Object	Yes	Metadata associated with the vector. For integrated embedding vector tables, include the configured embedding source field in this object.	Must be valid JSON-serializable metadata.

If table is configured with auto generated as True, then you do not need to provide id as part of the upsert object.

For integrated embedding vector tables, you can provide text in metadata as one of the values with embed_metadata_jsonpath configured earlier as key and embeddings will be generated automatically.

Performance consideration: For an integrated embedding vector table, each upsert that supplies text instead of dense_vector generates the embedding inline. This consumes database CPU resources and increases upsert latency. For high-volume ingestion, precomputing embeddings outside the database can reduce database CPU usage and improve ingestion throughput.

Raises Exception – InvalidTableNameFormatError may be raised when the table name is invalid. InvalidVectorsError is raised when vectors is empty. VectorPayloadTooLargeError is raised when one vector record cannot fit in a safe request batch. The operation can also fail if the table does not exist, a vector record is invalid, or a vector dimension does not match the vector table’s configured dimension.

Upsert pre-computed vectors

response = client.upsert_vectors(
    table_name='products',
    vectors=[
        {
            'id': 'prod_1',
            'dense_vector': [0.1, 0.2, 0.3, 0.4, 0.5],
            'metadata': {
                'name': 'Wireless Headphones',
                'category': 'electronics',
                'price': 99.99
            }
        },
        {
            'id': 'prod_2',
            'dense_vector': [0.2, 0.3, 0.1, 0.5, 0.4],
            'metadata': {
                'name': 'Smart Watch',
                'category': 'electronics',
                'price': 199.99
            }
        }
    ]
)
print(response)

Upsert with automatic embedding (table must have embed_params configured)

response = client.upsert_vectors(
    table_name='documents',
    vectors=[
        {
            'id': 'doc_1',
            'metadata': {
                'content': 'Machine learning is transforming healthcare',
                'category': 'AI',
                'author': 'John Doe'
            }
        },
        {
            'id': 'doc_2',
            'metadata': {
                'content': 'Vector databases enable semantic search',
                'category': 'Database',
                'author': 'Jane Smith'
            }
        }
    ]
)
print(response)

Return type UpsertVectorsResponse

Returns JSON response confirming upsert with count of inserted/updated vectors. Example response:

{
    "upserted_count": 10
}