> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devias.io/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> The docs are served at https://docs.devias.io. Every path in these docs is relative to that root: /llms.txt is https://docs.devias.io/llms.txt.
> Devias is an open-source platform that works as an operating system for a business: a core (records, views, workflows, agents, permissions) with installable modules.
> Pages are typed by folder. concepts/ explains what things are, guides/ gives procedures, reference/ is exhaustive (SDK, CLI, HTTP API), operate/ covers hosting. Use /start/glossary for exact terms.
> Every id in a module (module, object, field, view, action, workflow, step, connection, variable, event, policy) is a uuid. Generate them with `devias id <count>`. Never invent dotted or readable ids.
> Run `devias plan` and read its output before `devias apply`. Apply only what the plan says.
> The OpenAPI document, including the routes of the modules in the reference setup, is at /reference/api/openapi.json.
> Devias is young and changes quickly. If a page and the source repository (github.com/devias-io/devias) disagree, the repository is right.

# SDK records and queries

> How to read and write records with the TypeScript SDK. Covers records.create, get, update, delete, upsert and import, the q() query builder with select, where, orderBy, limit, cursor, include, search and count, every filter helper, cursor paging, lookup and aggregate.

Records are addressed by the **API name** of their object, such as `'person'`. Every method returns a promise.

## Create, read, update, delete

```ts theme={"dark"}
const ada = await client.records.create('person', { first_name: 'Ada', last_name: 'Lovelace' });

const same = await client.records.get('person', ada.id);

await client.records.update('person', ada.id, { last_name: 'King' });

await client.records.delete('person', [ada.id]);
```

`delete` takes a list of ids, so several records can be removed at once.

Two more write methods avoid a separate read:

* `upsert(object, match, values)` updates the record whose unique field matches, or creates one, and tells you which it did.
* `import(object, body)` writes the rows of a CSV, reporting any that are invalid by row.

## Ask for records

`records.list` takes a **query**, built with `q()`, a chainable builder.

```ts theme={"dark"}
import { q } from '@devias/sdk';

const page = await client.records.list(
  q('person')
    .where((f) => f.contains('first_name', 'a'))
    .orderBy('first_name', 'asc')
    .limit(10)
    .build(),
);

page.items; // the records
page.nextCursor; // pass it to .cursor() for the next page
```

| Step | What it does |
| - | - |
| `select(...fields)` | Return only these fields. |
| `where(build)` | Keep records that match. Combine conditions with `f.and` and `f.or`. |
| `orderBy(field, direction)` | Sort. Call it again to sort by more. |
| `limit(n)`, `cursor(c)` | Page through results. |
| `include(relation)` | Also return the records a relation field points at. |
| `search(text)` | Match a word across the searchable fields. |
| `count()` | Also return the total number of matches. |

## Filters

Filters are built with helpers named after what they check: `eq`, `neq`, `in`, `notIn`, `lt`, `lte`, `gt`, `gte`, `between`, `contains`, `startsWith`, `isEmpty`, `isNotEmpty`, `anyOf` and `allOf`. Combine them with `and`, `or` and `not`.

```ts theme={"dark"}
f.and(f.eq('stage', 'customer'), f.or(f.contains('last_name', 'king'), f.isEmpty('email')))
```

## Page through everything

A page carries a `nextCursor` while there is more. Keep passing it back until it is `null`.

## Other helpers

* `lookup` finds records by what a person types, for pickers.
* `aggregate` counts and totals records, in groups or overall.

## Related

* [Querying records](https://docs.devias.io/reference/api/querying.md): the same query as JSON.
* [Metadata and modules](https://docs.devias.io/reference/sdk/metadata-and-modules.md): read the schema.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.