Columns

A column is one typed field of a collection. Each column is a JSON file in the collection's datahoster-collection-columns folder, named for the column: the key a record carries its value under.

<datahoster-config-contentRoot>/
  api.example.com/
    datahoster-collections/
      messages/
        datahoster-collection-columns/
          name.json       the "name" column
          email.json      the "email" column
          message.json    the "message" column
          handled.json    the "handled" column
A collection's columns, one JSON file each.

Contents

Inside a collection's datahoster-collection-columns folder, every column is one JSON file, named for the column. This page describes that file.

NameTypeDescription
name.jsonfileA column: its type, its default value and any limit.
email.jsonfileAnother column, the same shape as name.json.

name.json

One JSON object. Its keys are fixed names starting with datahoster-column-; the column's own name is the file name, not a key.

{
  "datahoster-column-name": "name",
  "datahoster-column-type": "text",
  "datahoster-column-default": "",
  "datahoster-column-max": 100
}
The name column: text, defaulting to empty, at most 100 characters.
NameTypeDescription
datahoster-column-nametextThe column's name. Must match the file name. Required.
datahoster-column-typetextOne of the column types. See below. Defaults to text.
datahoster-column-defaultthe column's typeThe value a record takes when an endpoint does not set this column. A column with a default is optional in an import record; one with no default is required there. Defaults to the type's own empty value.
datahoster-column-maxintegerMaximum length of a text value, in characters. A char type's size is fixed by its name, so it ignores this. Defaults to 8000.

datahoster-column-type

One of text, the fixed-size strings char8, char16, char32, char64, char128, char256, char512, char1024, or integer, number, boolean, int128. See the type reference for each. A value that fails its type (a non-numeric integer, a string too long for its char size) is rejected when an endpoint writes it, so every stored record is valid against the collection. Defaults to text.

A char type holds a fixed number of bytes of UTF-8, not characters: char8 is 8 bytes, char64 is 64, up to char1024 at 1024. Because they are fixed-width they are held in memory, so a char column can be filtered (including contains and prefix) and sorted like a number. Pick the smallest size a value fits, since the whole width is held in memory whether or not the value fills it. A text column is variable-length and kept on disc, read only when a record is returned, so it can be returned by a select but not filtered, sorted, or used in an endpoint's logic. Use a char size for a value you want to query, text for one you only store and return.

Automatic columns

Every collection carries three columns the server fills in for you. You do not define them and cannot write them, but an select endpoint may return, filter and sort on them like any other column. All three are held in memory (by is a short value kept in each record's metadata, not an on-disc text column), so all three can be filtered and sorted.

NameTypeDescription
idint128A unique id the server assigns to each record on insert. It is how update and delete endpoints name the record to change or remove. An import record may set its own id.
atnumberWhen the record was written, in milliseconds since 1970. Filter on it with the same millisecond value.
bytextThe user who wrote the record, or empty for a public write. An imported record carries the built-in user datahoster-import.