Skip to main content

 

Documentation & User Guides | FotoWare

Collection Queries

What are Collection Queries?

Collection queries are search queries for assets in a single collection. 

The correct way to make a collection query request is to:

  1. Look for the searchURL attribute in the collection's JSON representation
  2. Replace the placeholder {?q} with the query.

If the searchURL attribute is null, it means that the collection does not support collection queries, so you cannot search in it.
Only the following types of collections support collection queries:

Important:

Collection queries cannot be appended directly to data URL's, which are commonly used when working with the API. Use the method described above to look for the searchURL attribute in the JSON representation.

Usage example:

1. Request the archive list, then for one or more archives in the returned collection list, get searchURL and search as described above.

2. Client already has the URL of an archive or folder. Make a browse request and get the searchURL and search as described above. If a browse request has been made before, then the client already has the searchURL and can search right away.

The resulting URL refers to a new collection resource, which contains the result of the collection query. This means that the result of a collection query can be used in the same way as a regular collection.

Query examples

Queries can be created in two ways:

1. In the form of KEY=VALUE (or, in FotoWare jargon, PREDICATE=TERM), where all predicates documented in Search Expressions can be used.

2. Using Search expressions using the q= parameter in the search string. Using search expressions allows the creation of more complex queries.

Examples of both types of queries are shown below. Remember that all queries need to be percent-encoded (External link to Wikipedia).

Query examples using predicates and terms

PREDICATE and TERM Explanation Example URL
fn=albert.jpg Searches for the filename albert.jpg
.../fotoweb/archives/5013-Demo%20assets/?fn=albert.jpg

p=artwork

Searches for a name that occurs in the full path of an asset.

.../fotoweb/archives/5013-Demo%20assets/?p=artwork
5=yellow Searches for assets where field 5 (Title) contains the word yellow
.../fotoweb/archives/5013-Demo%20assets/?5=yellow
5=yellow&5=coffee

Searches for terms yellow OR coffee in field 5.

When using the predicate=term form of search, searching for two words in the same field always combines them with OR. You can use Search Expressions as described below to use other operators, such as AND.

.../fotoweb/archives/5013-Demo%20assets/?5=yellow&5=coffee

A note on the last example above: When using Collection queries, a search for two or more terms in the same field will result in a search for Term 1 OR Term 2. If you need to search for Term 1 AND Term 2, use Search expressions according to the similar example in the table below.

Query examples using Search Expressions

Note: To use search expressions through the API the q= parameter must be specified, as shown in the example URL's below.

Search Expression Explanation Example URL
5:yellow Searches for the word yellow in metadata field 5 (Title)
.../fotoweb/archives/5013-Demo%20assets/?q=5%3Ayellow

The colon in the search expression is percent-encoded

5:yellow AND 5:coffee

Searches for assets that contain the words yellow AND coffee in the Title field (no 5).

This would not have been possible with a PREDICATE=TERM search as outlined in the above table, since that type of search automatically combines two terms in the same field with an OR operator.

.../fotoweb/archives/5013-Demo%20assets/?q=5%3Ayellow+AND+5%3Acoffee

The colon and the spaces surrounding the AND operator have been percent-encoded

mtf:2014-01-01 mtt:2018-01-01

Searches for all assets with a modification time between Jan 01 2014 and Jan 01 2018
.../fotoweb/archives/5013-Demo%20assets/?q=mtf%3A2014-01-01+mtt%3A2018-01-01

The URL has been percent-encoded

Endpoint

The URL of a collection query is the URL of the collection without the query plus a query string which specifies the collection query. For example, if the collection is a public archive URL such as

/fotoweb/archives/5000-Wirefeed/

then the following URL:

/fotoweb/archives/5000-Wirefeed/?q=Tower&101=London

is the URL of a collection query which matches all assets that contain the string "Tower" in any metadata field and the string "London" in metadata field 101.

Usage

A collection query is a collection, which can be used as follows: