Skip to main content

 

Documentation & User Guides | FotoWare

Searching for Numbers and Time / Date values

 

FotoWeb supports search for time points and time ranges, numbers and numeric ranges. This article explains how date/time values and numbers can be used in search queries and how search matches results using date/time and numeric values.

Date/time values and numbers can be used

Date/Time Representation

A date/time value must be given in ISO 8601 format:

YYYY-MM-DDThh:mm:ss.ss

 where:

Field

Description

Example

YYYY Year (4 digits) 2016
MM Month of the year (2 digits) 05
DD Day of the month (2 digits) 30
hh

Hour of the day (2 digits)

Given in 24 hour format (0-23)

12
mm Minute of the hour (2 digits) 59
ss.ss Second of the minute (2 digits with optional fractional part)

12

12.345

 

 All components except the year are optional.

Time Zone Designators

A date/time value may optionally be followed by a time zone designator, which can be in one of the following formats:

+hh
-hh
+hh:mm
-hh:mm
Z

where hh is the number of hours and mm is the number of minutes difference to universal time (UTC). For example, +02:00 indicates a time zone "UTC - 2 hours", where the time is 14:00 (2 pm) while it is 12:00 (12am) in UTC. The minutes part is optional, so a the time zone designator can also be written as -02, which also means "UTC - 2 hours". A time zone indicator of Z means that the time zone is UTC, and it is preferred over +00:00.

If no time zone indicator is given, then the date/time value is expressed in server local time. Currently, this is the Windows time zone set on the FotoWeb server. In future versions, this will be a configuration option.

Examples

Date/time value

Meaning

2016-05-17

17th of May 2016, 00:00 (midnight) in server local time. 24 hours, midnight to midnight. When used in a range search, it refers to precisely midnight.

2016-05-17T12:25:00 17th of May 2016, 12:25 (midnight) in server local time
2016-05-17T12:25:00Z 17th of May 2016, 12:25 (midnight) in UTC
2016-05-17T12:25:00+02:00 17th of May 2016, 12:25 (midnight) in UTC + 2 hours (i.e., 10:25 in UTC)
2016-05+02:00 1st of May 2016, 00:00 (midnight) in UTC + 2 hours (i.e., 30th of April, 22:00 in UTC)

 

Number Representation

Numbers can be given as integer or floating-point numbers in the same syntax as in the JSON language (external link):

123
-123
123.456
-0.123
0.123e+4
0.123e-4
00123
+123

Leading zeroes or plus signs are ignored.

FotoWeb search only supports integer numbers, so all numbers are converted to integers internally. For example, a search for {{0.5~~123.456}} is the same as a search for 0~~123.

Searching for Numbers and Date/Time Values

It may not always be the user's intention to search for a date/time value or number. For example, a search expression of 000123 looks like a number, but it may actually be a literal string that represents a unique identifier. The zeroes may be important, but if the expression is interpreted as a number, they will be stripped. Other examples:

  • A user may want to search for a unique identifier that looks like a date, e.g., 1234-01-01-01. If interpreted as a date, the date would be out of range and invalid (FotoWeb only supports searches for dates after 1601-01-01).
  • A user may want to search for an international phone number, e.g., +47000000. If interpreted as a number, the leading plus sign would be stripped.

Therefore, it depends on context (predicates) whether FotoWeb interprets an expression as a number, a date/time value or just a literal string. The rules are as follows:

  • If a date/time value is expected in the search context, then FotoWeb interprets all terms as date/time values. Any other terms make the predicate invalid and match nothing.
  • If a number is expected in the search context, then FotoWeb interprets all terms as numbers. Any other terms make the predicate invalid and match nothing.
  • If text is expected in the search context, then FotoWeb interprets all terms as literal strings. Numbers and dates are therefore interpreted literally and have no special meanings.
  • When doing a full text search, FotoWeb interprets all terms as literal strings. Numbers and dates are therefore interpreted literally and have no special meanings.

The search context depends on what predicates are used. Here are some examples:

Search Expression

Interpreted as

Explanation

0123 "0123" This is a full text search, so the term is always interpreted as a literal string, even though it looks like a number.
2016-01-01-01 "2016-01-01-01" This is a full text search, so the term is always interpreted as a literal string, even though it looks like a date.
fn:0123 fn:"0123" The search context is the file name, which is always text, so the term is always interpreted as a literal string, even though it looks like a number.
fn:2016-01-01 fn:"2016-01-01" The search context is the file name, which is always text, so the term is always interpreted as a literal string, even though it looks like a date.
fs:0123 fs:123 The search context is the file size, which is always a number, and the term is a valid number, so it is interpreted as a number.
mt:2016-01-01 mt:2016-01-01 The search context is the modification time, which is always a date/time value, and the term is a valid date/time value, so it is interpreted as a date/time value.
fs:abcde (no match) The term is not a valid number, but the search context is file size, which is always a number, so the predicate matches nothing.
mt:abcde (no match) The term is not a valid date/time value, but the search context is file modification time, which is always a date/time value, so the predicate matches nothing.
mt:1234-01-01 (no match) The term looks like a date/time value, but it is invalid (out of range), but the search context is modified time, which is always a date/time value, so the predicate matches nothing.

