Skip to main content
Cisco SD-WAN
Support
Product Documentation
Viptela Documentation

vManage Simple Query

The vManage NMS statistics database collects statistics from all vEdge routers periodically, starting from when they join the overlay network. The vManage API query language allows you to build queries that retrieve selected statistics from the vManage NMS statistics database.

vManage simple queries retrieve raw data from the vManage statistics database.

In a simple query, you specify the name or names of the fields whose values you want to retrieve, the time period over which to retrieve the value, and the order in which to sort the retrieved data. For example, you can retrieve statistics for an IP address for the last 6 hours, and you can sort them in descending order by hostname.

Simple Query Format

In a simple query, you define the number of records to retrieve, the query conditions and rules, the sort order of the output, and the fields to include in the output. Each query consists of four sections:

  • Size—Number of statistics records to retrieve.
  • Query—Input values for the statistics database query.
  • Sort—Output field to sort the results by and sorting order.
  • Fields—Statistics data fields to include in the query output.

A vManage simple query has the following format:

{
  "size": integer,
  "query":
  {
    "condition": "AND | OR",
    "rules":
    [
      {
        "field": "field-name",
        "type": "data-type",
        "value":
        [
          "value"
        ],
        "operator": "operator"
      }
    ]
  },
  "sort":
  [
    {
      "field": "field-name",
      "order": "(asc | desc)"
    }
  ],
  "fields":
  [
    "field-name",
  ],
}

Simple Query Components

Size Component

Number of Records To Return
"size": integer
Number of statistics records to return in the simple query. This field is optional.
Values: Any integer.
Default: 10000

Query Component

Rules To Select Data
"query":
One or more rules to use to select data from the statistics records. This field is mandatory.
Filter Condition
"condition": "(AND | OR)"
Condition to use to filter statistics records if a query has two or more rules. It can be:
• AND—Record must match all rules.
• OR—Record must match at least one rule.
Rules for Collecting Statistics Records
"rules": [...]
Rules to use to collect statistics records. You can specify one or more rules.
Property Component of a Rule
"field": "field-name"
Name of the property for which to select statistics. The Response Body of the API calls whose URLs end in /fields lists the allowable values for field-name in the "property" field. For more information, see the last section of this article.
Values: Any string listed in the "property": line of an API call's Response Body.
Property Type Component of a Rule
"type": "data-type"
Data type of the property. The Response Body of the API calls whose URLs end in /fields, list the allowable values for data-type in the "dataType" field. For more information, see the last section of this article. data-type can be one of the following:
date—Date and time, in the format yyyy-MM-ddThh:mm:ss (for example, 2017-01-23T15:59:59).
double—64-bit number that includes a decimal point.
int—32-bit number that does not include a decimal point.
long—64-bit number that does not include a decimal point.
string—Text string. It can include any ASCII and extended ASCII characters, and it can include spaces.
Value Component of a Rule
"value": [ "value" ]
Value or values to query for. Specify the value in the format required by the data-type. To specify more than one value, separate them with commas.
Operator Component of a Rule
"operator": "operator"
Operator to use to perform filtering of statistics records. You use date, numeric, and strings operators. The type of operator in a rule is a function of the field type.
Date Operators
When the field type requires a date or time, specify it in one of the following formats:
between date1, date2—Time range, starting at date1 and ending at date2. Specify the date in the format yyyy-MM-dd.
last_n_days—Last number of days from the current time. For example, for a current date and time of 2017-01-23T15:59:59, last_3_days returns data from 2017-01-20T15:59:59 through 2017-01-23T15:59:59.
last_n_hours—Last number of hours from the current time. For example, for a current time of 15:13, last_2_hours returns data from 13:13 through 15:13.
last_n_weeks—Last number of weeks from the current time. For example, for a current date and time of 2017-01-23T15:59:59, last_2_weeks returns data from 2017-01-09T15:59:59 through 2017-01-23T15:59:59.
Numeric Operators
When the field type requires a number, specify it in one of the following formats. You cannot include wildcards in these operators.
equal value—Match a value exactly.
greater value—Match a value greater than the specified number.
greater_or_equal value—Match a value greater than or equal to the specified number.
in value[, value]—Match a value that contains the specified number. To specify more than one number, separate them with commas.
less value—Match a value less than the specified number.
less_or_equal value—Match a value less than or equal to the specified number.
not_equal value—Match all values except the specified number.
not_in value[, value]—Match all values except those that contain the specified number. To specify more than one number, separate them with commas.
String Operators
When the field type requires a text string, specify it in one of the following formats. You cannot include wildcards in these operators.
equal value—Match a value exactly.
in value[, value]—Match a value that contains the specified string. To specify more than one string, separate them with commas.
not_equal value—Match all values except the specified string.
not_in value[, value]—Match all values except those that contain the specified string. To specify more than one string, separate them with commas.

