WoodWing Help Center

The Elvis 4 query syntax

The Elvis 4 query syntax

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

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

Rule queries

When you create permission rules in the Elvis admin you can use queries to give permissions if metadata meets specific criteria. Although these queries use the same syntax as normal Elvis queries, not all query types can be used in these rules.

Query types supported in rule queries

  • Exact term queries

status:Final

assetDomain:image

  • Phrase queries

tags:"San Francisco"

ancestorPaths:"/Demo Zone/Images"

  • Range queries (only on numeric and date fields)

licenseEndDate:[NOW TO *]

  • Boolean queries

(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 or tokenized fields with pureLowerCase analyzer. More information on tokenization can be found on Wikipedia.

Field tokenization settings can be checked on the Elvis server in the assetinfo report:

<Config>/plugins/active/internal/assetinfo_report/

Search for the specific field name in this xml file and check the <compass> section for tokenization settings.

Search queries

Terms

An Elvis query is broken up into terms and operators. There are two types of terms:

  • _ Single Terms_. A single word such as "hello" or "world".
  • Phrases. A group of words surrounded by double quotes such as "hello world".

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


Term queries

Searching on fields is possible by specifying the technical Elvis metadata field name followed by a colon, followed by the value to search for.

Query on assets where the value of the Usage Rights field is "Rights managed":

usageRights:"Rights managed"

Query on assets where the value of the Status field is "Production":

status:Production


Boolean queries - combing queries

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

Note: Operators must be ALL CAPS.

AND

The AND operator finds assets where both query terms match the metadata. The symbol && can also be used instead of the word AND.

Query on assets where Usage Rights is "Rights managed" and Status is "Production":

usageRights:"Rights managed" AND status:Production

Note: If you do not specify an operator when combining multiple queries, Elvis will use an AND operator by default.


OR

The OR operator links two queries to find matching assets if either of the terms exist in the metadata. The symbol || can also be used instead of the word OR.

Query on assets where Status is "new" OR Status is "Draft":

status:New OR status:Draft


+

The + or "must" operator, requires that the term after the + symbol exist somewhere in a the field of an asset.

Query on assets where Status is "Production":

+status:Production

Query on assets where Usage Rights is "Rights managed" and Status is "Production":

usageRights:"Rights managed" +status:Production


NOT

The NOT operator excludes assets that contain the term after NOT. The symbol ! can be used instead of the word NOT.

Query on assets where Usage Rights is "Rights managed" and Status is not "Production":

usageRights:"Rights managed" NOT status:Production


-

The - or prohibit operator excludes assets that contain the term after the - symbol.

Query on assets where Status is not "Production" (note that we have to prefix this with an 'all' search *:*, it can't subtract hits from nothing):

*:* -status:Production

Query on assets where Usage Rights is "Rights managed" and Status is not "Production":

usageRights:"Rights managed" -status:Production


Range queries

Range queries are queries to find assets whose field(s) values are between the lower and upper bound specified by the range query.

Range queries can be inclusive or exclusive of the upper and lower bounds. Inclusive_ range queries_ are denoted by square brackets "[ ]". Exclusive range queries are denoted by curly brackets { }.

Query on assets where Resolution X (dpi) is between 100 and 300 (inclusive):

resolutionX:[100 TO 300]

Query on assets where the License start date is May 1st, 2nd, 3rd or 4th in the year 2010 (inclusive). Note that you should specify a time when searching in datetime fields. If you would only specify the date, the upper bound time would default to 00:00:00, which would not return any results for that day.

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

Query on assets where the License start date is May 2nd or 3rd in the year 2010 (exclusive):

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

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

Query on assets where the License start date is up to May 2nd 2010:

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

Query on assets where the License start date is after May 2nd 2010:

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

Range queries are particularly useful on date and number fields but can also be used on text fields. The following will find all documents whose titles are between aida and carmen:

title:[aida TO carmen]


Grouping

The search engine supports using parentheses to group clauses to form sub queries. This can be very useful if you want to control the boolean logic for a query.

Query on assets where Status is "New" or "Draft" and Usage Rights is "Rights managed".

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


Field grouping

The search engine supports using parentheses to group multiple clauses to a single field.

Query on assets where Description contains "Reuters", "free" and "use".

description:(+Reuters +free +use)


Special queries

Wildcard queries

You can use "*" and "?" wildcards in queries if you do not know the exact word you are searching for. You cannot use wildcards within "phrase queries".

The following will match both "test" and "text".

te?t

The following will search all terms starting with "test".

test*

Note: Wildcard queries are much slower than normal queries, so only use them if you really need to. Do not use a wildcard at the start of a word, such queries are even slower.

So if you want to find all files with a specific extension, do not use filename:*.jpg, but instead use extension:jpg. And if you need to find all assets below a folder, do not use folderPath:/Demo Zone* but instead use ancestorPaths:"/Demo Zone"


Fuzzy queries

Lucene supports fuzzy searches based on the Levenshtein Distance, or edit distance algorithm. To do a fuzzy search, use the tilde, ~, symbol at the end of a 'single word term'. For example to search for a term similar in spelling to "roam" use the fuzzy search:

roam~

This search will find terms like foam and roams.

You can even influence the required similarity. The value is between 0 and 1, with a value closer to 1 only terms with a higher similarity will be matched. For example:

roam~0.8

The default that is used if the parameter is not given is 0.5.


Match all values

In some cases you may want to restrict your search to only include assets that have a value entered in a certain field, for example the copyright field. This can be done with a special variation of the wildcard query:

copyright:*

Or for example, find all assets that have a status entered:

status:*

Note: Beware on which fields you use these queries. It is slower on fields with lots of unique values. So a 'status' field is ok, but a 'filename' field could be very slow.


Match all assets - search all

Another special query is the 'match all assets' query. This query will find all assets (of course still filtered to only return assets that you have view permission for).

*:*

Elvis also interprets an 'empty' query as a 'match all assets' query.

When to use it

The usefulness of the 'match all assets' query is limited. One specific case is to search assets that do not have a specific field value. For example:

-status:Final **(wont work)**

In Lucene, the "-" or NOT operators can only 'filter' assets that are matched by another part of the query. Since there is no 'other part' of the query we can simulate one by using a 'match all assets' query. The following will return all assets that do not have status "Final".

*:* -status:Final

Another case where this is useful, is when searching for assets that do not have a value entered for a specific field. Lucene can not find these assets, since it cannot search for a field that has no value. By using a 'match all assets' query and subtracting all assets that DO have a value for the field it is possible to get the desired result:

*:* -copyright:*


Relation queries

A very special query is the 'relation query' that allows searching for assets that are related to another asset in Elvis. This query has the following form:

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

If you use this type of query, take note of the following:

  • Make sure to put the statement at the very start of your query and respect the exact order used above. Your 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).

Example:

Incorrect:

q=relatedTo:20HKy2L1qeHA9Ll-G1LKSM AND viewCount:2

Correct:

q=relatedTo:20HKy2L1qeHA9Ll-G1LKSM viewCount:2
q=relatedTo:20HKy2L1qeHA9Ll-G1LKSM assetType:png OR assetType:jpg
  • Both relationTarget and relationType are optional and can be omitted to search all material related to the asset.

The following example will search the contents of the collection with id "6mPOhZmlak-89zedbCx4oJ":

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


Date and time queries

Query on assets where the License start date is pattern is yyyy-MM-dd'T'HH:mm:ssZ:

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

Current date - NOW

Date values are not restricted to static values. There are several cases where you need the current date in a query instead of a static date. NOW represents the current date.

Query on assets 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. The first pattern that is recognized will be used to parse the date.

Date and Time Pattern

Result 1

yyyy-MM-dd HH:mm:ss Z 2010-07-04 12:08:56 -0700
yyyy-MM-dd HH:mm:ss 2010-07-04 12:08:56
yyyy/MM/dd HH:mm:ss Z 2010/07/04 12:08:56 -0700
yyyy/MM/dd HH:mm:ss 2010/07/04 12:08:56
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 HH:mm:ss 2010:07:04 12: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
EEE MMM dd HH:mm:ss z yyyy Wed Jul 04 12:08:56 PDT 2010
EEE MMM dd HH:mm:ss yyyy Wed Jul 04 12:08:56 2010
GMT_Milliseconds 1278245336
yyyyMMddHHmmss 20100704120856
yyyyMMdd 20100704

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


Date math

Date math can be used to do 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

Query on assets 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

Was this article helpful?
0 out of 0 found this helpful / Created: / Updated:
Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.