Skip to main content

Label API Concepts

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.

Label API

Label API

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 1. 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 0.

  • 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": "float"
      },
      {
        "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"
}