Sort Component

To sort on multiple fields, include multiple "field""order" pairs in the query. Sorting is done in the order the fields are listed, starting with the first field.

Field To Sort By
"field": "field-name"
Field to use to sort the data. The Response Body of the API calls whose URLs end in /fields, list the allowable values for field-name in the "property" field. For more information, see the last section of this article.
Sort Order
"order": "(asc | desc)"
Sort the field in ascending or descending order. This field is optional.
Default: Sort by data creation time.

Fields Component

Fields To Return in Query
fields": [ "field-name" ]
List of fields to return in the response. To specify more than one field, separate them with commas. This field is optional.
Default: Return all fields.

Determine Field Names and Data Types

To determine the field names and data types to include in the field and type portions of a query, use the API GET calls whose names end in the string /fields. The Response Body for these calls shows two fields:

  • "property"—Property name to include in a field or fields portion of a query.
  • "dataType"—Type of data to include in the type portion of a query.

For example, to create a query regarding DPI statistics, use the /statistics/dpi/fields API call. You can issue this call from the following URL:

https://vManage-ip-address/dataservice/statistics/dpi/fields

You can also issue this call from the URL https://vManage-ip-address/apidocs:

  1. Click Monitoring – DPI.
  2. Click /statistics/dpi/fields.
  3. Click Try it out.

For dataservice/statistics/dpi/fields, the Response Body looks like this:

[
  {
    "property": "vip_idx",
    "dataType": "number"
  },
  {     
    "property": "entry_time",     
    "dataType": "date"   
  },   
  {     
    "property": "vpn_id",     
    "dataType": "number"   
  },   
  {     
    "property": "source_ip",     
    "dataType": "string"   
  },   
  {     
    "property": "dest_ip",     
    "dataType": "string"   
  },   
  {     
    "property": "source_port",     
    "dataType": "number"   
  },   
  {     
    "property": "dest_port",     
    "dataType": "number"   
  },   
  {     
    "property": "octets",     
    "dataType": "number"   
  },   
  {     
    "property": "packets",     
    "dataType": "number"   
  },   
  {     
    "property": "application",     
    "dataType": "string"   
  },   
  {     
    "property": "family",     
    "dataType": "string"   
  },   
  {     
    "property": "create_time",     
    "dataType": "date"   
  },   
  {     
    "property": "expire_time",     
    "dataType": "date"   
  },   
  {     
    "property": "ip_proto",     
    "dataType": "number"   
  }
]

Example Simple Query

The following example shows a simple query for the dataservice/event POST call. This query returns, for the last 24 hours, the latest 100 security events whose severity is critical.

{
  "size": 100,                          <== Return 100 records
  "query": {
    "condition": "AND",                 <== Records must match all rules; there are three:
    "rules": [
      {
        "value": [                      <== Rule #1: Records from the last 24 hours
          "24"
        ],
        "field": "entry_time",
        "type": "date",
        "operator": "last_n_hours"
      },
      {
        "value": [                      <== Rule #2: Severity level = critical
          "critical"
        ],
        "field": "severity_level",
        "type": "string",
        "operator": "in"
      },
      {
        "value": [                      <== Rule #3: Event type = security
          "security"
        ],
        "field": "component",
        "type": "string",
        "operator": "in"
      }
    ]
  }
}
  • Was this article helpful?