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: Fri, 09 Sep 2011 12:46:11 -0000
Message-ID: <20110909124611.27464.50446@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?action=3Ddiff&rev1=3D3&rev2=
=3D4

+ <<TableOfContents(2)>>
- =3D Brief =3D
+ =3D=3D Brief =3D=3D
  The Jira issue [[https://issues.apache.org/jira/browse/SOLR-2366|SOLR-236=
6]] discusses how to implement variable gap sizes into range faceting. This=
 is useful for things like prices, date ranges etc. This page is an sandbox=
 for preparing the WIKI documentation for Range Facet, until the feature is=
 released.
  =

  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 =
for the new advanced range spec feature. See below how this would look in W=
IKI:
  =

- =3D=3D Facet by Range =3D=3D
+ =3D=3D Facet by Range - second take by janhoy =3D=3D
  =

  <!> [[Solr3.1]]
  =

@@ -85, +86 @@

  =

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

+ {{{facet.range.spec=3D[<start>,]<gap>[,<gap>[,<gap>[,<gap>]]][,<end>]}}}
+ <<BR>>
+ where
+  * {{{<start>}}} is of syntax N.. where N is either a number or a date or=
 {{{*}}} (asterisk) for MIN
+  * {{{<end>}}} is of syntax ..M where M is either a number or a date or {=
{{*}}} (asterisk) for MAX
+  * {{{<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}}}
+    * an explicit range, e.g. {{{0..10}}} or {{{100..*}}} or {{{2011-01-01=
..NOW}}}. '''NOTE''' that these ranges may be '''overlapping'''
+ =

+ Some constraints:
+  * Relative {{{<gap>s}}} repeat until next absolute number/date. There ''=
'must''' be an absolute gap value following a relative one
+  * If you want to specify explicit ranges, then '''all''' <gap>s must be =
in this format, and <start>/<end> are not allowed. Any global start/end val=
ues will be disregarded in this mode.
+ =

+ =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=3D0..,+10,50,250,..500}}} - gives ranges: 0-10, 10-20=
, 20-30, 30-40, 40-50, 20-250, 250-MAX
+ <<BR>>
+ {{{facet.range.spec=3D0..,+10,50,250,500&facet.range.end=3D*}}} - gives t=
he exact same result as previous example, but the end is specified as a sep=
arate query parameter
+ <<BR>>
+ {{{facet.range.spec=3D0..,10,50,+50,+100,500,..*}}} - gives ranges: 0-10,=
 10-50, 50-100, 100-200, 200-300, 300-400, 400-500, 500-MAX
+ <<BR>>
+ {{{facet.range.spec=3DNOW-1DAY..NOW, NOW-1WEEK..NOW, NOW-1MONTH..NOW}}} -=
 gives three overlapping date ranges for last day, week and month. '''Any s=
tart/end will be disregarded'''
+ =

+ This parameter can be specified on a per field basis.
+ =

+ Example: {{{f.price.facet.range.spec=3D*..,10,50,100,250,..*}}} to config=
ure the range spec for the price field
+ =

+ This parameter is mutually exclusive to facet.range.gap
+ =

+ =

+ =

+ =3D=3D Facet by Range - first take by janhoy =3D=3D
+ =

+ <!> [[Solr3.1]]
+ =

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

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

+ This param indicates what field to create range facets for.  This param a=
llows you to specify names of fields  which should be treated as range face=
ts.
+ =

+ 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 boun=
d.  For date fields, this should be expressed using the [[http://lucene.apa=
che.org/solr/api/org/apache/solr/util/DateMathParser.html|DateMathParser]] =
syntax.  (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 {{{face=
t.range.gap}}} does not divide evenly between {{{facet.range.start}}} and {=
{{facet.range.end}}}.  If this is true, the last range constraint will have=
 an upper bound of {{{facet.range.end}}}; if false, the last range will hav=
e the smallest possible upper bound greater then {{{facet.range.end}}} such=
 that 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 constr=
aint between {{{facet.range.start}}} and {{{facet.range.end}}}, counts shou=
ld also be computed for...
+ =

+    * {{{before}}} all records with field values lower then lower bound of=
 the first range
+    * {{{after}}} all records with field values greater then the upper bou=
nd of the last range
+    * {{{between}}} all records with field values between the start and en=
d 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 mult=
iple times to indicate multiple choices -- but {{{none}}} will override all=
 other options.
+ =

+ =

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

+ By default, the ranges used to compute range faceting between facet.range=
.start and facet.range.end are inclusive of their lower bounds and exclusiv=
e of the upper bounds. The "before" range is exclusive and the "after" rang=
e is inclusive. This default, equivalent to {{{lower}}} below, will ''not''=
 result in double counting at the boundaries. This behavior can be modified=
 by the {{{facet.range.include}}} param, which can be any combination of th=
e 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 boun=
ds (ie: lower for the first one, upper for the last one) even if the corres=
ponding upper/lower option is not specified
+    * {{{outer}}} =3D the "before" and "after" ranges will be inclusive of=
 their bounds, even if the first or last ranges already include those bound=
aries.
+    * {{{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 choic=
es.
+ =

+ If you want to ensure you don't double-count, don't choose both lower & u=
pper, 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 p=
rices, e.g. '''0-10$''', '''10-50$''', '''50-100$''', '''100-250$''', '''25=
0-500$'''. Another common example is date ranges, where we also need overla=
pping ranges such as '''last day''', '''last week''', '''last month'''. The=
 facet.range.spec parameter lets you configure such complex ranges with one=
 parameter. The syntax of this parameter is as follows:
+ =

  {{{facet.range.spec=3D<lower-bound>,<gap>[,<gap>...,<gap>n],<upper-bound>=
}}}
  <<BR>>
  where