Upserting Vectors

Every database needs data, and your vector database is no exception.

Our SDK makes it easy to insert or update (upsert) vector data in your indexes and/or namespaces.

Upsert

With Upstash Vector, you can upsert one or more vectors. For now, let’s focus on upserting a single vector.

We’ll use the upsert() method to instruct the SDK to upsert vectors into an index, as shown below:

use Upstash\Vector\Index;
use Upstash\Vector\VectorUpsert;

$index = new Index(
  url: "<UPSTASH_VECTOR_REST_URL>",
  token: "<UPSTASH_VECTOR_REST_TOKEN>",
);

$index->upsert(new VectorUpsert(
  id: '1',
  vector: [0.1, 0.2, ...], // "..." represents the dimension size of your vector index.
));
// or within a namespace
$index->namespace('my-namespace')->upsert(new VectorUpsert(
  id: '1',
  vector: [0.1, 0.2, ...],
));

You can also enhance your index by adding metadata, enabling more efficient filtering in the future.

You can read more about Metadata, Data and Metadata Filtering on our docs.

Upsert Many

Building on the previous section, Upstash Vector also supports upserting multiple vectors at once.

To do this, we’ll use the upsertMany() method, which allows you to efficiently insert or update multiple vectors into an index, as shown below:

use Upstash\Vector\Index;
use Upstash\Vector\VectorUpsert;

$index = new Index(
  url: "<UPSTASH_VECTOR_REST_URL>",
  token: "<UPSTASH_VECTOR_REST_TOKEN>",
);

$index->upsertMany([
  new VectorUpsert(
    id: '1',
    vector: [0.1, 0.2, ...],
  ),
  new VectorUpsert(
    id: '2',
    vector: [0.3, 0.1, ...],
  ),
]);

Upserting multiple records simultaneously improves performance by allowing you to batch your imports efficiently.

For optimal results, we recommend limiting each batch to no more than 1,000 records at a time.

Sparse Indexes

If you are using a sparse index, you’ll need to modify your upsert call accordingly.

Sparse indexes require a set of indices and their corresponding values, which can be upserted as demonstrated below:

use Upstash\Vector\Index;
use Upstash\Vector\VectorUpsert;
use Upstash\Vector\SparseVector;

$index = new Index(
  url: "<UPSTASH_VECTOR_REST_URL>",
  token: "<UPSTASH_VECTOR_REST_TOKEN>",
);

$index->upsert(new VectorUpsert(
  id: '1',
  sparseVector: new SparseVector(
    indices: [0, 1],
    values: [1.0, 2.0],
  ),
));

You can read more about Sparse Indexes on our docs.

Hybrid Indexes

If you are using a hybrid index, you need to provide both sparse vectors and dense vectors.

use Upstash\Vector\Index;
use Upstash\Vector\VectorUpsert;
use Upstash\Vector\SparseVector;

$index = new Index(
  url: "<UPSTASH_VECTOR_REST_URL>",
  token: "<UPSTASH_VECTOR_REST_TOKEN>",
);

$index->upsert(new VectorUpsert(
  id: '1',
  vector: [0.1, 0.2, ...],
  sparseVector: new SparseVector(
    indices: [0, 1],
    values: [1.0, 2.0],
  ),
));

You can read more about Hybrid Indexes on our docs.