/data/{collection}Query Records
Retrieves records from a named user-collection using cursor-based pagination and the full query-builder vocabulary:
- column filters (Supabase-style
?col=op.value) - column selection
- multi-column ordering
.single()assertion- range access
- OR groups
- aggregates
- embedded joins
- full-text search (
?textSearch=col:query) - vector/semantic search (
?vectorSearch)
All four query modes route through the _query credential and are subject to compiled RLS policies; filters compose as additional AND constraints that cannot widen visibility beyond the caller's auth context.
Returns K9O_COLLECTION_NOT_FOUND (404) if the collection does not exist, and K9O_MULTIPLE_ROWS_RETURNED (409) when .single() matches more than one row.
Filters are bounded:
- a
match,likeorilikepattern may be at most 256 characters; - a
jsonPathmay be at most 512 characters; - an
inornotInlist may hold at most 1,000 items.
Past a cap the read answers K9O_INVALID_FILTER (400) with context.reason operand_too_long or too_many_items and context.max.
The read runs under a time limit (10 seconds by default).
A read that runs past it answers K9O_QUERY_TIMEOUT (504) with context.timeoutSeconds, and nothing is returned.
On a protected column, eq and in are allowed only when the read returns that column as plaintext.
On a searchable column that needs a reveal purpose, the same read must reveal it (reveal=<column>&revealPurpose=...), and it is audited as a reveal even when no row matches.
Without that reveal the read answers K9O_ENCRYPTED_COLUMN_OPERATION_UNSUPPORTED (400) with context.reason: "reveal_required".
An aggregate carries no reveal, so it refuses the same way.
| collection * | path | The collection's name. |
| projectSlug * | path | The project's slug: the path segment after It is unique within the org. |
| HTTP | K9O Code | Description |
|---|---|---|
| 200 | Success | |
| 400 | K9O_INVALID_FIELD_VALUE | A filter, select or order expression is invalid, or the vectorSearch column does not exist on the collection, is not a vector column (reason not_a_vector_column), or holds a different dimension than the query vector (reason dimension_mismatch). |
| 400 | K9O_INVALID_FILTER | A 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. |
| 400 | K9O_ENCRYPTED_COLUMN_OPERATION_UNSUPPORTED | The 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"`). |
| 401 | K9O_SESSION_EXPIRED | Your session has expired; sign in again to query data. |
| 401 | K9O_INVALID_CREDENTIALS | The credentials provided are not valid; the data query was rejected. |
| 403 | K9O_ACCESS_DENIED | Your role does not permit reading from this collection. |
| 403 | K9O_FIELD_REVEAL_DENIED | You requested reveal of a protected field without supplying a purpose or without reveal authority (an administrator role or a fields.<column>.reveal grant). |
| 404 | K9O_COLLECTION_NOT_FOUND | The requested collection does not exist in this project. |
| 504 | K9O_QUERY_TIMEOUT | The read ran past its time limit and returned nothing. `context.timeoutSeconds` gives the limit; narrow the filter or simplify a pattern. |
| data * | any | A page of records; a single record with |
| 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. |
| cursor | object | Pagination. Present on a list answer; absent with |
| next * | any | Opaque cursor for the next page; pass it back as Null on the last page, and always null with |
| One of: string | ||
| or: null | ||
| totalCount | any | The filtered row count when Absent with |
| One of: integer | ||
| or: null | ||
| countMethod | "none" | "exact" | "estimated" | The Absent with |
| warnings | object[] | Present only when a warning applies. |
| code * | string | A warning code. This read adds |
| message * | string | A readable explanation. |
// const k9o = new K9o({ orgSlug: 'playground', projectSlug: 'storefront', apiKey: 'k9o_…' })
const { data } = await k9o.from('products').select()Showing example in TypeScript
{
"data": [],
"meta": {
"cursor": {
"next": "string",
"totalCount": 0,
"countMethod": "none"
},
"warnings": [
{
"code": "string",
"message": "string"
}
]
}
}