The Elvis 6 query syntax

Search queries in Elvis Server are based on the Lucene query syntax.

The basic query format is identical, but Elvis Server adds additional functionality in some places. For example with date range queries, Elvis Server can parse various input formats and allows dynamic queries and date/time arithmetic.

Basics

For an overview of the basics of the Lucene query syntax, see for example the logz.io blog post Elasticsearch Queries: A Thorough Guide.

Metadata references

When building a query, make sure to use the internal name for a metadata field and that it is written correctly (in camelCase).

For example, a file type is referred to as fileType, the extension of a file as assetType, the directory as folderPath, and so on.

For more information, see:

• Elvis 6 metadata fields explained
• Metadata field information for Elvis 6

Rule queries

When creating permission rules in the Management Console, queries can be used for giving permissions if metadata meets specific criteria.

Figure: Using a query when setting up a Permission Rule in the Management Console.

Although these queries use the same syntax as normal queries, not all query types can be used in these rules.

Query types supported in rule queries

Type	Example
Exact term query Search for files by using a single word.	Searching for all images with the status 'Final': assetDomain:image status:Final
Phrase query Search for files by using multiple words, contained in double quotes.	Searching for all files with the tag 'Nature' that are stored in the Demo Zone > Images folder: tags:"Nature" ancestorPaths:"/Demo Zone/Images"
Range query Search for a range using numeric or date fields.	Searching for files for which the license expires, starting today. licenseEndDate:[NOW TO *]
Boolean query Search for files for which one or more conditions are true.	Searching for files with status Production or Correction for which not all required metadata fields are set and which license expires starting today: (status:Production OR status:Correction) -metadataComplete:false licenseStartDate:[* TO NOW] AND licenseEndDate:[NOW TO *]

Metadata fields supported in rule queries

Not all metadata fields can be used in a rule query. Fields that can be used are:

• Un_tokenized fields
• Tokenized fields with pureLowerCase analyzer

More information on tokenization can be found on Wikipedia.

Field tokenization settings can be checked in Elvis Server on the Metadata field information page (also known as the assetinfo report).

Search queries

Search queries are used by end users who type in one or more search terms to search for.

Figure: Searching for files by entering a search term.

A query is broken up into terms (a single word or a group of words) and operators (AND, OR, +, and so on).

Term queries

A term can be a single word such as hello or world or a phrase: a group of words surrounded by double quotes such as "hello world".

Multiple terms can be combined with Boolean operators to form a complex query.

The search is performed on all metadata fields of a file.

Field queries

To only search within specific metadata fields, the technical name of that field can be included. The format is as follows:

<technical metadata field name>:<search term>

Examples
Search for files where the value of the Usage Rights field is "Rights managed": usageRights:"Rights managed"
Search for files where the value of the Status field is "Production": status:Production

Boolean queries and combing queries

A query may contain multiple fields or sub queries. These sub queries can be combined using logical operators.

Note: Operators must be ALL CAPS.

Operator	Example
AND Finds files where both query terms match the metadata. Instead of AND, && can also be used. When no operator is specified when combining multiple queries, the AND operator is used by default.	Search for files where Usage Rights is "Rights managed" and Status is "Production": usageRights:"Rights managed" AND status:Production
OR Links 2 queries to find matching files if either of the terms exist in the metadata. Instead of OR, || can also be used.	Search for files where Status is "new" OR Status is "Draft": status:New OR status:Draft
+ Also known as the "must" operator. Requires that the term after the + symbol exists somewhere in a the field of a file.	Search for files where Status is "Production": +status:Production Search for files where Usage Rights is "Rights managed" and Status is "Production": usageRights:"Rights managed" +status:Production
NOT Excludes files that contain the term after NOT. Instead of NOT, ! can also be used.	Search for files where Usage Rights is "Rights managed" and Status is not "Production": usageRights:"Rights managed" NOT status:Production
- Also known as the prohibit operator. Excludes files that contain the term after the - symbol.	Search for files where Status is not "Production" (note that this has to be prefixed with an 'all' search *:*; subtracting results from nothing is not possible): *:* -status:Production Search for files where Usage Rights is "Rights managed" and Status is not "Production": usageRights:"Rights managed" -status:Production

