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

Search Vectors

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

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
queryVector *number[]

The query embedding.

Its dimension must match the collection's (400 K9O_INVALID_VECTOR_DIMENSION otherwise).

topKinteger

The most results to return.

Default 10.

minScorenumber

Drop results whose score is below this.

No threshold when omitted.

metric"cosine" | "euclidean" | "dot"

How similarity is measured and scored.

Default cosine.

filtersobject

Equality filters; every one must match.

Keys are id, contentHash, source.<key> or metadata.<key>, where <key> is letters, digits and _ (any other key is 400 K9O_INVALID_FIELD_VALUE).

Values are strings, numbers or booleans, compared by their text form (so 2 matches a stored 2 or "2").

Responses
HTTPK9O CodeDescription
200Success
400K9O_INVALID_FIELD_VALUEThe project identifier in the request path is not valid.
400K9O_INVALID_FIELD_VALUEVector search only targets a '_'-prefixed derived collection; use the query-builder vectorSearch() for a regular collection.
400K9O_INVALID_FIELD_VALUEThe filters object referenced an unsupported path; only id, contentHash, source.<key>, and metadata.<key> are allowed.
400K9O_INVALID_VECTOR_DIMENSIONThe query vector's dimension does not match the dimension stored for this collection.
404K9O_COLLECTION_NOT_FOUNDThis derived vector collection has never been upserted into, so there is nothing to search.
Response body (200)
data *object

The search results.

results *object[]

The closest chunks, most similar first (ties broken by id), at most topK, filtered by filters and minScore and by the caller's row access.

Empty when nothing matches.

id *string

The chunk's id.

score *any

Similarity to the query, higher is closer. cosine: 1 minus the cosine distance (1 for an identical direction). euclidean: 1 / (1 + distance), in (0, 1]. dot: the inner product.

Null when the similarity is undefined: a cosine search with an all-zero query vector, or a stored vector of all zeros.

One of: number
or: null
_source *object

The _source object sent on upsert.

handle *string

The source handle sent on upsert.

chunkIndex *integer

The chunk's position within its source.

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
text *any

The chunk's source text (decrypted for a per-subject chunk), or null when none was sent.

One of: string
or: null
metadata *object

The chunk's metadata object exactly as sent on upsert ({} when none was sent): your own keys, with any JSON values.

model *any

metadata.model copied out, or null when the chunk's metadata has no model key.

Normally the embedding model's name (a string); the gateway returns whatever value was stored.

chunk *any

_source.chunkIndex copied out, or null when it is absent.

One of: integer
or: null
collection *string

The derived collection searched.

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.nearest('<collection>', {})

Showing example in TypeScript

Request example
{
  "queryVector": [
    0
  ],
  "topK": 0,
  "minScore": 0,
  "metric": "cosine"
}
Response example (200)
{
  "data": {
    "results": [
      {
        "id": "string",
        "score": 0,
        "_source": {
          "handle": "string",
          "chunkIndex": 0
        },
        "contentHash": "string",
        "text": "string",
        "chunk": 0
      }
    ],
    "collection": "string"
  }
}

More in Data, Queries & Vectors