One of the ways of searching for files in Assets Server 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?
|
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 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 Assets Server 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?
|
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 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} The following query searches for files 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 can give unexpected results.
|
Example 1 In this search the upper limit is set to 31st of December 2020: dueDate:[2020-12-31T00:00:00 TO 2020-12-31T02:00:00} However, the results also show files with a due date after 31st of December 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 sub queries
|
Info: When can this method be used?
|
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?
|
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?
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 stored in Assets Server 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 Assets Server 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:
-status:Final The following query will work because first a search on all files is done: *:* -copyright:* |
Relational queries
Relational queries make it possible to search for files that are related to another file in Assets Server. 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:
|
Current date
|
Info: When can this method be used?
|
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?
|
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 Assets Server. 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?
|
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 |
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.