EDA query language (EQL)

EDA supports queries using a syntax that is collectively referred to as the EDA Query Language, or EQL.

In EDA, a query consists of:

  • a Table that identifies the overall set of data being queried.
    Note: The Table is the only mandatory element of any query.
  • a Selector that defines a set of fields to return (along with any functions to run on those fields).
  • a Filter that restricts the set of results to return.
  • a Sort that indicates the order in which results should be returned.
  • a Limit that restricts the number of results to return.
  • a Frequency that indicates the minimum period after which to automatically update the query results.
For example:

  • .namespace.alarms.current-alarm

  • .namespace.alarms.current-alarm where (severity = "critical")

  • .namespace.alarms.current-alarm where (severity = "critical") order by [type]

  • .namespace.alarms.current-alarm where (severity = "critical") limit 5

  • .namespace.alarms.current-alarm where (severity = "critical") order by [type] sample milliseconds 500

EDA also supports queries using Natural Query Language.

Queries and namespaces

Query results are always constrained to the set of namespaces to which the current user has access permissions. By default a system administrator can see query results spanning all namespaces; but users with fewer namespace privileges see results from only some namespaces, or only a single namespace.

If you have permission to access multiple namespaces, you can cite one or more specific namespaces as part of the filter to constrain the result to those namespaces.

Elements of a query

A query using EQL can include the following elements.

Table

A Table is specified in jspath notation, with a Table boundary at all lists and containers within a TopoNode schema, or within containers/lists provided by StateEngine scripts or external gRPC publishers via StateController.

In simple terms, each node within the jspath is its own table: .namespace.node is a table, .namespace.node.srl is a table, and .namespace.node.srl.interface is a table.

A Table can be identified in the format as a complete jspath without keys. For example: .namespace.node.srl.interface.subinterface

Selector

A Selector is denoted by the fields keyword, where the value is an array of fields to return, along with any functions to run.

  • These fields must exist in the Table that is being queried, or the query fails.
  • For example .namespace.node.srl.interface FIELDS [admin-state, description] ORDER BY [oper-state ascending natural] .
  • No fields other than those defined are returned. If no fields are selected then all fields from the table are returned.
  • The fields keyword must precede any where or order by keywords.

A set of functions can assist with evaluation and aggregation. For example:

  • average() to evaluate the average of a field matching a Filter over time (the time window here is currently fixed to the current set of data).
  • count() to return the count of unique combinations matching a Filter.
  • sum() to sum the values for a field matching a Filter.

Filter

A Filter is a string defining any filters to use. A Filter is defined with a where term. The following rules apply:

  • A Filter consists of an ordered set of fields, operators, values, and keywords.
    • Keywords may be capitalized or not. For example, both and and AND are valid.
    • Operators include:
      • Comparison operators with where clause - =, !=, <=, >=, >, <
      • and, or, and grouping constructs within where clause
      • in operator, allowing an array of values to be provided for comparison
      • not in operator, allowing an array of values to be provided for exclusion in the comparison
  • Field names in a Filter are unquoted, and values are quoted where they are strings, and unquoted when they are integers:
    • For example, .namespace.node.srl.interface where (oper-state = "up").
    • For example, .namespace.node.srl.interface where (ifindex = 49150).
  • A Filter may string together multiple criteria through the use of (), and the keywords AND, and OR.
    Note: Even when using a single where statement it must be contained within ().

Sort

A Sort is similar to a Filter, but instead of describing how to select data, it describes how to return data. A Sort is denoted by the ORDER BY keywords which control the ordering (sorting) of data.

  • A Query may include a single ORDER BY keyword, where the value is an array of fields, sorting algorithms, and directions which are evaluated in the order they are presented.
    • For example .namespace.node.srl.interface ORDER by [oper-state ascending natural].
    • The second value may be either ascending or descending.
    • The third value is optional but currently can only be natural.

Limit

A Limit restricts the number of results that are returned. It is denoted by the limit keyword. A Limit is processed after any other operations (for example, the Sort operation).

  • A limit accepts a single integer value.
  • This can be combined with Sort to get the 'top' N results, or the 'bottom' N results, where N is the value provided to the limit keyword.
  • The maximum value for limit is 1000, and the minimum value is 1. Any values above or below this return an error.

Frequency

A Frequency allows you to control the rate at which data is returned, and is denoted by the delta keyword.

  • The delta keyword must be passed two values - one denoting the units used, and another the actual value.
  • For example, .namespace.node.srl.interface.traffic-rate where (in-bps != 0) delta seconds 1 means "do not update the client more than once every 1 second."
  • The value is the minimum period at which results are updated for the query.
  • Valid units are seconds and milliseconds.

Natural-language queries

When creating a query in EDA, you also have the option of writing the query in natural language. With a natural-language query, you can ask questions of EDA such as:

  • List all up interfaces
  • List all interfaces that have an MTU of 9232, sorted by interface name
  • What statistics are available on interfaces
  • Show me any interfaces with error counters above 0
  • Show me the unique reasons interfaces are down
  • Show me the unique reasons interfaces are down, and count the unique values
  • Show me all of my processes sorted by memory usage descending
  • Show me the total numbers of packets sent on all interfaces
  • Show me the number of MAC addresses on subinterfaces on "leaf-1-1", include the interface name
Note: Currently, natural-language queries are resolved only against the .node.srl table.

Creating a query with EQL

The page in the EDA UI on which to create queries is located at Main > Queries.

  1. From the Query drop-down, select EQL Query.
  2. Enter an expression using EDA Query Language (EQL), as described in Elements of a query.
    • Begin the query with a period (.).
    • As you begin typing the query, EDA offers suggestions for the next element in the expression.
    • The finished query must specify a Table in jspath notation. This table identifies the overall set of data being queried. Optionally, the query can also include:
      • a Selector that defines a set of fields to return (along with any functions to run on said fields).
      • a Filter that restricts the set of fields to return.
      • a Sort that indicates the order in which data should be returned.
      • a Limit that restricts the number of results to return.
      • a Frequency that indicates the minimum period after which to automatically update the query results.
  3. When you have completed the query expression, click Query to view the results.
    Note: Results are limited to the first 1,000 matches.

Creating a query with natural language

The page in the EDA UI on which to create queries is located at Main > Queries.

  1. From the Query drop-down, select Natural Language Query.
  2. Type your question using simple language (not necessarily English). Your question must specify something to return information about (such as nodes, links, or other network objects).
    Note: Currently, natural-language queries are resolved only against the .node.srl table.
    Optionally, your question can also specify:
    • conditions those objects must meet.
    • ways to sort the returned data.
    • a limit on how many results to return.
    • a time period after which to automatically update the query results.
  3. When you have finished typing your query, click Query to view the results.
    Note: EDA renders your natural language question in EDA Query Language, and displays the EQL expression immediately below the query field.
    Note: Results are limited to the first 1,000 matches.