Skip to main content
GET/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, like or ilike pattern may be at most 256 characters;
  • a jsonPath may be at most 512 characters;
  • an in or notIn list 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.

Parameters
collection *path

The collection's name.

projectSlug *path

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

It is unique within the org.

Responses
HTTPK9O CodeDescription
200Success
400K9O_INVALID_FIELD_VALUEA 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).
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_EXPIREDYour session has expired; sign in again to query data.
401K9O_INVALID_CREDENTIALSThe credentials provided are not valid; the data query was rejected.
403K9O_ACCESS_DENIEDYour role does not permit reading from this collection.
403K9O_FIELD_REVEAL_DENIEDYou requested reveal of a protected field without supplying a purpose or without reveal authority (an administrator role or a fields.<column>.reveal grant).
404K9O_COLLECTION_NOT_FOUNDThe requested collection does not exist 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.

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

Showing example in TypeScript

Response example (200)
{
  "data": [],
  "meta": {
    "cursor": {
      "next": "string",
      "totalCount": 0,
      "countMethod": "none"
    },
    "warnings": [
      {
        "code": "string",
        "message": "string"
      }
    ]
  }
}

More in Data, Queries & Vectors