# JPath

JSONPath is a query language for JSON, often shortened to "JPath". Aggregations.io uses a simplified variation of JPath for **filtering** events and **addressing** individual properties.

---

## Addressing properties using JPath Notation {#notation}

A JPath expression specifies a path to an element, or a set of elements, in a JSON structure. Paths can be specified with three notation types:

+++ Dot Notation
```
@.device.platform
```
+++
+++ Bracket Notation
```
@['device']['plaftorm']
```
+++
+++ Mixed Dot and Bracket Notation
```
@['device'].platform
```
+++

!!!
For JSON properties that include spaces or other special characters, use bracket notation. See [Complex Payloads](/jpath#complex-payloads) for more details. 
!!!

---

## JPath Filters {#filters}

### Operators

Operator | Description | Example
--- | --- | ---
== | Equal to. String values must be enclosed in single quotes (not double quotes) |```@.app.version == 2.0```
!= | Not equal to. String values must be enclosed in single quotes |``` @.app.version != 2.0```
\> | Greater than | ```@.duration > 60```
\>= | Greater than or equal to | ```@.app.buildNum >= 4102 ```
/< | Less than | ```@.app.buildNum < 3000```
<= | Less than or equal to | ```@.app.version <= 1.9```
`LIKE` | String similarity comparison using `%` as wildcard. | ```@.eventName LIKE 'app%'```
`ILIKE` | Case-Insensitive String similarity comparison, using `%` as wildcard. | ```@.eventName ILIKE 'ApP%'```  
=~ | Matches an [re2](https://github.com/google/re2/wiki/Syntax){target="_blank"} regular expression, surrounded by `/` to denote start & end. |```@.color =~ /gr(a|e)y/```  _Matches events where the color property is "grey" or "gray"_
in | Checks if the value is equal to one of provided values | ```@.eventName in ['appOpen', 'appClose']``` see array rules below.
|| Checks existence of a field | ```@.error```  _Matches events who have an `error` field_
\! | Used to negate a filter | ```!(@.color)``` <br /> _Matches items that do not have the color property._
\&& | Logical `AND` - used to combine multiple filter expressions | ```@.app.version==2.0 && @.device.platform == 'ios'```
\|\| | Logical `OR`, used to combine multiple filter expressions | ```@.eventName == 'AppClose' || @.eventNamne == 'AppBackground'```
`.length` | Used with array properties to compare array length | ``` @.player.weapons.length > 0```

### Values

Value type | Description
--- | ---
String | String literals, ensure they are enclosed in single-quotes. 
Numeric | Number literals, `0` or `0.1` or `-12345678910112` etc...  When a numeric literal is the value, an attempt will be made to cast the field to a number (float), if that cast fails, the event is disregarded. 
Boolean | `true` or `false`. When a boolean literal is the value, the field specified will be cast to a boolean. If that cast fails, the event is disregarded.
Null | `null` literals can be checked to confirm that a field exists and the value is explicitly `null`. If the field doesnt exist, it will not be included.
Array | Array literals can be used with the `in` operator. Arrays of mixed types (strings, numbers) will all be considered strings. For example `@.value in ['abc', 123]` will be treated like `@.value in ['abc','123']`. 
Regex | Regex literals will be treated like regex, **experimental**.  Uses Google's [re2](https://github.com/google/re2/wiki/Syntax){target="_blank"} syntax.

!!!
Need something else? [Contact us](https://aggregations.io/contact?subject=Jpath%20Request)
!!!

---

## Complex Payloads

Complex payloads are those that have spaces and other special characters in JSON property keys. To ensure proper JPath syntax, use bracket notation and/or `\` as an escape character.

+++ Spaces and Most Special Characters
For spaces (and several other special characters), simply using bracket notation will work.

![](/assets/images/complex-payload1.png)

+++ "Extra" Special Characters
Certain special characters will require `\` as an escape character, such as single quotes ('), double quotes (") and back-slash (\). 

![](/assets/images/complex-payload2.png)

+++