Skip to main content
Documentation & User Guides | Fotoware

Fotoware search expressions reference

Overview

Fotoware search expressions are a rich query language that can be used by both regular users and API clients to get more fine-tuned search results. Some of its features are:

  • Boolean operators (AND, OR, NOT)
  • Search in specific metadata fields vs. "full text search"
  • Date and numeric ranges
  • Dynamic tag expansion

Search expressions can be used in the following places:

The custom taxonomy search string syntax from previous versions is a subset of search expressions, so existing taxonomies created in versions of Fotoware that did not have search expressions will still work.

Definitions

A search expression is a string that consists of the following components:

Definition Explanation Example
Term

Describes "what to search for", i.e., a piece of information to match against.

A term may be a literal word or phrase to search for, a number or date value or a range of values given as terms.

 

London
"New York"

 

Predicate

Describes "where to search", i.e., the part of an object that is being searched.

By default, Fotoware performs a "full text search" in all metadata fields and attributes of an object. However, a predicate may limit the search to a specific metadata field or attribute.

 

London
90:"New York"

 

Clause

Describes "how to search", i.e., the search query as a whole.

A clause may be a simple predicate, but it may also be a logical combination of multiple predicates using boolean operators such as AND, OR and NOT.

 

London
90:London OR 90:"New York"

 

In general, every search expression is a clause.

A predicate that stands alone is also a clause (simple clause) and, therefore, a valid search expression.

A term that stands alone is also a predicate (full-text predicate), which matches against all metadata in an asset. It is, therefore, also a clause and a valid search expression.

In the following sections about terms, predicates, and clauses, you can use all of the examples as actual search expressions and test them in Fotoware.

Terms

A term describes the content to match against, such as a word, phrase, or range of values. A search expression that consists of only a term causes Fotoware to search in all metadata of an asset ("full text search").

Fotoware recognizes the following terms:

Definition Explanation Example
Word

A word is a literal piece of text to match against.

Searching for single words normally does not require any special syntax. Sometimes, however, part of a word may have a special meaning in a search expression. Then, it is necessary to put the word into double quotes, and it becomes a phrase (see below). Phrases consisting of multiple words separated by spaces must also be placed in double quotes.

A word cannot contain spaces and characters with special meanings (delimiters), which are & | ( ) ~.

A word cannot be equal to a reserved word with a special meaning. Reserved words are andornotto. Reserved words are case-insensitive.

The following characters have special meanings in certain cases:

  • The hyphen is always interpreted as a NOT operator when it precedes a word, e.g., -cars. However, a hyphen in the middle of a word is always interpreted literally.
  • The colon may be interpreted as a separator between a predicate and a term. It is interpreted literally only if the characters to the left of it do not have any special meaning. For an overview of all such cases, see the section about predicates.
  • A word consisting of only digits and dots and starting with a plus or minus sign may be interpreted as a number. This depends on the context. For more information, see Searching for Numbers and Date/Time values.
  • A word consisting of only digits, dashes, and some other characters may be interpreted as a date. This depends on the context. For more information, see Searching for Numbers and Date/Time values.
  • A double-quote at the beginning of a word makes the word a phrase and requires a closing double-quote. See below for more information. However, it is allowed to search for words containing double quotes in the middle, such as abbreviations in Hebrew: רמב״ם.

Words may contain wildcards. It is not possible to search for a literal wildcard character, as they are always interpreted as wildcards. Wildcard characters are ? *.

Examples of words:

London
orange
notebook
austin*powers
201?
ABC-12345-xzy
John-Fredrik

The following expressions are NOT words and will be interpreted as something else:

New York
San Francisco earthquake

Each word (separated by spaces) is a separate term in the above expressions.

Tom&Jerry

In the above expression, "&" is a delimiter (a shorthand for the AND operator), so it separates the words Tom and Jerry and combines them to a clause.

2016-01-01

123

The above expressions are interpreted as date values or numbers, so they are not words. Each of them still is a single term, though.

and

The above expression is not a word because and is a reserved word (the AND operator). In isolation, this expression is invalid because the operator has no left and right operands.

