> ## Documentation Index
> Fetch the complete documentation index at: https://upstash.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

<CodeGroup>
  ```php simple theme={"system"}
  use Upstash\Vector\Index;
  use Upstash\Vector\VectorUpsert;

  use function Upstash\Vector\createRandomVector;

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

  $index->upsert(new VectorUpsert(
    id: '1',
    vector: createRandomVector(dimensions: 1536)
  ));
  ```

  ```php using namespaces theme={"system"}
  use Upstash\Vector\Index;
  use Upstash\Vector\VectorUpsert;

  use function Upstash\Vector\createRandomVector;

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

  $index->namespace('my-namespace')->upsert(new VectorUpsert(
    id: '1',
    vector: createRandomVector(dimensions: 1536)
  ));
  ```
</CodeGroup>

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

You can read more about [Metadata](/vector/features/metadata#metadata), [Data](/vector/features/metadata#data) and [Metadata Filtering](/vector/features/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:

<CodeGroup>
  ```php simple theme={"system"}
  use Upstash\Vector\Index;
  use Upstash\Vector\VectorUpsert;

  use function Upstash\Vector\createRandomVector;

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

  $index->upsertMany([
    new VectorUpsert(
      id: '1',
      vector: createRandomVector(dimensions: 1536)
    ),
    new VectorUpsert(
      id: '2',
      vector: createRandomVector(dimensions: 1536)
    ),
  ]);
  ```

  ```php using namespaces theme={"system"}
  use Upstash\Vector\Index;
  use Upstash\Vector\VectorUpsert;

  use function Upstash\Vector\createRandomVector;

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

  $index->namespace('my-namespace')->upsertMany([
    new VectorUpsert(
      id: '1',
      vector: createRandomVector(dimensions: 1536)
    ),
    new VectorUpsert(
      id: '2',
      vector: createRandomVector(dimensions: 1536)
    ),
  ]);
  ```
</CodeGroup>

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

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

## Update

When you upsert data you are basicly overriding the data that is already in the index. If you want to update the data you can use the `update` method.

The `update` method is similar to the `upsert` method, but it will only update the data that is already in the index.

<CodeGroup>
  ```php simple theme={"system"}
  use Upstash\Vector\Index;
  use Upstash\Vector\VectorUpdate;
  use Upstash\Vector\Enums\UpdateMode;

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

  $index->update(new VectorUpdate(
    id: '1',
    metadata: ['foo' => 'baz'],
    metadataUpdateMode: UpdateMode::OVERWRITE,
  ));
  ```

  ```php using namespaces theme={"system"}
  use Upstash\Vector\Index;
  use Upstash\Vector\VectorUpdate;
  use Upstash\Vector\Enums\UpdateMode;

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

  $index->namespace('my-namespace')->update(new VectorUpdate(
    id: '1',
    metadata: ['foo' => 'baz'],
    metadataUpdateMode: UpdateMode::OVERWRITE,
  ));
  ```
</CodeGroup>

## 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:

<CodeGroup>
  ```php simple theme={"system"}
  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],
    ),
  ));
  ```

  ```php using namespaces theme={"system"}
  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->namespace('my-namespace')->upsert(new VectorUpsert(
    id: '1',
    sparseVector: new SparseVector(
      indices: [0, 1],
      values: [1.0, 2.0],
    ),
  ));
  ```
</CodeGroup>

You can read more about [Sparse Indexes](/vector/features/sparseindexes) on our docs.

## Hybrid Indexes

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

<CodeGroup>
  ```php simple theme={"system"}
  use Upstash\Vector\Index;
  use Upstash\Vector\VectorUpsert;
  use Upstash\Vector\SparseVector;

  use function Upstash\Vector\createRandomVector;

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

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

  ```php using namespaces theme={"system"}
  use Upstash\Vector\Index;
  use Upstash\Vector\VectorUpsert;
  use Upstash\Vector\SparseVector;

  use function Upstash\Vector\createRandomVector;

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

  $index->namespace('my-namespace')->upsert(new VectorUpsert(
    id: '1',
    vector: createRandomVector(dimensions: 1536),
    sparseVector: new SparseVector(
      indices: [0, 1],
      values: [1.0, 2.0],
    ),
  ));
  ```
</CodeGroup>

You can read more about [Hybrid Indexes](/vector/features/hybridindexes) on our docs.