A date facet uses a calendar-based facet bucket collection:
- first query results in one facet bucket for each "year"
- drill down on "year" results in getting "month" buckets for that year
- drill down on "month" results in getting "days" buckets for that month
- drill down on "day" results in getting "hours" buckets for that day
- drill down on "hour" results in getting "minutes" buckets for that hour
- drill down on "minute" results in getting "seconds" buckets for that minute
General information common to all facet features can be found on the Facets page.
View incoming links.
Creating Date Test Data
A date facet performs best when the index contains numerous documents that have a wide range of dates. If you don't have access to an appropriate data set for testing, you can create one by passing documents through an ingest transformer that inserts randomly-generated timestamps in the date field.
The following transformer class is an elaboration of the simple one described in Creating Custom Ingest Transformers.
Create a new ingest transformer based on this class, and insert it in the ingest workflow just before the indexer subflow. Then load the Factbook country feed (or any other documents). The transformer will generate a random timestamp and insert it in each document's date field. The granularity of the timestamps can be controlled by adjusting the limits on the random values.
Requesting a Date Facet
Java Query API
It is very simple to add a DateFacetRequest to a QueryRequest. The following QueryTransformer can be inserted at the beginning of the defaultQuery workflow. It will append a DateFacetRequest to every passing query. This example is based on the one in Creating Custom Query Transformers.
The critical details are in these two lines:
The processQuery() method picks up the incoming QueryRequest and adds a DateFacetRequest for the date field. That's really all you have to do. The default date-facet behavior adapts flexibly to most situations.
HTTP REST Query API
A date facet request can be added to a query request through the REST Query API by adding this element to the query URL.
Setting dateIntervals to "auto" enables the date facet's sophisticated automatic interval discovery mechanism.
JSON REST Query API
To add a date-facet request to a query request using JSON, specify the date schema field in the query's facets array with the (dateIntervals=auto) parameter value, as in this example:
You should see the facet and its buckets displayed in the JSON response's facets list as usual, along these lines:
The Facetfinder will automatically replace facet requests on date fields with a DateFacetRequest (unless that facet has the "facetfinder=false" parameter value set on it).
Viewing Date-Facet Behavior
Note that the Facets page contains examples of facet response values returned from AIE searches.
Viewing Date Facets in SAIL
As of the release of AIE 5.0, the SAIL search interface has not entirely caught up with recent advances in DateFacetRequest. You can use Sail to verify that your date facet is working, but the labels on the facet buckets may require some interpretation. Specifically, each facet bucket is a range, but the label on the bucket is the bucket's minimum limit. In the example below, "January 1, 2000" is a six-month bucket that begins on January 1.
After ingesting 260 documents with creation dates between 2000 to 2002, inclusive, we searched for *:*.
|Date Facet Display||Remarks|
Each facet bucket in this list represents half a year. (With a wider range of dates, each bucket would have represented a year or some other increment that would yield about ten buckets (the default granularity).
We chose January 1, 2001, which means creation dates falling in the first half of 2001.
Each bucket in the next display represents a calendar month.
We selected June 1, 2001, meaning the entire month of June, 2001.
These buckets represent "weeks in June, 2001," but the first few days of June are actually in the week of May 27, 2001. That's why we have a "May" bucket in the "weeks of June."
We selected the June 3, 2001 bucket.
These buckets are the days of "the week of June 3, 2001."
With sufficiently dense data, the date facet can continue to drill down to individual hours, minutes, seconds and milliseconds.
See the Debug Search Results (below) to view the returned buckets in more detail.
Viewing Date Facet in Debug Search Results
The date facet information returned in the QueryResponse object contains a full description of each "bucket." To view it, use the Debug Search page. Set the Output Format to Legacy-XML and perform a search. This returns a page of search results in XML format. The date facet information is very near the bottom of the page. Here's an example:
This excerpt defines a date facet consisting of three buckets, each of which represents a calendar week:
- May 20-27, 2001
- May 27 to June 3, 2001
- June 3-10, 2001
Consult the min and max timestamps for a bucket if there is any question about what range it represents.