Model your data: entities, fields, relations

Your data model is the set of entities and fields in your project. An entity is a table. A field is a typed column on it. When you create or change either one, Anythink changes the database and your REST API in the same step. There is no migration to write and no deploy to wait for.

This page walks through the whole life of a data model: creating entities, adding fields, setting constraints, linking entities, changing things later, and the limits to design around.

Create an entity

Create one entity per kind of thing you store: customers, orders, blog_posts.

anythink entities create customers

Creating entity 'customers'...
✓ Entity customers created (id: 653).

anythink entities get customers

Create an entity called customers.

Name rules

Use plural, snake_case names. The name appears in your API paths (/entities/customers/items) and in permission names (customers:read), so it's worth choosing well.

What gets created

Creating an entity sets up three things at once:

• A database table named after the entity, with an auto-incrementing id and created_at and updated_at timestamps that Anythink manages. These system fields are locked: you can't edit or delete them.
• A REST API for the entity: list, get, create, update and delete endpoints, available as soon as the entity exists. See Call the instant REST API.
• Four permissions: customers:read, customers:create, customers:update and customers:delete. Administrator roles get all four automatically. Every other role gets none, so grant them under Roles and permissions before your app's users can call the API.

Entity options

Add fields

Add one field per piece of information you want on each record. An entity with no fields beyond id and the timestamps can't hold much, so this is where the model takes shape.

anythink fields add customers email --type varchar --unique --required
anythink fields add customers notes --type text
anythink fields add customers plan --type varchar --display select --options "Free,Pro,Team"
anythink fields add customers signed_up_at --type timestamp

✓ Field email (id: 3163) added to customers.

Add these fields to customers: email (unique, required), notes (long text), plan (a select with Free, Pro and Team) and signed_up_at (timestamp).

Field names

Field names follow the entity rules, with two extra restrictions: you can't use id, locked, created_at or updated_at (or other names Anythink reserves for itself), and a name can't start with anythink. A name is permanent once the field exists, and so is its type.

A Label is the friendly name shown in the dashboard (up to 100 characters). A Description is a note for your team (up to 500 characters). Neither changes the API.

Field types

Choose the type by what the value is. The type decides how the value is stored, and which display types you can pick.

Choosing a type:

• Money and measurements. Use decimal, not a float: it keeps exact values. For prices you can also store whole pence or cents in an integer or bigint.
• Counts, ages and IDs. integer. Use bigint for very large numbers such as epoch timestamps.
• Short strings you filter on. varchar with select for a fixed list of choices, such as a status.
• Anything longer than a line. text, with rich-text if editors need Markdown.
• When something happened. timestamp. Use date only when the time of day is meaningless, such as a birthday.
• Free-form structure. jsonb, when the shape varies between records and you don't need to filter on its contents.

Types that point at other data (file, user, the four relationship types and dynamic-reference) are covered in Link entities with relationships and in Upload and manage files. For a longer description of each type, see Field types reference.

Display options

The display type controls how the field looks in the dashboard's forms and grids. It doesn't change the stored value or the REST API. Each display type has its own options, set in the Create New Field drawer or through the options object of the API.

Give a select field its choices in one go from the CLI. A plain list uses each word as both label and value. Use label=value to store something different from what people see:

anythink fields add orders status --type varchar --display select --options "Pending=pending,Shipped=shipped,Delivered=delivered"

Tick Multiple (CLI: --multiple) to let one record hold several choices. Anythink then stores the field as an array (varchar[], integer[] or decimal[], matching the type you picked).

anythink fields add customers interests --type varchar --display select --multiple --options "Running,Cycling,Rugby"

Required, unique, indexed and name field

These switches sit on every field. Some are about data quality, some about speed, and some about how a record is shown.

Things to know:

• Choose Unique and Indexed when you create the field. Unique is applied to the database as the column is made, so decide it up front.
• Unique and nulls. Unique compares values, so any number of records can leave an optional unique field empty.
• Defaults fill old records. When you add a field with a default value to an entity that already has records, existing records get the default. Without one they get an empty value. Boolean fields default to false.
• Required relationships. A required relationship field can't use Set null for its on-delete behaviour, since that would empty a required value.
• Pick one name field per entity. Choose the field that makes a record recognisable at a glance: a title, a name or a reference.

Searchable fields feed Search records across your entities, which also covers public search.

Link entities with relationships

A relationship is a field that points at records of another entity: an order belongs to a customer, a post has many tags. You create one by adding a field of a relationship type.

Each relationship field asks for a target entity and an on-delete behaviour: what happens to a record when the record it points at is deleted. The choices are CASCADE (delete it too), SET NULL (clear the link), RESTRICT (refuse the delete) and SET DEFAULT. The CLI defaults to CASCADE.

anythink fields add orders customer --type many-to-one --target customers --on-delete "SET NULL"

The REST API stores the id of the related record in the field, and can expand and filter on related records. The relationships page covers every type in depth, including how to read, write and filter linked records: Connect entities with relationships.

Edit fields and entities

You can change a data model whenever you like. The API updates as soon as you save.

Edit a field

Edit an entity

Select the entity in Settings › Data Model, then select Edit to change Enable Row-Level Security, Public, Lock New Records or Lock Schema. The name stays fixed. With the CLI:

anythink entities update customers --rls true --public false --lock-records false

Turning on row-level security hides records that have no grants. Read Groups and row-level security before you switch it on for an entity that already holds data. Lock New Records affects only records created after you turn it on.

Delete an entity

Deleting an entity permanently removes the entity, every record in it, its search index, and its four permissions. Its API endpoints stop working at once and return 404.

anythink entities delete temp_data --yes

Delete the temp_data entity and everything in it.

Field order and display

Fields appear in the dashboard's record form and grid in the order you set. Drag them into the order you want.

anythink fields list customers
anythink fetch /entities/customers/fields/reorder --method PUT \
  --body '[{"field_id": 3163, "sort_order": 1}, {"field_id": 3164, "sort_order": 2}]'

On customers, put email first, then plan, then notes.

Read the model from your app

Your app can read the model it sits on: an entity with its fields, how its fields and relationships are laid out, and the workflows a user can start from its records. All three calls need anythink_entities:read, and they only show fields your role is allowed to see.

anythink fetch /entities/id/365
anythink fetch /entities/orders/hierarchy
anythink fetch /entities/orders/workflows

GET /org/{project_id}/entities/orders/hierarchy

Show me how the orders entity connects to other entities.

Limits

Next steps

• Connect entities with relationships: link records across entities and filter on them.
• Field types reference: a longer description of every field type.
• Call the instant REST API: read and write records through the API your model generates.
• Roles and permissions: give your users access to the entities you create.
• Groups and row-level security: show each user only their own records.
• Search records across your entities: make fields searchable.
• Upload and manage files: add file fields.