Tags

Tags are additional metadata that can be associated with a record. They provide extra search criteria for more detailed queries, either on their own or in combination with indexes. Unlike indexes, tags cannot be queried with conditional operators. The number of records is also tracked for each tag name.

To add tags to a record, you can use the config.tags parameter in the postRecord() method. This parameter accepts a string or an array of strings or string with comma separated values, allowing you to add multiple tags to a single record.

Adding Tags to a Record

Here's an example of how to add tags to a record:

let record = {
    title: "Dukkha",
    artist: "Asian Spice House",
    tracks: 7
};

let config = {
    table: {name: 'Albums', access_group: 'public'},
    index: {
        name: "year",
        value: 2023
    },
    tags: ['Indie', 'Experimental']
}

skapi.postRecord(record, config);

DANGER

Tag validation rules:

• Maximum length: 64 characters per tag
• Must not be empty
• Must not include control characters or sentinel 􏿿

Querying Records by Tag

You can also utilize tags in your queries.

Example below lists albums released after 2020, that have the tag 'Experimental'.

skapi.getRecords({
    table: {name: 'Albums', access_group: 'public'},
    index: {
        name: "year",
        value: 2020,
        condition: '>'
    },
    tag: 'Experimental'
}).then(response=>{
    // List of albums released after 2020, that have the tag 'Experimental'.
    console.log(response.list);
});

The tag in a record query is matched exactly, and no condition widens it: the prefix search described below belongs to getTags(), not to getRecords(). When one thing has been tagged more than one way, Experimental and Experimental Rock for example, a query on one of those spellings returns only that spelling's records and reports its count as though it were the whole set. List the spellings first with getTags({ table, tag, condition: '>=' }), then query each one and merge the results yourself.

TIP

To query multiple tags simultaneously, you can make multiple API calls and await them all at once in Javascript Promise.all(). Then you may sort the data as you wish.

Following Example below shows fetching albums with the tag 'Experimental' OR 'Indie'

let experimental = skapi.getRecords({
    table: {name: 'Albums', access_group: 'public'},
    tag: 'Experimental'
})

let indie = skapi.getRecords({
    table: {name: 'Albums', access_group: 'public'},
    tag: 'Indie'
});

Promise.all([experimental, indie]).then(res=>{
    let experimental = res[0].list;
    let indie = res[1].list;

    let or_list = {};
    for(let r of experimental) or_list[r.record_id] = r;
    for(let r of indie) or_list[r.record_id] = r;

    // 'Experimental' OR 'Indie' in { [record_id]: record } format.
    console.log(or_list);
})

Fetching Tag Information

You can fetch all tags used in a table with getTags().

skapi.getTags({
    table: 'MyTable'
}).then(response=>{
    console.log(response); // List of all tags in table named 'MyTable'
})

This call gives no condition, and that is what makes it a listing. When only table is given, the omitted condition defaults to >=, a prefix search on the tag name, and with no tag to prefix it matches every tag in that table.

When both table and tag are given and condition is omitted, the default is an exact match on the tag instead.

Calling getTags() with no argument at all, or with an empty query object, returns every tag in the project, ordered by record count, descending. That is the widest listing there is:

skapi.getTags().then(response=>{
    console.log(response); // Every tag in the project, most used tag first
})

Given only a tag and no table, the same >= default runs across the whole project, so the call finds that tag in every table that uses it:

skapi.getTags({
    tag: 'Experimental'
}).then(response=>{
    console.log(response); // The tag 'Experimental', in every table it appears in
})

So the combinations are:

• neither table nor tag: every tag in the project, ordered by record count, descending.
• table alone: every tag in that table.
• tag alone: that tag across all tables.
• table and tag: an exact match on that tag in that table.
• table, tag and condition: '>=': every tag in that table whose name starts with the value.
• condition with neither table nor tag: rejected with "table" or "tag" is required for condition.

skapi.getTags({ condition: '>=' }); // Error: "table" or "tag" is required for condition.

Who can read tag information

When the project's Require Login setting is on, getTags() is refused to a visitor who is not signed in. The SDK throws REQUIRE_LOGIN before the request leaves the browser, and the backend refuses the same call with INVALID_REQUEST, so a direct API call or an older SDK with no gate is refused as well. A project that has never set that option counts as on. Tag metadata used to be served to anyone who knew the project ID, so an integration that reads it without a signed in user now gets an error.

WARNING

The tag listing is not filtered by access group, and cannot be. A tag is stored as one row keyed by the tag and the table name, with the access group left out of the key, so number_of_records counts the records in every access group together. Any caller allowed to read the listing reads the whole project's tag vocabulary, including tags carried only by private or admin records, and their cross group counts.

The records themselves stay gated: a tag tells a signed in user that records exist, not what is in them. Still, treat a tag name as visible to every signed in user, and do not encode anything sensitive in one.

For more detailed information on all the parameters and options available with the getTags() method, please refer to the API Reference below:

getTags(query, fetchOptions?): Promise<DatabaseResponse<Tag>>

Querying tags

You can also query tags that meets the condition.

skapi.getTags({
    table: 'MyTable',
    tag: 'A',
    condition: '>'
}).then(response=>{
    console.log(response); // List of all tags starting from 'A' in table named 'MyTable'
})

In this example, the condition property is set to >, and tag is set to A. This query will return the tag names that come after tag 'A' in lexicographic order, such as 'Ab', 'B', 'C', 'D' and so on.

To list only the tags whose name starts with 'A', set condition to >=, which is a prefix search.

While you are exploring and do not know the exact spelling, pass >=. Because it is a prefix search it surfaces related entries: in real data a tag very often carries a leading name shared with the rest of its data set, a series name for example, or an entity recorded once plainly and once with a parenthesised alias, such as a tag Asian Spice House and a tag Asian Spice House (alias). An exact match finds one spelling and silently misses its siblings, while the prefix finds the whole family. When you already know the exact name, give both table and tag and omit condition: that is the exact match you want.