Range queries

Range queries are used for finding files of which the values of one or more metadata fields fall between a starting value and an end value.

Range queries can be inclusive or exclusive of the starting and end value. Inclusive range queries are denoted by square brackets "[ ]"; exclusive range queries are denoted by curly brackets { }.

Examples
Search for files where Resolution X (DPI) is between 100 and 300 (inclusive): resolutionX:[100 TO 300]
Search for files where the License start date is May 1st, 2nd, 3rd or 4th in the year 2020 (inclusive). Note that when searching in datetime fields, a time should be specified. If only the date would be specified, the upper bound time would default to 00:00:00 which would not return any results for that day. licenseStartDate:[2020-05-01T00:00:00 TO 2020-05-04T23:59:59]
Search for files with a due date of the 29th and 30th of December and none from the 31st of December: dueDate:[2020-12-29 TO 2020-12-31}

A range query may also contain ANY lower or upper bound value, this can be specified by a *.

Examples
Search for files where the License start date is up to and including May 2nd 2020: licenseStartDate:{* TO 2020-05-02T23:59:59}
Search for files where the License start date is after May 2nd 2020: licenseStartDate:{2020-05-02T00:00:00 TO *}

Range queries are particularly useful on date and number fields but can also be used on text fields.

Example
Search for documents whose titles are between aida and carmen: title:[aida TO carmen]

Known issue: Incorrect results for searches with dates with a time as upper bound

When performing a search for dates combined with a time as upper bound where the upper bound is specified to be excluded from the range, results can be unexpected.

Example 1
In this search the upper limit of 31st of December 2020 at 02:00:00 is specified to be excluded: dueDate:[2020-12-31T00:00:00 TO 2020-12-31T02:00:00} However, the results also show files with a due date of exactly 02:00:00.

Example 2
In this search the lower limit and upper limit include a time and are both specified to be excluded: dueDate:{2020-12-31T00:00:00 TO 2020-12-31T02:00:00} However, the results show files with a dueDate after 00:00:00 up to 02:00:00 but also incorrectly includes files with a dueDate of exactly 02:00:00.

Grouping

Use parentheses to group clauses to form sub queries. This can be very useful to control the Boolean logic for a query.

Example
Search for files where Status is "New" or "Draft" and Usage Rights is "Rights managed". (status:New OR status:Draft) AND usageRights:"Rights managed"

Field grouping

Use parentheses to group multiple clauses to a single field.

Example
Search for files where Description contains "Reuters", "free" and "use". description:(+Reuters +free +use)

Additional queries

To further specify a search, use any of the additional queries described below.

