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

Search Records by Vector

The record list read with its query in the body, for a vector too long for a URL.

The body is:

{ vectorSearch: { column, vector, metric?, limit? }, filter?, select?, order?, limit?, cursor?, count?, or? }

Runs exactly what GET /data/{collection} runs for the same parameters (the same read access, row policies and field reveal), so the rows and their order are the same, nearest first.

A vectorSearch.column the collection does not have answers K9O_INVALID_FIELD_VALUE (400).

Exempt from read-only suspension, like the GET.

The same filter bounds, time limit (K9O_QUERY_TIMEOUT, 504) and protected-column equality rule apply.

Parameters
collection *path

The collection's name.

projectSlug *path

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

It is unique within the org.

Request body
vectorSearch *object

The nearest-neighbour search to run.

column *string

The vector column to search, as named in the collection.

It must be a vector column of the collection.

vector *number[]

The query vector: finite numbers.

Its length must equal the column's dimension.

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

How similarity is measured.

Default cosine.

limitinteger

The most nearest records to return, 1 to 1000.

filterobject

Narrows the records searched.

Each key is a column name and each value is the same <operator>.<value> expression the list endpoint takes in its query string.

A key that is a list parameter name, or deleted, is refused.

selectstring

The columns to return, as in the list endpoint's select parameter.

orderstring

The sort order, as in the list endpoint's order parameter.

limitany

The page size, as in the list endpoint's limit parameter.

A number or a numeric string.

One of: integer
or: string
cursorstring

A meta.cursor.next value from an earlier answer, to fetch the next page.

count"none" | "exact" | "estimated"

Whether to count the matching records, as in the list endpoint's count parameter.

Default none.

orstring

An OR group of filters, as in the list endpoint's or parameter.

Responses
HTTPK9O CodeDescription
200Success
400K9O_INVALID_FIELD_VALUEThe body is not `{ vectorSearch: { column, vector, metric?, limit? }, filter?, select?, order?, limit?, cursor?, count?, or? }`. Any of these cases applies: - An unknown field, a non-numeric vector, an invalid column, metric or limit, or a filter key that is not a column. - A filter, select or order expression is invalid. - The vectorSearch column does not exist on the collection. - The vectorSearch column is not a vector column (reason not_a_vector_column). - The vectorSearch column holds a different dimension than the query vector (reason dimension_mismatch).
400K9O_INVALID_FILTERA filter operand is past its cap: a `match`, `like` or `ilike` pattern over 256 characters or a `jsonPath` over 512 (`context.reason: "operand_too_long"`), or an `in` / `notIn` list over 1,000 items (`too_many_items`). `context.column`, `context.op` and `context.max` say which.
400K9O_ENCRYPTED_COLUMN_OPERATION_UNSUPPORTEDThe operation is not supported on a protected column: only `eq` and `in` on a searchable one, and on one that needs a reveal purpose only in a read that reveals it (`context.reason: "reveal_required"`).
401K9O_SESSION_EXPIREDThe caller's session has expired.
401K9O_INVALID_CREDENTIALSThe caller is not authenticated.
403K9O_ACCESS_DENIEDThe caller has no read access to this collection, the same as GET /data/{collection}.
403K9O_EXTENSION_PERMISSION_DENIEDAn extension caller lacks (documents, read, <collection>), the grant GET /data/{collection} requires.
404K9O_COLLECTION_NOT_FOUNDNo such collection in this project.
504K9O_QUERY_TIMEOUTThe read ran past its time limit and returned nothing. `context.timeoutSeconds` gives the limit; narrow the filter or simplify a pattern.
Response body (200)
data *any

A page of records; a single record with single=true (an error when no record or more than one record matches); or the aggregate values with aggregate.

One of: object[]
or: object
or: object
meta *object

Request metadata (cost, timing, request and trace ids), plus the pagination cursor on a list answer.

cursorobject

Pagination.

Present on a list answer; absent with single or aggregate.

next *any

Opaque cursor for the next page; pass it back as cursor.

Null on the last page, and always null with range.

One of: string
or: null
totalCountany

The filtered row count when count is exact or estimated (from the planner's statistics); null when count is none (the default).

Absent with deleted=true.

One of: integer
or: null
countMethod"none" | "exact" | "estimated"

The count mode the read ran with.

Absent with deleted=true.

warningsobject[]

Present only when a warning applies.

code *string

A warning code.

This read adds K9O_ORG_CLAIM_UNBOUND (the token has no org claim, so org-scoped row policies may hide every row) and OFFSET_PAGINATION_INEFFICIENT (a range starting past row 1000).

message *string

A readable explanation.

cURL
curl -X POST 'https://<org>.api-<region>.k9o.io/@storefront/data/products/search' \
  -H 'Authorization: Bearer $K9O_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{}'

Showing example in cURL

Request example
{
  "vectorSearch": {
    "column": "string",
    "vector": [
      0
    ],
    "metric": "cosine",
    "limit": 0
  },
  "select": "string",
  "order": "string",
  "limit": 0,
  "cursor": "string",
  "count": "none",
  "or": "string"
}
Response example (200)
{
  "data": [],
  "meta": {
    "cursor": {
      "next": "string",
      "totalCount": 0,
      "countMethod": "none"
    },
    "warnings": [
      {
        "code": "string",
        "message": "string"
      }
    ]
  }
}

More in Data, Queries & Vectors