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
- as terms in Search Expressions
- as arguments to search query parameters in collection queries
Date and 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) | 2023 |
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
(2 pm) while it is 14:00
12:00
(12 am) in UTC. The minutes part is optional, so 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, 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 |
---|---|
2023-05-17 |
17th of May 2023, 00:00 (midnight) in server local time. 24 hours, midnight to midnight. When used in a range search, it refers to precisely midnight. |
2023-05-17T12:25:00 |
17th of May 2023, 12:25 (midnight) in server local time |
2023-05-17T12:25:00Z |
17th of May 2023, 12:25 (midnight) in UTC |
2023-05-17T12:25:00+02:00 |
17th of May 2023, 12:25 (midnight) in UTC + 2 hours (i.e., 10:25 in UTC) |
2023-05+02:00 |
1st of May 2023, 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 TO 123.456}} is the same as a search for 0 TO 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 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; for example,
1234-01-01-01
. If interpreted as a date, the date would be out of range and invalid (FotoWeb only supports searches for dates after1601-01-01
). - A user may want to search for an international phone number; for example,
+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. |
2023-01-01-01 |
"2023-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:2023-01-01 |
fn:"2023-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:2023-01-01 |
mt:2023-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), for example,
2023-05-17T00:00:00Z
- Server local time, for example,
2023-05-17T00:00:00
- A specific time zone, for example,
2023-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 the (physical) point or range in time given in the search query, regardless of the 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 searching, all date and time values 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:2023-05-17 TO 2023-05-18
matches all assets which were modified on 17th of May 2023.
Ranges are a bit tedious to write, so there is a shorthand:
mt:2023-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 |
---|---|---|
2023 |
2023-01-01T00:00:00 TO 2024-01-01T00:00:00 |
If only the year is given, then the expression is converted to a range that spans the entire year. |
2023-05 |
2023-05-01T00:00:00 TO 2023-06-01T00:00:00 |
If only the month is given, then the expression is converted to a range that spans the entire month. |
2023-05-17 |
2023-05-17T00:00:00 TO 2023-05-18T00:00:00 |
If only the day is given, then the expression is converted to a range that spans the entire day. |
2023-05-17T12 |
2023-05-17T12:00:00 TO 2023-06-01T13:00:00 |
If only the hour is given, then the expression is converted to a range that spans the entire hour. |
2023-05-17T12:30 |
2023-05-17T12:30:00 TO 2023-05-17T12:31:00 |
If only the minute is given, then the expression is converted to a range that spans the entire minute. |
2023-05-17T12:30:45 |
2023-05-17T12:30:45 |
If the second is given (with or without a fractional part), 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 |
---|---|---|
2023-05-17T12:30 TO ... |
2023-05-17T12:30:00 TO ... |
If the second is not given, it is set to zero (start of the minute). |
2023-05-17T12 TO ... |
2023-05-17T12:00:00 TO ... |
If the minute is not given, it is set to zero (start of the hour). |
2023-05-17 TO ... |
2023-05-17T00:00:00 TO ... |
If the time is not given, it is set to midnight (start of the day). |
2023-05 TO ... |
2023-05-01T00:00:00Z TO ... |
If the day is not given, it is set to the first of the month. |
2023 TO ... |
2023-01-01T00:00:00Z TO ... |
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:2021 TO 2023
matches all assets modified in the years 2021 and 2022 but not those modified in the year 2024. If both operands of a range are equal, then the range is empty, and the term matches nothing.
Dynamic date and time tags
To learn about using dynamic date and time tags in search expressions, see Date and time tags.