WoodWing Help Center

Searching for files in Elvis 5 by using a query

 

Searching for files in Elvis 5 by using a query

One of the ways of searching for files in Elvis is by using a query: a request for information in text form.

Queries range from simply entering a single word to defining a complex rule.

Examples:

The following query searches for files that have the term 'flower' in any of their metadata fields:

flower

The following query searches for files where Usage Rights is "Rights managed" and Status is not "Production":

usageRights:"Rights managed" NOT status:Production

You use a query when:

  • Searching for files by using the Search box
  • Setting user permissions (as a system administrator)

Free text search

Info: When can this method be used?

  • When searching for files by using the Search box: yes
  • When setting user permissions: no

The most common method of searching for files is to just type a word or combination of words, exactly as you would do when for example using Google.

You can type single words ("hello"), combine single words into phrases by placing them between double quotes ("hello world"), or combine words or phrases by using logical operators ("hello" AND "world").

Searching in a metadata field

Info: When can this method be used?

  • When searching for files by using the Search box: yes
  • When setting user permissions: yes

When entering a free text search ("hello world"), the search is performed in all metadata fields.

To search in one metadata field only, use the following syntax:

[internal metadata field name]:[search term]

Examples:

The following query searches for files where the value of the Usage Rights field is "Rights managed":

usageRights:"Rights managed"

The following query searches for files where the value of the Status field is "Production":

status:Production

About the internal metadata field name. The internal metadata field name is the name of the field that is used internally by Elvis and is usually different than the name that you see displayed. To find this internal name, reference the metadata field information overview.


Creating complex queries

Info: When can this method be used?

  • When searching for files by using the Search box: yes
  • When setting user permissions: yes

More complex queries can be created by making use of operators such as AND, OR, NOT, and so on. All supported operators are described below.

Note: Operators must be written in CAPITALS.

AND

The operators AND or && find files where both query terms match the metadata.

Examples:

The following queries search for files where Usage Rights is "Rights managed" and Status is "Production":

usageRights:"Rights managed" AND status:Production

usageRights:"Rights managed" && status:Production

usageRights:"Rights managed" status:Production

Note: If you do not specify an operator when combining multiple queries, the AND operator is automatically used.


OR

The operators OR or || (a double pipe character) link 2 queries to find matching files if either of the terms exist in the metadata.

Examples:

The following queries search for files where Status is "new" OR Status is "Draft":

status:New OR status:Draft

status:New || status:Draft


Must

The + or "must" operator requires that the term after the + symbol exists somewhere in the metadata field of a file.

Examples:

The following query searches for files where Status is "Production":

+status:Production

The following query searches for files where Usage Rights is "Rights managed" and Status is "Production":

usageRights:"Rights managed" +status:Production


NOT

The operators NOT, ! or - exclude files that contain the term after NOT, ! or -.

Examples:

The following queries search for files where Usage Rights is "Rights managed" and Status is not "Production":

usageRights:"Rights managed" NOT status:Production

usageRights:"Rights managed" !status:Production

usageRights:"Rights managed" -status:Production

Note: When using the ! or - character, make sure that it is directly followed by the search term and not by a space.


Range

The TO operator finds files between a starting value and an ending value.

  • When the starting and ending values need to be included in the results, place the range between square brackets "[]".
  • When the starting and ending values need to be excluded from the results, place the range between curly brackets "{ }".
  • Use an asterisk (*) to specify ANY starting value or ending value.
  • Range queries are particularly useful on date and number fields but can also be used on text fields.

Examples:

The following query searches for files where Resolution X (dpi) is between 100 and 300 (inclusive):

resolutionX:[100 TO 300]

The following query searches for files where the License start date is May 1st, 2nd, 3rd or 4th in the year 2015 (inclusive):

licenseStartDate:[2015-05-01T00:00:00 TO 2015-05-04T23:59:59]

Note: When searching in date/time fields, also specify a time. If only the date is specified, the upper bound time would default to 00:00:00, which would not return any results for that day.

The following query searches for files where the License start date is May 2nd or 3rd in the year 2015 (exclusive):

licenseStartDate:{2015-05-01T23:59:59 TO 2015-05-04T00:00:00}

The following query searches for files where the License start date is up to May 2nd 2015:

licenseStartDate:{* TO 2015-05-02T23:59:59}

The following query searches for files where the License start date is after May 2nd 2015:

licenseStartDate:{2015-05-02T00:00:00 TO *}

The following query searches for files whose titles are between "aida" and "carmen":

title:[aida TO carmen]


Grouping sub queries

Info: When can this method be used?

  • When searching for files by using the Search box: yes
  • When setting user permissions: no

When a query contains multiple statements, these sub queries can be grouped together by using parentheses. This controls the boolean logic for a query and makes the query better readable.

Example:

The following query searches for files where Status is "New" or "Draft" and Usage Rights is "Rights managed":

(status:New OR status:Draft) AND usageRights:"Rights managed"


Grouping clauses for a single field

Info: When can this method be used?

  • When searching for files by using the Search box: yes
  • When setting user permissions: yes

Multiple clauses for a single field can be grouped by placing them between parentheses.

