PDL Reference

This is a reference guide for the Padas Domain Language (PDL). In this manual you will find explanation of PDL syntax, descriptions, and examples.

In order to understand how PADAS works, please review Getting Started.

PDL Syntax

The following sections desribe the syntax used for Padas Domain Language (PDL) queries. PDL performs operations on a single JSON event and simply compares to the query, then returns a boolean response to indicate a match or mismatch.

PDL syntax requires fields to be available in JSON object that it compares against and supports nested JSON objects/fields with dotted notation (e.g. field.subfield.anothersubfield etc.)

Examples

JSON Event Data PDL Query Expected Result

{
  "field1":{
    "subfield1":"subvalue1",
    "subfield2":"sub value2"
  },
  "field2":"value2",
  "field3":123
}

field1.subfield2 ?= "value2"

true

{
  "field1":"value1",
  "field2":"value2 text2 value2",
  "field3":123,
  "field4":"value4",
  "field_5":5,
  "field-6":6,
  "field:7":7
}

field1="va*e1"

true

  {
    "field1":{
      "subfield1":"subvalue1",
      "subfield2":"sub value2"
    },
    "field2":"value2",
    "field3":123
  }

(field1.subfield2 = "value2" AND field3=123)

false

Supported Operators

PDL supports the following operators and keywords when comparing events to the query.

Below table provides examples based on the following JSON value:

{
  "field1":"value1",
  "field2":"value2 text2 value2",
  "field3":123
}

Operator/Keyword	Description	Example (evaluates to `true`)
`NOT`	Negates the result.	`NOT (field1 = "valueXXX")`
`AND`	Expects both sides of the expression to be `true`.	`field1="value1" AND field3=123`
`OR`	Expects at least one side of the expression to be `true`.	`field1="xyz" OR field3=123`
`IN`	Returns `true` if the field value exists within the provided array. Note that all array values must be one value type (either String or Integer).	`field3 IN [111, 222, 123, 444]`
`=`	Equals, returns `true` if the value is an exact match. A single wildcard `*` is also accepted for string values.	`field1="value1"` `field1="val"` `field1=""`
`!=`	Not Equals, returns `true` if the value does not match.	`field3 != 456`
`?=`	Contains, checks whether the string value contains the query.	`field2 ?= "text2"`
`>`	Greater than, returns `true` if query comparison value is greater than event field value.	`field3 > 100`
`<`	Less than, returns `true` if query comparison value is less than event field value.	`field3 < 200`
`>=`	Greater than or equals, returns `true` if query comparison value is greater than or equals to the event field value.	`field3 >= 123`
`<=`	Less than or equals, returns `true` if query comparison value is less than or equals to the event field value.	`field3 <= 123`

Supported JSON Data Types

PDL comparisons work on String, Integer, and Boolean JSON value data types. String comparisons MUST be defined in quotes " within PDL query definition.

Examples:

PDL query with field1="123" will compare "123" as a String JSON data type.

PDL query with field2=123 will compare 123 as an Integer JSON data type.

PDL query with field3=true will compare true as an Boolean JSON data type.

Wildcard Support

PDL supports a single wildcard * with Equals operator (=) for String JSON values. Following are valid PDL query examples with wildcard usage:

field1="val*1"
field1="val*"
field1="*ue1"
field1="*"

Grouped arguments

Sometimes the syntax must display arguments as a group to show that the set of arguments are used together. Parenthesis ( ) are used to group arguments.

For example in this syntax: (field1="val1" OR field2=123) AND field3="value3"

The grouped argument is (field1="val1" OR field2=123) and its results are evaluated as a whole.