Faceting Dates

The search appliance supports a variety of terminology when faceting on dates. The following examples illustrates how to work with that terminology.

Dates for faceting support the granularity that is defined in the parsetable.xml for that field.

Example:

https://<appliance_ip>/search?q=data&facets=lastmodified:range(begin:2012-05-13, end:2012-05-19, gap:{2012-05-14, 2012-05-16})

Response:

<facets>
  <facet name="lastmodified" type="date">
    <bins>
      <bin range="[2012-05-13 TO 2012-05-14}">0</bin>
      <bin range="[2012-05-14 TO 2012-05-16}">0</bin>
      <bin range="[2012-05-16 TO 2012-05-19}">0</bin>
    </bins>
  </facet>
</facets>

Round Down, <, and Round Up, >, Operators

The < and > are used to round to a minute, hour, day, week, month or year. Dates are rounded up (>) or down (<) to the nearest interval for convenience.

>
Day - 2003-05-01 03:25>day finds the first midnight on or after 3:25 a.m. on 2003-05-01 -- in other words, 2003-05-02
Week - 2003-05-01>week finds the first Sunday on or after 2003-05-01
Month - 2003-05-09>month finds the next month, 2003-06-01
Year - 2003-05-01>year finds the next year, 2004-01-01

<
Day - 2003-05-01 03:25<day finds the first midnight on or before 3:25 a.m. on 2003-05-01 -- in other words, 2003-05-01
Week - 2003-05-01<week finds the first Sunday on or before 2003-05-01
Month - 2003-05-09<month finds the first of the month, 2003-05-01
Year - 2003-05-01<year finds the current year, 2003-01-01

Example:

https://<appliance_ip>/search?q=data&facets=lastmodified:range(begin:2012-07-19 03:40>day, end:+5 days, gap:+1 day)

Response:

<facets>
  <facet name="lastmodified" type="date">
    <bins>
      <bin range="[2012-07-20 TO 2012-07-21}">0</bin>
      <bin range="[2012-07-21 TO 2012-07-22}">0</bin>
      <bin range="[2012-07-22 TO 2012-07-23}">0</bin>
      <bin range="[2012-07-23 TO 2012-07-24}">0</bin>
      <bin range="[2012-07-24 TO 2012-07-25}">0</bin>
    </bins>
  </facet>
</facets>

Today

The word today is used to refer to the current date. The following example assumes that today's date is 06/30/2012.

Example:

https://<appliance_ip>/search?q=data&facets=lastmodified:range(begin:-1month, end:today, gap:-10days)

Response:

<facets>
  <facet name="lastmodified" type="date">
    <bins>
      <bin range="[2012-05-30 TO 2012-05-31}">0</bin>
      <bin range="[2012-06-01 TO 2012-06-10}">0</bin>
      <bin range="[2012-06-10 TO 2012-06-20}">0</bin>
      <bin range="[2012-06-20 TO 2012-06-30}">0</bin>
    </bins>
  </facet>
</facets>

Incrementing Date Gaps

The following example returns bins that increment steps of one day.

Example:

https://<appliance_ip>/search?q=data&facets=lastmodified:range(begin:2005-01-20, end:2005-01-24, gap:1day)

Response:

<facets>
  <facet name="lastmodified" type="date">
    <bins>
      <bin range="[2005-01-20 TO 2005-01-21}">0</bin>
      <bin range="[2005-01-21 TO 2005-01-22}">0</bin>
      <bin range="[2005-01-22 TO 2005-01-23}">0</bin>
      <bin range="[2005-01-23 TO 2005-01-24}">0</bin>
    </bins>
  </facet>
</facets>

The following also returns bins that increment in one-day steps.

Example:

https://<appliance_ip>/search?q=data&facets=lastmodified:range(begin=2005-01-20, end=2005-01-24, gap=+1day)

Response:

<facets>
  <facet name="lastmodified" type="date">
    <bins>
      <bin range="[2005-01-20 TO 2005-01-21}">0</bin>
      <bin range="[2005-01-21 TO 2005-01-22}">0</bin>
      <bin range="[2005-01-22 TO 2005-01-23}">0</bin>
      <bin range="[2005-01-23 TO 2005-01-24}">0</bin>
    </bins>
  </facet>
</facets>

In order to map easily onto dates as we use them in casual conversation (e.g. with the word "ago", or the phrase "from now"), date ranges support the notion of a pivot and a delta. In the date range (begin:today, end:+1year, gap:+1month), the +1year value for the end parameter is a delta (something added or subtracted), and today is a pivot (a value resolvable to a specific date, against which the delta is applied). The delta and pivot can be reversed; in (begin:-1year, end:2004-01-06, gap:+1month), the begin value of -1year is a delta, and 2004-01-06 is a pivot.

