Skip to main content

"describeTopics" (JSON Action)

JSON MQ "describeTopics" action returns info about MQTT topics

The "describeTopics" action returns all available information about specified MQTT topics.

Request examples

Minimal

{
  "api": "mq",
  "apiVersion": "1.0",
  "action": "describeTopics",
  "params": {
    "topics": [
      "test/topic1"
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Response examples

Minimal

{
  "result": {
    "data": [
      {
        "name": "test/topic1",
        "creationTime": "2024-02-01T23:47:45.814",
        "messageCount": 2,
        "lastMessageTime": "2024-02-01T23:47:51.716",
        "averageMessagesPerMinute": 0,
        "averageMessagesPerHour": 0,
        "averageMessagesPerDay": 0,
        "subscriberList": [
          {
            "topicExpression": "#",
            "connectionList": [
              {
                "connection": {
                  "clientId": "mqtt-explorer-001",
                  "ipaddress": "127.0.0.1",
                  "port": 35646,
                  "mqttProtocol": 4,
                  "keepAliveSeconds": 60,
                  "status": "Connected with clean flag = 1",
                  "connectionTime": "2024-01-31T17:31:19"
                },
                "qos": 0
              }
            ]
          },
          {
            "topicExpression": "test/#",
            "connectionList": [
              {
                "connection": {
                  "clientId": "NodeREDSecure",
                  "ipaddress": "127.0.0.1",
                  "port": 36115,
                  "mqttProtocol": 4,
                  "keepAliveSeconds": 60,
                  "status": "Connected with clean flag = 1",
                  "connectionTime": "2024-01-31T17:31:30"
                },
                "qos": 1
              }
            ]
          }
        ],
        "persistence": {
          "topic": "test/topic1",
          "mqttPayloadType": "json",
          "databaseConnectionString": "FAIRCOMS",
          "databaseUserName": "admin",
          "databaseName": "faircom",
          "tableName": "mqtt_msg_test_topic1",
          "ownerName": "admin",
          "threads": 1,
          "tableAutoTimeStamp": true,
          "tableAutoTimeStampIndex": true,
          "tableReplicationReady": true,
          "retentionPolicy": "autoPurge",
          "retentionUnit": "week",
          "retentionPeriod": 4,
          "storeAndForward": true,
          "maxDeliveryRatePerSecond": 0,
          "newSubscriberDeliveryMode": "default",
          "newSubscriberMaxDeliveredMessages": 0,
          "retrySeconds": 20,
          "outputPayloadField": "source_payload",
          "label": {
            "id": 1,
            "group": "test",
            "name": "test",
            "value": null,
            "enum": null,
            "sequence": 0,
            "deprecated": false,
            "description": null,
            "metadata": null
          }
        }
      }
    ]
  },
  "errorCode": 0,
  "errorMessage": "",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

The "describeTopics" JSON action retrieves information about MQTT topics using action parameters, notably "topics", while the "result" object returns data, including topic details and "sourcePayloadFormat", which specifies the data type of the MQTT payload. The document also specifies how the server handles different "sourcePayloadFormat" values, including validation and conversion, and highlights that it's a hint for the server's handling of the payload rather than a strict validation rule in most cases.

API actionsJSON MQ APIJSON Actiondescribe topicdecribeTopicsdescribeTopics actionJSON MQMQTT topicsreturn topic detailstopic informationdescribe topic detailsdescribe topic properties

"params"

The "params" property is an object that contains an action's request parameters as defined by a set of properties. Each action defines its own required and optional properties. See System limits for a comprehensive overview of property requirements and limitations.

Table 1. describeTopics "params" property summaries

Property

Description

Default

Type

Limits (inclusive)

topics

(optional) contains "topic" strings.

[]

array

0 or more topic strings



"topics"

The "topics" property specifies the name of each "topic" that you want to be described in the results.

"result"

Table 2. describeTopics "result" property summaries

Property

Description

Type

Contents

data

is an array of objects or arrays. Each item in the array describes a record. The array is empty if no results are available.

It is an empty array when there are no results available.

array

The action determines its contents.

averageMessagesPerDay

is a count of how many messages the topic publishes per day on average.

integer

The average number of messages published per day

averageMessagesPerHour

is a count of how many messages the topic publishes per hour on average.

integer

The average number of messages published per hour

averageMessagesPerMinute

is a count of how many messages the topic publishes per minute on average.

integer

The average number of messages published per minute

creationTime

describes the date and time when the topic was created.

timestamp

An ISO 8601 timestamp

messageCount

is the total number of messages published by the topic.

BigInteger

0 to 9223372036854775807

name

specifies the name of an existing field in a table.

string

A name between 0 and 64 bytes

persistence

defines the parameters of the persistence table.

object

parameters of the persistence table.

persistence
.databaseConnectionString

specifies the connection string for the database that holds the persistence table.

string

No limits

persistence
.databaseName

specifies the name of a database.

string

A database name between 1 and 64 bytes

persistence
.databaseUserName

specifies the user name of the account logged into the database that holds the persistence table.

string

0 to 64 bytes

persistence
.maxDeliveryRatePerSecond

describes the max throttle rate for subscribers of the topic.

integer

0 to 2147483647

persistence
.mqttPayloadType

specifies the variant type format of the "source_payload" field.

string enum

"json"
"xml"
"binary"
"jpeg"
"siemensUdt"
"utf8"
persistence
.newSubscriberDeliveryMode

describes what kinds of messages new subscribers will receive from this topic.

string enum

"newMessages"
"storedMessages"
persistence
.newSubscriberMaxDeliveredMessages

describes the maximum number of previously stored historical messages a client receives automatically when subscribing to a topic.

integer

-1 to 2147483647

persistence
.outputPayloadField

specifies the field that the MQTT Subscription service should use as the payload when it sends the payload to subscribers.

string

"source_payload" or a user-defined field
persistence
.ownerName

identifies the user who owns the topic.

string

An owner name between 1 and 64 bytes

persistence
.retentionPeriod

specifies the number of retention units, which controls how long data is retained – see "retentionUnit".

integer

1 to 100

persistence
.retentionPolicy

specifies how messages persist.

string enum

"autoPurge"
"neverPurge"
persistence
.retentionUnit

purges expired messages each time this unit cycles – see "retentionPeriod".

string enum

"minute"
"hour"
"day"
"week"
"month"
"year"
persistence
.retrySeconds

specifies the number of seconds to wait for the next expected packet during a PUBLISH packet exchange with a client.

integer

1 to 65535

persistence
.tableName

specifies the name of a table.

string

A table name between 1 and 64 bytes

persistence
.tableReplicationReady

enables the transaction log on the persistence table.

Boolean

true
false
persistence
.threads

specifies the number of threads assigned to a topic to write published messages to disk.

integer

1
2
3
persistence
.topic

specifies a unique user-defined name for the topic.

string

A topic name between 1 and 65,500 bytes

persistence
.validateMqttPayload

determines whether the FairCom server will attempt to validate the incoming MQTT message payload against the expected data type specified in the "mqttPayloadType" property.

Boolean

true
false

sourcePayloadFormat

deprecated version of "mqttPayloadType". Please use "mqttPayloadType".

string

"json"
"xml"
"binary"
"jpeg"
"siemensUdt"
"utf8"

subscribedTopics

lists the topics that the specified topic is subscribed to.

array

No limits



"data"

The "data" property lists each topic that you specified in the request. Each topic returns as an object with properties describing the topic.

    "data": [
      {
        "name": "acmefactory/line1/station1/acidbath/telemetry",
        "creationTime": "2025-09-24T22:55:51.813",
        "messageCount": 0,
        "averageMessagesPerMinute": 0,
        "averageMessagesPerHour": 0,
        "averageMessagesPerDay": 0,
        "subscribedTopics": [],
        "persistence": {
          "topic": "acmefactory/line1/station1/acidbath/telemetry",
          "databaseConnectionString": "FAIRCOMS",
          "databaseUserName": "admin",
          "databaseName": "faircom",
          "tableName": "mqtt_msg_line1_station1_acidbath_telemetry1",
          "ownerName": "admin",
          "threads": 1,
          "tableAutoTimeStamp": true,
          "tableAutoTimeStampIndex": true,
          "tableReplicationReady": true,
          "retentionPolicy": "autoPurge",
          "retentionUnit": "week",
          "retentionPeriod": 4,
          "storeAndForward": true,
          "maxDeliveryRatePerSecond": 0,
          "newSubscriberDeliveryMode": "default",
          "newSubscriberMaxDeliveredMessages": 0,
          "retrySeconds": 20,
          "outputPayloadField": "source_payload",
          "mqttPayloadType": "binary",
          "validateMqttPayload": true
        }
      }
    ]

"averageMessagesPerDay"

The "averageMessagesPerDay" property describes how many messages the specified topic publishes per day on average.

    "data": [
      {
        "name": "acmefactory/line1/station1/acidbath/telemetry",
        "creationTime": "2025-09-24T22:55:51.813",
        "messageCount": 0,
        "averageMessagesPerMinute": 0,
        "averageMessagesPerHour": 0,
        "averageMessagesPerDay": 0,
        "subscribedTopics": [],
      }
    ]

"averageMessagesPerHour"

The "averageMessagesPerHour" property describes how many messages the specified topic publishes per hour on average.

    "data": [
      {
        "name": "acmefactory/line1/station1/acidbath/telemetry",
        "creationTime": "2025-09-24T22:55:51.813",
        "messageCount": 0,
        "averageMessagesPerMinute": 0,
        "averageMessagesPerHour": 0,
        "averageMessagesPerDay": 0,
        "subscribedTopics": [],
      }
    ]

"averageMessagesPerMinute"

The "averageMessagesPerMinute" property describes how many messages the specified topic publishes per minute on average.

    "data": [
      {
        "name": "acmefactory/line1/station1/acidbath/telemetry",
        "creationTime": "2025-09-24T22:55:51.813",
        "messageCount": 0,
        "averageMessagesPerMinute": 0,
        "averageMessagesPerHour": 0,
        "averageMessagesPerDay": 0,
        "subscribedTopics": [],
      }
    ]

"creationTime"

The "creationTime" property details the date and time when the specified topic was created. This property stores the creation date in an ISO 8601 timestamp.

    "data": [
      {
        "name": "acmefactory/line1/station1/acidbath/telemetry",
        "creationTime": "2025-09-24T22:55:51.813",
        "messageCount": 0,
        "averageMessagesPerMinute": 0,
        "averageMessagesPerHour": 0,
        "averageMessagesPerDay": 0,
        "subscribedTopics": [],
      }
    ]

"messageCount"

The "messageCount" property defines the total number of messages published by the topic.

    "data": [
      {
        "name": "acmefactory/line1/station1/acidbath/telemetry",
        "creationTime": "2025-09-24T22:55:51.813",
        "messageCount": 0,
        "averageMessagesPerMinute": 0,
        "averageMessagesPerHour": 0,
        "averageMessagesPerDay": 0,
        "subscribedTopics": [],
      }
    ]

"name"

The optional "name" property is a case-sensitive string from 1 to 64 bytes in length. It is a new name for an existing field in a table. A field is not renamed when "name" is zero-length or omitted..

  • A zero-length "name" is invalid.

  • A client should enforce the uniqueness of the "name".

Request example

"fields": [
  {
    "name": "field1",
    "type": "varchar",
    "newName": "company"
  }
]

"persistence"

The "persistence" property is an object that defines the parameters of the persistence table.

        "persistence": {
          "topic": "acmefactory/line1/station1/acidbath/telemetry",
          "databaseConnectionString": "FAIRCOMS",
          "databaseUserName": "admin",
          "databaseName": "faircom",
          "tableName": "mqtt_msg_line1_station1_acidbath_telemetry1",
          "ownerName": "admin",
          "threads": 1,
          "tableAutoTimeStamp": true,
          "tableAutoTimeStampIndex": true,
          "tableReplicationReady": true,
          "retentionPolicy": "autoPurge",
          "retentionUnit": "week",
          "retentionPeriod": 4,
          "storeAndForward": true,
          "maxDeliveryRatePerSecond": 0,
          "newSubscriberDeliveryMode": "default",
          "newSubscriberMaxDeliveredMessages": 0,
          "retrySeconds": 20,
          "outputPayloadField": "source_payload",
          "mqttPayloadType": "binary",
          "validateMqttPayload": true
        }

"databaseConnectionString"

The "databaseConnectionString" property specifies the connection string for the database that holds the persistence table.

        "persistence": {
          "topic": "acmefactory/line1/station1/acidbath/telemetry",
          "databaseConnectionString": "FAIRCOMS",
          "databaseUserName": "admin",
          "databaseName": "faircom",
          "tableName": "mqtt_msg_line1_station1_acidbath_telemetry1",
          "ownerName": "admin",
          "threads": 1,
          "tableAutoTimeStamp": true,
          "tableAutoTimeStampIndex": true,
          "tableReplicationReady": true,
          "retentionPolicy": "autoPurge",
          "retentionUnit": "week",
          "retentionPeriod": 4,
          "storeAndForward": true,
          "maxDeliveryRatePerSecond": 0,
          "newSubscriberDeliveryMode": "default",
          "newSubscriberMaxDeliveredMessages": 0,
          "retrySeconds": 20,
          "outputPayloadField": "source_payload",
          "mqttPayloadType": "binary",
          "validateMqttPayload": true
        }

"databaseName"

The "databaseName" property is a string that identifies the name of the target database.

  • A zero-length "databaseName" is invalid.

  • Its limits are from 1 to 64 bytes.

"databaseUserName"

The "databaseUserName" property specifies the user name of the account logged into the database that holds the persistence table.

        "persistence": {
          "topic": "acmefactory/line1/station1/acidbath/telemetry",
          "databaseConnectionString": "FAIRCOMS",
          "databaseUserName": "admin",
          "databaseName": "faircom",
          "tableName": "mqtt_msg_line1_station1_acidbath_telemetry1",
          "ownerName": "admin",
          "threads": 1,
          "tableAutoTimeStamp": true,
          "tableAutoTimeStampIndex": true,
          "tableReplicationReady": true,
          "retentionPolicy": "autoPurge",
          "retentionUnit": "week",
          "retentionPeriod": 4,
          "storeAndForward": true,
          "maxDeliveryRatePerSecond": 0,
          "newSubscriberDeliveryMode": "default",
          "newSubscriberMaxDeliveredMessages": 0,
          "retrySeconds": 20,
          "outputPayloadField": "source_payload",
          "mqttPayloadType": "binary",
          "validateMqttPayload": true
        }

"maxDeliveryRatePerSecond"

The "maxDeliveryRatePerSecond" property sets the throttle rate for current and new subscribers of the topic. This property is optional. If omitted, it defaults to 0, which means no throttling is applied.

  • It must be a value between 0 and 2,147,483,647, but a more realistic range is between 0 and 1,000. It is useful to keep a client from being overwhelmed with too many messages sent too quickly.

  • You can set it to a number greater than 0 to throttle the delivery rate. This allows you to avoid saturating the network and other resources.

    For example, you can set it to 100 to throttle the delivery to 100 messages per second. This is a maximum setting because the actual message delivery rate is bounded by the network, local resources, the hardware running FairCom's servers, and a client’s ability to process messages quickly.

"mqttPayloadType"

The "mqttPayloadType" property is an optional string that specifies the expected data type of the MQTT payload. When omitted or set to null, it defaults to "binary". When the server receives an MQTT message, it always takes the binary value from the MQTT payload and stores it in the source_payload field. The source_payload field is a variant, which means it stores the type of data it contains. If there are no errors in validating the MQTT payload to match the type specified in "mqttPayloadType", the server assigns the value of "mqttPayloadType" as the variant field's type. 

Depending on the values of the "mqttPayloadType" and "validateMqttPayload" properties, the server may validate the MQTT payload to ensure it matches the type. The default value for the "validateMqttPayload" property is true. The server may also convert the MQTT payload into another form before storing it. If the MQTT payload does not match the type or cannot be converted, the server stores the payload in the source_payload field, sets its variant type to "binary", and sets the error field to 1 to indicate there is an error. It also adds an error entry to the JSON array in the log field. 

FairCom's MQTT server does the following when a topic receives an MQTT message and "mqttPayloadType" is set to one of the following values:

"mqttPayloadType" Value

Description

"binary"

The server stores the MQTT payload in the source_payload field with no validation or conversion and assigns the "binary" type to the field. It ignores the value of "validateMqttPayload".

"json"

The server stores the MQTT payload in the source_payload field.

  • If "validateMqttPayload" is true, it validates the MQTT payload as JSON.

    • If successful, it assigns the "json" type to the source_payload field.

    • If unsuccessful, the server assigns a "binary" type to the source_payload field and sets the error field to 1 to indicate there is an error. It also adds an error entry to the JSON array in the log field.

  • If "validateMqttPayload" is false, it does not validate the MQTT payload and assigns the "json" type to the source_payload field. The publisher must send MQTT messages containing valid JSON, or database queries may return errors.

"utf8"

The server stores the MQTT payload in the source_payload field.

  • If "validateMqttPayload" is true, it validates the MQTT payload as a UTF-8 string.

    • If successful, it assigns the "utf8" type to the source_payload field.

    • If unsuccessful, the server assigns a "binary" type to the field and sets the error field to 1 to indicate there is an error. It also adds an error entry to the JSON array in the log field.

  • If "validateMqttPayload" is false, it does not validate the MQTT payload and assigns the "utf8" type to the source_payload field. The publisher must send MQTT messages containing valid UTF-8, or database queries may return errors.

"variantObject"

The server validates the payload as a variant object.

  • If successful, the server extracts the value from the variant object’s "value" property and assigns it to the value of the source_payload field. It also assigns the variant object’s type to the type of the source_payload field.

  • If unsuccessful, the server writes the MQTT payload to the source_payload field, assigns a  "binary"  type to the field, and sets the error field to  1, to indicate that it also adds an error entry to the JSON array in the log field.

The server ignores the value of "validateMqttPayload". The server always validates "variantObject".

"siemensUdt"

The server stores the MQTT payload in the source_payload field without validation or conversion and assigns the "binary" type to the field. It ignores the value of "validateMqttPayload".

"jpeg"

The server stores the MQTT payload in the source_payload field without validation or conversion and assigns the "binary" type to the field. It ignores the value of "validateMqttPayload".

"xml"

The server stores the MQTT payload in the source_payload field without validation or conversion and assigns the "binary" type to the field. It ignores the value of "validateMqttPayload".

  • This property is a hint to the server about the format and type of the MQTT message payload.

  • This property does not cause server to validate the MQTT payload to see if it matches the type you set. The server stores the payload as is without validation. For example, setting the type to "json", it does not stop the server from receiving and storing a non-JSON value or invalid JSON document in the source payload.

  • The FairCom Edge Explorer application may use the value of this property to determine the default way to display a topic's payload.

  • The transform engine may use the value of this property to help it transform the source payload.

"newSubscriberDeliveryMode"

The "newSubscriberDeliveryMode" property defines how new subscribers receive messages. The default is "newMessages".

  • It may be set to one of two values:

    • "newMessages"

    • "storedMessages"

  • When set to "newMessages" new subscribers only receive new messages.

  • When set to "storedMessages" new subscribers will receive some or all previously sent messages. The "newSubscriberDeliveryMode" property defines the maximum number of messages.

"newSubscriberMaxDeliveredMessages"

The "newSubscriberMaxDeliveredMessages" property is the maximum number of previously stored historical messages a client receives automatically when subscribing to a topic. The default is 0.

  • A value of -1 or "all" defaults to delivering all currently stored messages.

  • A non-negative number limits the delivery of currently stored messages to that number, which may be a maximum of 2,147,483,647 messages.

  • This property only applies when the "newSubscriberDeliveryMode" property is set to "storedMessages".

  • The broker can only send messages stored in the topic’s integration table. The table's retention policy automatically removes old messages.

  • Each time a client unsubscribes from a topic and then subscribes to the topic, the broker sends historical messages as specified by this property. A client can use this behavior to reprocess messages, such as refresh a local data cache or recalculate aggregates.

Note

A topic’s "retentionPolicy", "retentionUnit", and "retentionPeriod" properties define how long the broker retains messages in a topic’s integration table.

"outputPayloadField"

The "outputPayloadField" property specifies the field that the MQTT Subscription service should use as the payload when it sends the payload to subscribers. If omitted or if it is an empty string, it defaults to "source_payload".

  • "outputPayloadField" must be one of the following values: 

    • "source_payload"

    • A user-defined field

    This makes it possible for the output from any transform to be used as the payload delivered to subscribers.

"ownerName"

The "ownerName" property is an optional string from 1 to 64 bytes that identifies the user who owns an object (see Object owner). If it is omitted or set to "" or null, the server uses the default owner name supplied during the "createSession" action or uses the account's "username" as the owner name.

"params": {
  "ownerName": "SuperUser"
}

"retentionPeriod"

The "retentionPeriod" property specifies how many units of data to retain. It must be an integer value from 1 to 100. It refers to the unit of time specified by the "retentionUnit" property — for example, if "retentionPeriod" is 14 and "retentionUnit" is "day", then message data is retained for 14 days. This property is optional.

  • Periodically, the system increments the age of each table partition.

    • "Minute" units are incremented at the zero second of each minute, whether the table partition was created 1 second before or 59 seconds before.

    • "Day" units are incremented at midnight GMT, not midnight of the local UTC time zone. A table partition becomes one day old at midnight GMT, whether it was created one second before or 23 hours and 59 seconds before.

    • "Week" units are incremented at midnight GMT on the last day of each week, even if the table partition was created one second before. The last day of the week is Saturday GMT.

    • "Month" units are incremented at midnight GMT on the last day of each month.

    • "Year" units are incremented at midnight GMT on Dec 31.

  • "retentionPeriod" implicitly calculates an upper bound on how many partitions are able to accumulate on your hard drive. However, partitions are not deleted just because this calculated number of partitions is reached. The system also does not restrict the deletion of all partitions.

  • If the FairCom database is shut down for a month, when the database is started up again, all partitions that are retained for less than one month are immediately deleted.

  • If someone purposely or accidentally sets the date to a future date, all partitions immediately become older, and auto-deletion ensues accordingly.

When partitions are auto-purged, some data are maintained "forever" in a global index. Auto-purge does not prevent these files from growing without bounds and filling up your hard drive.

If not specified, the default found in the services.json file is used. Initially, it is 4 (weeks).

Automatically purging data is important to ensure that retained data does not consume all storage and shut down the computer. The default value of 4 weeks allows FairCom's servers to store 1 TB of messages when 200 topics send one 2K message per second.

Note

  • If the value is not an integer from 1 to 100, FairCom's servers set it to the default value.

  • Smaller numbers improve SQL performance.

  • Each time the "retentionPeriod" cycles, FairCom's servers automatically and efficiently delete expired data.

  • The "retentionUnit" and "retentionPeriod" properties are used only when the "retentionPolicy" is set to "autoPurge".

  • FairCom's servers only use the "retentionPeriod" property when the "retentionPolicy" is "autoPurge".

  • The "retentionPeriod" can be changed to retain fewer or more messages. Changing it does not necessarily destroy existing data, but data may expire more quickly or be retained longer.

  • The "retentionPeriod" and "retentionUnit" properties control data granularity as well as the retention time.  In other words, "retentionPeriod" defines how many sets of data are stored, and "retentionUnit" defines how often data is purged.

    For example, if "rententionPeriod" is set to 14 , the server stores 14 sets of data. At the beginning of the 15th cycle, the server automatically purges the oldest set of data. If "retentionUnit" is set to day, then data will be purged daily. If set to "week", then data will be purged weekly.

  • The current calendar date affects purging.

    FairCom's servers automatically purge all retained data that has expired. This is noticeable when FairCom's servers come online after having been offline for a long time. When a server comes back online, it automatically purges all expired data.

    For example, if a FairCom server is offline for four weeks when it comes online, it will completely purge all retained data that has a retention time of less than 4 weeks.

"retentionPolicy"

The "retentionPolicy" property controls how messages are persisted. This property is optional.

If not specified, the default found in the services.json file is used. Initially, it is "autoPurge".

retentionPolicy values:

  • "autoPurge"

    This is the default. It is automatically applied when a new topic is created. It is preferred because it allows FairCom's servers to automatically remove messages that are older than the retention time. This helps ensure message data does not consume all storage space. It also minimizes storage costs and speeds up data access. The server partitions a table into multiple files so it can efficiently delete expired files.

  • "neverPurge"

    This stores messages on disk and never removes them. This is useful when you need the entire history of the message stream. If message velocity is high, this can consume all storage space and cause an outage. The server creates a non-partitioned table, which is slightly faster than a partitioned table because it stores all records in one file.

"retentionUnit"

Each time this unit cycles, FairCom purges expired messages. For example, if you want a week's worth of messages to be purged once a week, set "retentionUnit" to "week" . This property is optional.

If not specified, the default found in the services.json file is used. Initially, it is "week". 

  • This property is used in concert with "retentionPeriod" to determine retention time.

  • "retentionUnit" values:

    • "minute"

    • "hour"

    • "day"

    • "week"

    • "month"

    • "year"

    • "forever"

Note

  • For best performance, set the "retentionUnit" to a value that keeps "retentionPeriod" between 5 and 30. 

  • When you set "retentionUnit" property to "forever" the server will not purge messages. This setting is the same as setting "retentionPolicy" to "neverPurge".

  • The "retentionUnit" and "retentionPeriod" properties are used only when the "retentionPolicy" is set to "autoPurge".

"retrySeconds"

The "retrySeconds" property is the number of seconds that FairCom's MQTT broker will wait for the next expected packet from a client during a QoS 1 or QoS 2 PUBLISH packet exchange/PUBLISH handshake with an MQTT client. The default value is 5. It applies when a client is publishing to the broker and when the broker is publishing to a client. This property does not apply to QoS 0 PUBLISH operations because QoS 0 PUBLISH operations are not answered. "retrySeconds" is optional.

  • If the "retrySeconds" time expires, FairCom's broker will disconnect the MQTT client with MQTT error code 7.  MQTT 5 clients will also receive a Reason Code.  An error message will be logged to <faircom>/data/CTSTATUS.FCS explaining why the disconnect happened. For example: 

    MQTT connection for client ID [myMqttClient7] has been disconnected due to inactivity timeout. retrySeconds is set to [25] seconds for topic [my/test/topic12].: 14226

    When the MQTT client reconnects, FairCom's MQTT broker will attempt to resume the PUBLISH handshake by resending the unanswered packet to the client, hoping that the client will reply with the next step of the handshake.

  • The minimum value is 1 and the maximum value is 65535.

  • If "retrySeconds" is omitted or its range is exceeded, FairCom's broker uses the default value.

  • Note that this parameter is not related to MQTT Keep Alive or when PINGREQ packets should be sent by the client.

"tableName"

The "tableName" property is a string containing the name of an integration table that stores the messages of an MQTT topic.

  • See table name in System limits for table naming requirements and limitations.

  • You must specify a non-empty string for an integration table name.

  • FairCom Edge an FairCom MQ automatically create an integration table for each new MQTT topic they process. The first characters in the table name are "mqtt_msg_" followed by the topic name. Because an MQTT topic can be 65500 bytes and a table name can be 64 bytes, the server may abbreviate the topic name.

  • To better identify the data it holds, rename an integration using the "tableName" property of the "configureTopic" action.

"tableReplicationReady"

The "tableReplicationReady" property enables the transaction log on the persistence table. Transaction logs must be enabled before a table can be replicated.

        "persistence": {
          "topic": "acmefactory/line1/station1/acidbath/telemetry",
          "databaseConnectionString": "FAIRCOMS",
          "databaseUserName": "admin",
          "databaseName": "faircom",
          "tableName": "mqtt_msg_line1_station1_acidbath_telemetry1",
          "ownerName": "admin",
          "threads": 1,
          "tableAutoTimeStamp": true,
          "tableAutoTimeStampIndex": true,
          "tableReplicationReady": true,
          "retentionPolicy": "autoPurge",
          "retentionUnit": "week",
          "retentionPeriod": 4,
          "storeAndForward": true,
          "maxDeliveryRatePerSecond": 0,
          "newSubscriberDeliveryMode": "default",
          "newSubscriberMaxDeliveredMessages": 0,
          "retrySeconds": 20,
          "outputPayloadField": "source_payload",
          "mqttPayloadType": "binary",
          "validateMqttPayload": true
        }

threads

The "threads" property is the number of threads assigned to a topic to write published messages to disk. This property is optional. The default value is 1.

  • The default of 1 is enough to handle typical workloads.

  • For heavy workloads, you may increase the number of threads to 2 or 3.

"topic"

The "topic" property is an optional string that specifies the MQTT topic on the external broker to which messages will be forwarded.

"validateMqttPayload"

The "validateMqttPayload" property determines whether the FairCom server will attempt to validate the incoming MQTT message payload against the expected data type specified in the "mqttPayloadType" property.

        "persistence": {
          "topic": "acmefactory/line1/station1/acidbath/telemetry",
          "databaseConnectionString": "FAIRCOMS",
          "databaseUserName": "admin",
          "databaseName": "faircom",
          "tableName": "mqtt_msg_line1_station1_acidbath_telemetry1",
          "ownerName": "admin",
          "threads": 1,
          "tableAutoTimeStamp": true,
          "tableAutoTimeStampIndex": true,
          "tableReplicationReady": true,
          "retentionPolicy": "autoPurge",
          "retentionUnit": "week",
          "retentionPeriod": 4,
          "storeAndForward": true,
          "maxDeliveryRatePerSecond": 0,
          "newSubscriberDeliveryMode": "default",
          "newSubscriberMaxDeliveredMessages": 0,
          "retrySeconds": 20,
          "outputPayloadField": "source_payload",
          "mqttPayloadType": "binary",
          "validateMqttPayload": true
        }

"subscribedTopics"

The "subscribedTopics" property lists the topics that the specified topic is subscribed to.

    "data": [
      {
        "name": "acmefactory/line1/station1/acidbath/telemetry",
        "creationTime": "2025-09-24T22:55:51.813",
        "messageCount": 0,
        "averageMessagesPerMinute": 0,
        "averageMessagesPerHour": 0,
        "averageMessagesPerDay": 0,
        "subscribedTopics": [],
      }
    ]

A database is a set of data that is managed by a database server. A database contains data that is organized into tables, records, and fields. A database is a huge composite data type that represents a group of interconnected objects. A database allows records to be joined together for querying, searching, and processing by users, applications, and services.

A database is a security container that controls which accounts have permissions to access specific data.