Skip to main content

Label API

Use the Label API's actions to manage labels, lookup lists, and tag sets

FairCom's label actions manage labels, lookup lists, and tag sets. They speed up application development by codifying the best practices for using lookup lists and tag sets. They eliminate the mundane work of creating tables and indexes in the database to manage labels, lookup lists and tag sets; instead, your application can use these simple label actions.

Table 1. Label API actions

Action

Description

createLabel

Creates a new label.

alterLabel

Alters an existing label.

changeLabels

Change many labels, including permanently deleting labels.

listLabels

Lists the existing label names for a given filtering criteria.

listLabelGroups

Lists the existing "label group" names.



Label API

Label API

Use cases

You can use labels to do a wide variety of things:

  • Organize information.

    • Create as many labels as your application needs.

    • Use labels to create lookup lists and tags.

    • Tag records with labels.

    • Assign lookup lists to fields in a table.

    • Use the Label API to dynamically update lookup lists and tags during an application upgrade. No database schema changes are needed.

    • Use the Label API to create, manage, group, and rename labels at runtime.

    • Allow your customers to manage labels and lookup lists.

    • A label's "id" never changes, but your application can change all other label properties, including its name, group, value, description, enum, sequence, status, and metadata.

    • Change label properties as desired to evolve the meaning of a label and redefine how the application uses it.

  • Find records that match specific labels.

    • Create one or more label fields in an application table.

      • A label field categorizes a record, such as its brand, cost category, or material.

      • Create a label group for each type of label field in a table, such as its color, size category, or rating.

      • In your application code, associate a different label group to each label field.

      • Index each label field with a b-tree index.

      • In each label field in an application, store the integer identifier of a specific label record in the FairCom label table.

    • Allow users to update label fields in an application table.

      • Let a user choose labels by name from the field's label group.

      • Use the "listLabels" action to return the "id" of the user's selected label.

      • Store the selected label "id" in the field.

    • Allow users to query a table's labels.

      • Allow users to choose a label by name from a field's label group.

      • Use the "listLabels" action to retrieve the selected label's "id".

      • Add the "id" to a query filter.

      • Use SQL or JSON DB's "getRecords..." actions to query the data.

  • Categorize a record using many tags.

    • Create one or more multi-value label fields in an application table.

      • A multi-value label field labels a record with zero or more labels.

      • A multi-value label field is a JSON field that contains an array of integer identifiers.

      • Create a label group for each type of multi-value label field in a table, such as its color, size category, or rating.

      • In your application code, associate a different label group to each multi-value label field.

      • Index each multi-value label field with a full-text index.

      • In each label field in an application, store the integer identifier of a specific label record in the FairCom label table.

    • Allow users to update multi-value label fields in an application table.

      • Let a user choose multiple labels by name from the field's label group.

      • Use the "listLabels" action to return an "id" for each of the user's selected labels.

      • Add the selected label "id" values to a JSON array, such as [ 1, 32, 523, 4].

      • Store the JSON array in the multi-value label field.

    • Allow users to query a table by filtering on its multi-value label fields.

      • Allow users to choose multiple labels by name from a multi-value field's label group.

      • Use the "listLabels" action to retrieve the "id" values for the selected labels.

      • Create a SQL full-text query that contains each "id" selected by the user.

  • Create lookup lists.

    • An application typically uses many lookup lists.

      • A lookup list is a table containing "id" and "name" fields.

      • Some fields in application tables contain foreign keys to lookup tables.

      • The application stores a lookup "id" in each lookup field.

      • When an application queries a table, it joins the table to its lookup tables and retrieves the name associated with the "id".

      • Users see and use friendly lookup names while the application efficiently stores integer values.

      • This approach allows users to change the names of items in lookup lists without breaking queries and application code.

    • Rather than creating multiple lookup tables, an application can use labels to create lookup lists.

      • You can create a virtually unlimited number of lookup lists without creating tables.

      • SQL queries and JSON APIs can use these lookup lists.

      • A lookup list is a group of labels.

      • Each label associates an "id" with a name and value.

      • A label is an advanced lookup record that optionally includes additional application-defined properties including an enumerated integer, a sequence number to define the order of lookup items, a status to deprecate and undeprecate items, a description, and flexible metadata.

      • Use the "listLabels" action to quickly look up the label's "id" to return all information about a label.

      • Use the label "id" in SQL queries to join your tables to the label table in the FairCom database to display label properties rather than identifiers.

    • Allow users and applications to rename and change the label's name and other properties.

      • The "alterLabel" action makes it easy for an application to modify all label properties except for the immutable "id" property.

Additional label features

  • The FairCom server caches labels in application memory for fast processing.

  • You can also cache labels and lookup lists in your application.

  • Use SQL to join application tables to the label table in the faircom database to return meaningful values rather than "id" values.

  • Create as many labels and lookup lists as you want because the label "id" is a 32-bit signed integer ranging from 0 to 2147483647.

The FairCom MQ API uses this Label API to categorize MQ connections and topics.

Label data

The FairCom server stores label data in the label table in the faircom database. Each label has the following field names and matching JSON property names.

Table 2. Label data properties

Property Name

Description

Usage Examples

"id"

Uniquely identifies each label in the label table regardless of the value of the group.

Categorize records in application tables by storing a label "id" in fields that define its attributes, such as color, purpose, and ranking.

"group"

Assigns a label to a named group.

Organize labels into named lookup lists and tag sets.

"name"

Uniquely names a label within a label group.