For convenience, date gaps can be specified counting either from the end of the range or the beginning. In the date range (begin:today, end:+4months, gap:+3weeks), gaps are counted from the beginning of the range, because bins ascend and the delta is positive. In the date range (begin:today, end:+4months, gap:-3weeks), gaps are counted from the end of the range, because bins ascend and the delta is negative. Although these two range specifications are similar, they do not produce identical bins, because 3 weeks does not divide evenly into 4 months. In the first spec, the final bin covers fewer days than the others; in the second spec, the first bin does.

The following query constructs a histogram with all gaps relative to the pivot.

Example:

https://<appliance_ip>/search?q=data&facets=lastmodified:range(begin:-36 mo,end:2012-07-19>month, gap:{-1w, -1mo, -1q, -1y, -2y})

Response:

<facets>
  <facet name="lastmodified" type="date">
    <bins>
      <bin range="[2009-08 TO 2010-08}">0</bin>
      <bin range="[2010-08 TO 2011-08}">0</bin>
      <bin range="[2011-08 TO 2012-05}">0</bin>
      <bin range="[2012-05 TO 2012-07}">0</bin>
      <bin range="[2012-07 TO 2012-07-25}">0</bin>
      <bin range="[2012-07-25 TO 2012-08}">0</bin>
    </bins>
  </facet>
</facets>

Since the deltas are negative, the pivot is the end value (2012-17-19 rounded up to the nearest month, or 2012-08-01). Therefore, the first gap is at pivot -1 week = 2012-07-25; the second gap is at pivot -1 month = 2012-07-01; the third gap is at pivot -1 quarter = 2012-05-01, etc.

The following query constructs a histogram with all gaps relative to one another (the first one is always relative to the pivot).

Example:

https://<appliance_ip>/search?q=data&facets=lastmodified:range(begin:-1year, end:2005-01-10, gap:{--3 days, --14 days, --1quarter, --1 month})

Response:

<facets>
  <facet name="lastmodified" type="date">
    <bins>
      <bin range="[2004-01-10 TO 2004-08-24}">0</bin>
      <bin range="[2004-08-24 TO 2004-09-24}">0</bin>
      <bin range="[2004-09-24 TO 2004-12-24}">0</bin>
      <bin range="[2004-12-24 TO 2005-01-07}">0</bin>
      <bin range="[2005-01-07 TO 2005-01-10}">0</bin>
    </bins>
  </facet>
</facets>

The first gap is at pivot -1 week = 2012-07-25; the second gap is at gap1 -1 month = 2012-06-25; the third gap is at gap2 -1 quarter = 2012-03-25, etc. Use "--" and "++" for relative gaps; this computes the gap location by increment instead of addition or subtraction.

Mix and match this notation, though relative dates may not be used for both starting and ending gap values.

Example:

https://<appliance_ip>/search?q=data&facets=lastmodified:range(begin:-1year, end:2005-01-06>week, gap:{-3 days, --14 days, --1quarter, --1 month})

Response:

<facets> 
  <facet name="lastmodified" type="date"> 
    <bins> 
      <bin range="[2004-01-09 TO 2004-08-23}">0</bin> 
      <bin range="[2004-08-23 TO 2004-09-23}">0</bin> 
      <bin range="[2004-09-23 TO 2004-12-23}">0</bin> 
      <bin range="[2004-12-23 TO 2005-01-06}">0</bin> 
      <bin range="[2005-01-06 TO 2005-01-09}">0</bin> 
    </bins> 
  </facet> 
</facets>

We can also have custom gap sizes.

Example:

https://<appliance_ip>/search?q=data&facets=lastmodified:range(begin:-36 mo, end:2012-07-19>month, gap:{--1w, --1mo, --1q, --1y, --2y})

Response:

<facets> 
  <facet name="lastmodified" type="date"> 
    <bins> 
      <bin range="[2009-08 TO 2011-03-25}">0</bin> 
      <bin range="[2011-03-25 TO 2012-03-25}">0</bin> 
      <bin range="[2012-03-25 TO 2012-06-25}">0</bin> 
      <bin range="[2012-06-25 TO 2012-07-25}">0</bin> 
      <bin range="[2012-07-25 TO 2012-08}">0</bin> 
    </bins> 
  </facet> 
</facets>

Using a negative sign, the bins are created from the maximum date of the range rather than its minimum.

Example:

https://<appliance_ip>/search?q=data&facets=lastmodified:range(begin:-36 mo,end:2012-07-19>month, gap:{-1w, -1mo, -1q, -1y, -2y})

Response:

<facets> 
  <facet name="lastmodified" type="date"> 
    <bins> 
      <bin range="[2009-08 TO 2010-08}">0</bin> 
      <bin range="[2010-08 TO 2011-08}">0</bin> 
      <bin range="[2011-08 TO 2012-05}">0</bin> 
      <bin range="[2012-05 TO 2012-07}">0</bin> 
      <bin range="[2012-07 TO 2012-07-25}">0</bin> 
      <bin range="[2012-07-25 TO 2012-08}">0</bin> 
    </bins> 
  </facet> 
