Documentation { elastic.js }

ejs ⟩ DateHistogramFacet

The DateHistogram facet works with time-based values by building a histogram across time intervals of the value field. Each value is rounded into an interval (or placed in a bucket), and statistics are provided per interval/bucket (count and total).

Facets are similar to SQL GROUP BY statements but perform much better. You can also construct several "groups" at once by simply specifying multiple facets.

Tip: For more information on faceted navigation, see this Wikipedia article on Faceted Classification.

Module

 DateHistogramFacet

 DateHistogramFacet ( name )

A facet which returns the N most frequent terms within a collection or set of collections.


Parameters
name <String> The name which be used to refer to this facet. For instance, the facet itself might utilize a field named doc_authors. Setting name to Authors would allow you to refer to the facet by that name, possibly simplifying some of the display logic.

Method Summary

Returns Name Description
String_type()The type of ejs object. For internal use only.
ObjectcacheFilter(trueFalse)

Enables caching of the facetFilter
ObjectfacetFilter(oFilter)

Allows you to reduce the documents used for computing facet results.
Objectfactor(f)

The date histogram works on numeric values (since time is stored in milliseconds since the epoch in UTC).

But, sometimes, systems will store a different resolution (like seconds since UTC) in a numeric field. The factor parameter can be used to change the value in the field to milliseconds to actual do the relevant rounding, and then be applied again to get to the original unit.

For example, when storing in a numeric field seconds resolution, the factor can be set to 1000.
Objectfield(fieldName)Sets the field to be used to construct the this facet.
Objectglobal(trueFalse)

Computes values across the entire index
Objectinterval(timeInterval)Sets the bucket interval used to calculate the distribution.
ObjectkeyField(fieldName)Allows you to specify a different key field to be used to group intervals.
Objectlang(language)The script language being used. Currently supported values are javascript, groovy, and mvel.
Objectmode(m)

Sets the mode the facet will use.

collector
post
Objectnested(path)

Sets the path to the nested document if faceting against a nested field.
Objectorder(o)

Sets the type of ordering that will be performed on the date buckets. Valid values are:

time - the default, sort by the buckets start time in milliseconds.
count - sort by the number of items in the bucket
total - sort by the sum/total of the items in the bucket
Objectparams(p)Sets parameters that will be applied to the script. Overwrites any existing params.
ObjectpostOffset(offset)Set's a specific post-rounding offset. Format is 1d, 1h, etc.
ObjectpostZone(tz)

By default, time values are stored in UTC format.

This method allows users to set a time zone value that is then used to compute intervals after rounding on the interval value. The value is an offset from UTC. The tz offset value is simply added to the resulting bucket's date value.

For example, to use EST you would set the value to -5.
ObjectpreOffset(offset)Set's a specific pre-rounding offset. Format is 1d, 1h, etc.
ObjectpreZone(tz)

By default, time values are stored in UTC format.

This method allows users to set a time zone value that is then used to compute intervals before rounding on the interval value. The value is an offset from UTC.

For example, to use EST you would set the value to -5.
ObjectpreZoneAdjustLargeInterval(trueFalse)

Enables large date interval conversions (day and up).

Set to true to enable and then set the interval to an interval greater than a day.
Objectscope(scope)

Computes values across the the specified scope
ObjecttimeZone(tz)

By default, time values are stored in UTC format.

This method allows users to set a time zone value that is then used to compute intervals before rounding on the interval value. Equalivent to preZone. Use preZone if possible. The value is an offset from UTC.

For example, to use EST you would set the value to -5.
StringtoJSON()

Retrieves the internal facet object. This is typically used by internal API functions so use with caution.
ObjectvalueField(fieldName)Allows you to specify a different value field to aggrerate over.
ObjectvalueScript(scriptCode)Allows you modify the value field using a script. The modified value is then used to compute the statistical data.

Method Detail

 _type

 String _type ( )
The type of ejs object. For internal use only.

Returns
the type of object

 cacheFilter

 Object cacheFilter ( trueFalse )

Enables caching of the facetFilter


Parameters
trueFalse <Boolean> If the facetFilter should be cached or not
Returns
returns this so that calls can be chained.

 facetFilter

 Object facetFilter ( oFilter )

Allows you to reduce the documents used for computing facet results.


Parameters
oFilter <Object> A valid Filter object.
Returns
returns this so that calls can be chained.

 factor

 Object factor ( f )

The date histogram works on numeric values (since time is stored in milliseconds since the epoch in UTC).

But, sometimes, systems will store a different resolution (like seconds since UTC) in a numeric field. The factor parameter can be used to change the value in the field to milliseconds to actual do the relevant rounding, and then be applied again to get to the original unit.

For example, when storing in a numeric field seconds resolution, the factor can be set to 1000.