Type	Example
Wildcard query Broaden the search when not exactly knowing what to search for, or when variations of a term need to be included. Notes: Wildcards '*' and '?' can be used. Wildcard queries are much slower than regular queries; only use them when necessary. Do not use a wildcard at the start of a word, such queries are very slow. Example: To find all files with a specific extension, do not use filename:*.jpg, but instead use extension:jpg. To find all assets below a folder, do not use folderPath:/Demo Zone* but instead use ancestorPaths:"/Demo Zone"	Search for "test" and "text". te?t Search all terms starting with "test". test*
Fuzzy query Search for words that are similar.	Search for a term similar in spelling to 'roam' such as 'foam' and 'roams': roam~ Influence the required similarity by including a value between 0 (low similarity) and 1 (high similarity): roam~0.8 The default similarity value is 0.5.
Fields with values Search for fields that have a value. Note: This query is slow on fields with many unique values such as the 'filename' field.	Find all files that have a status entered: status:*
Find all files Search for all files.	Search for all files: *:* When to use it The usefulness of this query is limited. One specific case is to search for files that do not have a specific field value: -status:Final **(wont work)** In Lucene, the "-" or NOT operators can only 'filter' files that are matched by another part of the query. Because there is no 'other part' of the query, one can be simulated by using a 'find all files' query. Search for files that do not have status "Final": *:* -status:Final Another useful case is when searching for files that do not have a value entered for a specific field. Lucene cannot find these files because it cannot search for a field that has no value. By using a 'find all files' query and subtracting all files that do have a value for the field it is possible to get the desired result: *:* -copyright:*
Relation queries Search for files that are related to other files. The following format is used: relatedTo:<asset id> [relationTarget:any|child|parent] [relationType:contains|related|...] [...normal query filters...] Notes: Put the statement at the very start of the query and respect the exact order used above. The normal query filters can be put at the end of the relation query elements. Relation queries cannot be combined with other sub queries by using explicit logical operations. Doing so will result in a query error (PrivateMalformedQueryException). The inclusion of relationTarget and relationType is optional; they can be omitted to search all material related to the asset. The following keywords can be used for the relationType field (for an explanation of each see How files are related to each other in Elvis 6): contains duplicate references related variation	Search the contents of the Collection with id "6mPOhZmlak-89zedbCx4oJ": relatedTo:6mPOhZmlak-89zedbCx4oJ relationTarget:child relationType:contains Incorrect use of operators: q=relatedTo:20HKy2L1qeHA9Ll-G1LKSM AND viewCount:2 Correct use of combining queries: q=relatedTo:20HKy2L1qeHA9Ll-G1LKSM viewCount:2 q=relatedTo:20HKy2L1qeHA9Ll-G1LKSM assetType:png OR assetType:jpg
Date and time queries Search for files based on a date or date range. Notes: The pattern is yyyy-MM-dd'T'HH:mm:ssZ. NOW represents the current date.	Search for files where the License start date is after a specific date and time: licenseStartDate:[2020-07-04T12:08:56-0700 TO *] Search for files where the License is still valid (current date between license start and end date): licenseStartDate:[* TO NOW] AND licenseEndDate:[NOW TO *]

Date patterns

Date or datetime queries can use several different patterns to specify their date and time. The following list shows the date patterns supported by Elvis Server. The first pattern that is recognized will be used to parse the date.

Date and Time Pattern	Result 1
yyyy-MM-dd'T'HH:mm:ssZ	2010-07-04T12:08:56-0700
yyyy-MM-dd'T'HH:mm:ss	2010-07-04T12:08:56
yyyy:MM:dd	2010:07:04
yyyy-MM-dd	2010-07-04
yyyy/MM/dd	2010/07/04
HH:mm:ss	12:08:56
GMT_Milliseconds	1278245336
yyyyMMdd	20100704

¹ For 2010-07-04 12:08:56 in the U.S. Pacific Time zone.

---

Date math

Date math can be used to perform date calculations before the date is used by the query. Supported operations are: rounding (@), adding (+) and subtracting (-) date parts.

The following examples show how the several date math operations can be used and combined.

Date math expression	Result
@HOUR	Round to the start of the current hour.
@DAY	Round to the start of the current day.
+2YEARS	Exactly two years in the future from now.
-1DAY	Exactly 1 day prior to now.
@DAY+6MONTHS+3DAYS	6 months and 3 days in the future from the start of the current day.
+6MONTHS+3DAYS@DAY	6 months and 3 days in the future from now, rounded down to nearest day.

The list below shows the available date parts for math operations. Each date part has multiple aliases, for example: @HOUR is equivalent to @HOURS and @H.

Date part	Aliases
Year	Y, YEAR, YEARS
Month	M, MONTH, MONTHS
Day	D, DAY, DAYS, DATE
Hour	H, HOUR, HOURS
Minute	MIN, MINUTE, MINUTES
Second	S, SECOND, SECONDS
Millisecond	MILLI, MILLIS, MILLISECOND, MILLISECONDS

Search for files where the License start date is exactly today (between 00:00 and 23:59):

licenseStartDate:[NOW@DAY TO NOW@DAY+1DAY-1SECOND]

Escaping Special Characters

The search engine uses special characters as part of the query syntax:

+ - && || ! ( ) { } [ ] ^ " ~ * ? : \

To use these special characters as values in queries, escape them by placing a \ before the character. For example: to search for John&Doe in the copyright field, use the query:

copyright:John\&Doe

Sources

• Lucene query parser documentation
• Java SimpleDateFormat documentation

Document history

• 17 August 2021: Updated section 'Range queries' with details about incorrect results for searches with dates with a time as upper bound.