Creating collections and fields

Field types, technical columns and the rule that a collection only grows.

A collection is a set of data with fixed fields. The agent creates it with ensure_collection and extends it later with the same call. In production one rule holds without exception: a collection only grows. So plan names and types before you build.

Starting in the practice room

Build a collection in the practice room first. A token for the practice room creates and extends freely there. What is created then waits in the admin area under Apply schema changes until a person carries it over to production (Carrying over from the practice room).

As long as a field or a collection has never been in production, the agent can discard it in the practice room with discard_field and discard_collection. After that the rule of production applies.

Field types

Type	Content	Filter	Sort
`text`	short text, at most 1000 characters	yes	yes
`longtext`	long text, at most 100,000 characters	only for empty	no
`integer`	whole number	yes	yes
`decimal`	decimal number with four decimal places, exact	yes	yes
`boolean`	yes or no	yes	yes
`date`	date	yes	yes
`datetime`	point in time, stored in UTC	yes	yes
`choice`	one value from a fixed list	yes	yes
`reference`	link to a row of another collection	yes	no
`person`	link to a person of this instance	yes	no
`context`	a value of a context, for example a site	yes	no

There are no other types. Which operators a type allows in a filter is described under Reading and writing data.

A field is required or optional. Think about this carefully: a tool that does not send a required field gets an error.

References, people and contexts

reference points to exactly one row of another collection. The value is the id of that row. Never model a link as text holding an id: switching later would be a change of type.
person stores the id of a person, never their name. A name changes, the id does not. A person exists only after their first sign-in.
context holds a value of a context the administration maintains (Contexts). A collection has at most one such field. The scope context on a permission relies on it.

Technical columns

Every row carries five columns that you do not create and do not write yourself:

Column	Meaning
`id`	the id of the row, which a reference points at
`created_by`	who created the row. The scope `own` relies on it
`created_at`	when it was created
`updated_at`	when it last changed
`version`	goes up with every change. Every write states it

A field cannot have the name of one of these columns.

What is not possible

Deleting a field or a collection. Nothing disappears in production.
Changing a type. text never becomes reference, integer never becomes decimal.
Removing a value from a choice list. Values are added, none goes away.

Renaming and deprecating

A person does both in the admin area, on the page of the collection (Structure).

Rename a field: the field gets a new name, and the old name keeps working. A tool that still sends the old name carries on. Answers always use the current name.
Deprecate: a deprecated field takes no new values, existing ones stay readable. A tool that still sends it gets an error naming the field. Deprecating can be undone. A whole collection can be deprecated too: it then takes no new rows.

Purpose and retention period

A new collection states its Purpose (what your organisation processes the data for, one or two sentences) and its Retention (a number of months or unlimited). Without both the instance does not create the collection. They come from you, not from the agent.

Permissions

A new collection has no permissions. Pass a role to ensure_collection with grantTo, or grant the permission afterwards (Granting permissions).