Skip to main content
POST/metadata/vectors/nearest

Find Nearest Vectors

Create nearest. (Data, Queries & Vectors) POST /@:projectSlug/metadata/vectors/nearest.

Parameters
projectSlug *path

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

It is unique within the org.

Request body
surface *string

A surface label <slice>:<scope>: collection:<name>, telemetry:<eventType> or storage:<bucket>.

The scope is 1 to 128 characters of letters, digits, ., _, : and -, starting with a letter or digit.

Only a collection surface is accepted here.

column *string

The declared vector column to rank by, as metadata.<column>.

Not a protected column.

embedding *number[]

The query vector.

Its length must match the column's dimension.

kinteger

How many nearest rows to return, as the vector search limit on POST /data/{collection}/search.

metricstring

The distance metric, as the vector search metric on POST /data/{collection}/search.

whereobject[]

Filters on declared columns, as in POST /metadata/query.

field *string

The field to filter on.

On a collection surface, metadata.<column> for a declared column.

On a telemetry surface, createdAt (with gt, gte, lt, lte) or actorId (with eq).

op *"eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "contains" | "startsWith" | "endsWith" | "in" | "notIn" | "and" | "or" | "not"

The operator. and, or and not are accepted by the parser but refused by every surface.

A protected (encrypted) column allows only eq with a non-null value, and in.

value *any

The value to compare with. in and notIn take a non-empty array of strings, numbers or booleans (none containing ,, ( or )). eq and neq with null test for null.

Other operators take one string, number or boolean.

One of: string
or: number
or: boolean
or: null
or: any[]
Responses
HTTPK9O CodeDescription
200Success
400K9O_INVALID_FIELD_VALUEThe body is malformed: an unknown field, a wrong type, or an unsupported where operator.
400K9O_UNKNOWN_SURFACEA surface is not collection:<name>, storage:<bucket> or telemetry:<eventType>.
400K9O_METADATA_FIELD_NOT_INDEXEDA field is not a declared metadata field of the surface (ch04 §1.3.1); declare it with PUT /metadata/index/{collection}.
400K9O_INVALID_FILTERThe embedding does not match the column, or a where value is invalid.
401K9O_INVALID_CREDENTIALSThe caller is not authenticated.
403K9O_ACCESS_DENIEDThe caller has no read access to the collection (the record read's own gate).
403K9O_EXTENSION_PERMISSION_DENIEDAn extension token: the Metadata API is not extension-callable yet.
Response body (200)
data *object[]

The matching rows.

A query over several surfaces lists each surface's rows in the order the surfaces were named.

surface *string

The surface label the row came from, as sent.

scope *string

The surface's scope: the collection name, or the audit event type for telemetry.

recordIdstring

The record's id.

Present on collection rows only.

eventIdstring

The audit event's id.

Present on telemetry rows only.

metadata *object

For a collection surface: the record's declared metadata columns (see PUT /metadata/index/{collection}), keyed by column name, with each value as the record read returns it (string, number, boolean, null, or an array or object for array and jsonb columns).

A declared column the record read did not return is absent.

For a telemetry surface: the audit event as GET /audit-log returns it.

meta *any

Request metadata (request id, trace id, timing and cost) plus cursor.next: pass it as cursor to read the next page, or null when there is no next page.

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

Showing example in TypeScript

Request example
{
  "surface": "string",
  "column": "string",
  "embedding": [
    0
  ],
  "k": 0,
  "metric": "string",
  "where": [
    {
      "field": "string",
      "op": "eq",
      "value": "string"
    }
  ]
}
Response example (200)
{
  "data": [
    {
      "surface": "string",
      "scope": "string",
      "recordId": "string",
      "eventId": "string"
    }
  ]
}

More in Data, Queries & Vectors