Skip to main content

We've Moved!

Product Documentation has moved to docs.hitachivantara.com
Hitachi Vantara Knowledge

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.

Request line
baseURL?action=query&dataset =<Datasetname>&processSync=<true | false>
Request body
{
  "query":"",
  "startTime":"",
  "endTime":""
}
Request example
POST action=query&dataset=defaultDs HTTP /1.1 Authorization:Basic ZnJlZDpmcmVk
{
  "query":" vm[~memory]",
  "startTime":"20140713_230100",
  "endTime":"20140714_000000"
}
Request parameters
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 pending.result.limit.to.proceed.external property from the /usr/local/megha/conf/sys/query.properties file.

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.

Response body
{
  "status":{
    "total":,
    "matched":,
    "processed":,
    "completed":,
    "aborted":,
    "hasErrors":
  },
  "result":[
    {
      "signature":"",
      "name":"",
      "memory":{
       "type":"",
       "name":"",
       "unit":"",
       "data":""
       },
      "cpu Usage":[
        {
          "type":"",
          "name":"",
          "unit":"",
          "interval":,
          "start":"",
          "data":[
            , , , , 
          ]
        }
      ]
    }
  ]
}
Response example
{
  "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
          ]
        }
      ]
    }
  ]
}
Request parameters

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 specified inputInterval (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 codes

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.
Response codes

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.

Avoid inordinate resource usage on the Analyzer detail view server

Compose your queries by considering the system performance monitor resource usage.

Aborting requests to collect results

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.

Split resource-intensive queries

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 .*]
Avoid too many filtering conditions

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
.*]

 

  • Was this article helpful?