Query API resources
You can run the Analyzer detail view query language (MQL) to get the resources data from the database.
Running the MQL query
The MQL query can get both time series and scalar data. The query time window must be specified in the Analyzer detail view server time zone.
baseURL?action=query&dataset =<Datasetname>&processSync=<true | false>
{ "query":"", "startTime":"", "endTime":"" }
POST action=query&dataset=defaultDs HTTP /1.1 Authorization:Basic ZnJlZDpmcmVk
{ "query":" vm[~memory]", "startTime":"20140713_230100", "endTime":"20140714_000000" }
Parameter | Type | Description |
action | String | MQL query.
Specify the API function to be invoked. |
dataset | String | Dataset name. From 2 to 32 alphanumeric, underscore (_), and hyphen (-) characters are allowed. |
query | String | Specify the MQL query. |
processSync | Boolean |
(Optional) Specify if the query should return incremental or complete results. False: Query returns the incremental result. True: Query returns the complete result. The default value is false. |
startTime | String |
Start time of the query. Date format: yyyyMMdd_HHmmss. Time zone: Analyzer detail view server time zone. |
endTime | String |
End time of the query. Date format: yyyyMMdd_HHmmss. Time zone: Analyzer detail view server time zone. |
maxResults | Integer | (Optional) Specifies the maximum number of top-level resources on which the query can return in the response. This parameter is ignored if the
processSync parameter is set to true.
Positive integers. If not specified then the default value is the value of the
|
splitResponse | Boolean | (Optional) If the value of this parameter is set to true, then the server splits the query response based on the maxResponseSize specified by the user or the default maxResponseSize.
True or false Default: false |
useRealTime | Boolean | (Optional) Helps to define whether real-time data should be included for performance reporting or analysis. If the value of this parameter is set to true, real-time data is included while reporting.
True or false Default: false |
utcOffset | String | (Optional) Offset from the coordinated universal time. The UTC offset is applicable for API request and response.
UTC+/-HH:MM Example: UTC+09:00 Default: Non-DST offset of Analyzer detail view server time zone is used. Note: When a time zone is within daylight saving time, the changes in offset according to daylight saving time are not applicable for this API. Only the Analyzer detail view server time zone offset is applicable. |
{ "status":{ "total":, "matched":, "processed":, "completed":, "aborted":, "hasErrors": }, "result":[ { "signature":"", "name":"", "memory":{ "type":"", "name":"", "unit":"", "data":"" }, "cpu Usage":[ { "type":"", "name":"", "unit":"", "interval":, "start":"", "data":[ , , , , ] } ] } ] }
{ "status":{ "total":100, "matched":1, "processed":10, "completed":false, "aborted":false, "hasErrors":false }, "result":[ { "signature":"vm#cumulus1-lab-vm2", "name":"cumulus-lab-vm2", "memory":{ "type":"scalar", "name":"Memory", "unit":"", "data":"204800" }, "cpu Usage":[ { "type":"timeseries", "name":"cpu usage", "unit":"", "interval":60, "start":"20140713_230100", "data":[ 24.00, 33.00, 68.00, null, 4.00 ] } ] } ] }
Parameter |
Type |
Description |
status | Object | Object that holds meta information about the progress of the query operation. |
status.total | Number |
Total number of top-level resources that exist in the database for the given time range. |
status.matched | Number | Total number of top-level resources matched after applying all filters. |
status.processed | Number | Total number of top-level resources processed. |
status.completed | Boolean | Indicates that the query processing is finished. |
status.aborted | Boolean | Indicates that the query processing is stopped by the user. |
status.hasErrors | Boolean | Indicates that the query processing has encountered a runtime error. Results are processed until error conditions are returned. |
result | Object[ ] | List of results. |
result.signature | String | Unique identifier of the resource data. |
result.name | String | Value of the scalar attribute name, or in its absence the value of the signature. |
result.<scalar attribute> | Object | If the scalar filter is present. |
result.<scalar attribute>.type | String | Scalar (fixed value of the scalar data object). |
result.<scalar attribute>.name | String | Display the name of the scalar attribute. |
result.<scalar attribute>.unit | String | Unit of the scalar attribute. |
result.<scalar attribute>.data | String | String value of the scalar attribute. |
result.<timeseries attribute> | Object[ ] | If the timeseries filter is present. |
result.<timeseries attribute>.type | String | The fixed value of the timeseries data object. |
result.<timeseries attribute>.name | String | Name of the timeseries attribute. |
result.<timeseries attribute>.unit | String | Unit of the timeseries attribute. |
result.<timeseries attribute>.interval | Number | Integer interval of the data, in seconds. |
result.<timeseries attribute>.start | String | Begin time of the data in the API server time zone, in the yyyyMMdd_HHmmss format. |
result.<timeseries attribute>.data | Double[ ] | Timeseries (fixed value for timeseries data object). |
result.related | String[ ] | Shows if the current path has the subpath. |
result.scalarChanges | Object | Shows if the scalar data change filter is present. |
result.scalarChanges.attrId | String | ID of the scalar attribute. |
result.scalarChanges.data.name | String | Name of the scalar attribute. |
result.scalarChanges.data.oldValue | String | Previous value of the scalar attribute. |
result.scalarChanges.data.newValue | String | New value of the scalar attribute . |
result.scalarChanges.data.time | String | Time when the change is observed in the Analyzer detail view server time zone, in yyyyMMdd_HHmmss format. |
result.relationChanges | Object | Shows if the relation change filter is present. |
result.relationChanges.signature | String | Signature of the resource data. |
result.relationChanges.name | String | Name of the resource data. |
result.relationChanges.connected | Boolean | Indicates if the resource is connected or not. |
result.relationChanges.time | String | Time when the change in the relation status is observed, in the API server time zone in yyyyMMdd_HHmmss format. |
code | String | Eight-digit hexadecimal error code. |
error | String | Error message. |
Request examples
Query to get timeseries and scalar data:
{ "query":"vm[=memory rx .*][@cpuUsage rx b .*]", "startTime":"20140713_230000", "endTime":"20140713_230500" }
Query to get Tuning Manager historical timeseries (performance) data:
To query the migrated historical timeseries (performance) data, you must specify the following parameters in the request body:
- db=cdb1 Obtains only the Tuning Manager historical timeseries (performance) data.
- inputInterval=supported-values The migrated
historical timeseries (performance) data collection intervals. The supported
values for
inputInterval
are: h (hour), d (day), w (week), m (month), and y (year). The query output is based on the specifiedinputInterval
(data collection interval).
{ "query":"(db=cdb1)raidLdev[=name rx 421358-00:00:09]&[@readIOPS rx b .*]{inputInterval=h}", "startTime":"20190404_113000", "endTime":"20190405_113000" }
Notes:
- You cannot set the advanced MQL aggregations, roll up and script filters, and synthetic attributes on the Tuning Manager historical timeseries (performance) data.
- Only
.*
is allowed as regex for timeseries attributes (double or string regex is not allowed).
Query to get changes in the scalar data:
This query gets the resources for which the scalar data of the specified attribute has been changed within the query time window.
{ "query":" vm[~memory]", "startTime":"20140713_230100", "endTime":"20140714_000000" }
Query to get resource relation changes:
This query gets the resources for which relation of the specified resource type has been changed within the query time window.
{ "query":" vm[+h]", "startTime":"20140713_230100", "endTime":"20140714_000000" }
Get the complete query result at the same time with
utcOffset
specified:
{ "query":"vm[=memory rx .*][@cpuUsage rx b .*]", "startTime":"20140713_230000", "endTime":"20140713_230500", "utcOffset":"UTC-04:00" }
When
splitResponse
and
maxResponseSize
are specified:
{ "query":"vm[=memory rx .*][@cpuUsage rx b .*]", "startTime":"20140713_230000", "endTime":"20140713_230500", "splitResponse":true, "maxResponseSize":0.05 }
If
useRealTime
is not specified in the API URL but specified in the query API body, the value defined in the query API request body is considered.
{ "query":"(useRealTime=true)raidPort[@totalIOPS rx b .*]", "startTime":"20170124_000000", "endTime":"20170124_150000" }
Status code |
Message |
Description |
200 | OK | Request was successful, and the response body contains the requested log details. |
206 | PARTIAL CONTENT | Request is in progress, and the incremental content is available in the response body. |
400 | BAD REQUEST | Request URL or request body validation failed. Check the response body for details. |
401 | UNAUTHORIZED | Supplied authentication token is invalid or does not have the appropriate credentials to access the resource. |
404 | NOT FOUND | API server could not find a resource matching the request. |
405 | METHOD NOT ALLOWED | Request HTTP method is not allowed for the operation. |
500 | SERVER ERROR | API operation request failed. Check the response body for details. |
The following table lists the common API response codes that might be generated through the standard API. If an error response is not listed, examine the HTTP status codes to determine the best method for addressing the issue.
Response code | Message | Condition |
62010008 | Mandatory parameter {query} is not specified. | Parameter
query is not specified.
|
6201000F | Invalid value specified for parameter {query}. Query : vm[memory rx .*]. | Parameter
query contains an invalid MQL query.
|
62010008 | Mandatory parameter {startTime} is not specified. | Parameter
startTime is not specified.
|
6201000F | Invalid value specified for parameter {startTime}. | Parameter
startTime is not specified in the correct format (yyyyMMdd_HHmmss).
|
6201000F | Invalid value specified for parameter {startTime}. | Specified
startTime parameter is not in the valid range.
|
62010008 | Mandatory parameter {endTime} is not specified. | Parameter
endTime is not specified.
|
6201000F | Invalid value specified for parameter {endTime}. | Parameter
endTime is not specified in proper format (yyyyMMdd_HHmmss).
|
6201000F | Invalid value specified for parameter {endTime}. | Specified
endTime is not in the valid range.
|
6202000F | Invalid value specified for parameter {startTime, endTime} the endTime must be after startTime. | Specified
endTime parameter is before or equal to the
startTime parameter.
|
62010002 | Invalid JSON Request. | Specified input JSON is invalid. |
6202001B | Input query length is beyond the permissible limit of 8192 characters. | Input query length is beyond the permissible limit. |
620000E9 | License is not valid. | License is not uploaded, or the uploaded license is invalid or expired. |
620000E9 | Authorization needed. | Request is sent with an invalid authentication token. |
620000E4 | Dataset with {name}:[ds1] does not exist. | Request is sent for a dataset that does not exist. |
620000E0 | HTTP method [GET] is not supported for action [query]. | Request is sent with any HTTP method other than POST. |
620000E2 | Application encountered an internal error. | API server encountered an unknown error. |
Best practices for query APIs
Consider the following best practices when using the query API.
Compose your queries by considering the system performance monitor resource usage.
If HTTP status code 206 is returned from the query API, use the get request status API to obtain the results until status code 200 is returned. To stop an API request while it is still processing, use the abort request API. If you do not use the abort request API, then the query result is saved in memory until the response is obtained (default: one hour), after the query processing is complete.
We do not recommend running a query that might involve a large number of resources. If you must run such a query, use the REST API to check the CPU and memory usage. For best results, divide the request into multiple queries.
For example, the following query involves a large number of resources at a time:
raidMPB[=name rx XXXXXX.*]/raidLdev[=volumeAttribute rx V-VOL]&[=name rx .*]/raidPool[=name rx .*]/raidLdev[=volumeAttribute rx POOL]&[=name rx .*]/raidPG[=name rx .*]
The best practice is to split the query as shown in the following example.
Query1:
raidMPB[=name rx XXXXXX.*]/raidLdev[=volumeAttribute rx V-VOL]&[=name rx .*]/raidPool[=name rx .*]
Query 2:
raidPool[=name rx Pool-names-retrieved-by-query-1]/raidLdev[=volumeAttribute rx POOL]&[=name rx .*]/raidPG[=name rx .*]
Using a large number of filter conditions can significantly increase the system load. When specifying filter conditions in MQL, use the REST API to monitor the resource usage, and reduce the number of filter conditions accordingly.
Separate the query conditions
For example, the following query involves too many conditions at a time:
raidLdev[=name rx XXXXXX-00:00:00|XXXXXX-00:00:01|Too-many-conditions|XXXXXX-00:03:FF]&[@totalIOPS rx b .*][@responseTime rx b .*]
The best practice is to split the conditions as shown in the following example.
Query 1:
raidLdev[=name rx XXXXXX-00:00:00|XXXXXX-00:00:01|Conditions|XXXXXX-00:01:FF]&[@totalIOPS rx b .*][@responseTime rx b .*]
Query 2:
raidLdev[=name rx XXXXXX-00:02:00|XXXXXX-00:02:01|Conditions|XXXXXX-00:03:FF]&[@totalIOPS rx b .*][@respo
Use a regular expression
For example, the following query involves too many conditions at a time:
raidLdev[=name rx XXXXXX-00:00:00|XXXXXX-00:00:01|Too-many-conditions|XXXXXX-00:03:FF]&[@totalIOPS rx b .*][@responseTime rx b .*]
The best practice is to use the regular expression as follows:
raidLdev[=name rx XXXXXX-00:0[0-3]:.*]&[@totalIOPS rx b .*][@responseTime rx b .*]