Example:

The following query searches for files where Description contains "Reuters", "free" and "use":

description:(+Reuters +free +use)


Special queries

Info: When can this method be used?

  • When searching for files by using the Search box: yes
  • When setting user permissions: no1

1 Using wildcard queries in a query for setting up a Rule is not supported because they slow down searches too much and will affect every search done on the system. Setting up access for users should always be based on solid queries. For more information about setting up a security rule structure, see Organizing content in Elvis DAM by using Permissions.

Wildcard search

When you don't know the exact word to look for or if you want to find a broad range of words with a similar spelling, replace one or more characters by an asterisk (*) or question mark.

Note: This method is referred to as a 'wildcard' search and only works for single words, not for multiple words.

Examples:

The following query searches for all 4-letter words with any character in the third position (such as "test", "tent", "text" and so on):

te?t

The following query searches for a words starting with "test":

test*

Wildcard queries and performance

Wildcard queries are much slower than normal queries, so use them sparingly. Using a wildcard at the start of a word can be especially slow.

Some best practices:

  • To find all files with a specific extension, do not use filename:*.jpg, but instead use extension:jpg.
  • To find all files in a folder, do not use folderPath:/Demo Zone* but instead use ancestorPaths:"/Demo Zone".

Fuzzy search

Use a tilde character (~) to search for files that are similar to the entered search term.

Note: This method is referred to as a 'fuzzy' search and only works for single words, not for multiple words.

Example:

The following query searches for a term similar in spelling to "roam" (such as "foam" and "roams"):

roam~

You can influence the required similarity by adding a value between 0 and 1. The closer the value is to 1, the more files with a higher similarity will be matched.

Example:

roam~0.8

Note: If you do not specify a value between 0 and 1, a default value of 0.5 is automatically used.


Match all values for a field

To restrict your search to only include files that have a value entered in a certain field, use the following syntax:

[internal metadata field name]:*

Example:

The following query searches for files that have a value entered in the copyright field:

copyright:*

About the internal metadata field name. The internal metadata field name is the name of the field that is used internally by Elvis and is usually different than the name that you see displayed. To find this internal name, reference the metadata field information list.

About performance

Beware on which fields you use these type of queries: it is slower on fields with many unique values. For example: it would be fine to use it on the 'status' field, but using it on a 'filename' field can result in a slow performance.


Match all files - search all

The "*:*" or empty query will find all files that you have view permission to view.

Example:

*:*

 

Use cases

  • Searching for files that do not have a specific field value. First reference all files and subsequently subtract those files that you are not after.

Examples:

The following query will not work because we have not specified from which set of files to subtract from:

-status:Final

The following query will work because first a search on all files is done:

*:* -status:Final

  • Searching for files that do not have a value entered for a specific field. First reference all files and subsequently subtract all files that DO have a value for the field:

Examples:

  • The following query will not work because we have not specified from which set of files to subtract from:

-status:Final

The following query will work because first a search on all files is done:

*:* -copyright:*


Relational queries

Relational queries allows searching for files that are related to another file in Elvis. This query has the following form:

relatedTo:<file id>
[relationTarget:any|child|parent]
[relationType:contains|related|...]
[...normal query filters...]

Example:

The following query searches the contents of the Collection with id "6mPOhZmlak-89zedbCx4oJ":

relatedTo:6mPOhZmlak-89zedbCx4oJ relationTarget:child relationType:contains

Notes:

  • Place this at the very start of your query and respect the exact order used above. The regular query filters can be placed at the end of the relation query elements.
  • Both relationTarget and relationType are optional and can be omitted to search for all material that is related to the file.

Current date

Info: When can this method be used?

  • When searching for files by using the Search box: yes
  • When setting user permissions: no

The NOW operator represents the current date.

Example:

The following query searches 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

Info: When can this method be used?

  • When searching for files by using the Search box: yes
  • When setting user permissions: no

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

Example:

The following query searches for files where the License start date is pattern is yyyy-MM-dd'T'HH:mm:ssZ:

licenseStartDate:[2015-07-04T12:08:56-0700 TO *]

Date and Time Pattern

Result 1

yyyy-MM-dd'T'HH:mm:ssZ 2015-07-04T12:08:56-0700
yyyy-MM-dd'T'HH:mm:ss 2015-07-04T12:08:56
HH:mm:ss 12:08:56
GMT_Milliseconds 1278245336
yyyyMMdd 20150704

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


Date math

Info: When can this method be used?

  • When searching for files by using the Search box: yes
  • When setting user permissions: no

Date math can be used to do date calculations before the date is used by the query. Supported operations are:

  • Rounding (@)
  • Adding (+)
  • Subtracting (-)

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

Example:

The following query searches 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 back-slash '\' in front of the character.

Example:

The following query searches John&Doe in the copyright field:

copyright:John\&Doe

Sources

Document history

  • 19 April 2017: Removed date/time examples that don't use 'T' from section 'Date patterns'.
  • 19 April 2017: Corrected the structure of the Date patterns table.
Was this article helpful?
1 out of 1 found this helpful / Created: / Updated:
Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.