</facets>

Example:

https://<appliance_ip>/search?q=data&facets=lastmodified:range(begin:2012-05-13, end:2012-05-19, gap:{+1 day, +2 days})

Response:

<facets> 
  <facet name="lastmodified" type="date"> 
    <bins> 
      <bin range="[2012-05-13 TO 2012-05-14}">0</bin> 
      <bin range="[2012-05-14 TO 2012-05-16}">0</bin> 
      <bin range="[2012-05-16 TO 2012-05-19}">0</bin> 
    </bins> 
  </facet> 
</facets>

If needed, we can also mix absolute values with relative values.

Example:

https://<appliance_ip>/search?q=data&facets=lastmodified:range(begin:2012-05-13, end:2012-05-19, gap:{2012-05-14, ++1day, 2012-05-17})

Response:

<facets> 
  <facet name="lastmodified" type="date"> 
    <bins> 
      <bin range="[2012-05-13 TO 2012-05-14}">0</bin> 
      <bin range="[2012-05-14 TO 2012-05-15}">0</bin> 
      <bin range="[2012-05-15 TO 2012-05-17}">0</bin> 
      <bin range="[2012-05-17 TO 2012-05-19}">0</bin> 
    </bins> 
  </facet> 
</facets>

Example:

https://<appliance_ip>/search?q=data&facets=lastmodified:range(begin:2012-05-13, end:2012-05-19, gap:{+1day, 2012-05-15, ++2day})

Response:

<facets> 
  <facet name="lastmodified" type="date"> 
    <bins> 
      <bin range="[2012-05-13 TO 2012-05-14}">0</bin> 
      <bin range="[2012-05-14 TO 2012-05-15}">0</bin> 
      <bin range="[2012-05-15 TO 2012-05-17}">0</bin> 
      <bin range="[2012-05-17 TO 2012-05-19}">0</bin> 
    </bins> 
  </facet> 
</facets>

Matching Signs

All signs must match, as the following will result in an error.

Example:

https://<appliance_ip>/search?q=data&facets=lastmodified:range(begin:2012-05-13, end:2012-05-19, gap:{+1 day, +2 days, -3 days})

Response:

Error

Partial Dates

Partially specified dates (e.g., 2000 [no month or day] or 2000-01 [no day]) are supported. The query logic uses the greatest precision implied by either begin or end. For example, if a query requests &facets=birthdate:range(begin:1969, end:2005-03, gap:+year), the more precise boundary on the range is the end value, which is precise to the month. Thus, the range starts with all values having a year of 1969 and a month of 1 or greater (the 1 is inferred), and ends with the first value that has a year of 2005 and a month of 3.

This convention can make your requests more terse. However, if your data contains partially specified dates, it also provides an important function. Suppose you have a genealogy database, and birth dates are not always specified to the day; sometimes a person's birth year (1885) or birth year + birth month (1885-04) are the only values provided. A birth date of 1885 is easily handled when we facet values between 1883 and 1886 by year--but what about when we facet by month? If we treat 1885 as 1885-01, we make a lousy and unwarranted assumption. If we treat 1885 as 1885-00, we end up with 13 bins per year, rather than 12, and users may be thoroughly confused. By allowing you to choose the precision with which bins are assigned, the partial dates feature gives you control. If your data never uses partial dates, or if you are uninterested in the distinction between partial and fully specified dates, define the range with less precise values (e.g., year precision), and behavior will match casual expectations. If you ask for precise bin assignment on values that lack that precision, the values drop out of the count--a query with 50 hits, faceted by birth date into month, where one of the hits is only precise to the year, will only show a cumulative count of 49 in its bins.

Before and After

Before values create a bin that contains values before the start value.

Example:

https://<appliance_ip>/search?q=data&facets=lastmodified:range(begin:2001-01-03, end:+3w, gap:+1w, before:true)

Response:

<facets> 
  <facet name="lastmodified" type="date"> 
    <bins> 
      <bin range="[* TO 2001-01-03}">0</bin> 
      <bin range="[2001-01-03 TO 2001-01-10}">0</bin> 
      <bin range="[2001-01-10 TO 2001-01-17}">0</bin> 
      <bin range="[2001-01-17 TO 2001-01-24}">0</bin> 
    </bins> 
  </facet> 
</facets>

After values create a bin that contains values after the end value.

Example:

https://<appliance_ip>/search?q=data&facets=lastmodified:range(begin:2001-01-03, end:+3w, gap:+1w, after:true)

Response:

<facets> 
  <facet name="lastmodified" type="date"> 
    <bins> 
      <bin range="[2001-01-03 TO 2001-01-10}">0</bin> 
      <bin range="[2001-01-10 TO 2001-01-17}">0</bin> 
      <bin range="[2001-01-17 TO 2001-01-24}">0</bin> 
      <bin range="[2001-01-24 TO *}">0</bin> 
    </bins> 
  </facet> 
</facets>