EDA query language (EQL)

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 file 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 format 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.
• max() to return the maximum found value for a given field matching a Filter.
• concat() to merge multiple keys into a single field with a user defined delimiter.
  For example :

  fields [ concat(.namespace.name, “/”, .namespace.node.name) as “Namespace/Node”, .namesace.node.srl.interface.name as Interface ]

  Note: concat() is used for EDA dashboards when a chart requires a single unique key (or a primary and secondary key), but the EDB path includes three or more keys.

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 ().
• EQL Filters support the is set and is not set operators within a where clause.

  Evaluations against an unset field will yield True for not equal and NULL for equal.

  • The evaluation follows the three-valued logic of True, False, and Null to ensure for logical consistency.
  • not Null is Null
  • X and Null is Null
  • X or Null is X
  • You can use is set and is not set to check for a field that is optional or has no default value. This comparison on a field checks whether the field has any value. If you want to include unset fields, you must also use is not set .
  • This can also be used to check for Null such as a case where (mtu < 2000) is not set since it behaves like unset field

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.

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.

Regular expressions with ~

Some EQL expressions need to match substring (or contains), prefix, and suffix matching on fields. To support these cases (among others), the ~ operator is supported. This allows the matching of regular expressions against values.

For example the expression .field where (fieldname ~ "regex-pattern") would match all objects in the .field table, where those objects have a field named fieldname and that field contains the string value regex-pattern.

The right side of the ~ operator must be a quoted string. If quotes are required inside the regex (for example, to match a literal quote character), you must escape them with a backslash (\).