<commit_before>---
title: "PuppetDB 2.2 » API » v4 » Query Operators"
layout: default
canonical: "/puppetdb/latest/api/query/v4/operators.html"
---

[resources]: ./resources.html
[facts]: ./facts.html
[nodes]: ./nodes.html
[query]: ./query.html
[fact-contents]: ./fact-contents.html

PuppetDB's [query strings][query] can use several common operators.

> **Note:** The v4 API is experimental and may change without notice. For stability, it is recommended that you use the v3 API instead.

## Binary Operators

Each of these operators accepts two arguments: a **field,** and a
**value.** These operators are **non-transitive:** their syntax must always be:

    ["<OPERATOR>", "<FIELD>", "<VALUE>"]

The available fields for each endpoint are listed in that endpoint's documentation.

**Note**
In past API versions PuppetDB has supported comparisons between strings in the
database and numerical values.  For example, equality and inequality queries for 0
would match database values of "0". This behavior is not supported on the v4 API,
since typed and structured facts allow us to distinguish the two in the database.
Instead, binary operators must be predicated on the same type as the desired
database value.

### `=` (equality)

**Works with:** strings, numbers, timestamps, booleans, arrays, multi, path

**Matches if:** the field's actual value is exactly the same as the provided value.

* Most fields are strings.
* Some fields are booleans.
* Arrays match if any **one** of their elements match.
* Path matches are a special kind of array, and must be exactly matched with this operator.

### `>` (greater than)

**Works with:** numbers, timestamps, multi

**Matches if:** the field is greater than the provided value.

### `<` (less than)

**Works with:** numbers, timestamps, multi

**Matches if:** the field is less than the provided value.

### `>=` (greater than or equal to)

**Works with:** numbers, timestamps, multi

**Matches if:** the field is greater than or equal to the provided value.

### `<=` (less than or equal to)

**Works with:** numbers, timestamps, multi

**Matches if:** the field is less than or equal to the provided value.

### `~` (regexp match)

**Works with:** strings, multi

**Matches if:** the field's actual value matches the provided regular expression. The provided value must be a regular expression represented as a JSON string:

* The regexp **must not** be surrounded by the slash characters (`/rexegp/`) that delimit regexps in many languages.
* Every backslash character **must** be escaped with an additional backslash. Thus, a sequence like `\d` would be represented as `\\d`, and a literal backslash (represented in a regexp as a double-backslash `\\`) would be represented as a quadruple-backslash (`\\\\`).

The following example would match if the `certname` field's actual value resembled something like `www03.example.com`:

    ["~", "certname", "www\\d+\\.example\\.com"]

