Skip to content

Schemas, collections and records

Three ideas carry everything in civex. People new to it mix up the first and the last, so here they are in plain words before anything else.

Schema   Collection   Record

These colours are used wherever the docs name the three.

A blank form, a binder, a filled-in form

A schema is a blank form. When you design the form you decide the boxes (fields) and what is allowed in each box (rules): "Depth, a number, in metres, not below 0". You design it once.

A record is one filled-in copy of that form. Every time you have another sample, you fill in a new copy. You don't redesign the form.

A collection is the binder the filled-in forms go in. Forms of any kind go in any binder. One per study, site or season, as suits you.

flowchart LR
    T["Schema<br/><i>blank form, designed once</i>"]:::rt -->|is the form for| R["Record<br/><i>one filled-in form</i>"]:::rec
    C["Collection<br/><i>the binder</i>"]:::coll -->|holds| R
    classDef rt fill:#dbeafe,stroke:#1e3a8a,color:#1e3a8a
    classDef coll fill:#fef3c7,stroke:#78350f,color:#78350f
    classDef rec fill:#dcfce7,stroke:#14532d,color:#14532d
How many Looks like Made where
Schema A handful per project Sample, Site, Visit New schema… in a collection (its own button, apart from New) takes you to the Schemas page with the collection remembered; or Schemas in the sidebar
Collection One per study or season survey-2024 Collections → New collection
Record Hundreds or thousands Sample 03, North Ridge Inside a collection: New ▸ Sample

Which one do I want?

Ask yourself about the thing you're about to create:

  • Can you say "a ___"? "A sample", "a site", "a visit". That is a schema. You will have a few of them in the whole project.
  • Is it "this ___"? "Sample 3", "the North Ridge site", "the visit on 15 March". That is a record. You will have hundreds.
  • Does it have the same boxes as something you already have? Then you want a new record of that type, not a new type.

If you're making a new schema every time you add data, stop

You want New ▸ Sample inside your collection. A schema is the form, not the data. A project with one schema per measurement has no way to list, filter or export them together; a project with one Sample type and five hundred sample records does.

Types that go inside other types

A schema can be designed to sit inside another: a Visit goes inside a Site, a Sample goes inside a Visit. Then every sample record you add is filed under the visit it belongs to, and can show and filter on the visit's and the site's fields without you typing them again.

flowchart LR
    S["Site"]:::rt --> V["Visit"]:::rt --> P["Sample"]:::rt
    s1["North Ridge"]:::rec --> v1["2024-03-15"]:::rec --> p1["Sample 01"]:::rec
    v1 --> p2["Sample 02"]:::rec
    s1 --> v2["2024-04-02"]:::rec --> p3["Sample 01"]:::rec
    classDef rt fill:#dbeafe,stroke:#1e3a8a,color:#1e3a8a
    classDef rec fill:#dcfce7,stroke:#14532d,color:#14532d

The top row is the three schemas. Everything below is records. Where you press New schema… decides the nesting: inside a site it starts a schema that goes inside sites. It can't be moved later.

The same example everywhere

The rest of the docs use this one example, a field survey:

Schema Its fields Goes inside
Site name, location —
Visit visited on, team, notes Site
Sample number, depth (m), taken at, photo, reading Visit

Collection: survey-2024. Records look like North Ridge › 2024-03-15 › Sample 03.

Next: Five-minute tour →