Upsert Vectors

client.VectorStores.Upsert(ctx, vectorStoreName, body) (*VectorStoreUpsertResponse, error)

POST/v5/vector-stores/{vector_store_name}/upsert

Insert new documents or update existing documents in a vector store.

Upsert Behavior: If a document ID already exists, it will be completely replaced with the new content and metadata. The previous document’s text, embedding, and all metadata fields are discarded. If the ID does not exist, a new document is created.

Document Content: Each document supports several modes:

content only: text is automatically embedded using the store’s configured model.
embedding only: pre-computed embedding vector is used directly. Dimension must match the store’s configuration.
Both content and embedding: the pre-computed embedding is stored and text is kept for retrieval/search.
Neither (metadata-only): only metadata is updated on an existing document without re-embedding. If the document does not exist, it will appear as a failure in the batch response.

A store created without an embedding model (dimensions-only) only accepts documents with pre-computed embedding.

Batch Operations: This endpoint supports batch operations with partial success handling and mixed document types (some with raw embeddings, some with content) in the same call.

Metadata: Supports nested metadata with string, number, boolean, object, and array types. Null values are not permitted—omit the field or use an empty string instead.

ParametersExpand Collapse

vectorStoreName string

The name of the vector store

body VectorStoreUpsertParams

Vectors param.Field[[]VectorStoreUpsertParamsVector]

Array of documents to upsert

ID string

Unique document ID

Content TextContentOptional

Text content for documents.

Text string

Text content to be embedded

Type TextContentTypeOptional

Content type identifier

Embedding []float64Optional

Pre-computed embedding vector

Metadata map[string, any]Optional

Key-value metadata

ReturnsExpand Collapse

type VectorStoreUpsertResponse struct{…}

Response for batch insert/upsert operations.

FailureCount int64

Number of failed documents

SuccessCount int64

Number of successfully processed documents

Failed []VectorStoreUpsertResponseFailedOptional

Failed documents with their error messages

ID string

Document ID

Error string

Error message describing why the document failed

Succeeded []stringOptional

IDs of successfully processed documents

Upsert Vectors

package main

import (
  "context"
  "fmt"

  "github.com/scaleapi/sgp-dev-go"
  "github.com/scaleapi/sgp-dev-go/option"
)

func main() {
  client := sgpdev.NewClient(
    option.WithAPIKey("My API Key"),
    option.WithAccountID("My Account ID"),
  )
  response, err := client.VectorStores.Upsert(
    context.TODO(),
    "vector_store_name",
    sgpdev.VectorStoreUpsertParams{
      Vectors: []sgpdev.VectorStoreUpsertParamsVector{sgpdev.VectorStoreUpsertParamsVector{
        ID: "id",
      }},
    },
  )
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", response.FailureCount)
}

{
  "failure_count": 0,
  "success_count": 0,
  "failed": [
    {
      "id": "id",
      "error": "error"
    }
  ],
  "succeeded": [
    "string"
  ]
}

Returns Examples

{
  "failure_count": 0,
  "success_count": 0,
  "failed": [
    {
      "id": "id",
      "error": "error"
    }
  ],
  "succeeded": [
    "string"
  ]
}