Allow users to create an rename labels that your application uses for lookup lists and tags.

"value"

Associates a label with any JSON value.

Create lookup lists that associate names with values and let end-users modify the names and values.

"enum"

Specifies an application-defined integer identifier of a label within a group.

Assign an integer number to a label to match an enumerated value hardcoded in the application.

"sequence"

Defines the sort order of a label in a group.

Let users manage the sort order of a lookup list.

"deprecated"

Changes a label's status.

Let users deprecate and undeprecate labels.

"description"

Describes a label.

Use the description to show users how to use a label. Let users change the description to meet evolving usage of the label.

"metadata"

Adds JSON metadata to a label.

Store multiple language translations of the label's name and description, track change history, relate a label to other labels, etc.



Label table

Labels are stored in a table named label in the faircom database. You can join this table to other tables in your SQL queries.

Warning

You should not insert, update, or delete the data in the label table. Use the JSON label actions instead.

Fields

  • "id"

    • The "id" field is automatically created by the JSON DB API.

    • It is the surrogate primary key of the table.

    • FairCom and customer applications use the "id" field to join the label table with other tables. This allows a record to be assigned to a label.

    • For example, the FairCom server uses the "label_id" field in the mqtt_client and mqtt_topic tables to join records to the "id" field in the label table.

  • The "group" field organizes labels into groups. Customers can list labels by group. It defaults to the empty string "" so that it can be indexed well in the label_group_and_name index.

  • The "name" field uniquely identifies a label within a label group. It is required.

  • The "value" field allows applications to add a user-defined JSON value to the label. It is typically a JSON number, string, or object, but may be any valid JSON value. It defaults to null.

  • The "enum" field allows applications to add an integer number to a label. It defaults to null.

  • The "deprecated" field is a bit field that allows a customer to deprecate a label.

    • The server sets it to 0 to indicate the label is not deprecated.

    • The server sets it to 1 to indicate the label is deprecated. In other words it is marked as deleted or no longer in use.

  • The "sequence" field allows a customer to assign an order to the labels in a group. It is an unindexed, eight-byte floating point number. The customer can set it to any numeric value to control the order of labels. It is a floating point number so that a customer can change the label sequence by changing the sequence number of one label. For example, to move a label in between two other labels, a customer can assign a fractional number to the label that is in between the sequence numbers of two other labels. This allows a customer to reorder the sequence of labels without renumbering every label in the sequence.

  • The "metadata" field allows a customer to add a user-defined JSON value to the label. It is typically a JSON object, but may be any valid JSON value. It defaults to null.

  • The "description" field allows a customer to add a user-defined description to the label. It is a JSON string up to 65,500 bytes long. It defaults to null.

  • The "group" and "name" fields combined are the natural unique key of each label.

    • The label has a unique B-tree index on the group and label fields combined.

      • This index ensures that each label name in each label group is unique.

      • The index is named label_group_and_name.

  • The MQ Dashboard UI uses two label groups: "mqttClient" and "mqttTopic" so the user can specify different labels for MQTT clients and topics.

label table

{
  "api": "db",
  "action": "createTable",
  "params": {
    "databaseName": "faircom",
    "ownerName": "admin",
    "tableName": "label",
    "fields": [
      {
        "name": "id",
        "type": "integer",
        "primaryKey": 1,
        "autoValue": "incrementOnInsert"
      },
      {
        "name": "group",
        "type": "varchar",
        "length": 64,
        "defaultValue": ""
      },
      {
        "name": "name",
        "type": "varchar",
        "length": 64,
        "nullable": false
      },
      {
        "name": "value",
        "type": "json",
        "length": 65500
      },
      {
        "name": "enum",
        "type": "smallint"
      },
      {
        "name": "sequence",
        "type": "double"
      },
      {
        "name": "deprecated", 
        "type": "bit",
        "nullable": false,
        "defaultValue": "0"
      },
      {
        "name": "description",
        "type": "varchar",
        "length": 65500
      },
      {
        "name": "metadata",
        "type": "json",
        "length": 65500
      }
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

label_group_and_name index

This index ensures each label in a group has a unique name. It is the natural primary index of the label table. The group_name field is nullable, but the API defaults a null value to the empty string, "", to ensure this index works well. The "listLabels" action uses this index to return labels in a group.

{
  "api": "db",
  "action": "createIndex",
  "params": {
    "tableName": "label",
    "indexName": "label_group_and_name",
    "fields": [
      {
        "name": "group"
      },
      {
        "name": "name"
      }
    ],
    "unique": true,
    "waitToBeLoaded": true
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

label_deprecated_only index

This non-unique, conditional index is a list of all deprecated labels. It makes it fast to find and manage deprecated labels. The "listLabels" action uses this index to return deprecated labels so customers can undeprecate them.

{
  "api": "db",
  "action": "createIndex",
  "params": {
    "tableName": "label",
    "indexName": "label_deprecated_only",
    "fields": [
      {
        "name": "deprecated"
      }
    ],
    "conditionalExpression": "deprecated = 1",
    "waitToBeLoaded": true
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

label_name index

This non-unique index contains all labels sorted by "name". It makes it fast to find labels by partial name. The "listLabels" action uses this index to return labels that match a partial name.

{
  "api": "db",
  "action": "createIndex",
  "params": {
    "tableName": "label",
    "indexName": "label_name",
    "fields": [
      {
        "name": "name"
      }
    ],
    "waitToBeLoaded": true
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
Would you like to provide feedback?