Getting Started With Panl
A rather pleasing companion to the Apache® Solr® Faceted Search Engine
_____________
Author: Synapticloop - Version 1.2.0
This book will rapidly get you up and running with a fully featured, SEO friendly, keyword searchable, faceted search engine with an in-built, example search page to test it all out.
(Note: The most up-to-date version of this book can always be found here: https://github.com/synapticloop/panl/tree/main/src/book)
WHY?
Because...
/Caran+d'Ache/true/Black/bDW/
looks so much nicer than...
q=*:*&facet.mincount=1&rows=10&facet.field=lead_size_indicator&facet.fie
ld=grip_material&facet.field=colours&facet.field=nib_shape&facet.field=d
iameter&facet.field=cap_shape&facet.field=brand&facet.field=mechanism_ty
pe&facet.field=length&facet.field=hardness_indicator&facet.field=grip_ty
pe&facet.field=cap_material&facet.field=lead_grade_indicator&facet.field
=tubing_material&facet.field=in_built_sharpener&facet.field=disassemble&
facet.field=category&facet.field=body_shape&facet.field=clip_material&fa
cet.field=mechanism_material&facet.field=lead_length&facet.field=body_ma
terial&facet.field=in_built_eraser&facet.field=grip_shape&facet.field=re
lative_weight&facet.field=name&facet.field=nib_material&facet.field=weig
ht&facet.field=variants&facet=true&fq=brand:"Caran+d'Ache"&fq=disassembl
e:"true"&fq=colours:"Black"&q.op=AND
TL;DR
If you are looking to get the quickest start on understanding how a Panl server is configured and up and running, then...
- Start with the Quick Start - The 5 Steps section to get the Solr and Panl servers up and running.
- Look at the Panl Results Viewer
http://localhost:8181/panl-results-viewer/mechanical-pencils/default/ - Work through the A Walkthrough Example - The Book Store section to gain a deeper understanding of the configuration options.
- Use your existing dataset with Integrating An Existing Solr Schema
- Need help understanding the options? See the Panl Configuration section
QUICK TIP
If you need to restart the example Solr server installation - try these commands:
Windows:
Command(s) |
cd SOLR_INSTALL_DIRECTORY
bin\solr start -cloud -p 8983 -s "example\cloud\node1\solr" bin\solr start -cloud -p 7574 -s "example\cloud\node2\solr" -z localhost:9983 |
*NIX:
Command(s) |
cd SOLR_INSTALL_DIRECTORY
bin/solr start -cloud -p 8983 -s "example/cloud/node1/solr" bin/solr start -cloud -p 7574 -s "example/cloud/node2/solr" -z localhost:9983 |
|
Tip: Documentation for this book can also be read online, see https://synapticloop.github.io/panl/, or to download the latest copy of this book, see https://github.com/synapticloop/panl/releases/. |
Copyright Notice
The data used in this book is based on 2mm mechanical pencil data hand curated by the author. The data and associated Solr search results utilised in this book references manufacturers of writing instruments, specifically 2mm mechanical pencils. The manufacturer's name, the name of the pencil (and/or model number) is a trademark and/or is copyright of the manufacturer.
Additional datasets may have information that is copyright to the respective owners.
IMPORTANT: Whilst the project is released under the very liberal MIT licence, the sample mechanical data remains under the copyright of Synapticloop, and may not be used for commercial purposes.
~ ~ ~ * ~ ~ ~
TABLE OF CONTENTS
Welcome To Synapticloop Panl 14
Nomenclature Used Throughout This Book 16
How Many Facets Does Panl Support? 23
In-Built Web Apps (Viewer / Explainer / Single Search Page) 26
What is a LPSE (pronounced 'lapse') code? 36
The three types of LPSE codes 37
Is Synapticloop Panl For Me? 38
The Panl Directory Structure 40
Solr-Panl-8-x.x.x & Solr-Panl-7-x.x.x 43
Solr-Panl-6-x.x.x and earlier version 44
A Note On Running The Commands 46
Creating and Starting a Solr Cloud Instance 52
You will then need to re-create the collection, and re-index the data. 60
Restarting the Solr Panl tutorial process 60
Creating and Indexing the Data 64
panl.properties File Additions 65
Mechanical Pencils OR Facet 65
Creating and Indexing the Data 65
panl.properties File Additions 65
Mechanical Pencils More Facets 66
Creating and Indexing the Data 66
panl.properties File Additions 66
A Walkthrough Example - The Book Store 68
1. Understanding the Dataset 70
2. Configure the Solr Index 72
3. Configure the Panl Server 77
The Default Search Page Configuration 78
The Generated panl.properties File 80
The Generated <panl_collection_url>.panl.properties File 80
4. Determine the Web Pages to Render 96
The Iterative Implementation Process 97
Unsupported/Partially Supported Solr Field Types 99
A Brief Introduction To Solr (And Faceted Search) 108
Determining the Appropriate FieldType and Attributes 115
The Solr Configuration File 119
The <panl_collection_url>.panl.properties file 124
The panl.properties Configuration File 126
Configuring The SolrJ Connector 127
Setting The Solr Server URL(s) 128
Enabling The Panl Results Testing URLs 129
The Panl Results Explainer 131
The Panl Single Page Search 132
Setting HTTP Status Message Verbosity 133
Binding Solr collections to Panl URL paths 134
The <panl_collection_url>.panl.properties Configuration File 136
Parameter and Operand Definitions 137
panl.param.passthrough.canonical 141
panl.include.single.facets 143
panl.include.same.number.facets 143
solr.default.query.operand 145
Properties Available for Fields 147
Properties Available for Facets 149
Decoding the URL Without a Prefix or Suffix 155
Defining a Prefix and Suffix 156
Decoding the URL With a Prefix or Suffix 157
The Difference Between Multi-valued Facets and OR Facets 158
Suppressing Individual Facet Values 167
Visualising the Properties 168
Decoding the URL - Range facet with an infix 170
Decoding the URL - Range facet without an infix 170
Putting It All Together (Technically) 181
Setting the Logging Levels 184
Generating SEO Friendly URLs 184
Panl LPSE URL Paths Explained 186
Explaining A More Complex Example 195
Search Integration And The Panl Response Object 197
Overall Integration and Implementation 201
The "active.facet" JSON Array (Regular facet object) 202
Integration and Implementation 203
The "active.facet" JSON Array (BOOLEAN facet object) 203
Integration and Implementation 204
The "active.facet" JSON Array (DATE Range facet object) 205
Integration and Implementation 206
The "active.facet" JSON Array (OR facet object) 207
Integration and Implementation 208
The "active.facet" JSON Array (RANGE facet object) 208
Integration and Implementation 209
The "active.numrows" JSON Object 210
Integration and Implementation 210
The "active.page" JSON Object 210
Integration and Implementation 211
The "active.query" JSON Object 211
Integration and Implementation 212
The "active.query" JSON Object 212
Integration and Implementation 213
The "active.sort" JSON Array 213
Integration and Implementation 213
The "available" JSON Object 214
The "available.date_range_facets" JSON Array 215
Integration and Implementation 216
The "available.facets" JSON Array 217
Integration and Implementation 218
The "available.range_facets" JSON Object 219
Integration and Implementation 219
The "pagination" JSON Object 226
Integration and Implementation 226
Integration and Implementation 229
Single Search Page Integration And The Panl Response Object 233
The "lpse_lookup" JSON Object 235
The "lpse_order" JSON Array 236
Generating the LPSE URL path 236
More Facets Integration And The Panl Response Object 237
Determining The Facet Limit 238
Integrating An Existing Solr Schema 243
Running the Command Line Utility 243
Editing the Generated Files 247
Manually Creating the Configuration Files 247
Properties Quick Reference 249
Property References Format Explained 249
panl.bool.<lpse_code>.false 250
panl.bool.<lpse_code>.true 251
panl.collection.<solr_collection_name> 252
panl.date.<lpse_code>.days 253
panl.date.<lpse_code>.hours 254
panl.date.<lpse_code>.months 255
panl.date.<lpse_code>.next 256
panl.date.<lpse_code>.previous 257
panl.date.<lpse_code>.years 259
panl.facetsort.<lpse_code> 261
panl.include.same.number.facets 263
panl.include.single.facets 264
panl.multivalue.<lpse_code> 266
panl.or.always.<lpse_code> 268
panl.param.passthrough.canonical 272
panl.range.facet.<lpse_code> 274
panl.range.infix.<lpse_code> 275
panl.range.max.<lpse_code> 276
panl.range.max.value.<lpse_code> 276
panl.range.max.wildcard.<lpse_code> 277
panl.range.min.<lpse_code> 278
panl.range.min.value.<lpse_code> 278
panl.range.min.wildcard.<lpse_code> 279
panl.range.prefix.<lpse_code> 280
panl.range.suffix.<lpse_code> 281
panl.range.suppress.<lpse_code> 281
panl.results.fields.<field_set> 282
panl.results.fields.default 282
solr.default.query.operand 287
Collections And FieldSet URL Paths (CaFUPs) 292
In-Built Panl Results Testing URLs 293
500 - Internal Server Error 296
Additional Functionality in the Pipeline 301
Panl Internal Functional URL Bindings 306
Internal Testing URL Bindings 307
The Sample panl.properties Files 317
The Sample <panl_collection_url>.panl.properties Files 318
Solr Version 8 & 7 Integration Notes 319
Setting up a Solr 7 or 8 server 320
Additional Solr Version 7 Integration Notes 325
~ ~ ~ * ~ ~ ~