Using Date Filters
Using Date Filters
The date filter can be applied or is used in the command line, URLs, in profiles, in reports and report elements, in the Scheduler to apply a date per report and in the Date Picker and Calendar.
Here are some examples of how it's used on the command line:
-df 18jan2009, -df "18 jan 2009 20 00 00", -df 3M, -df "1 month", -df "3 months", -df "recent 3M", -df "recent 3 months", -df "last 3 months"
In the URLs, it's similar syntax:
df=18jan2009, df=1month, df=3months
Absolute date filters
Absolute date filters specify a definitive calendar date or the earliest (start) or latest (end) log date.
There are general rules for creating absolute date filters:
Absolute date filter types
We distinguish between three different absolute date filter types: single dates, date ranges and multiple dates.
Single dates
A single date is composed of the following date/time units:
| Date/time unit | Unit values |
| year | 2 digit or 4 digit year |
| quarter | q1-q4 or quarter1-quarter4 |
| month | jan-dec or january-december |
| day | 1-31 or 01-31 |
| hour | 00-23 |
| minute | 00-59 |
| second | 00-59 |
Date/time unit sequences allowed per single date:
| Date/time unit sequence | df example |
| year | 2009 |
| quarter year | Q1/2009 |
| month year | Jan/2009 |
| day month year | 1/Jan/2009 |
| day month year hour | 1/Jan/2009 14 |
| day month year hour minute | 1/Jan/2009 14:30 |
| day month year hour minute second | 1/Jan/2009 14:30:20 |
Date Ranges
Date ranges are the combination of two arbitrary single dates or one single date with the "start" or "end" keyword separated by a dash "-".
The dash "-" dividing the single dates may be surrounded by two other dividers such as spaces or any other non-alphanumeric character, except dash "-" and comma ",".
| Date range sequences | df example |
| (single date) - (single date) | q2/2008 - 5/Jan/2009 |
| start - (single date) | start - 5/jan/2009 |
| (single date) - end | feb/2009 - end |
Note: Start specifies the earliest log date, end specifies the latest log date.
Multiple dates
Multiple dates are an arbitrary sequence of single dates separated by a comma ",". Multiple dates are in particular required when a user zooms to multiple date items.
The comma "," dividing multiple dates may be surrounded by two other dividers such as spaces or any other non-alphanumeric character, except dash "-" and comma ",".
| Multiple dates sequence | df example |
| (single date), (single date), (single date) | 18jul2009, 20jul2009, 17dec2009 |
Multiple dates with different date/time units are required when zooming on a Pivot Table with different date/time units, i.e.: 10feb2007, jul2007, 4aug2007, 2008 Multiple dates must not overlap, so "2jul2007, 2jul2007, jul2007" will not return a reliable result.
Examples
This specifies the date filters to use when generating a report. It is similar to the Report Filters option, but with a few differences:
-
It is intended only for date filtering (use Report Filters for other types of filtering).
-
It supports a wider range of syntax options.
-
It is displayed attractively in the \"Date Filter\" section of the report (filter specified with Report Filters will appear below that, and will appear as literal filter expressions).
| df | Calculated date applied in the report |
| 2/jan/2009 | 02/Jan/2009 |
| 2/jan/2009 14 | 02/Jan/2009 14:00:00 - 02/Jan/2009 14:59:59 |
| 2/jan/2009 14:30 | 02/Jan/2009 14:30:00 - 02/Jan/2009 14:30:59 |
| 2/jan/2009 14:30:00 | 02/Jan/2009 14:30:00 |
| jan2009 | 01/Jan/2009 - 31/Jan/2009 |
| quarter1 2009 | 01/Jan/2009 - 31/Mar/2009 |
| jan2008-jan2009 | 01/Jan/2008 - 31/Jan/2009 |
| 2jan2008-2009 | 02/Jan/2008 - 31/Dec/2009 |
| start-2/JAN/09 | earliest log date - 02/Jan/2009 |
| 2/jan/2009-end | 02/Jan/2009 - latest log date |
| 08 - 28 feb 2009 14 | 01/Jan/2008 - 28/Feb/2009 14:59:59 |
| 10 feb 2009 13 - 10 feb 2009 13 | 10/Feb/2009/13:00:00 - 10/Feb/2009/13:59:59 |
| 14dec2008, 1jan2009, 5jan2009 | 14/Dec/2008, 01/Jan/2009, 05/Jan/2009 (Comma separated dates are in particular used internally when zooming date items in a report element) |
Relative date filters
Relative date filters allow the user to specify a date by defining the number of a given date unit. I.e. the date filter "recent3M" shows the recent 3 months.
The general rules about relative date filters are the syntax is case insensitive, spaces are allowed, ranges are not allowed, and the -show extension is optional.
A relative date filter is composed of the components in the table below, the -show extension is optional.
| Relative prefix | Date/time unit count | Date/time unit | -show extension | -show date/time unit count | -show date/time unit |
|---|---|---|---|---|---|
| "" (none) | Integer > = 1 | year | -show | Integer > = 1 | year |
| recent | quarter | quarter | |||
| last | month | month | |||
| first* | week,day,hour,minute,second | week,day,hour,minute,second |
* The "first" prefix is reserved in case that we require a relative date filter which calculates dates from the earliest log date.
Date/time units may be written as single letters (except time units), as singular or plural word, in lowercase and/or uppercase.
There are three different main types of relative date filters which are described by a "Show 3 months" example:
| df | Description |
| 3M | Shows the most recent 3 months relative to the latest log date. If we assume a log date range from 1/Jan/2006 until 10/Jul/2007 then Sawmill will calculate a date which shows May/2007, Jun/2007 and Jul/2007. This type of date filter doesn't consider the current calendar date! |
| recent3M | Shows the most recent 3 months relative to the currrent calendar date. If we assume a current calendar date of 5/Jan/2008 then Sawmill will calculate a date which shows Nov/2007, Dec/2007 and Jan/2008. recent includes the current calendar month. |
| last3M | Shows the last 3 months relative to the currrent calendar date. If we assume a current calendar date of 5/Jan/2008 then Sawmill will calculate a date which shows Oct/2007, Nov/2007 and Dec/2007. last excludes the current calendar month. |
Note: The above main type example is valid for all date/time units such as Y (years), Q (quarters), M (months), W (weeks), D (days), hours, m minutes and seconds.
Optional -show extension
-show is an extension to the relative filters, i.e. 3M-show1M
The optional -show extension of a date filter calculates first the start date/time of what is defined on the left side of the dash and then limits the date of what is defined in the optional show part. "show" must be followed by an integer >= 1 and a date/time unit. The "Q" (quarter) in -show1Q does not mean a calendar quarter but simply three months. The "W" (week) in -show1W does not mean a calendar week but simply seven days.
Examples: recent6M-show5D: This shows 5 days beginning with the day of the recent 6M.recent2Y-show2M: Shows 2 months beginning with the month of recent2Y.