Collections, filters and totals

Create collections, read and write records, filter, count and total.

Collections

You create collections, each with its safety rule; the SDK never does. Locally, use npx gemmein collection add <name> or the dev terminal. On Gemmein, use the dashboard's Data (one click), or carry them there with npx gemmein sync.

Names are lowercase letters, numbers, and underscores only (saved_games, never savedGames), and a bad name throws synchronously.

const tasks = g.collection("tasks")

const task = await tasks.create({ title: "Buy milk", done: false })
console.log(task.id, task.data.title)          // fields live under .data

const { records } = await tasks.list()      // { records, cursor, hasMore }
const recent   = await tasks.list({ limit: 10, sort: "newest" })
const filtered = await tasks.list({ where: { done: false } })   // a filter — see below
const one      = await tasks.get("rec_abc123")
await tasks.update("rec_abc123", { done: true })
await tasks.delete("rec_abc123")

Your fields live under data. Everything else on a record is set by the server and read-only:

Filters, counts and totals

A where names up to 5 of your data fields (link fields too), and every field must match. A field's value is a literal, an exact match, or an object of operators, 1 to 3 per field, every one of which must hold:

await orders.list({ where: { amount: { gte: 10 } } })
await orders.list({ where: { status: { in: ["paid", "sent"] } } })
await orders.list({ where: { title: { contains: "invoice" } } })
await orders.list({ where: { dueAt: { lt: "2026-10-01" } } })

const open = await orders.count({ where: { status: "open" } })                // a number
const paid = await orders.stats("amount", { where: { status: "paid" } })  // { count, sum, avg, min, max }

The same grammar serves list, watch, count and stats, and a relay's when and where. Server-managed fields are refused. A where outside the grammar is 400 invalid_filter, and the message names the field and the operator.

In a live collection with fixed fields, a field's default is read by eq, ne, in and nin; the ordered operators, contains, startsWith and exists read the stored value only.

• count({ where?, search? }) answers how many records this person could list, under the same safety rule, scope and filters, without paging them.
• list({ count: true }) adds the total to a page: total, exact up to 10,000, or past that totalAtLeast: 10000 (show "10,000+"). It counts under the same safety rule, filters and search as the page, reads at most 10,001 records, rides the first page only (a page fetched with cursor carries none), and is refused on a since delta (400 invalid_count).
• list({ author: "me" }) or list({ author: userId }) lists one person's records on shared, community, public_read and direct, inside the reader's own scope, so it only ever returns fewer records. On private, addressed and admin_write it is 403 author_not_visible. ownerUserId stays refused in where; author is the filter for it.
• stats(field, { where?, search? }) reduces one numeric field over the same records. count is how many held a number there (a record whose field is missing or not a number is skipped). sum, avg, min and max are null when none did. A sum past 2⁵³ is answered as a string.
• Neither pages its results, so since, sort, cursor, limit and expand are refused (400 invalid_count / 400 invalid_stats).
• A stats field name starts with a letter and uses only letters, digits and underscores; anything else is 400 invalid_stats.
• Both share list's read rate limit, and each call counts as one read for a secret key.

The grammar has no or group and no sort by a data field; search is a case-insensitive substring match over stored text; stats reduces one field per call.