/metadata/queryFilter Metadata
Create query. (Data, Queries & Vectors) POST /@:projectSlug/metadata/query.
| projectSlug * | path | The project's slug: the path segment after It is unique within the org. |
| surfaces * | string[] | The surfaces to read, at least one. A Together they may return at most 10,000 rows (413 above that). |
| where | object[] | Filters; every clause must match. On a collection surface, one clause per field. |
| field * | string | The field to filter on. On a collection surface, On a telemetry surface, |
| op * | "eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "contains" | "startsWith" | "endsWith" | "in" | "notIn" | "and" | "or" | "not" | The operator. A protected (encrypted) column allows only |
| value * | any | The value to compare with. Other operators take one string, number or boolean. |
| One of: string | ||
| or: number | ||
| or: boolean | ||
| or: null | ||
| or: any[] | ||
| limit | integer | Rows per surface. Default 100. A telemetry surface returns at most 200. |
| cursor | any |
Only with a single surface. |
| One of: string | ||
| or: null | ||
| HTTP | K9O Code | Description |
|---|---|---|
| 200 | Success | |
| 400 | K9O_INVALID_FIELD_VALUE | The body is malformed: an unknown field, a wrong type, or an unsupported where operator. |
| 400 | K9O_UNKNOWN_SURFACE | A surface is not collection:<name>, storage:<bucket> or telemetry:<eventType>. |
| 400 | K9O_METADATA_FIELD_NOT_INDEXED | A field is not a declared metadata field of the surface (ch04 §1.3.1); declare it with PUT /metadata/index/{collection}. |
| 400 | K9O_INVALID_FILTER | A where value is invalid for the column. |
| 401 | K9O_INVALID_CREDENTIALS | The caller is not authenticated. |
| 403 | K9O_ACCESS_DENIED | The caller has no read access to the collection (the record read's own gate). |
| 403 | K9O_EXTENSION_PERMISSION_DENIED | An extension token: the Metadata API is not extension-callable yet. |
| 413 | K9O_QUERY_RESULT_TOO_LARGE | The union of the surfaces' rows exceeds the cross-surface cap. |
| 501 | K9O_NOT_IMPLEMENTED | The storage slice is not available yet (object metadata has no query index). |
| 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. |
| recordId | string | The record's id. Present on collection rows only. |
| eventId | string | 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 |
// const k9o = new K9o({ orgSlug: 'playground', projectSlug: 'storefront', apiKey: 'k9o_…' })
const { data } = await k9o.metadata.filter({})Showing example in TypeScript
{
"surfaces": [
"string"
],
"where": [
{
"field": "string",
"op": "eq",
"value": "string"
}
],
"limit": 0,
"cursor": "string"
}{
"data": [
{
"surface": "string",
"scope": "string",
"recordId": "string",
"eventId": "string"
}
]
}