Block patterns enable users to define a multi-command pattern of configuration. Block patterns can be used with NQE functions to determine if they match a device configuration or to extract data from a device configuration.

Block patterns can be defined within an NQE query, via the block pattern literal syntax, presented in the following sections. The following functions provide additional methods of creating and modifying block patterns:

• blockPattern
• mergeBlocks
• withOption

The functions that match block patterns against configuration are

• blockMatches
• hasBlockMatch
• blockDiff

⚠️ There are deprecated versions of these methods that end in the suffix _alpha1.

Creating Block Patterns

Block patterns can be defined within an NQE query using block pattern literal syntax. For example, the following NQE variable definition defines a block pattern:

pattern = ```
interface
  zone-member security
  ip address {ip:string}
parameter-map
  log dropped-packets
```;

A block pattern literal starts with triple backticks (```), then continues withany number of lines, and then ends with triple backticks on a newline.

Each line is a line pattern (see the data extraction guide for more details on these line patterns).

The indentation of the lines defines the hierarchical (tree) structure among the lines. For example, in the above pattern, zone-member security and ip address {ip:string} are children of the interface line.

A block pattern can also be created from an arbitrary String value by using the blockPattern function.

Block Pattern Matching

A block pattern matches a configuration if all the lines of the pattern match lines of configuration in a way that respects the hierarchical structure of the pattern. For example a successful match of the above pattern to a device configuration would need to match interface to a top-level line of configuration and would match zone-member security and ip address {ip:string} lines to child lines of the configuration line that matched interface. For example, the above block pattern would match the following configuration:

parameter-map type inspect SampleObject
  log dropped-packets
interface GigabitEthernet2
  ip address 1.2.3.4 255.255.255.248
  zone-member security abcde

Note that a block pattern is unordered: a configuration can match a pattern while having its lines appear in an order different from the order of the lines in the block pattern, as long as the hierarchy is respected. For example, the above block would also match the following configuration, where lines appear in different orders:

interface GigabitEthernet2
  zone-member security abcde
  ip address 1.2.3.4 255.255.255.248
parameter-map type inspect SampleObject
  log dropped-packets

caution

The block pattern syntax uses indentation to provide hierarchical structure and uses curly braces to denote non-literal pattern elements, such as {string} and {vlan:number}. Some device OSes do not use indentation for structure and use curly braces in their configuration syntax. For example, the following is a JunOS configuration fragment:

system {
  syslog {
    host 1.2.3.4 {
      facility-override kernel;
    }
  }
}

To use block patterns to match this sort of configuration, the curly braces must be removed (because otherwise they would be interpreted as keywords in the pattern syntax), and the indentation must correspond to the structure of the original curly braces. For example, to match the above configuration, we can use the following block pattern:

pattern = ```
system
  syslog
    host 1.2.3.4
      facility-override kernel;
```;

Unmatched configuration

By default, block patterns match as long as the lines can be matched to lines of configuration. In other words, the device configuration may have extra lines of configuration that are not relevant to the block pattern. For example, the above block pattern matches a configuration such as the following, which has some extra lines of configuration in the matched interface configuration block:

parameter-map type inspect SampleObject
  log dropped-packets
interface GigabitEthernet2
  encapsulation dot1Q 75
  ip address 1.2.3.4 255.255.255.248
  zone-member security abcde
  no ip redirects

If you prefer to match a particular block of configuration only if it contains the pattern lines and no other lines of configuration, then use the {%unmatched-config:forbid%} line. For example, the above block pattern can be modified as follows to match interface blocks that have only the zone-member and ip address lines and nothing else:

pattern = ```
interface
  zone-member security
  ip address {ip:string}
  {%unmatched-config:forbid%}
parameter-map
  log dropped-packets
```;

Note that this {%unmatched-config:forbid%} line applies this option in the block in which it appears and any blocks at a deeper level (underneath the interface parent of the {%unmatched-config:forbid%} line). Include the {%unmatched-config:forbid%} line at the top-level to apply this option to the whole block pattern.

Negated Block Patterns

The above block patterns match configurations if the configurations contain certain lines. Block patterns also support the ability to specify that a configuration should not contain a specific line or block matching some pattern. For example, the following pattern matches an interface that has an ip address but which does not have a zone-member configured:

pattern = ```
interface
  {%-%} zone-member security
  ip address {ip:string}
```;