-cars

The above expression is not a word because the hyphen is interpreted as a NOT operator, so this expression is equivalent to the expression NOT "cars".

Phrase

A phrase is a literal string of Unicode characters to match against. Phrases are enclosed in double quotes. They can contain spaces, delimiters reserved words, and even literal double quotes.

Phrases have the same syntax as strings in the JSON language. This means that the backslash \ character has a special meaning. It denotes the beginning of an escape sequence. Escape sequences are documented below.

Phrases can contain wildcards (? *). Wildcards are documented here. It is not possible to search for a literal wildcard character, as they are always interpreted as wildcards. Wildcard characters are ? *.

Words and characters with special meanings in Index Manager search strings are automatically removed from phrases. This includes the words "and", "or", "not", "contains" and the characters % # ~ | ( ).

Examples of phrases:

"New York"
"fish and chips"
"Tom&Jerry"
"Austin \"Danger\" Powers"
"Austin*Powers"
"201?-??-??"

The following is not a valid phrase. It shows why proper escaping of user input is needed:

"Austin "Danger" Powers"

The following two phrases are equivalent because percent characters and the word "and" are removed by Fotoware:

"60% vodka and 40% milk"
"60 vodka 40 milk"

 

Number

An integer or floating point number.

Numbers can be used as operands of ranges (see below).

Also, some predicates (such as fs - file size) expect numbers.

For more information, see Searching for Numbers and Date/Time values.

 

123
123.456
Date/Time value

A date/time value in ISO 8601 format.

Dates can be used as operands of ranges (see below).

Also, some predicates (such as mt - modification time) expect dates.

For more information, see Searching for Numbers and Date/Time values.

2016-01-01T00:00:00
2016-01-01T00:00:00Z
2016-01-01T00:00:00+02:00
2016-01-01
2016-01-01Z
2016-01-01T12
2016-01

Note that the ISO 8601 standard allows date/time values consisting of only a year. However, the following term is interpreted as a number rather than a date/time value: 

2016

A date/time value in a search expression must therefore contain at least year and month.

Range

A range specifies a pair of either numbers or date values. It matches all numeric values or date values which fall into the range.

The syntax of a range is:

min_value TO max_value

where "TO" is case-insensitive or

min_value~~max_value

The operands, min_value and max_value can be either date/time values or numbers.

Ranges are only allowed when searching in attributes or metadata fields that are of numeric or date/time type.

 

20140101~~20141231
2014-01-01 TO 2014-12-31
2000~~2014
0.5 TO 0.9

 

Dynamic Tag

Dynamic tags can be used to insert dynamic text into a search expression that depends on various parameters, such as the current time or the current user.

Dynamic tags are only allowed:

These search expressions are set up by users with permission to edit taxonomies or smart folders.

Using dynamic tags in any interactive search dialogs or in API requests is forbidden and makes the search expression either invalid or not match anything.

The general syntax of a dynamic tag is as follows:

{{namespace.name:field+|-duration|number}}

For more information, see Dynamic Tags.

Not all dynamic tags that can be used in metadata macros in actions can be used in search expressions. Furthermore, some tags have different behavior in actions and search expressions.

 

Escape sequences

Phrases support the following escape sequences:

Escape sequence Character
\b Backspace
\f Formfeed
\n Newline
\r Carriage return
\t Horizontal tab
\uXXXX Any Unicode character, given by a 4-digit hex number. For example, the phrase "\u30C4" represents the Japanese character ツ.
\(any other character)

