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 is its own table: .node is a table, .node.srl is a table, and .node.srl.interface is a table.

A Table can be identified in one of the following formats:

• a complete jspath without keys. For example: .namespace.node.srl.interface.subinterface.
• a jspath with keys. For example: .namespace.node{.name=="dut1"}.srl.interface{.name=="ethernet-1/1"}.subinterface{.index=="0"}.
• a mix of the two. For example: .namespace.node.srl.interface{.name=="ethernet-1/1"}.subinterface.

In cases where keys are omitted, a wildcard key is assumed. This means the last example could be rewritten as:

• .namespace.node{.name=="*"}.srl.interface{.name=="ethernet-1/1"}.subinterface{.index=="*"}

This could also be written as:

• .namespace.node.srl.interface.subinterface where ..name="ethernet-1/1"

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:

• isSet() to evaluate if a field is set.
• 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 seen value 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. A few rules are used:

• A Filter consists of an ordered set of fields, operators, values, and keywords.
  • Keywords may be capitalized or may not For example, both and and AND are valid.
  • Operators include =, !=, <=, >=, >, <, ~, is not, is, in, not in, / (division), + (addition), - (subtraction), * (multiplication), % (modulo), ^ (power/exponent).
    • is and is not evaluate similarly to = and !=, except that they allow the EMPTY keyword, . For example: is not EMPTY.
    • in is provided an array of values, for example .node.srl.interface where (oper-state in ["up", "down"]).
• 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: Note that even when using a single where statement it must be contained within ().
  • For example: .table where ((oper-state = "down" and mtu = 1500) or oper-state = "up").

• A Filter can query ancestor keys and values by referencing their full jspath.

  • For example, to query the field oper-state in a direct parent, the query could read .namespace.node.srl.interface.subinterface where (../oper-state = "up").
  • A Filter could also query a grandparent with ../../, a great grandparent with ../../../, and so on.
  • For example, to add Filter criteria for a parent key, the full jspath can be used: .namespace.node.srl.interface.subinterface where (.node.name = "dut1").
• A Filter can query any child or parent containers, but cannot navigate into lists. For example, to query the field error-count in the statistics container of a parent, the query could read .namespace.node.srl.interface.subinterface where (../statistics.error-count > 0).
• Evaluations against an unset field yield True for not equal and False for equal.
  • For example, assuming .namespace.node.srl.interface.oper-state (with valid keys) would exist with the current value up.
    • This query (again with valid keys) would return True and return the interface: .node.srl.interface where (oper-state = "up").
    • This query (again with valid keys) would return False and not return the interface: .node.srl.interface where (oper-state != "up").
  • Taking the same example, where oper-state was not set:
    • This query (again with valid keys) would return False and not return the interface: .namespace.node.srl.interface where (oper-state = "up").
    • This query (again with valid keys) would return True and return the interface: .namespace.node.srl.interface where (oper-state != "up").

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 controls 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 (or short forms asc, desc).
  • The third value is optional and may be either 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 (perhaps most relevant, 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.