Fine-tuning your searches in Swivle by using queries – Home

In Swivle it is easy to enter a search term to filter out some of your files. However, this might be too limiting for you. For more fine-tuned searching and filtering, queries can be used.

The queries in Swivle are based on the Lucene query syntax. The basic query format is identical, but Swivle adds additional functionality in some places.

Example: For date range queries, Swivle can parse various input formats and allow dynamic queries and date/time arithmetic.

This article provides some examples of typical search queries.

Typical searches

Below are some examples of typical search queries.

Any text or metadata

When you search for one or more words without specifying any specific fields, Swivle will return all files that match that word in any useful field, typically with the most relevant matches on top. This will look in:

Any part of the file name.
Any part of any of the parent folder names.
Any metadata field that contains text.
The text contained by a file, for example the text contained by a document file.

The following will search for the word "coffee" in any text or metadata:

Coffee

Folders

You can search for content in a folder in two ways, by including content in any subfolders or by matching only content directly in the folder. Always make sure you wrap the path with double-quotes.

Including content in any subfolders of Images:

ancestorPaths:"/Demo Zone/Images"

Only content directly in the Images folder:

folderPath:"/Demo Zone/Images"

Collections

Match everything in Collection with ID 9F1AQwbaKFQB3IPFQuSeSQ:

parentContainerIds:9F1AQwbaKFQB3IPFQuSeSQ

Identifiers

In some cases, for example when using the API, it might be useful to search for a specific file by its unique identifier:

id:7eX5TGhwKm_9PsCG_q4r6i

Building up search queries

A Swivle 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 Swivle metadata field name followed by a colon, followed by the value to search for.

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

usageRights:"Rights managed"

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

status:Production

Boolean queries - combining queries

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

Note: Operators must be in ALL CAPS.

AND

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

Query on files 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, Swivle will use an AND operator by default.

OR

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

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

status:New OR status:Draft

+

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

Query on files where Status is "Production":

+status:Production

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

usageRights:"Rights managed" +status:Production

Caveat: when using a + in the URL of API queries, make sure it is encoded as %2B, else it will likely be interpreted as a 'space'.

NOT

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

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

usageRights:"Rights managed" NOT status:Production

-

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

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

*:* -status:Production

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

usageRights:"Rights managed" -status:Production

Range queries

Range queries are queries to find files whose field 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 files where Resolution X (dpi) is between 100 and 300 (inclusive):

resolutionX:[100 TO 300]

Query on files where the License start date is May 1st, 2nd, 3rd or 4th in the year 2010 (inclusive).

Note: Specify a time when searching in datetime fields. When only specifying 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 files 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 files where the License start date is up to May 2nd 2010:

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

Query on files 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 finds 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 files 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 files where Description contains "Reuters", "free" and "use".

description:(+Reuters +free +use)

Special queries

Below are what considered to be 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. If you want to find all files with a specific extension, do not use filename:*.jpg, but instead use extension:jpg. If you need to find all files 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 files 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 files that have a status entered:

status:*

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

Match all files - search all

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

*:*

Swivle also interprets an 'empty' query as a 'match all files' query.

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

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

In Lucene, the "-" or NOT operators can only 'filter' files 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 files' query. The following will return all files that do not have status "Final".

*:* -status:Final

Another case where this is useful 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 'match all files' query and subtracting all files that DO have a value for the field it is possible to get the desired result:

*:* -copyright:*

Date and time queries

Query on files where the License start date 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 (and time).

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

Date and Time Pattern	Result
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

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
/h	Round to the start of the current hour.
/d	Round to the start of the current day.
now+2Y	Exactly two years in the future from now.
now-1d	Exactly 1 day prior to now.
8now+6M/d	6 months and 3 days in the future from the start of the current day.
now+6M+3d/d	6 months and 3 days in the future from now rounded down to nearest day.

The list below shows the available units for math operations.

Unit	In Query
Years	Y
Months	M
Weeks	w
Days	d
Hours	H, h
Minutes	m
Seconds	s

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

licenseStartDate:[now/d TO now+1d-1s/d]

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

Rule queries

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

Query types supported in Rule queries

The following types are supported in Rule queries.

Exact term queries

status:Final

assetDomain:image

Phrase queries

tags:"San Francisco"