A backslash followed by any other character not listed in this table represents exactly that character (without the backslash). This is useful for

  • Representing the backslash character (as double-backslash, \\)
  • Representing a double quote (as a backslash followed by a double quote \")

since both of these characters have special meanings in a phrase. Examples:

"c:\\windows\\system32"
"Austin \"Danger\" Powers"

It is not possible to escape the wildcard characters ? and *. They are always interpreted as wildcards, and it is not possible to search for these characters literally.

Predicates

A predicate is a primary search expression that specifies what to match against what. Typically, it specifies a subset of an asset's metadata and attributes and a term to match against.

Fotoware understands the following predicates:

Predicate Explanation Example
Full text

Matches a term against all metadata and the filename of an asset.

The syntax is simply a term with no additions.

 

"New York"

 

Field

Matches a term against a single metadata field of an asset.

The syntax is as follows:

field_number:term

where field_number is an integer number, which specifies the metadata field.

 

80:"John Doe"
90:London

 

Range predicates

The following predicates are typically used together with range terms (using the "TO" or "~~" operator) and search in numeric or date fields. For compatibility with the custom taxonomy search string syntax in earlier versions as well as the query string search syntax of the Fotoware search API, these predicates come in two forms:

  1. Closed range form (predicate:term), e.g.

    pw:800~~2048
    
  2. Open range form (min_predicate:min_value AND max_predicate:max_value)

    pwf:800 AND pwt:2048

Using the open range form, it is also possible to specify only one limit of a range and search for, e.g., "all images with a with of less than 800 pixels". If both a lower and an upper limit is specified, then the closed range form is recommended, whereas the open range form exists for compatibility.

The following table lists the open-range and close-range forms of each predicate.

Predicate Explanation Example

File modification Time

(mt, mtf, mtt)

Matches assets with a file modification time within the given limits.

The limits are date/time values.

For more information, see Searching for Numbers and Date/Time values.

The following search expressions all match assets with a file modification time within the year 2014:

mt:2014-01-01~~2015-01-01
mtf:2014-01-01 mtt:2015-01-01

IPTC Creation Time

(it, itf, itt)

Matches assets with an IPTC creation time within the given limits.

In the default metadata configuration, IPTC creation time is mapped to metadata field 55, so the following searches are equivalent:

it: FROM_DATE~~TO_DATE
55: FROM_DATE~~TO_DATE

The following search expressions all match assets with an IPTC creation time within the year 2014:

it:2014-01-01~~2015-01-01
itf:2014-01-01 itt:2015-01-01

Released Time

(rt, rtf, rtt)

Matches assets with a release time within the given limits.

In the default metadata configuration, released time is mapped to metadata field 30, so the following searches are equivalent:

rt: FROM_DATE~~TO_DATE
30: FROM_DATE~~TO_DATE

The following search expressions all match assets with a release time within the year 2014:

rt:2014-01-01~~2015-01-01
rtf:2014-01-01 rtt:2015-01-01

Camera Time

(ct, ctf, ctt)

Matches assets with a camera time within the given limits.

In the default metadata configuration, camera time is mapped to metadata field 350, so the following searches are equivalent:

ct: FROM_DATE~~TO_DATE
350: FROM_DATE~~TO_DATE

 The following search expressions all match assets with a camera time within the year 2014:

ct:2014-01-01~~2015-01-01
ctf:2014-01-01 ctt:2015-01-01

File size

(fs, fsf, fst)

Matches assets with a file size within the given limits.

The file size is given in bytes. However, internally, it may be rounded to kilobytes or other larger units. Rounding is generally performed such that the search returns more results without rounding, not fewer.

The following search expressions all match assets with a file size between 1000 and 9999 bytes:

fs:1000~~9999
fsf:1000 fst:9999

 

Pixel width

(pw, pwf, pwt)

Matches images and image-like assets with a width within the given limits.

The width is given in pixels.

The following search expressions all match images and image-like assets with a width of between 800 and 2048 pixels:

pw:800~~2048
pwf:800 pwt:2048

 

Pixel height

(ph, phf, pht)

Matches images and image-like assets with a height within the given limits.

The height is given in pixels.

The following search expressions all match images and image-like assets with a height of between 800 and 2048 pixels:

ph:800~~2048
phf:800 pht:2048

 

Special predicates

Predicate Explanation Example

File name

(fn)

Matches assets whose filename matches the given term

 

fn:DSC1234.JPG
fn:DSC*.JPG

 

Directory name

(dn)

Matches assets located in a folder whose name matches the given term

 

dn:"Unsorted Photos"

 

Full file path

(fp)

Matches assets whose full patch matches the given term

 

fp:"2014\\March"

 

Color space

(cs)

Matches images and image-like assets stored in the given color space.

The following arguments are accepted:

grayscale
rgb
cmyk
unknown

 

Find all non-RGB images:

-cs:rgb

 

Image orientation

(o)

Matches images and image-like assets with the given image orientation.

The following arguments are accepted:

portrait
landscape

where "portrait" means that the height of the image is larger than the width, and "landscape" means the opposite.

 

o:landscape
o:portrait

 

Asset type

(dt)

Matches assets of the given type.

The following arguments are accepted:

generic
image
movie
audio
document
graphic

where "generic" matches all assets not matched by any of the other categories.

This is different from the FQYFT operator in Index Manager and FotoStation:

Fotoware classifies assets based on its file type configuration, which is configurable. Classification can be done by either the type information reported by IndexManager or by file extension or both.

If there is at least one type with a file extension defined for a class (e.g., "movie"), then Fotoware searches by file extension only. Otherwise, it will internally use the FQYFT operator of IndexManager.

This is because classification by file extension rather than file type is more precise and fully configurable.

If no file types are defined for a given class, then the search matches nothing.

Find only images and videos

dt:image dt:movie

 

Boolean operators

A clause combines predicates and other clauses with boolean operators.

Operators can be written as words (such as "and") or as delimiters (such as "&"). Words are case-insensitive, so "AND" has the same meaning as "and". Fotoware supports the following boolean operators:

Operator Explanation Example
Conjunction (AND, &)

Expression matches if both operands match.

The "AND" operator can also be omitted. If two clauses are put next to each other, they are implicitly combined using "AND".

The following examples all have the same meaning:

apples AND pears
apples & pears
apples pears
Disjunction (OR, |) Expression matches if one of both operands matches.

 

apples OR pears
apples | (pears or bananas)

 

Negation (NOT, -)

Expression matches if operand does not match.

The hyphen character (-) is not a delimiter, and it is interpreted literally when it appears in the middle of a word, e.g., John-Fredrik.

If the hyphen is to be interpreted as a NOT operator, it must be preceded by either a space or another delimiter character or appear at the beginning of a search expression.

The following examples all have the same meaning:

NOT apples
-apples

The following examples all have the same meaning:

apples AND -pears
apples AND NOT pears
apples NOT pears
apples-pears

Example of how to search for assets that do NOT have New York in the Title field (#005):

NOT 005:"New York"

 Searching for a Title field (#005) that is NOT empty:

NOT 005:""

Combining predicates and boolean operators

Predicates and boolean operators can be combined to specify the precise fields to search in. In such cases, the boolean operator precedes the predicate in the search syntax. Some examples:

Syntax Explanation
NOT 25:apples Retrieves assets where the word apples is not in Keywords (field 25)
25:apples OR 25:pears Retrieves all assets that contain either apples or pears in Keywords
NOT 501:Approved AND NOT 501:Rejected Retrieves all assets that do not have the words Approved or Rejected in field 501. Assets containing other values in field 501 will be found.

Operator precedence

Operators have different levels of precedence. NOT has the highest precedence (binds strongest), and OR has the lowest precedence (binds weakest). To override operator precedence, parentheses can be added.

The following examples show how operator precedence works. For each row, the right-hand column shows an expression equivalent to the one in the left-hand column. Parentheses are added on the right-hand side for clarity.

Expression Interpretation according to precedence

 

a AND b OR c

 

 

 (a AND b) OR c

 

 

 NOT a AND b

 

 

 (NOT a) AND b

 

 

 a OR b AND c

 

 

 a OR (b AND c)

 

 

 a AND NOT b

 

 

 a AND (NOT b)

 

How search string modification affects search expressions

Search string modification can be enabled site-wide to dictate how literal search strings with no operators in between are interpreted. The search string modification setting applies only to searches performed in the standard Fotoware interface (not Pro) and when using the Collection Queries API.

For more information about how searches are handled when using search string modification, see Configuring default search behavior