Add DateRangeField example to Ref Guide (#2330)

---------

Co-authored-by: Andrey Bozhko <[email protected]>
Co-authored-by: Eric Pugh <[email protected]>

solr/core/src/test/org/apache/solr/request/macro/TestMacroExpander.java

@@ -37,8 +37,7 @@ public void testExamples() {
       me = new MacroExpander(testParams, failOnMissingParams);
     }
 
-    // default examples: https://cwiki.apache.org/confluence/display/solr/Parameter+Substitution
-    // and http://yonik.com/solr-query-parameter-substitution/
+    // default examples: https://yonik.com/solr-query-parameter-substitution/
 
     // using params
     String[] lowParams = {"50"};

solr/solr-ref-guide/modules/indexing-guide/pages/date-formatting-math.adoc

@@ -217,4 +217,117 @@ Unlike most local params, `op` is actually _not_ defined by any query parser (`f
 In the above example, it would find documents with indexed ranges that _contain_ (or equals) the range 2013 thru 2018.
 Multi-valued overlapping indexed ranges in a document are effectively coalesced.
 
-For a DateRangeField example use-case, see https://cwiki.apache.org/confluence/display/solr/DateRangeField[Solr's community wiki].
+== An Example Use Case
+
+Suppose we want to find all restaurants that are open within a certain time window.
+Let's add a date range field to the schema.xml, so that we could index the information about the restaurant opening hours:
+
+[source,xml]
+----
+<field name="opening_hours" type="date_range" indexed="true" stored="true" multiValued="true"/>
+<fieldType name="date_range" class="solr.DateRangeField"/>
+----
+
+Next, we will add two restaurants to the index:
+
+====
+[.tab-label]*JSON*
+[source,json]
+----
+[{ "id": "r01",
+   "opening_hours": [ "[2016-02-01T03:00Z TO 2016-02-01T15:00Z]",
+                      "[2016-02-02T03:00Z TO 2016-02-02T15:00Z]",
+                      "[2016-02-03T03:00Z TO 2016-02-03T15:00Z]",
+                      "[2016-02-04T03:00Z TO 2016-02-04T15:00Z]",
+                      "[2016-02-05T03:00Z TO 2016-02-05T16:00Z]",
+                      "[2016-02-06T03:00Z TO 2016-02-06T16:00Z]",
+                      "[2016-02-07T03:00Z TO 2016-02-07T15:00Z]" ]},
+ { "id": "r02",
+   "opening_hours": [ "[2016-02-06T10:00Z TO 2016-02-06T12:00Z]",
+                      "[2016-02-06T14:00Z TO 2016-02-06T16:00Z]",
+                      "[2016-02-07T12:00Z TO 2016-02-07T16:00Z]" ]}
+]
+----
+====
+
+Each restaurant can have multiple opening hours in a single day,
+and the opening hours can be different on different days.
+
+NOTE: The date ranges in `opening_hours` should be converted to UTC before indexing.
+
+Now, to find the restaurants that are open during a specific time window,
+we can use a filter query:
+
+[source,text]
+----
+fq={!field f=opening_hours op=Contains}[2016-02-02T14:50 TO 2016-02-02T15:00]
+----
+
+[source,json]
+----
+{
+  "responseHeader":{
+    "status":0,
+    "QTime":29,
+    "params":{
+      "q":"id:*",
+      "fl":"id",
+      "fq":"{!field f=opening_hours op=Contains}[2016-02-02T14:50 TO 2016-02-02T15:00]",
+      "wt":"json"}},
+  "response":{"numFound":1,"start":0,"numFoundExact":true,"docs":[
+      {
+        "id":"r01"}]
+  }}
+----
+
+And if we need to get opening hour ranges, we can use a xref:query-guide:faceting.adoc[facet query]:
+
+[source,text]
+----
+q=id:*
+rows=0
+facet=true
+facet.range=opening_hours
+f.opening_hours.facet.range.start=NOW
+f.opening_hours.facet.range.end=NOW+6HOUR
+f.opening_hours.facet.range.gap=+1HOUR
+----
+
+[source,json]
+----
+{
+  "responseHeader":{
+    "status":0,
+    "QTime":16,
+    "params":{
+      "q":"id:*",
+      "facet":"true",
+      "facet.range":"opening_hours",
+      "f.opening_hours.facet.range.start":"NOW",
+      "f.opening_hours.facet.range.gap":"+1HOUR",
+      "f.opening_hours.facet.range.end":"NOW+6HOUR",
+      "rows":"0",
+      "wt":"json"}},
+  "response":{"numFound":2,"start":0,"numFoundExact":true,"docs":[]
+  },
+  "facet_counts":{
+    "facet_queries":{},
+    "facet_fields":{},
+    "facet_ranges":{
+      "opening_hours":{
+        "counts":[
+          "2016-02-06T11:01:00Z",2,
+          "2016-02-06T12:01:00Z",1,
+          "2016-02-06T13:01:00Z",2,
+          "2016-02-06T14:01:00Z",2,
+          "2016-02-06T15:01:00Z",2,
+          "2016-02-06T16:01:00Z",0],
+        "gap":"+1HOUR",
+        "start":"2016-02-06T11:01:00Z",
+        "end":"2016-02-06T17:01:00Z"}},
+    "facet_intervals":{},
+    "facet_heatmaps":{}}}
+----
+
+The query results show how many restaurants will be open in the next 6 hours,
+with a breakdown for each of the six consecutive one-hour intervals.

solr/solr-ref-guide/modules/query-guide/pages/learning-to-rank.adoc

@@ -811,8 +811,8 @@ Related links:
 * {solr-javadocs}/modules/ltr/org/apache/solr/ltr/feature/Feature.html[Feature javadocs]
 * {solr-javadocs}/modules/ltr/org/apache/solr/ltr/norm/Normalizer.html[Normalizer javadocs]
 * {solr-javadocs}/modules/ltr/org/apache/solr/ltr/interleaving/Interleaving.html[Interleaving javadocs]
-* https://cwiki.apache.org/confluence/display/solr/HowToContribute
-* https://cwiki.apache.org/confluence/display/LUCENE/HowToContribute
+* https://github.com/apache/solr/blob/main/CONTRIBUTING.md[Contributing to Solr]
+* https://github.com/apache/lucene/blob/main/CONTRIBUTING.md[Contributing to Lucene]
 
 == LTR Examples
 

solr/solr-ref-guide/modules/query-guide/pages/streaming-expressions.adoc

@@ -125,7 +125,7 @@ Instead, they operate on and return numbers, vectors, matrices and mathematical
 The documentation will show how to combine streaming expressions and math
 expressions.
 
-The math expressions user guide is available in <<>>
+The math expressions user guide is available in xref:math-expressions.adoc[].
 
 From a language standpoint math expressions are referred to as *stream evaluators*.