![No UI](https://img.shields.io/static/v1?label=UI&message=none&color=inactive)

*Search util 2*  allows the definition of search filters via configuration (*custom.properties*). Those filters are used in other plugins to define scopes. 

[MINITOC]

## Important Notes

- Literals (e.g. filters, logical operators, boolean values) are case-insensitive.
- Unknown characters (except in strings) are treated as space.
- If possible always use `<=` and `>=` instead of `<` and `>`, because `<` has to be modelled as `<= and not =`  (analogous for `>`).
- The backslash `\ ` is also the escape character for `*.properties` files and therefore needs to be escaped again. E.g. `He"ll\o` as string would become `"He\"ll\\o"` and because it is in a `*.properties` file it becomes `"He\\"ll\\\\o"`.

## Filter Expression

A filter expression consists of one or more filters which are connected by logical operators. Parentheses are supported.

A filter has always the following structure: `<filter><comparator><values>`. E.g. `assetType=11000`

## Logical Operators

The following logical operators are supported:

- And: `and` or `&`
- Or: `or` or `|`
- Not: `not` or `!`

Parantheses are supported.

## Comparators

- Equals: `=` or `==`
- Not equals: `!=` or `<>`
- Less equals: `<=`
- Greater equals: `>=`
- Less: `<`
- Greater: `>`
- Starts with: `^=`
- Ends with: `$=`
- Contains: `%=`

## Data Types

- **String**: Has to be in quotes `"`, e.g. `"Hello world!"`. If the string itself contains a quote it has to be escaped with a backslash `\"`. Backslashes have to be escaped too `\\`. `\n` is converted to a new line character and `\t` to a tab.
- **Boolean**: `true` or `false` (case-insensitive).
- **Long**: An integer in the range from `-2^63` to `2^63-1`
- **Integer**: An integer in the range from `-2^31` to `2^31-1`
- **Double**: A decimal number, e.g. `-3.987` or `55`, scientific notation (e.g. `7.65e4`) is not supported.
- **Date**: A string in the format `yyyy-MM-dd` or `yyyy-MM-dd hh:mm:ss` (e.g. `"2023-07-19"`) or the special literal `now`. Note that you can do math with this, e.g. `now - 30` to define a relative date for 30 days ago.
- **List**: Comma-separated values. E.g. list of double `3.141, 2.718, -77, 3.3 + 4.4`.
- **Range**: Basically a list with just two values, lower and upper bound. E.g. a range of long `22, 33` would mean `22 <= x <= 33`.
- **Empty**: `empty` or `null` (case-insensitive).

## Mathematical Operators

- Plus (`+`): Applicable to numeric types, *string* (concatenation) and *date* (add number of days). Also unary for numeric types.
- Minus (`-`): Applicable to numeric types and *date* (subtract number of days). Also unary for numeric types.
- Times (`*`): Applicable to numeric types.
- Through (`/`): Applicable to numeric types (*long* and *integer* are rounded down, e.g. 4 / 3 = 1).
- Power (`^`): Applicable to numeric types.

The numeric types are *long*, *integer* and *double*.

Parantheses are supported.

## Filters

##### assetType

> Synonyms: `assetTypes`

- `assetType = empty`: Assets which don't have an asset type set.
- `assetType != empty`: Assets which have an asset type set.
- `assetType = <list of long>`: Assets which have one of the specified asset type ids.
- `assetType != <list of long>`: Assets which don't have one of the specified asset type ids

##### assetIds

> Synonyms: -

- `assetIds = <list of long>`: Assets with one of the specified asset ids.
- `assetIds != <list of long>`: Assets without one of the specified asset ids.

Note the *s* at the end, which sets this filter apart from the following one.

##### assetId

> Synonyms: -

- `assetId = <long>`: The asset with the specified asset id.
- `assetId != <long>`: Assets without the specified asset id.
- `assetId = <range of long>`: Assets with an asset id within the specified range (inclusive).
- `assetId != <range of long>`: Assets with an asset id not in the specified range (inclusive).
- `assetId <= <long>`: Assets with an asset id less or equal to the specified one.
- `assetId >= <long>`: Assets with an asset id greater or equal to the specified one.
- `assetId < <long>`: Assets with an asset id less than the specified one.
- `assetId > <long>`: Assets with an asset id greater than the specified one.

##### nodeType

> Synonyms: `nodeTypes`

- `nodeType = <list of long>`: Assets linked to at least one of the nodes with the specified node type ids.
- `nodeType != <list of long>`: Assets linked to none of the nodes with the specified node type ids.

##### node

> Synonyms: `nodes`

- `node = <list of long>`: Assets linked to all of the nodes with the specified node ids.
- `node != <list of long>`: Assets not linked to all of the nodes with the specified node ids.

##### nodeRecursive

> Synonyms: `nodesRecursive`

- `nodeRecursive = <list of long>`: Assets linked to all of the nodes with the specified node ids or one of their children.
- `nodeRecursive != <list of long>`: Assets not linked to all of the nodes with specified node ids or one of their children.

##### anyNode

> Synonyms: `anyNodes`

- `anyNode = <list of long>`: Assets linked to at least one of the nodes with the specified node ids.
- `anyNode != <list of long>`: Assets linked to none of the nodes with the specified node ids.

##### anyNodeRecursive

> Synonyms: `anyNodesRecursive`

- `anyNodeRecursive = <list of long>`: Assets linked to at least one of the nodes with the specified node ids or one of their children.
- `anyNodeRecursive != <list of long>`: Assets linked to none of the nodes with the specified node ids or one of their children.

##### nodeName

> Synonyms: `nodeNames`, since: 1.47

Note: This executes a sub-query in order to retrieve all nodes matching the provided term, whereafter a `nodeAny` is performed on those. Requires a NodeTypeId and a Locale because the SDK does.

* `nodeName = <NodeTypeId>,<Locale>,<Searchterm>` Assets linked to at least one node whose name equals the search term
* `nodeName %= <NodeTypeId>,<Locale>,<Searchterm>` Assets linked to at least one node whose name contains the search term
* `nodeName ^= <NodeTypeId>,<Locale>,<Searchterm>` Assets linked to at least one node whose name starts with the search term
* `nodeName $= <NodeTypeId>,<Locale>,<Searchterm>` Assets linked to at least one node whose name ends with the search term

##### nodeNameRecursive

> Synonyms: `nodeNamesRecursive`, since: 1.47

Note: This executes a sub-query in order to retrieve all nodes matching the provided term, whereafter a `nodeAnyRecursive` is performed on those. Requires a NodeTypeId and a Locale because the SDK does.

* `nodeNameRecursive = <NodeTypeId>,<Locale>,<Searchterm>` Assets linked below at least one node whose name equals the search term
* `nodeNameRecursive %= <NodeTypeId>,<Locale>,<Searchterm>` Assets linked below at least one node whose name contains the search term
* `nodeNameRecursive ^= <NodeTypeId>,<Locale>,<Searchterm>` Assets linked below at least one node whose name starts with the search term
* `nodeNameRecursive $= <NodeTypeId>,<Locale>,<Searchterm>` Assets linked below at least one node whose name ends with the search term

##### creator

> Synonyms: `creators`

- `creator = <list of long>`: Assets created by one of the users with the specified user ids.
- `creator = <list of long>`: Assets created by none of the users with the specified user ids.

##### modifier

> Synonyms: `modifiers`

- `modifier = <list of long>`: Assets modified by one of the users with the specified user ids.
- `modifier = <list of long>`: Assets modified by none of the users with the specified user ids.

##### created

> Synonyms: `creation`

- `created = <date>`: Assets created on the specified date.
- `created != <date>`: Assets not created on the specified date.
- `created = <range of date>`: Assets created between the specified dates.
- `created != <range of date>`: Assets not created between the specified dates.
- `created <= <date>`: Assets created before or on the specified date.
- `created >= <date>`: Assets created after or on the specified date.
- `created < <date>`: Assets created before the specified date.
- `created > <date>`: Assets created after the specified date.

##### modified

> Synonyms: `modification`

- `modified = <date>`: Assets modified on the specified date.
- `modified != <date>`: Assets not modified on the specified date.
- `modified = <range of date>`: Assets modified between the specified dates.
- `modified != <range of date>`: Assets not modified between the specified dates.
- `modified <= <date>`: Assets modified before or on the specified date.
- `modified >= <date>`: Assets modified after or on the specified date.
- `modified < <date>`: Assets modified before the specified date.
- `modified > <date>`: Assets modified after the specified date.

##### conversionError

> Synonyms: `conversionErrors`, `error`, `errors`

- `conversionError = true` or `conversionError != false`: Assets with conversion errors.
- `conversionError = false` or `conversionError != true`: Assets without conversion errors.

##### lock

> Synonyms: `locked`

- `lock = true` or `lock != false`: Locked assets.
- `lock = false` or `lock != true`: Assets which aren't locked.

##### available

> Synonyms: `availability`

- `available = <boolean>`: Assets which are available.
- `available != <boolean>`: Assets which aren't available.
- `available = <date range>`: Assets which are available between the specified dates.
- `available != <date range>`: Assets which aren't available between the specified dates.

##### expires

> Synonyms: `expiration`

- `expires = <date range>`: Assets which expire between the specified dates.
- `expires != <date range>`: Assets which don't expire between the specified dates.
- `expires < <date>`: Assets expiring before the specified date.
- `expires > <date>`: Assets expiring after the specified date.

##### assetName

> Synonyms: `name`

- `assetName = <string>`: Assets with the specified name.
- `assetName != <string>`: Assets with a different name than the specified one.
- `assetName ^= <string>`: Assets with a name starting with the specified string.
- `assetName $= <string>`: Assets with a name ending with the specified string.
- `assetName %= <string>`: Assets with a name containing the specified string.

##### originalFilename

> Synonyms: `originalName`, `original`

- `originalFilename = <string>`: Assets with the specified original filename.
- `originalFilename != <string>`: Assets with a different original filename than the specified one.
- `originalFilename ^= <string>`: Assets with an original filename starting with the specified string.
- `originalFilename $= <string>`: Assets with an original filename ending with the specified string.
- `originalFilename %= <string>`: Assets with an original filename containing the specified string.

##### fileExtension

> Synonyms: `fileExtensions`, `extension`, `extensions`

- `fileExtension = empty`: Assets with no file extension.
- `fileExtension != empty`: Assets with a file extension.
- `fileExtension = <list of string>`: Assets with one of the specified file extensions.
- `fileExtension != <list of string>`: Assets with none of the specified file extensions.
- `fileExtension ^= <list of string>`: Assets with a file extension starting with one of the specified strings.
- `fileExtension $= <list of string>`: Assets with a file extension ending with one of the specified strings.
- `fileExtension %= <list of string>`: Assets with a file extension containing one of the specified strings.

##### fullText

> Synonyms: `text`

- `fullText = <string>`: Assets with an information field or name matching the specified string.
- `fullText != <string>`: Assets with no information field or name matching the specified string.
- `fullText ^= <string>`: Assets with an information field or name starting with the specified string.
- `fullText $= <string>`: Assets with an information field or name ending with the specified string.
- `fullText %= <string>`: Assets with an information field or name containing the specified string.

##### fileSize

> Synonyms: `size`

- `fileSize = <long>`: Assets with a file size equal to the specified one.
- `fileSize != <long>`: Assets with a file size not equal to the specified one.
- `fileSize = <range of long>`: Assets with a file size within the specified range.
- `fileSize != <range of long>`: Assets with a file size not between the specified range.
- `fileSize <= <long>`: Assets with a file size less or equal to the specified one.
- `fileSize >= <long>`: Assets with a file size greater or equal to the specified one.
- `fileSize < <long>`: Assets with a file size less than the specified one.
- `fileSize > <long>`: Assets with a file size greater than the specified one.

##### fileCategory

> Synonyms: `fileCategories`, `category`, `categories`

Available categories: `image`, `audio`, `document`, `video`, `text`, `unknown`, `3d` (only newer versions). Theoretically any known category is supported (there is an enumeration and as long as the value in upper case is in that enumeration it will work).

- `fileCategory = <list of category>`: Assets with one of the specified file categories.
- `fileCategory != <list of category>`: Assets with none of the specified file categories.

##### informationField&lt;long&gt;

> Synonyms: `informationField_<long>`, `infoField<long>`, `infoField_<long>`, `info<long>`, `info_<long>`, `field<long>`, `field_<long>`

Filter by the information field with the specified information field id (e.g. `informationField33`, `info_33` or `field33` would filter by the information field with the id 33). The filter options depend on the information field kind.

- Boolean fields (checkboxes):
  - `field_<long> = true` or `field_<long> != false`: Assets where the specified checkbox is checked.
  - `field_<long> = false` or `field_<long> != true`: Assets where the specified checkbox is not checked.
- Number fields and double fields (number field requires long):
  - `field_<long> = empty`: Assets where the specified field is empty.
  - `field_<long> != empty`: Assets where the specified field is not empty.
  - `field_<long> = <number>`: Assets where the specified field has the given number. 
  - `field_<long> != <number>`: Assets where the specified field doesn't have the given number.
  - `field_<long> = <number range>`: Assets where the specified field has a number in the given range.
  - `field_<long> != <number range>`: Assets where the specified field has a number outside of the given range.
  - `field_<long> <= <number>`: Assets where the specified field has a number less or equal to the given one.
  - `field_<long> >= <number>`: Assets where the specified field has a number greater or equal to the given one.
  - `field_<long> < <number>`: Assets where the specified field has a number less than the given one.
  - `field_<long> > <number>`: Assets where the specified field has a number greater than the given one.
- Text and text area fields:
  - `field_<long> = empty`: Assets where the specified field is empty.
  - `field_<long> != empty`: Assets where the specified field is not empty.
  - `field_<long> = <string>`: Assets where the specified field has the given string.
  - `field_<long> != <string>`: Assets where the specified field doesn't have the given string.
  - `field_<long> ^= <string>`: Assets where the specified field starts with the given string.
  - `field_<long> $= <string>`: Assets where the specified field ends with the given string.
  - `field_<long> %= <string>`: Assets where the specified field contains the given string.
- Localized text and localized text area fields (locales are two-letter ISO strings):
  - `field_<long> = <locale>, empty`: Assets where the specified field is empty for the given locale.
  - `field_<long> != <locale>, empty`: Assets where the specified field isn't empty for the given locale.
  - `field_<long> = <locale>, <string>`: Assets where the specified field has given string for the given locale.
  - `field_<long> != <locale>, <string>`: Assets where the specified field doesn't have the given string for the given locale.
  - `field_<long> ^= <locale>, <string>`: Assets where the specified field starts with the given string for the given locale.
  - `field_<long> $= <locale>, <string>`: Assets where the specified field ends with the given string for the given locale.
  - `field_<long> %= <locale>, <string>`: Assets where the specified field contains the given string for the given locale.
- Dropdown fields:
  - `field_<long> = empty`: Assets where the specified field is empty.
  - `field_<long> != empty`: Assets where the specified field is not empty.
  - `field_<long> = <integer>`: Assets where the specified field has the given value.
  - `field_<long> != <integer>`: Assets where the specified field doesn't have the given value.
- Node referencing fields and tag fields (since celum-utils v1.47.7):
  - `field_<long> = empty`: Assets where the specified field is empty.
  - `field_<long> != empty`: Assets where the specified field is not empty.
  - `field_<long> = <long>`: Assets where the specified field has the node with the given node id.
  - `field_<long> != <long>`: Assets where the specified field doesn't have the node with the given node id.
  - `field_<long> = <long>, true`: Assets where the specified field has the node with the given node id or one of its children.
  - `field_<long> != <long>, true`: Assets where the specified field doesn't have the node with the given node id or one of its children.
  - `field_<long> = <list of long>`: Assets where the specified field contains at least one of the given nodes (since celum-utils 1.39.17-6.4).
  - `field_<long> != <list of long>`: Assets where the specified field contains none of the given nodes (since celum-utils 1.39.17-6.4).
- Date fields:
  - `field_<long> = empty`: Assets where the specified field is empty.
  - `field_<long> != empty`: Assets where the specified field is not empty.
  - `field_<long> = <date>`: Assets where the specified field has the given date.
  - `field_<long> != <date>`: Assets where the specified field doesn't have the given date.
  - `field_<long> = <date range>`: Assets where the specified field has a date in the given range.
  - `field_<long> != <date range>`: Assets where the specified field doesn't have a date in the given range.
  - `field_<long> <= <date>`: Assets where the specified field has a date before or equal to the given one.
  - `field_<long> >= <date>`: Assets where the specified field has a date after or equal to the given one.
  - `field_<long> < <date>`: Assets where the specified field has a date before the given one.
  - `field_<long> > <date>`: Assets where the specified field has a date after than the given one.    

##### fileProperty_&lt;name&gt;

> Synonyms: `file_<name>`, `property_<name>`

Filter by the specified file property. 

Known file properties: `width`, `height`, `colorspace`, `profile`, `dpi`, `codec`, `aspect_ratio`, `pages`, `vector`, `raster`, `svg_layer_names`, `duration`, `scan_type`, `frame_rate`, `standard`, `audio_channel`, `audio_bit_rate`, `audio_sample_rate`, `audio_artist`, `audio_track_title`, `audio_album_title`, `audio_track_number`, `audio_year`, `audio_genre`

- Boolean file properties:
  - `property_<name> = true` or `property_<name> != false`: Assets where the specified file property is true.
  - `property_<name> = false` or `property_<name> != true`: Assets where the specified file property is false.
- Text file properties:
  - `property_<name> = empty`: Assets where the specified file property is empty.
  - `property_<name> != empty`: Assets where the specified file property is not empty.
  - `property_<name> = <string>`: Assets where the specified file property equals the given string.
  - `property_<name> != <string>`: Assets where the specified file property doesn't equal the given string.
  - `property_<name> ^= <string>`: Assets where the specified file property starts with the given string.
  - `property_<name> $= <string>`: Assets where the specified file property ends with the given string.
  - `property_<name> %= <string>`: Assets where the specified file property contains the given string.
- Number and double file properties:
  - `property_<name> = empty`: Assets where the specified file property is empty.
  - `property_<name> != empty`: Assets where the specified file property is not empty.
  - `property_<name> = <number>`: Assets where the specified file property has the given number.
  - `property_<name> != <number>`: Assets where the specified file property doesn't have the given number.
  - `property_<name> = <number range>`: Assets where the specified file property has a number in the given range.
  - `property_<name> != <number range>`: Assets where the specified file property has a number outside of the given range.
  - `property_<name> <= <number>`: Assets where the specified file property has a number less or equal to the given one.
  - `property_<name> >= <number>`: Assets where the specified file property has a number greater or equal to the given one.
  - `property_<name> < <number>`: Assets where the specified file property has a number less than the given one.
  - `property_<name> > <number>`: Assets where the specified file property has a number greater than the given one.
- Date file properties:
  - `property_<name> = empty`: Assets where the specified file property is empty.
  - `property_<name> != empty`: Assets where the specified file property is not empty.
  - `property_<name> = <date>`: Assets where the specified file property has the given date.
  - `property_<name> != <date>`: Assets where the specified file property doesn't have the given date.
  - `property_<name> = <date range>`: Assets where the specified file property has a date in the given range.
  - `property_<name> != <date range>`: Assets where the specified file property doesn't have a date in the given range.
  - `property_<name> <= <date>`: Assets where the specified file property has a date before or equal to the given one.
  - `property_<name> >= <date>`: Assets where the specified file property has a date after or equal to the given one.
  - `property_<name> < <date>`: Assets where the specified file property has a date before the given one.
  - `property_<name> > <date>`: Assets where the specified file property has a date after than the given one.

## Examples

Assets linked to (any subnode of) Node 1337 that has a copyright date (date-field 42) set in the future, or does not require a copyright (checkbox 41):

```
nodeRecursive = 1337 & (infoField_42 >= now | infoField_41 = false)
```

Assets linked to (any subnode of) Node 1337 that has a copyright date (date-field 42) in the past

```
nodeRecursive = 1337 & infoField_42 <= now
```

## Compatibility Matrix

| Search util 2                  | CELUM (min. version)  |
|:------------------------------ |:--------------------- |
| 1.0.0+                         | 6.4, tested up to 6.8 |
| 1.1.0 (Celum Utils 1.39.19)    | 6.4, tested up to 6.8 |
| 1.2.0 (Celum Utils 1.46.3-6.4) | 6.4 tested up to 6.8  |

## Release Notes

#### 1.0.0

> Released 2020-11-11

Initial version.

#### 1.1.0

> Released 2021-11-26

File properties added.

#### 1.2.0

> Released 2022-06-07

File categories: bug fix and dynamic