Organize Data

Grouping sets of values

Often it may be necessary to organize your preferences or settings by grouping them according to context, their purpose, or a project.

The API has ability to group or categorize submitted values. It is definitely advisable to somehow group or categorize your data items (either by project, or a domain, etc.) - but the need will clearly depend on your use case. There is a way to logically organize the data into groups.

Groupings can be: 'project', 'domain', 'subdomain', and 'list'. To assign a piece of data to a group (like domain, subdomain, project name, or a list), add the parameter to your /write? query.

Those are all optional values but they may help tremendously with your data queries later. A full list of reserved grouping parameters is listed below.

Grouping query example

The .write() action below will save the user selected (presumably!) theme and store email addresses collected via a landing page for a project "my_app" and a domain (domain as in "knowledge domain") we called "front-page".

prefs_us.project("my-app")
    .domain("front-page")
        .key("theme")
            .write("default-dark");

prefs_us.project("my-app")
    .domain("front-page")
        .list("waiting-list")
            .add("janedoe@someplace.com");

The above query creates a list called "waitinglist" within the project named "my_app" and domain "front-page". As one could expect, a project can contain any number of domains, lists, or domains.

The theme settings can then be retrieved with a .read() query:

let theme = null;

prefs_us.project("my-app")
    .domain("front-page")
        .key("theme")
            .read( (R)=>{
                if (R.success) {
                    theme = R.value;
                }
            });

Reserved keywords

The following keywords are used to identify a group of values. The keywords are all very abitrary - they are plain strings, and there is no meaning behind the names, and there is no naming convention. Their purpose is only to help with organization of the data. They can be combined together, so a domain can have several projects, or a single project several domains, it really is up to you, the developer, to decide how to organize the data for your own benefit.

Key name	Description
project	grouping variable
domain	grouping variable
subdomain	grouping variable
type	[reserved]
list	grouping variable; creates a list type collection

What are Lists?

Lists basically are collections of data grouped by a list name where duplicate keys are allowed. Submitted values with a duplicate key would typically be overridden. Unless (!) they are stored in a list. Lists are created by adding &list=[listname] parameter to your /write queries.

For instance, let's say we have a landing page for a product which collects emails of users interested in being notified about product updates. Normally, to save an email we'd simply send it to the write API:

prefs_us.project("my-app")
    .key("email")
        .write("janedoe@someplace.com");

Great! The problem is that if a field "email" already exists, this would update the email value with the new address - no duplicates rule. key/value pairs are by all means mutable. The seconds write operation (as shown below) will replace the existing value.

prefs_us.project("my-app")
    .key("email")
        .write("june.bug@whereever.com");

We don't want that. We want to collect multiple emails for out waitlist. To achieve that, we create a list called user-emails, by adding .list() command (is 'comand' the right term?):

prefs_us.project("my-app")
    .list("user-emails")
    .key("email")
        .write("june.bug@whereever.com");

Our list will now contain two email addresses.

The full list can be retrieved with a simple .read() query:

let myList = null;

prefs_us.project("my-app")
    .domain("front-page")
        .list("waiting-list")
            .read( (R)=>{
                if (R.success) {
                    myList = R.values;
                }
            });