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

POST baseURL/dbapi.do?action=query&dataset=<Datasetname>&processSync=<true | false>

Request body

{
  "query":"",
  "startTime":"",
  "endTime":""
}

Request example

POST /dbapi.do?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 can query Tuning Manager historical timeseries (performance) data that was processed until v11.0.0-00 of the Analyzer detail view server.
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.