Decoding the Solr Query Parameters
This section details the query parameters that are sent through to the Solr server, what they mean and the Panl properties which may affect the implementation.
The default logging configuration included with the Panl release package outputs debug logging for all queries sent to the Solr server. (See the sections on Logging and Setting the Logging Configuration and Levels for more information on how to set the levels). Examples used in this chapter all come from the debug logging
With time, practice, and curiosity, decoding the Solr query parameters becomes straight-forward, and is a good way to ensure that the Panl URL is passing through the correct Solr query parameters.
A Solr query string will look like the following:
q=*:*&q.op=OR&facet.limit=100&facet.mincount=1&rows=0&facet.field=lead_size_indicator&face
t.field=colours&facet.field=brand&facet.field=mechanism_type&facet.field=hardness_indicato
r&facet.field=in_built_sharpener&facet.field=disassemble&facet.field=category&facet.field=
lead_length&facet.field=in_built_eraser&facet.field=grip_shape&facet.field=weight&facet=tr
ue&fq=colours:"Black"&fq=colours:"Silver"&fq=colours:"Blue"&fq=weight:[15+TO+42]&stats.fie
ld=weight&stats=true&sort=brand+asc&start=0
This query string is made up of key/value pairs, delimited by the standard ampersand '&' character. Below is a list of query parameter keys and how they are interpreted by the Solr server.
facet=
This parameter tells the Solr server to return faceted results, this is ALWAYS set to true. This cannot be changed and is automatically added as soon as a facet.field parameter is added to the Solr query.
facet.field=
This parameter tells the Solr server to facet on the particular Solr field. There will be multiple facet.field parameters passed to the Solr server, one for each facet defined in the <panl_collection_url>.panl.properties.
For the default mechanical pencils collection Solr query:
facet.field=lead_size_indicator&facet.field=colours&facet.field=brand&facet.field=mechanis
m_type&facet.field=hardness_indicator&facet.field=in_built_sharpener&facet.field=disassemb
le&facet.field=category&facet.field=lead_length&facet.field=in_built_eraser&facet.field=gr
ip_shape&facet.field=weight
Which is generated from the panl.lpse.order property in the <panl_collection_url>.panl.properties file. For the mechanical pencils collection, this property is:
panl.lpse.order=z,b,N,m,W,G,C,L,D,h,I,Z,9,w,s,p,n,o,q
Where the following LPSE codes are not facets (they are operands and parameters):
- z - The passthrough parameter
- s - The sort operand
- p - The page number parameter
- n - The number of results parameter
- o - The query operand
- q - The query (keyword search) parameter
Which leaves the following LPSE codes:
- b - The brand facet - facet.field=brand
- N - The name facet - Note that this is not passed through in the above query as it is set as a hierarchical facet and will only be sent through when the brand facet above is selected.
- m - The mechanism_type facet - facet.field=mechanism_type
- W - The colours facet - facet.field=colours
- G - The grip_shape facet - facet.field=grip_shape
- C - The category facet - facet.field=category
- L - The lead_length facet - facet.field=lead_length
- D - The disassemble facet - facet.field=disassemble
- h - The hardness_indicator facet - facet.field=hardness_indicator
- I - The in_built_eraser facet - facet.field=in_built_eraser
- Z - The lead_size_indicator facet - facet.field=lead_size_indicator
- 9 - The in_built_sharpener facet - facet.field=in_built_sharpener
- w - The weight facet - facet.field=weight
facet.limit=
This parameter tells the solr Server the maximum number of facet values to be returned per facet. By default this is set to 100 in the <panl_collection_url>.panl.properties file:
solr.facet.limit=100
If this is set to -1, then all facets values will be returned. This value is also used by the Panl More Facets request handler when requesting more values for a specific facet.
For example, for the default mechanical pencils collection, it is set to 100 and as there are no facets with more than 100 values, all facets will be returned. The landing page (http://localhost:8181/panl-results-viewer/mechanical-pencils/empty) will return 23 facets:
The Solr query parameter
facet.limit=100
Returns the following brand facet values and counts
- Manufactured by Koh-i-Noor Company (11)
- Manufactured by Caran d'Ache Company (4)
- Manufactured by Faber-Castell Company (4)
- Manufactured by Pacific Arc Company (4)
- Manufactured by Alvin Company (3)
- Manufactured by Kaweco Company (3)
- Manufactured by Rotring Company (3)
- Manufactured by Hightide Penco Company (2)
- Manufactured by Kita-Boshi Company (2)
- Manufactured by Kuelox Company (2)
- Manufactured by Mitsubishi Company (2)
- Manufactured by OHTO Company (2)
- Manufactured by Scrikks Company (2)
- Manufactured by Staedtler Company (2)
- Manufactured by BIC Company (1)
- Manufactured by DEDEDEPRAISE Company (1)
- Manufactured by Ito-Ya Company (1)
- Manufactured by Mr. Pen Company (1)
- Manufactured by Muji Company (1)
- Manufactured by Redcircle Company (1)
- Manufactured by Unbranded Company (1)
- Manufactured by WSD Company (1)
- Manufactured by YStudio Company (1)
If the solr.facet.limit was set to 10 (i.e. solr.facet.limit=10) then only the first 10 facets will be returned:
The Solr query of
facet.limit=10
Will return the following brand facet values and counts:
- Manufactured by Koh-i-Noor Company (11)
- Manufactured by Caran d'Ache Company (4)
- Manufactured by Faber-Castell Company (4)
- Manufactured by Pacific Arc Company (4)
- Manufactured by Alvin Company (3)
- Manufactured by Kaweco Company (3)
- Manufactured by Rotring Company (3)
- Manufactured by Hightide Penco Company (2)
- Manufactured by Kita-Boshi Company (2)
- Manufactured by Kuelox Company (2)
facet.mincount=
For each facet value, this is the minimum that the value must be to be included in the returned results. By default this is set to 1, however it can be set in the <panl_collection_url>.properties file with the property key solr.facet.min.count.
This property is configured in two ways:
1. Default facet mincount
The Solr query parameter is set to the value of the solr.facet.min.count property and is passed through to Solr as
facet.mincount=1
For example, the following facet (Maximum Allowed Lead Length (L) [REGULAR]), returns values and counts of:
- 130mm (26)
- 120mm (23)
- 90mm (6)
Note: the 90mm value has 6 mechanical pencils within the results. If the solr.facet.min.count property was set to 10 (i.e. solr.facet.min.count=10)
The returned facet values and counts become:
- 130mm (26)
- 120mm (23)
The Solr query parameter is passed through to Solr as
facet.mincount=10
2. OR Facets mincount
If the Panl field is configured to be an OR facet, then the specific facet mincount is set (see the f.<solr_field>.facet.mincount Solr query parameter below). This does not affect the default facet minimum count.
For example, with OR Facets (e.g. the brand facet in the mechanical pencils collection) , the default minimum count remains, however an additional Solr query parameter is sent through as well:
facet.mincount=1&f.brand.facet.mincount=0
f.<solr_field>.facet.mincount=
When a Panl field is configured as an OR Facet, then the minimum count is always set to 0 (zero). This allows the user to select other facets and increase the number of returned results.
This only occurs when an OR Facet is defined in the Panl configuration file AND one of the OR facets has been selected. For each OR facet that has at least one value selected, the Solr parameter will be passed through to the Solr server.
In the default mechanical pencils OR Panl Results Viewer request:
http://localhost:8181/panl-results-viewer/mechanical-pencils-or/empty
Only the facet.mincount parameter is sent through
facet.mincount=1
Once one of the brand (which is defined as an OR Separator) facet values is selected:
facet.mincount=1&f.brand.facet.mincount=0
f.<solr_field_name>.facet.sort=
This only occurs if the facet is configured to sort the returned facet by index, rather than the default count. This will only ever be set to index if it is not configured to the default of count. I.e. you will never see a Solr query parameter key value pair of:
f.<solr_field_name>.facet.sort=count
fq=
This is the facet query that is applied to a specific facet name, the format for the Solr query parameter standard format is:
fq=<solr_field_name>:"<facet_value>"
Where
- <solr_field_name> is the name of the Solr field, and
- <facet_value> is the selected facet value stripped of prefixes, suffixes, and BOOLEAN values replaced.
This occurs for all facets, irrespective of the facet type - Panl will automatically create this query depending on the facet type.
REGULAR Facets
REGULAR facets pass through the query as per the standard format:
fq=<solr_field_name>:"<facet_value>"
http://localhost:8181/panl-results-viewer/mechanical-pencils/brandandname/Cylindrical Grip/G/
Note how the suffix has been removed by the Panl server and this is the Solr query:
fq=grip_shape:"Cylindrical"
REGULAR (multivalued) Facets
This is the same whether there is a multi-value separator configured or not.
With the first colour facet selected of "Black":
http://localhost:8181/panl-results-viewer/mechanical-pencils-multi-separator/empty/Colours:Black/W/
The Solr query is in the standard format:
fq=colours:"Black"
When adding a second colour facet of "Blue"
The Solr query is the two facet queries:
fq=colours:"Black"&fq=colours:"Blue"
BOOLEAN Facets
BOOLEAN Facets are the same as REGULAR facets, when a facet is
http://localhost:8181/panl-results-viewer/mechanical-pencils/empty/able to be disassembled/D/
The Panl server will translate the incoming value and the Solr query simply becomes a true or false value:
fq=disassemble:"true"
RANGE Facets
RANGE facets work differently and pass through the range
Note how the prefix and suffix are removed by the panl server to make the Solr query:
fq=weight:[17+TO+42]
When the panl.range.min.wildcard.<lpse_code> property is set to true (i.e. if the value is the minimum value as set by the panl.range.min.<lpse_code> property), then the value becomes an asterisk.
For the following properties:
panl.range.min.w=10
panl.range.max.w=50
panl.range.min.wildcard.w=true
panl.range.max.wildcard.w=true
Then setting the range from 10 to 50 will generate the wildcard (i.e. asterisk) inclusion and the Solr query is:
fq=weight:[*+TO+*]
If the min and max wildcard properties are set to false as in the following properties:
panl.range.min.w=10
panl.range.max.w=50
panl.range.min.wildcard.w=false
panl.range.max.wildcard.w=false
Then setting the range will only set the actual values and the Solr query becomes:
fq=weight:[10+TO+50]
OR Facets
This is the same whether there is a multi-value separator configured or not.
For the default selection of one OR Facet:
http://localhost:8181/panl-results-viewer/mechanical-pencils-or/empty/Manufactured by Muji/b/
The Solr query is the same as a REGULAR Facet:
fq=brand:"Muji"
When a second OR Facet is selected
The Solr query now changes to
fq=brand:("Muji"+OR+"Alvin")
DATE RANGE Facets
DATE Range facets have a specific query parameter value format
http://localhost:8181/panl-results-viewer/simple-date/empty/next 30 days/S/
Which is translated to the Solr query from NOW (as in the current server time).
fq=solr_date:[NOW+TO+NOW%2B30DAYS]
hl=
This will only be set to on if highlighting has been enabled in the Panl configuration, and will pass through the value of 'on', i.e.:
hl=on
This parameter will always be passed through with the hl=* Solr query parameter below.
hl.fl=
This is the field list that highlighting should be done on, this is always set to * which is to highlight all fields.
hl.fl=*
This parameter will always be passed through with the hl=on Solr query parameter above.
q=
This is the Solr query parameter - i.e. the keyword search parameter
The q Solr query parameter, if not set, this defaults to *.* which means to search for all words in all fields.
If there is a search query - e.g. hexagonal pencils, then this parameter will have the value of the URL encoded search query (this is also with the default query operand set to OR (i.e. solr.default.query.operand=-):
q="hexagonal"+OR+"pencils"
If there is a search query - e.g. "hexagonal pencils", including the double quotation marks, then this parameter will have the value of the URL encoded search query:
q="hexagonal pencils"
Note that unlike normal Solr installations, Panl does not support keyword boosting unless Specific Solr Field Searches are enabled, in which case this query parameter will include those specific fields in the query, for example on the Bookstore instance, searching for Mary sequel in the title, author, and description attributes of the document would generate the Solr query of:
q=title:"Mary"+OR+title:"sequel"+OR+text_author:"Mary"^4+OR+text_author:"sequel"^4+OR+description:"Mary"+OR+description:"sequel"
Note the text_author:"Mary"^4+OR+text_author:"sequel"^4, which has a query boost of 4 on the text_author Solr field.
q.op=
This is the query operand for searching between text indexes on the Solr server.
It is either one of the following
- q.op=OR - one of the keywords must be in the search fields, or
- q.op=AND - all of the keywords must be in the search fields.
This book uses copyfield definitions in the Solr managed schema to place all text into a single searchable field, so this operand will have an effect on the default search between individual keywords. For example
With q.op=OR
searching for the phrase 'hexagonal pencil' (without quotation marks) will search for the keyword hexagonal OR the keyword pencil (which will return 54 results), the Solr query is q="hexagonal"+"pencil"&q.op=OR
With q.op=AND
searching for the phrase 'hexagonal pencil' (without quotation marks) will search for the keyword hexagonal AND the keyword pencil (which will return 45 results), the solr query is q="hexagonal"+"pencil"&q.op=AND
If you are using an eDisMax type search then this will be the default query operation between fields if not set.
rows=
This is the number of rows (results/documents) that will be returned by the Solr server.
For 20 results per request
rows=20
Or 10 results per request
rows=10
sort=
The parameter that defines the fields that the sorting is to be performed on, the order in which the sorting should be performed, and whether it should be ascending, or descending.
One search order of the brand in ascending alphabetical order
sort=brand+asc
Two search orders, first the brand in ascending alphabetical order, then the name in descending alphabetical order.
sort=brand+asc,name+desc
start=
This is the offset of the results to return at starting at 0 (zero).
This works in conjunction with the rows= parameter above to determine the start result for returning a document.
For the first page of results, the start parameter will ALWAYS be 0 (zero).
start=0
For the second page with 10 results per page (i.e. rows-10), the start parameter will be 10.
start=10
The formula for the start parameter = (Page Number - 1) multiplied by (Number of Results Per Page)
stats=
Turn on statistical reporting for the Solr fields that are requested by the stats.field Solr query parameter key.
The stats Solr query parameter is only passed through with range facets and is used to generate the dynamic minimum and maximum values in the JSON response object returned by Panl.
This will be set to true if ANY of the facets are set to be a range facet - i.e.
panl.range.facet.<lpse_code>=true
The Solr query is
stats=true
Note that this Solr query parameter works in conjunction with the stats.field query parameter.
stats.field=
Return statistics for the specified fields.
One field is sent through for every Panl field that is configured to be a RANGE Facet, this will return information that will enable dynamic minimum and maximum range values.
stats.field=relative_weight&stats.field=weight
~ ~ ~ * ~ ~ ~