Start
Collections and fields
Define collection fields, relations and indexes, inspect the schema graph and understand upload and database limits.
By the end of this guide, you will know how to shape a collection, add fields safely and choose relations, indexes and file references for your database.
1. Define fields in the data model
Open Settings → Data model to build fields, relations and indexes. Collection pages focus on records. Collections are real SQL tables. Kanesh supports seven scalar types plus file and image references. The query contract explicitly names string, text, datetime and json; check the active adapter’s capabilities for its supported field types and storage changes.
Authorized clients can read GET /api/v1/workspaces/:workspace/capabilities. Studio uses this metadata during collection setup.
Every collection exposes read-only system fields:
| Field | Behavior |
|---|---|
id | System-managed record identifier. Imports generate new IDs. |
created_at | Server-managed UTC RFC3339 creation timestamp. |
updated_at | Server-managed UTC RFC3339 update timestamp. |
Note: Schema version 2 preserves unknown timestamps on old records as null. Resolve custom fields using the reserved timestamp names before upgrading.
Optional fields can be added to populated collections. Adding a required field needs an empty table. Existing populated-field conversions and primary-key changes remain planned.
2. Choose relations or read-only lookups
On SQLite and PostgreSQL, N:1, 1:N and N:N relations use managed junction tables with real foreign keys and cardinality constraints. Link updates are explicit, atomic, scoped to the workspace and capped at 100 targets; N:1 permits one. Inverse aliases and nested GraphQL relation writes are not available yet.
Read-only lookups are separate: they match a string field to another record’s ID and expose selected related fields. They do not establish foreign-key constraints. See REST API for query limits.
3. Add managed indexes
SQLite and PostgreSQL support up to 16 additional managed indexes per collection. Each uses 1–4 ordered regular fields and can be unique. Owner/admin permission is required, and primary indexes are protected.
Existing duplicate values reject unique index creation atomically. Indexes add storage and write cost, so choose fields that match your queries. Online index creation is unavailable. Storage changes that would orphan saved lookups or discard SQLite indexes are blocked.
4. Inspect the schema graph
Studio settings include an authorized schema graph with saved lookups, search, focus, zoom and collection/connection details. Related columns can reuse the saved mappings. Authorized clients can read scoped metadata and index capabilities through GET /api/v1/workspaces/:workspace/schema-model.
5. Use file and image fields
file and image fields reference authorized workspace uploads, stored in the database or in S3. The limit is 2 MiB per file. PNG, JPEG, GIF and WebP images are supported up to 16M pixels.
Downloads require authentication; generic content is served as an attachment. The picker lists the 50 most recent files. REST and scalar GraphQL writes validate file references.
Note: CSV/JSON transfers contain file IDs, not binary files or relation links.
Troubleshooting
- A required field cannot be added: required additions need an empty collection; optional additions work on populated collections.
- A unique index fails: check for duplicate values in its selected fields.
- An upload is rejected: check the 2 MiB file limit and, for images, the format and 16M-pixel limit.