Mailing-List: contact solr-commits-help@lucene.apache.org; run by ezmlm
Precedence: bulk
Reply-To: solr-dev@lucene.apache.org
MIME-Version: 1.0
Content-Type: text/plain; charset="utf-8"
Content-Transfer-Encoding: quoted-printable
From: Apache Wiki <wikidiffs@apache.org>
To: Apache Wiki <wikidiffs@apache.org>
Date: Mon, 29 Aug 2011 16:14:19 -0000
Message-ID: <20110829161419.36730.26623@eos.apache.org>
Subject: 
 =?utf-8?q?=5BSolr_Wiki=5D_Update_of_=22VariableRangeGaps=22_by_JanHoydahl?=
Auto-Submitted: auto-generated

Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Solr Wiki" for chan=
ge notification.

The "VariableRangeGaps" page has been changed by JanHoydahl:
http://wiki.apache.org/solr/VariableRangeGaps

Comment:
Sample documentation for range facet spec

New page:
=3D Brief =3D
The Jira issue [[https://issues.apache.org/jira/browse/SOLR-2366|SOLR-2366]=
] discusses how to implement variable gap sizes into range faceting. This i=
s useful for things like prices, date ranges etc. This page is an sandbox f=
or preparing the WIKI documentation for Range Facet, until the feature is r=
eleased.

I (janhoy) propose to leave the old facet.range.start/end/gap/ syntax as is=
 for backward compat, and introduce a new simpler param facet.range.spec fo=
r the new advanced range spec feature. See below how this would look in WIK=
I:

=3D=3D Facet by Range =3D=3D

<!> [[Solr3.1]]

As a generalization of the Date faceting described above, one can use the R=
ange Faceting feature on any date field or any numeric field that supports =
range queries.  This is particularly useful for the cases in the past where=
 one might stitch together a series of range queries (as facet by query) fo=
r things like prices, etc.

=3D=3D=3D facet.range =3D=3D=3D

This param indicates what field to create range facets for.  This param all=
ows you to specify names of fields  which should be treated as range facets.

Example: {{{facet.range=3Dprice&facet.range=3Dage}}}

=3D=3D=3D facet.range.start =3D=3D=3D

The lower bound of the ranges.

This parameter can be specified on a per field basis.

Example: {{{f.price.facet.range.start=3D0.0&f.age.facet.range.start=3D10}}}

=3D=3D=3D facet.range.end =3D=3D=3D

The upper bound of the ranges.

This parameter can be specified on a per field basis.

Example: {{{f.price.facet.range.end=3D1000.0&f.age.facet.range.start=3D99}}}

=3D=3D=3D facet.range.gap =3D=3D=3D

The size of each range expressed as a value to be added to the lower bound.=
  For date fields, this should be expressed using the [[http://lucene.apach=
e.org/solr/api/org/apache/solr/util/DateMathParser.html|DateMathParser]] sy=
ntax.  (ie: {{{facet.range.gap=3D%2B1DAY}}} ... '+1DAY')

This parameter can be specified on a per field basis.

Example: {{{f.price.facet.range.gap=3D100&f.age.facet.range.gap=3D10}}}

=3D=3D=3D facet.range.hardend =3D=3D=3D

A Boolean parameter instructing Solr what to do in the event that {{{facet.=
range.gap}}} does not divide evenly between {{{facet.range.start}}} and {{{=
facet.range.end}}}.  If this is true, the last range constraint will have a=
n upper bound of {{{facet.range.end}}}; if false, the last range will have =
the smallest possible upper bound greater then {{{facet.range.end}}} such t=
hat the range is exactly {{{facet.range.gap}}} wide.

The default is false.

This parameter can be specified on a per field basis.

=3D=3D=3D facet.range.other =3D=3D=3D

This param indicates that in addition to the counts for each range constrai=
nt between {{{facet.range.start}}} and {{{facet.range.end}}}, counts should=
 also be computed for...

   * {{{before}}} all records with field values lower then lower bound of t=
he first range
   * {{{after}}} all records with field values greater then the upper bound=
 of the last range
   * {{{between}}} all records with field values between the start and end =
bounds of all ranges
   * {{{none}}} compute none of this information
   * {{{all}}} shortcut for {{{before}}}, {{{between}}}, and {{{after}}}

This parameter can be specified on a per field basis.

In addition to the {{{all}}} option, this parameter can be specified multip=
le times to indicate multiple choices -- but {{{none}}} will override all o=
ther options.


=3D=3D=3D facet.range.include =3D=3D=3D

By default, the ranges used to compute range faceting between facet.range.s=
tart and facet.range.end are inclusive of their lower bounds and exclusive =
of the upper bounds. The "before" range is exclusive and the "after" range =
is inclusive. This default, equivalent to {{{lower}}} below, will ''not'' r=
esult in double counting at the boundaries. This behavior can be modified b=
y the {{{facet.range.include}}} param, which can be any combination of the =
following options...

   * {{{lower}}} =3D all gap based ranges include their lower bound
   * {{{upper}}} =3D all gap based ranges include their upper bound
   * {{{edge}}} =3D the first and last gap ranges include their edge bounds=
 (ie: lower for the first one, upper for the last one) even if the correspo=
nding upper/lower option is not specified
   * {{{outer}}} =3D the "before" and "after" ranges will be inclusive of t=
heir bounds, even if the first or last ranges already include those boundar=
ies.
   * {{{all}}} =3D shorthand for lower, upper, edge, outer

This parameter can be specified on a per field basis.

This parameter can be specified multiple times to indicate multiple choices.

If you want to ensure you don't double-count, don't choose both lower & upp=
er, don't choose outer, and don't choose all.

=3D=3D=3D facet.range.spec =3D=3D=3D
<!> [[Solr3.4]]

Often times you want un-equally spaced facet gaps. A typical example is pri=
ces, e.g. '''0-10$''', '''10-50$''', '''50-100$''', '''100-250$''', '''250-=
500$'''. Another common example is date ranges, where we also need overlapp=
ing ranges such as '''last day''', '''last week''', '''last month'''. The f=
acet.range.spec parameter lets you configure such complex ranges with one p=
arameter. The syntax of this parameter is as follows:

{{{facet.range.spec=3D<lower-bound>,<gap>[,<gap>...,<gap>n],<upper-bound>}}}
<<BR>>
where
<<BR>>
{{{<lower-bound>/<upper-bound>}}} is either a number or a date or {{{*}}} (=
asterisk) for MIN/MAX
<<BR>>
{{{<gap>}}} is either an absolute number or date, e.g. {{{50}}} or {{{2011-=
01-01T00:00:00Z}}}, a relative gap size, e.g. {{{+40}}} or {{{+1DAY}}} or e=
ven a complete range such as {{{10..50}}} or {{{2011-01-01..NOW}}}.

=3D=3D=3D=3D Examples: =3D=3D=3D=3D
{{{facet.range.spec=3D*,10,50,100,250,*}}} - gives 5 ranges: MIN-10, 10-50,=
 50-100, 100-250, 250->MAX
<<BR>>
{{{facet.range.spec=3D*,10,+40,+50,250,*}}} - gives exactly the same ranges=
, using relative gap size
<<BR>>
{{{facet.range.spec=3DNOW-1DAY..NOW, NOW-1WEEK..NOW, NOW-1MONTH..NOW}}} - g=
ives three overlapping date ranges for last day, week and month

This parameter can be combined with facet.range.include, but is mutually ex=
clusive to facet.range.gap, facet.range.begin, facet.range.end and facet.ra=
nge.other