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:

  • The syntax is case sensitive.
  • Words (month names and "quarter") must be written in English, regardless of the localized language.
  • Adjacent date/time units, which are a number, must be separated by a divider, otherwise the divider is optional.
  • A divider is any non-alphanumeric character except dash "-" and commma ",".
  • The dash is reserved for date ranges.
  • The comma is reserved for multiple dates.
  • Mixing absolute date filters with relative date filters is not allowed.
  • 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 unitUnit values
    year2 digit or 4 digit year
    quarterq1-q4 or quarter1-quarter4
    monthjan-dec or january-december
    day1-31 or 01-31

    Date/time unit sequences allowed per single date:

    Date/time unit sequencedf example
    quarter yearQ1/2009
    month yearJan/2009
    day month year1/Jan/2009
    day month year hour1/Jan/2009 14
    day month year hour minute1/Jan/2009 14:30
    day month year hour minute second1/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 sequencesdf example
    (single date) - (single date)q2/2008 - 5/Jan/2009
    start - (single date)start - 5/jan/2009
    (single date) - endfeb/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 sequencedf 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.


    This specifies the date filters to use when generating a report. It is similar to the Report Filters option, but with a few differences:

    dfCalculated date applied in the report
    2/jan/2009 1402/Jan/2009 14:00:00 - 02/Jan/2009 14:59:59
    2/jan/2009 14:3002/Jan/2009 14:30:00 - 02/Jan/2009 14:30:59
    2/jan/2009 14:30:0002/Jan/2009 14:30:00
    jan200901/Jan/2009 - 31/Jan/2009
    quarter1 200901/Jan/2009 - 31/Mar/2009
    jan2008-jan200901/Jan/2008 - 31/Jan/2009
    2jan2008-200902/Jan/2008 - 31/Dec/2009
    start-2/JAN/09earliest log date - 02/Jan/2009
    2/jan/2009-end02/Jan/2009 - latest log date
    08 - 28 feb 2009 1401/Jan/2008 - 28/Feb/2009 14:59:59
    10 feb 2009 13 - 10 feb 2009 1310/Feb/2009/13:00:00 - 10/Feb/2009/13:59:59
    14dec2008, 1jan2009, 5jan200914/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 prefixDate/time unit countDate/time unit-show extension-show date/time unit count -show date/time unit
    "" (none)Integer > = 1year-showInteger > = 1year

    * 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.

  • y = year = years
  • q = quarter = quarters
  • m = month = months
  • w = week = weeks
  • d = day = days
  • hour = hours
  • minute = minutes
  • second = seconds

    There are three different main types of relative date filters which are described by a "Show 3 months" example:

    3MShows 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!
    recent3MShows 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.
    last3MShows 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.