If the search context is a metadata field, then it depends on the type of the field in the metadata configuration whether terms are interpreted as date/time values, numbers or literal strings. For example, the following standard fields have the following types:

Field ID

Type

Description

5 Text Object name
25 Text Keywords
55 Date/time IPTC Created Date (Adobe Photoshop)
350 Date/time Original date (EXIF Properties)
362 Date/time Upload Time (FotoWare Reserved)

 

Time Zone Conversion

Search expressions can be given in different time zones:

  • Universal time (UTC), e.g., 2016-05-17T00:00:00Z
  • Server local time, e.g., 2016-05-17T00:00:00
  • A specific time zone, e.g., 2016-05-17T00:00:00+05:00

Not all searchable attributes contain time zone information. While the XMP standard specifies that date/time values in metadata fields may be in ISO 8601 representation, which means that they may contain time zone information, certain attributes, such as file modification time, are not given in any particular time zone. Time zone information may be useful, and time labels in local time zones may be more intuitive to users in a certain region. However, when searching, a user is typically only interested in whether a date/time value stored in an asset matches with the (physical) point or range in time given in the search query, regardless of time zone. For example, if a photo was taken in New York City at 5 am US Eastern Time, and a photo editor in Berlin searches for a date/time range in Central European Time, then the photo editor is interested if the photo was taken during that time range and not what time the clocks showed in New York, Berlin or Greenwich.

Therefore, when doing a search, all date/time values are in the search query are internally converted to universal time (UTC). All date/time values stored in assets are also indexed in universal time (UTC), although they may be stored and displayed in a different time zone. Being able to search in different time zones is therefore only a convenience for the user. Technically, all searches are in UTC.

Date Ranges and Incomplete Dates

Date values are most useful when used in range expressions. For example, the following expression:

mt:2016-05-17 TO 2016-05-18

matches all assets which were modified on 17th of May 2016.

Ranges are a bit tedious to write, so there is a shorthand:

mt:2016-05-17

In this expression, the date/time value is incomplete: It consists only of the date and does not include the time. If an incomplete date/time value appears outside of a range, then it is implicitly converted to a range according to the following rules:

Term

Interpreted As

Explanation

2016 2016-01-01T00:00:00~~2017-01-01T00:00:00 If only the year is given, then the expression is converted to a range that spans the entire year.
2016-05 2016-05-01T00:00:00~~2016-06-01T00:00:00 If only the month is given, then the expression is converted to a range that spans the entire month.
2016-05-17 2016-05-17T00:00:00~~2016-05-18T00:00:00 If only the day is given, then the expression is converted to a range that spans the entire day.
2016-05-17T12 2016-05-17T12:00:00~~2016-06-01T13:00:00 If only the hour is given, then the expression is converted to a range that spans the entire hour.
2016-05-17T12:30 2016-05-17T12:30:00~~2016-05-17T12:31:00 If only the minute is given, then the expression is converted to a range that spans the entire minute.
2016-05-17T12:30:45 2016-05-17T12:30:45 If the second is given (with or without fractional part), then the date/time value is complete and not converted to a range.

Incomplete date/time values which appear in ranges are not converted to ranges but expanded to complete date/time values by "adding zeroes", as follows:

Term

Interpreted As

Explanation

2016-05-17T12:30~~... 2016-05-17T12:30:00~~... If the second is not given, then it is set to zero (start of the minute).
2016-05-17T12~~... 2016-05-17T12:00:00~~... If the minute is not given, then it is set to zero (start of the hour).
2016-05-17~~... 2016-05-17T00:00:00~~... If the time is not given, then it is set to midnight (start of the day).
2016-05~~... 2016-05-01T00:00:00Z~~... If the day is not given, then it is set to the first of the month.
2016~~... 2016-01-01T00:00:00Z~~... If the month is not given, then it is set to January.

A range always includes the left operand but excludes the right operand. For example, the expression

mt:2014~~2016

matches all assets modified in the years 2014 and 2015, but not those modified in the year 2016. If both operands of a range are equal, then the range is empty, and the term matches nothing.

  • Was this article helpful?