Data discovery query examples
- Last UpdatedOct 28, 2025
- 5 minute read
- PI System
- Adapter for MQTT 1.4
- Adapters
A discovery against the data source of a Sparkplug B MQTT adapter allows you to specify the optional query parameter. The query discovers the contents of the data source and narrows the scope of the discovery. You can add the discovered items to the data selection.
Note: Only one discovery at a time is supported.
Sparkplug B query string
The string of the query parameter must contain string items in the following format:
Topics=<TopicName>;WaitTime=<waitTime>;MaxStreamIdLength=<MaxStreamIdLength>;IncludeField=<includeFields>;ExcludeField=<excludeFields>;IncludeDataType=<includeDataTypes>;ExcludeDataType=<excludeDataTypes>
where the Sparkplug B topic structure is of the form:
topics=spBv1.0/<Group_Id>/<Message_Type>/<Edge_Node_Id>/<[Device_Id]>
Note: Device Id is optional in the SparkplugB topic structure.
|
String item |
Required |
Description |
|---|---|---|
|
topics |
Optional |
The topics that the adapter subscribes to when the discovery posts. Note: If you want to specify multiple topics in the query, you must separate the topic names with a comma. If you do not specify a topic, the adapter subscribes to all topics. |
|
waitTime |
Optional |
The time window in which the adapter performs the discovery by listening for specified topics. After the wait time elapses, the discovery results are available. Minimum value: 0.00:00:30 (30 seconds) Note: If you do not specify a wait time, the default value is applied. If you set WaitTime to a number, for example WaitTime=45, the adapter treats that number as seconds rather than a time span. |
|
includeDataType |
Optional |
Supported data types to include during discovery. Discovery looks for the specified data types1 in the topic metrics found in the broker. If you want to specify multiple data types in the query, you must separate them with a comma. If you do not specify a data type, nothing will be excluded. Note: This filter is applicable only to the metricName parameter in Data selection. Mutual exclusion applied1 |
|
excludeDataType |
Optional |
Supported data types to exclude during discovery. Discovery ignores the specified data types1 in the topic metrics found in the broker. If you want to specify multiple data types in the query, you must separate them with a comma. If you do not specify a data type, nothing will be excluded. Note: This filter is applicable only to the metricName parameter in Data selection. Mutual exclusion applied2 |
|
includeField |
Optional |
Name of the fields to include during discovery. Discovery looks for the specified fields in the MQTT message payload sent by the broker. If you want to specify multiple fields in the query, you must separate them with a comma. If you do not specify a field, the adapter subscribes to all applicable fields. In order to specify JSON-formatted data, use JSONPath expression starting with $. For non-JSON data, use the direct field name. You can also specify a Unit of Measurement (uom) for each field. For example, IncludeField=Field1{uom=Unit1},Field2{uom=Unit2},Field3 Additional examples can be found below. Mutual exclusion applied2 |
|
excludeField |
Optional |
Name of the fields to exclude during discovery. Discovery ignores the specified fields in the MQTT message sent by the broker. If you want to specify multiple fields in the query, you must separate them with a comma. If you do not specify a field, nothing will be excluded. In order to specify JSON-formatted data, use JSONPath expression starting with $. For non-JSON data, use the direct field name. You can also specify a Unit of Measurement (uom) for each field. For example, ExcludeField=Field1{uom=Unit1},Field2{uom=Unit2},Field3 Mutual exclusion applied2 |
|
maxStreamIdLength |
Optional |
The maximum length of stream IDs during data discovery. If you set this value, stream IDs longer than the specified length will be trimmed3. Minimum value: 40 |
1 Data Type Support for Sparkplug B: Supported discovery query data types for the MQTT Sparkplug B component are the 15 basic data types listed in the Metric Datatype section (Section 15.2.1) on page 51 of the SparkplugB Specification.
2 INCLUDEDATATYPE and INCLUDEFIELD cannot be used with EXCLUDEDATATYPE or EXCLUDEFIELD and vice versa. See the Query Rules section below for valid and invalid combinations.
3 When MaxStreamIdLength is specified in the discovery query, the discovery operation trims the length of automatically generated stream IDs to specified value. This is done using a deterministic hashing algorithm by replacing the parts of the Topic value with hash results.
Query rules
The following rules apply for specifying the query string:
-
The query is made up of key=value pairs.
-
Pairs are separated with a semicolon (;).
-
Keys and values are separated with an equals (=).
-
Multiple values per key are supported. These values are separated with a comma (,).
-
Valid combinations for string items include INCLUDEFIELD and INCLUDEDATATYPE along with EXCLUDEFIELD and EXCLUDEDATATYPE. Defining both INCLUDEFIELD and INCLUDEDATATYPE in same query results in union, that is logical OR operation, of columns covered under both conditions.
-
Invalid combination for string items include
-
INCLUDEFIELD and EXCLUDEFIELD
-
INCLUDEFIELD and EXCLUDEDATATYPE
-
INCLUDEDATATYPE and EXCLUDEFIELD
-
INCLUDEDATATYPE and EXCLUDEDATATYPE
-
Topics
The following rules apply when specifying the topics in a query string:
-
Only one query at a time is supported. That query can contain as many topics with the same wait time as needed. If you need different wait times for different topics, you need to create a new query once the query from the previous discovery has completed.
-
Partial queries are terminated by a multi-level wildcard (#).
-
A query cannot be terminated by a trailing slash (/).
-
A query cannot start with a leading slash (/) or $.
-
Topics are case sensitive.
-
White spaces are supported.
-
Special characters are replaced by the text parser. For more information, see Text parser
Note: The data source might contain large amounts of metrics. Use # judiciously and narrow down the query string to something specific or break down the query into different discoveries.
Wildcards
Wildcards are allowed in the topics query with the following specifications:
-
A single-level wildcard replaces one topic level and is indicated by +.
-
A multi-level wildcard covers many topic levels and is indicated by #.
-
Wildcards can be combined.
-
# must not be used more than once and can only be used at the end of the topic.
-
No query, an empty string, or null as the query parameter is equivalent to #.
Sparkplug B UoM Discovery example
Payload Structure
The following example payload shows how SparkplugB metrics include the Unit of Measure (UoM) inside the properties field, which lets the MQTT Adapter pull out and set UoM values when discovering devices and handling data selection.
{
"metrics": [
{
"name": "Inputs/Temperature",
"alias": 1,
"timestamp": 1479123452194,
"dataType": "Float",
"value": 55.2,
"properties": {
"unitOfMeasure": "Celsius",
"engineeringUnitsLow": 0,
"engineeringUnitsHigh": 100
}
},
{
"name": "Inputs/Humidity",
"timestamp": 1486144502122,
"dataType": "Float",
"value": 55.9,
"properties": {
"unitOfMeasure": "g/cm3",
"engineeringUnitsLow": 0,
"engineeringUnitsHigh": 100
}
}
],
"seq": 2
}
Discovery query
To help find Unit of Measure (UoM) values in Sparkplug B metric properties, the adapter uses a structured query that focuses on specific topic paths, such as spBv1.0/group1/DDATA/Plant,and links the property keys you want (like unitOfMeasure) to the right metrics by using the includeField parameter.
For example:
{
"id": "spB",
"query": "topics=spBv1.0/#;includeField=Inputs/Temperature{uom=unitOfMeasure},Inputs/Humidity{uom=unitOfMeasure}"
}
The corresponding data selection configuration for this file structure would be:
[
{
"topic": "spBv1.0/group1/DDATA/Plant",
"metricName": "Inputs/Temperature",
"selected": false,
"name": null,
"streamId": "spBv1.0/group1/DDATA/Plant/Inputs/Temperature",
"dataFilterId": null,
"uom": "Celsius"
},
{
"topic": "spBv1.0/group1/DDATA/Plant",
"metricName": "Inputs/Humidity",
"selected": false,
"name": null,
"streamId": "spBv1.0/group1/DDATA/Plant/Inputs/Humidity",
"dataFilterId": null,
"uom": "g/cm3"
}
]