Advanced Search

Updated on 2024-11-06 GMT+08:00

View PDF

Overview

To quickly find the desired device, you can use advanced search to set flexible search criteria using SQL-like statements to search. For example, you can search for devices by prefix fuzzy match or by tag. This section guides you on using advanced search and SQL-like syntax.

Constraints

This API is supported only by Standard and Enterprise editions.
The maximum TPS for an account to call this API is 1 (one request per second).

Scenarios

Device search: On the All Devices > Device List page, use SQL-like statements to search for specified devices for subsequent management operations.

Dynamic device grouping: Based on the rules of SQL-like statement, devices that meet the filter criteria are automatically added to the group for management.

Procedure

Access the IoTDA service page and click Access Console. Click the target instance card.
In the navigation pane, choose Devices > All Devices. By default, all devices under your account are displayed in the device list.
Click Advanced Search, enter an SQL-like statement, and click Search to display the target devices.

Figure 1 Device - Advanced search

SQL-like Syntax Description

When using SQL-like statements on the console, omit the select, from, order by, and limit clauses. You only need to enter a where clause to edit user-defined conditions. The maximum length of a statement is 400 characters. The content in the clause is case sensitive, but keywords in SQL statements are case insensitive. On the console, data is sorted based on the marker field desc by default.

A where clause:

[condition1] AND [condition2]

Example:

product_id = 'testProductId'

Up to five conditions are supported. Conditions cannot be nested. For details about the parameters that support query, see Table 1 and Table 2.

AND and OR are supported. For details about the priority, see the standard SQL syntax. By default, the priority of AND is higher than that of OR.

**Table 1** Description of query condition parameters
Parameter	Data Type	Description	Value Range
app_id	string	Resource space ID.	The value can contain up to 36 characters. Only letters, digits, underscores (_), and hyphens (-) are allowed.
device_id	string	Device ID.	The value can contain up to 128 characters. Only letters, digits, underscores (_), and hyphens (-) are allowed.
gateway_id	string	Gateway ID.	The value can contain up to 128 characters. Only letters, digits, underscores (_), and hyphens (-) are allowed.
product_id	string	ID of the product associated with the device.	The value can contain up to 36 characters. Only letters, digits, underscores (_), and hyphens (-) are allowed.
device_name	string	Device name.	The value can contain up to 256 characters. Only letters, digits, and special characters (_?'#().,&%@!-) are allowed.
node_id	string	Node ID.	The value can contain up to 64 characters. Only letters, digits, underscores (_), and hyphens (-) are allowed.
status	string	Device status.	The value can be ONLINE, OFFLINE, ABNORMAL, INACTIVE, or FROZEN.
node_type	string	Device node type.	The value can be GATEWAY (a directly connected device or gateway) and ENDPOINT (an indirectly connected device).
tag_key	string	Tag key.	The value can contain up to 64 characters. Only letters, digits, underscores (_), periods (.), and hyphens (-) are allowed.
tag_value	string	Tag value.	The value can contain up to 128 characters. Only letters, digits, underscores (_), periods (.), and hyphens (-) are allowed.
sw_version	string	Software version.	The value can contain up to 64 characters. Only letters, digits, underscores (_), hyphens (-), and periods (.) are allowed.
fw_version	string	Firmware version.	The value can contain up to 64 characters. Only letters, digits, underscores (_), hyphens (-), and periods (.) are allowed.
group_id	string	Group ID.	The value can contain up to 36 characters, including hexadecimal strings and hyphens (-).
create_time	string	Device registration time.	Format: yyyy-MM-dd'T'HH:mm:ss.SSS'Z', for example, 2015-06-06T12:10:10.000Z
marker	string	Result record ID.	The value is a string of 24 hexadecimal characters, for example, ffffffffffffffffffffffff.

**Table 2** Supported operators
Operator	Supported By
=	All parameters
!=	All parameters
>	create_time and marker
<	create_time and marker
like	device_name, node_id, tag_key, and tag_value
in	Parameters except tag_key and tag_value.
not in	Parameters except tag_key and tag_value.

SQL Restrictions

like: Only prefix match is supported. Suffix match or wildcard match is not supported. At least four characters must be contained for prefix match. Special characters cannot be contained. Only letters, digits, underscores (_), and hyphens (-) are allowed. The prefix must end with %.
Other SQL statements, such as nested SQL statements, union, join, and alias, are not supported.
The SQL statement can contain up to 400 characters. Up to five request conditions are supported.
The condition value cannot be null or an empty string.