Skip to main content
POST/metadata/search

Search Metadata

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

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.

field *string

The declared text column to search, as metadata.<column>.

Not a protected column.

q *string

The full-text search terms.

limitinteger

How many rows to return, as the record read's limit.

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}.
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.search({})

Showing example in TypeScript

Request example
{
  "surface": "string",
  "field": "string",
  "q": "string",
  "limit": 0
}
Response example (200)
{
  "data": [
    {
      "surface": "string",
      "scope": "string",
      "recordId": "string",
      "eventId": "string"
    }
  ]
}

More in Data, Queries & Vectors