Data discovery query examples

Save PDF

Last UpdatedNov 13, 2025
6 minute read

A discovery against the data source of a generic 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 is supported at a time.

Generic 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>

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) Maximum value: 7.00:00:00 (7 days) Default value: 0.00:01:00 (1 minute) 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 types in the files found in the discovery directory in the data source configuration. 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, the adapter subscribes to all supported data types. Note: This filter is applicable only to the valueField parameter in Data selection. Mutual exclusion applied1
excludeDataType	Optional	Supported data types to exclude during discovery. Discovery ignores the specified data types in the files found in the discovery directory in the data source configuration. 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, the adapter subscribes to all supported data types. Note: This filter is applicable only to the valueField parameter in Data selection. Mutual exclusion applied1
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 data types in the query, you must separate them with a comma. If you do not specify a data type, the adapter subscribes to all supported data types. Note: This filter is applicable only to the valueField parameter in Data selection. 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 applied1
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 data types in the query, you must separate them with a comma. If you do not specify a data type, the adapter subscribes to all supported data types. Note: This filter is applicable only to the valueField parameter in Data selection. 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 applied1
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 trimmed2. Minimum value: 40

1 INCLUDEDATATYPE and INCLUDEFIELD cannot be used with EXCLUDEDATATYPE or EXCLUDEFIELD and vice versa. See the Query Rules section below for valid and invalid combinations.

2 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.

Data type support - Generic MQTT component

The following data types are supported by the Generic MQTT component:

float32
float64
Boolean
string
DateTime

To discover any numeric types/numbers (integers, doubles etc.) in a discovery operation, you must choose float32 or float64 to specify in IncludeDataType or ExcludeDataType fields within the discovery query.

If an incorrect data type is used, the adapter returns an error message suggesting the supported data types. For example:

"errors": "Discovery operation failed: Exception type: ArgumentException. Message: Unsupported data type in discovery query. Supported types for IncludeDataType or ExcludeDataType are Float32,Float64,Date-Time,Boolean,String."

Query rules

The following rules apply for specifying the query string:

The query is made up of key-value pairs.
Keys and values are separated with an equals (=).
Pairs are separated with a semicolon (;).
Multiple values per key are supported. These values are separated with a comma (,).
Special characters are replaced by the text parser. For more information, see Text parser.

Note: The data source might contain tens of thousands of metrics. Ensure that the query only returns data for the selection items you are interested in.
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
Unrecognized string items are not processed. A common cause of unrecognized string items is a misspelling. We recommend checking the logs when troubleshooting unprocessed strings.

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 the # judiciously and narrow down the query string to something specific or break down the query into different discoveries.

Wildcards

Wildcards are allowed in the 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 #.

Single Field

Data source

Topic Name: tele/tasmota/growschrank/SENSOR

{

"time": "2025-06-09T17:31:55",

"AM2301": {

"temperature": 23.7,

"humidity": 60.1,

"dewPoint": 15.5

"tempUnit": "C"

}

Timestamp	Temperature	Humidity	DewPoint	TempUnit
05/05/2025 17:30:36	26.2	41.1	11.9	C
05/05/2025 17:30:37	23.4	43.7	10.3	C
05/05/2025 17:30:39	14.2	75.9	10.0	C

Discovery query

{

"id": "mqtt-telel",

"query": “topics=tele/tasmota/growschrank/SENSOR;WaitTime=00:00:30;IncludeField=$.AM2301.Temperature{Uom=$.TempUnit}"

}

The subsequent data selection configuration for this file structure would be:

[

{

"topic" : "tele/tasmota/growschrank/SENSOR",

"valueField" : "$.AM2301.Temperature",

"dataFields" : null,

"indexField" : null,

"dataType" : "Float32",

"uom" : "C",

"indexFormat" : null,

"selected" : false,

"name" : null,

"streamId" : "tele/tasmota/growschrank/SENSOR.$.AM2301.Temperature",

"dataFilterId" : null,

]

Multiple Fields

Data source

Topic Name: tele/tasmota/growschrank/SENSOR

{

"time": "2025-06-09T17:31:55",

"AM2301": {

"temperature": 23.7,

"humidity": 60.1,

"dewPoint": 15.5

"tempUnit": "C"

}

Timestamp	Temperature	Humidity	DewPoint	TempUnit
05/05/2025 17:30:36	26.2	41.1	11.9	C
05/05/2025 17:30:37	23.4	43.7	10.3	C
05/05/2025 17:30:39	14.2	75.9	10.0	C

Discovery query

{

"id": "mqtt-telel",

"query": “topics=tele/tasmota/growschrank/SENSOR;WaitTime=00:00:30;IncludeField=$.AM2301.Temperature{Uom=$.TempUnit},$.AM2301.Humidity"

}

The subsequent data selection configuration for this file structure would be:

[

{

"topic" : "tele/tasmota/growschrank/SENSOR",

"valueField" : "$.AM2301.Temperature",

"dataFields" : null,

"indexField" : null,

"dataType" : "Float32",

"uom" : "C",

"indexFormat" : null,

"selected" : false,

"name" : null,

"streamId" : "tele/tasmota/growschrank/SENSOR.$.AM2301.Temperature",

"dataFilterId" : null,

{

"topic" : "tele/tasmota/growschrank/SENSOR",

"valueField" : "$.AM2301.Humidity",

"dataFields" : null,

"indexField" : null,

"dataType" : "Float32",

"uom" : null,

"indexFormat" : null,

"selected" : false,

"name" : null,

"streamId" : "tele/tasmota/growschrank/SENSOR.$.AM2301.Humidity",

"dataFilterId" : null,

]

Multiple topics

Data sources

Topic Names: tele/tasmota/growschrank/SENSOR, tele/tasmota/Tasmota123/SENSOR

{

"time": "2025-06-09T17:31:55",

"AM2301": {

"temperature": 23.7,

"humidity": 60.1,

"dewPoint": 15.5

"tempUnit": "C"

}

Timestamp	Temperature	Humidity	DewPoint	TempUnit
05/05/2025 17:30:36	26.2	41.1	11.9	C
05/05/2025 17:30:37	23.4	43.7	10.3	C
05/05/2025 17:30:39	14.2	75.9	10.0	C

Discovery query

{

"id": "mqtt-telel",

"query": “topics=tele/tasmota/growschrank/SENSOR,topics=tele/tasmota/Tasmota123/SENSOR;WaitTime=00:00:30;IncludeField=$.AM2301.Temperature{Uom=$.TempUnit},$.AM2301.Humidity"

}

The subsequent data selection configuration for this file structure would be:

[

{

"topic" : "tele/tasmota/growschrank/SENSOR",

"valueField" : "$.AM2301.Temperature",

"dataFields" : null,

"indexField" : null,

"dataType" : "Float32",

"uom" : "C",

"indexFormat" : null,

"selected" : false,

"name" : null,

"streamId" : "tele/tasmota/growschrank/SENSOR.$.AM2301.Temperature",

"dataFilterId" : null,

{

"topic" : "tele/tasmota/Tasmota123/SENSOR",

"valueField" : "$.AM2301.Humidity",

"dataFields" : null,

"indexField" : null,

"dataType" : "Float32",

"uom" : null,

"indexFormat" : null,

"selected" : false,

"name" : null,

"streamId" : "tele/tasmota/Tasmota123/SENSOR.$.AM2301.Humidity",

"dataFilterId" : null,

]

AVEVA™ Adapter for MQTT