Parameters
f <Integer> The conversion factor.
Returns
returns this so that calls can be chained.

 field

 Object field ( fieldName )
Sets the field to be used to construct the this facet.

Parameters
fieldName <String> The field name whose data will be used to construct the facet.
Returns
returns this so that calls can be chained.

 global

 Object global ( trueFalse )

Computes values across the entire index


Parameters
trueFalse <Boolean> Calculate facet counts globally or not.
Returns
returns this so that calls can be chained.

 interval

 Object interval ( timeInterval )
Sets the bucket interval used to calculate the distribution.

Parameters
timeInterval <String> The bucket interval. Valid values are year, month, week, day, hour, and minute.
Returns
returns this so that calls can be chained.

 keyField

 Object keyField ( fieldName )
Allows you to specify a different key field to be used to group intervals.

Parameters
fieldName <String> The name of the field to be used.
Returns
returns this so that calls can be chained.

 lang

 Object lang ( language )
The script language being used. Currently supported values are javascript, groovy, and mvel.

Parameters
language <String> The language of the script.
Returns
returns this so that calls can be chained.

 mode

 Object mode ( m )

Sets the mode the facet will use.

collector
post

Parameters
m <String> The mode: collector or post.
Returns
returns this so that calls can be chained.

 nested

 Object nested ( path )

Sets the path to the nested document if faceting against a nested field.


Parameters
path <String> The nested path
Returns
returns this so that calls can be chained.

 order

 Object order ( o )

Sets the type of ordering that will be performed on the date buckets. Valid values are:

time - the default, sort by the buckets start time in milliseconds.
count - sort by the number of items in the bucket
total - sort by the sum/total of the items in the bucket

Parameters
o <String> The ordering method: time, count, or total.
Returns
returns this so that calls can be chained.

 params

 Object params ( p )
Sets parameters that will be applied to the script. Overwrites any existing params.

Parameters
p <Object> An object where the keys are the parameter name and values are the parameter value.
Returns
returns this so that calls can be chained.

 postOffset

 Object postOffset ( offset )
Set's a specific post-rounding offset. Format is 1d, 1h, etc.

Parameters
offset <String> The offset as a string (1d, 1h, etc)
Returns
returns this so that calls can be chained.

 postZone

 Object postZone ( tz )

By default, time values are stored in UTC format.

This method allows users to set a time zone value that is then used to compute intervals after rounding on the interval value. The value is an offset from UTC. The tz offset value is simply added to the resulting bucket's date value.

For example, to use EST you would set the value to -5.


Parameters
tz <Integer> An offset value from UTC.
Returns
returns this so that calls can be chained.

 preOffset

 Object preOffset ( offset )
Set's a specific pre-rounding offset. Format is 1d, 1h, etc.

Parameters
offset <String> The offset as a string (1d, 1h, etc)
Returns
returns this so that calls can be chained.

 preZone

 Object preZone ( tz )

By default, time values are stored in UTC format.

This method allows users to set a time zone value that is then used to compute intervals before rounding on the interval value. The value is an offset from UTC.

For example, to use EST you would set the value to -5.


Parameters
tz <Integer> An offset value from UTC.
Returns
returns this so that calls can be chained.

 preZoneAdjustLargeInterval

 Object preZoneAdjustLargeInterval ( trueFalse )

Enables large date interval conversions (day and up).

Set to true to enable and then set the interval to an interval greater than a day.


Parameters
trueFalse <Boolean> A valid boolean value.
Returns
returns this so that calls can be chained.

 scope

 Object scope ( scope )

Computes values across the the specified scope


Deprecated
since elasticsearch 0.90
Parameters
scope <String> The scope name to calculate facet counts with.
Returns
returns this so that calls can be chained.

 timeZone

 Object timeZone ( tz )

By default, time values are stored in UTC format.

This method allows users to set a time zone value that is then used to compute intervals before rounding on the interval value. Equalivent to preZone. Use preZone if possible. The value is an offset from UTC.

For example, to use EST you would set the value to -5.


Parameters
tz <Integer> An offset value from UTC.
Returns
returns this so that calls can be chained.

 toJSON

 String toJSON ( )

Retrieves the internal facet object. This is typically used by internal API functions so use with caution.


Returns
returns this object's internal facet property.

 valueField

 Object valueField ( fieldName )
Allows you to specify a different value field to aggrerate over.

Parameters
fieldName <String> The name of the field to be used.
Returns
returns this so that calls can be chained.

 valueScript

 Object valueScript ( scriptCode )
Allows you modify the value field using a script. The modified value is then used to compute the statistical data.

Parameters
scriptCode <String> A valid script string to execute.
Returns
returns this so that calls can be chained.

Request

Queries

Filters

Aggregations

Facets

Suggesters

Geo