Table of Contents
Collection queries
31. March 2025
Table of Contents
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:
- Look for the searchURL attribute in the collection's JSON representation
- 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:
Note: Collection queries cannot be appended directly to data URLs, which are commonly used when working with the API. Use the method described above to look for the searchURL attribute in the JSON representation.
Exception
In general, every distinct key can only be used at most once in a query, with the exception of:
-
q(full text search). If this key is used in multiple query arguments, then their values are AND-combined. - Field predicates (numbers). If the same field number is given in multiple query arguments, then their values are OR-combined, and the resulting term is AND-combined with the remaining query.
Using any other key in multiple query arguments has undefined results.
Note: This limitation does NOT apply to search expressions. In a search expression, any predicate can be used multiple times and in any combination, e.g., fn:.jpg OR fn:.png, and such search expressions can also be passed to the q parameter)
Example use case
- Request the archive list, then for one or more archives in the returned collection list, get searchURL and search as described above.
- 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:
- In the form of KEY=VALUE (or, in Fotoware jargon, PREDICATE=TERM), where all predicates documented in Search Expressions can be used.
- 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.
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 URLs 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 are 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 is percent-encoded |
Endpoint
The URL of a collection query is the URL of the collection without the query plus a query string that 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 that 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:
- Request the asset list representation to get all assets that match the collection query.
- Request the collection list representation to get all direct sub-collections of the collection with the collection query appended to their URLs.