Search queries in Assets Server are based on the Lucene query syntax.
The basic query format is identical, but Assets Server adds additional functionality in some places. For example with date range queries, Assets Server can parse various input formats and makes it possible to use 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:
Queries and Webhooks
Note that when using queries to create a filter for a Webhook, that the use of wildcards is not supported (see also the Webhook API article).
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 Assets 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 with status Final.
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.
|
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.
|
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.
|
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:
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:
|
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:
|
|
Date and time queries Search for files based on a date or date range. Notes:
|
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 Assets 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 |
1 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
Comment
Do you have corrections or additional information about this article? Leave a comment! Do you have a question about what is described in this article? Please contact Support.
0 comments
Please sign in to leave a comment.