> **Note:** Regular expression matching is performed by the database backend, and the available regexp features are backend-dependent. For best results, use the simplest and most common features that can accomplish your task. See the links below for details:
>
> * [PostgreSQL regexp features](http://www.postgresql.org/docs/9.1/static/functions-matching.html#POSIX-SYNTAX-DETAILS)
> * [HSQLDB (embedded database) regexp features](http://docs.oracle.com/javase/6/docs/api/java/util/regex/Pattern.html)

### '~>' (regexp array match)

**Works with:** paths

**Matches if:** the array matches using the regular expressions provided within in each element. Array indexes are coerced to strings.

The following example would match any network interface names starting with eth:

    ["~>", "path", ["networking", "eth.*", "macaddress"]]

If you want to match any index for an array path element, you can use regular expressions to do this as the element acts like a string:

    ["~>", "path", ["array_fact", ".*"]]

### `null?` (is null)

**Works with:** fields that may be null

**Matches if:** the field's value is null (when second argument is `true`) or the field is **not** null, i.e. has a real value (when second argument is `false`).
<commit_msg>(PDB-775) Update operators doc link for psql 9.3<commit_after>---
title: "PuppetDB 2.2 » API » v4 » Query Operators"
layout: default
canonical: "/puppetdb/latest/api/query/v4/operators.html"
---

[resources]: ./resources.html
[facts]: ./facts.html
[nodes]: ./nodes.html
[query]: ./query.html
[fact-contents]: ./fact-contents.html

PuppetDB's [query strings][query] can use several common operators.

> **Note:** The v4 API is experimental and may change without notice. For stability, it is recommended that you use the v3 API instead.

## Binary Operators

Each of these operators accepts two arguments: a **field,** and a
**value.** These operators are **non-transitive:** their syntax must always be:

    ["<OPERATOR>", "<FIELD>", "<VALUE>"]

The available fields for each endpoint are listed in that endpoint's documentation.

**Note**
In past API versions PuppetDB has supported comparisons between strings in the
database and numerical values.  For example, equality and inequality queries for 0
would match database values of "0". This behavior is not supported on the v4 API,
since typed and structured facts allow us to distinguish the two in the database.
Instead, binary operators must be predicated on the same type as the desired
database value.

### `=` (equality)

**Works with:** strings, numbers, timestamps, booleans, arrays, multi, path

**Matches if:** the field's actual value is exactly the same as the provided value.

* Most fields are strings.
* Some fields are booleans.
* Arrays match if any **one** of their elements match.
* Path matches are a special kind of array, and must be exactly matched with this operator.

### `>` (greater than)

**Works with:** numbers, timestamps, multi

**Matches if:** the field is greater than the provided value.

### `<` (less than)

**Works with:** numbers, timestamps, multi

**Matches if:** the field is less than the provided value.

### `>=` (greater than or equal to)

**Works with:** numbers, timestamps, multi

**Matches if:** the field is greater than or equal to the provided value.

### `<=` (less than or equal to)

**Works with:** numbers, timestamps, multi

**Matches if:** the field is less than or equal to the provided value.

### `~` (regexp match)

**Works with:** strings, multi

**Matches if:** the field's actual value matches the provided regular expression. The provided value must be a regular expression represented as a JSON string:

* The regexp **must not** be surrounded by the slash characters (`/rexegp/`) that delimit regexps in many languages.
* Every backslash character **must** be escaped with an additional backslash. Thus, a sequence like `\d` would be represented as `\\d`, and a literal backslash (represented in a regexp as a double-backslash `\\`) would be represented as a quadruple-backslash (`\\\\`).

The following example would match if the `certname` field's actual value resembled something like `www03.example.com`:

    ["~", "certname", "www\\d+\\.example\\.com"]

> **Note:** Regular expression matching is performed by the database backend, and the available regexp features are backend-dependent. For best results, use the simplest and most common features that can accomplish your task. See the links below for details:
>
> * [PostgreSQL regexp features](http://www.postgresql.org/docs/9.3/static/functions-matching.html#POSIX-SYNTAX-DETAILS)
> * [HSQLDB (embedded database) regexp features](http://docs.oracle.com/javase/6/docs/api/java/util/regex/Pattern.html)

### '~>' (regexp array match)

**Works with:** paths

**Matches if:** the array matches using the regular expressions provided within in each element. Array indexes are coerced to strings.

The following example would match any network interface names starting with eth:

    ["~>", "path", ["networking", "eth.*", "macaddress"]]

If you want to match any index for an array path element, you can use regular expressions to do this as the element acts like a string:

    ["~>", "path", ["array_fact", ".*"]]

### `null?` (is null)

**Works with:** fields that may be null

**Matches if:** the field's value is null (when second argument is `true`) or the field is **not** null, i.e. has a real value (when second argument is `false`).

{'fraction_non_alphanumeric': 0.11942428928274057, 'fraction_numerical': 0.003925300344950636, 'mean_word_length': 4.473958333333333, 'pattern_counts': {'":': 0, '<': 13, '<?xml version=': 0, '>': 29, 'https://': 0, 'lorem ipsum': 0, 'www.': 6, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1878272', 'n_tokens_mistral': 2392, 'n_tokens_neox': 2276, 'n_words': 1119}