From 602ba18e7c3874bcbd13e364d91793f36d195545 Mon Sep 17 00:00:00 2001 From: Andrey Bozhko Date: Sat, 2 Mar 2024 10:23:57 -0600 Subject: [PATCH] Add DateRangeField example to Ref Guide (#2330) --------- Co-authored-by: Andrey Bozhko Co-authored-by: Eric Pugh --- .../solr/request/macro/TestMacroExpander.java | 3 +- .../pages/date-formatting-math.adoc | 115 +++++++++++++++++- .../query-guide/pages/learning-to-rank.adoc | 4 +- .../pages/streaming-expressions.adoc | 2 +- 4 files changed, 118 insertions(+), 6 deletions(-) diff --git a/solr/core/src/test/org/apache/solr/request/macro/TestMacroExpander.java b/solr/core/src/test/org/apache/solr/request/macro/TestMacroExpander.java index a02c400cce8..b17d99f1b91 100644 --- a/solr/core/src/test/org/apache/solr/request/macro/TestMacroExpander.java +++ b/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"}; diff --git a/solr/solr-ref-guide/modules/indexing-guide/pages/date-formatting-math.adoc b/solr/solr-ref-guide/modules/indexing-guide/pages/date-formatting-math.adoc index f8b2c1c9317..596b098d9cd 100644 --- a/solr/solr-ref-guide/modules/indexing-guide/pages/date-formatting-math.adoc +++ b/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] +---- + + +---- + +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. diff --git a/solr/solr-ref-guide/modules/query-guide/pages/learning-to-rank.adoc b/solr/solr-ref-guide/modules/query-guide/pages/learning-to-rank.adoc index 1dc37fbdae9..411b6dfb88f 100644 --- a/solr/solr-ref-guide/modules/query-guide/pages/learning-to-rank.adoc +++ b/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 diff --git a/solr/solr-ref-guide/modules/query-guide/pages/streaming-expressions.adoc b/solr/solr-ref-guide/modules/query-guide/pages/streaming-expressions.adoc index 502e41fa7c5..a9a6bf564aa 100644 --- a/solr/solr-ref-guide/modules/query-guide/pages/streaming-expressions.adoc +++ b/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*.