Advanced search

Limitations

• Supported regions: China (Shanghai), China (Beijing), China (Shenzhen).

• Feature limitations:

  • Legacy public instances: You cannot search for devices or download device files by using Thing Specification Language (TSL) models.

  • Enterprise Edition instances and new public instances: In the China (Shanghai) region, searching for devices by TSL model is available only on the Advanced Search tab of the Devices > Device page.

    To search by TSL model, you must first configure a TSL index. IoT Platform then uses device runtime data to retrieve the most recently reported property values and find devices that meet the specified conditions.

    Important

    • For each Enterprise Edition instance, you can configure indexes for a maximum of 100 TSL model properties.

    • The advanced search feature is not supported for MQTT Enterprise Edition instances.

Use cases

You can use advanced search in the following scenarios in the IoT Platform console:

• View device information: On the Advanced Search tab of the Devices > Device page, search for and manage specific devices.

• Device grouping: When adding devices to a device group, search for the devices to add.

• Over-the-air (OTA) updates: When you verify an OTA update package or create a batch update, search for the devices to update.

You can also call the QueryDeviceBySQL API operation to perform an advanced search. The API is not limited to these console scenarios.

Procedure

The following examples show how to use advanced search in the IoT Platform console to add devices to a device group and to search for devices by TSL model.

1. Log on to the IoT Platform console.

2. On the Overview page, find the instance that you want to manage and click the instance ID or instance name.

3. search for devices that meet your criteria.

   1. In the navigation pane on the left, choose Devices > Groups. On the Groups page, find the group that you created and click View in the Actions column.

   2. On the Group Details page, click the Device List > Add Device to Group. In the Add Device to Group panel, turn on the Advanced Search switch in the upper-right corner.

   3. Enter a query in the search box and click the search icon .

      For more information about the query syntax, see SQL-like syntax.

      The search results are displayed in a list, and a download icon appears to the right of the search box.

      You can click the download icon to download a CSV file that contains a list of the matching devices.

4. Search for devices by TSL model.

   1. In the navigation pane on the left, choose Devices > Device, and then click the Advanced Search tab.

   2. On the Advanced Search tab, click Configure Index next to Search by TSL model data.

   3. In the TSL Index Configuration panel, select a product, a TSL model module, and the properties to index, then click OK.

      Note

      • After you configure property indexes, they take effect within one minute.

      • After you configure a property index, you can still search for devices based on the last reported value for that property, even if you delete the TSL model property from the product.

      In the TSL Index Configuration dialog box, select the Temperature and Humidity Sensor product from the drop-down list on the left and the Default module from the drop-down list on the right. In the property list, select the Humidity (identifier: Humidity) and Temperature (identifier: Temperature) properties.

   4. Enter a TSL index condition in the search box and click Search.

      Under Search by TSL model data, you can copy property.floatText > 11 or property.module.floatText > 11. Replace floatText with the identifier of the indexed property, replace module with the identifier of the custom module, and replace 11 with the value for your search condition.

      Important

      The data type of the condition value must match the data type of the TSL model property.

      For example, the TSL model property Temperature is of the Double type. To find devices that reported a temperature greater than 11, you must use the value 11.0 in your query. Otherwise, the search will fail.

      The search results are displayed on the Advanced Search tab. If any devices meet the criteria, you can click Download Search Result to download a CSV file of the matching devices.

   5. Optional: To remove a property's index, click Reset on the Advanced Search tab to return to the search page. Then, click Configure Index to open the TSL Index Configuration panel.

      You can select a product and a TSL model module, or click Selected in the upper-right corner. Then, deselect the target property and click OK.

      If a property has been deleted from a product, you can find the property in the Selected list to un-index it.

      Important

      If you remove a property's index, you can no longer search for devices based on that property.

      When you remove a property index, the property's historical search data is cleared. If a large amount of historical data exists, the clearing process may take some time, and the index status is not immediately updated. If you reopen the TSL Index Configuration panel, the property may still appear as selected. Wait for the process to complete and do not repeat the operation.

SQL-like syntax

When you use advanced search in the console, an SQL-like statement consists of a WHERE clause and an optional ORDER BY clause. The SELECT and LIMIT clauses, and the WHERE keyword itself, are omitted. Statements are limited to 400 characters.

Example:

product_key = "a1*****" order by active_time

WHERE clause

Format:

[condition1] AND [condition2] 

Omit WHERE.

You can specify a maximum of five conditions. Nested conditions are not supported.

The AND and OR logical operators are supported. You can use a maximum of five logical operators per statement.

ORDER BY clause (optional)

Use the ORDER BY clause to sort results. You can sort by the gmt_create, gmt_modified, and active_time fields.

This clause is optional. If omitted, results are returned in a random order.

Searchable fields

Operators

The LIKE operator supports prefix matching but does not support suffix or wildcard matching. The prefix must meet the following conditions:

• The prefix must contain at least four characters and cannot contain any special characters, such as backslashes (\), forward slashes (/), ampersands (&), plus signs (+), hyphens (-), exclamation points (!), parentheses (), colons (:), tildes (~), square brackets ([]), curly brackets ({}), asterisks (*), and question marks (?).

• The prefix must end with %.

Example:

product_key = "a1*********" and name LIKE "test%"

Related API

QueryDeviceBySQL: searches for devices that meet specified conditions by using SQL-like statements.