Skip to main content
POST/vectors/{collection}/upsert

Upsert Vectors

Upsert vectors. (Data, Queries & Vectors) POST /@:projectSlug/vectors/{collection}/upsert.

Parameters
collection *path

The derived collection's name.

It starts with _.

projectSlug *path

The project's slug: the path segment after @.

It is unique within the org.

Request body
rows *object[]

The chunks to write, 1 to 1,000 per request, all with the same vector dimension.

idstring

The chunk's id.

An existing id is overwritten (every column replaced).

Omitted: a new rec_... id is minted.

vector *number[]

The pre-computed embedding.

Every row in the request, and every row already in the collection, must have the same dimension: the first upsert fixes it.

_source *object

Where the chunk came from.

Stored as sent and returned by search; filter on it with source.<key>.

handle *string

An opaque handle for the source document the chunk came from.

chunkIndex *integer

The chunk's position within its source, from 0.

textstring

The chunk's source text, returned by search.

On a per-subject collection it is encrypted at rest under the subject's key.

Never filterable.

metadataobject

Your own filter keys for the chunk, stored as a JSON object (default {}) and returned by search as sent.

Keys are yours; values may be any JSON value.

Only keys made of letters, digits and _ can be filtered on (metadata.<key>), and a filter compares the value's text form, so keep filter values to strings, numbers and booleans.

A model key, when present, is also returned as the result's model.

There is no per-key or per-object limit beyond the 2 MiB request size; don't put source text here (use text).

subjectIdsstring[]

The end user (eu_...) the chunk's content belongs to: exactly one.

Required on a per-subject collection (400 K9O_VECTOR_SUBJECT_ATTRIBUTION_REQUIRED without it) and refused on a collection declared shared.

An end user calling for themselves must name themselves.

Responses
HTTPK9O CodeDescription
200Success
400K9O_INVALID_FIELD_VALUEThe project identifier in the request path is not valid.
400K9O_INVALID_VECTOR_DIMENSIONAll vectors in a single upsert batch must share the same dimension as the first row.
400K9O_VECTOR_SUBJECT_ATTRIBUTION_FORBIDDENThis collection is declared residencyClass='shared' (no data subject), so rows must not carry subjectIds; remove them or declare the collection per-subject.
400K9O_VECTOR_SUBJECT_ATTRIBUTION_REQUIREDEach vector row must carry subjectIds identifying the content-subject the chunk derives from, so it can later be sealed and erased.
403K9O_RESERVED_COLUMN_WRITE_PROHIBITEDVector upserts are only allowed into an extension's own '_'-prefixed derived collection; this collection name is not one.
403K9O_IAM_POLICY_DENIEDThe caller's project role can read vector data but not change it (reason read_only_role): only admin, editor, member and author roles write, as for storage objects.
409K9O_BYOK_REGION_MISMATCHA chunk belongs to a data subject, and the project's customer-managed key does not cover the region it is written in. Nothing was written, and the chunk text is never sealed under a platform key.
503K9O_KEY_SERVICE_UNAVAILABLEThe keyed content hash for the chunks couldn't be computed, so nothing was written (context.reason content_hash_unavailable). Retry shortly.
Response body (200)
data *object

What the upsert wrote.

upserted *integer

How many chunks were written (inserted or overwritten): the number of rows sent.

rows *object[]

One entry per row sent, in the order sent.

id *string

The chunk's id: the one sent, or the rec_... id minted for it.

contentHash *any

A keyed hash of the chunk's text, computed by the platform: 64 lowercase hex.

It is the same for the same text in the same collection, so a caller can skip re-embedding a chunk whose hash is unchanged, and it can't be compared across collections or projects.

Null when the chunk has no text, or when the project's keys are held in the customer's own cloud KMS.

Filterable as contentHash.

One of: string
or: null
collection *string

The derived collection written.

It is created on the first upsert.

meta *any

Request metadata: request id, trace id, timing and cost.

TypeScript
// const k9o = new K9o({ orgSlug: 'playground', projectSlug: 'storefront', apiKey: 'k9o_…' })
const { data } = await k9o.vectors.upsert('<collection>', {})

Showing example in TypeScript

Request example
{
  "rows": [
    {
      "id": "string",
      "vector": [
        0
      ],
      "_source": {
        "handle": "string",
        "chunkIndex": 0
      },
      "text": "string",
      "subjectIds": [
        "string"
      ]
    }
  ]
}
Response example (200)
{
  "data": {
    "upserted": 0,
    "rows": [
      {
        "id": "string",
        "contentHash": "string"
      }
    ],
    "collection": "string"
  }
}

More in Data, Queries & Vectors