Getting Started With Panl
A rather pleasing companion to the Apache® Solr® Faceted Search Engine
_____________
Author: Synapticloop - Version 2.2.0 (Release 1)
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 latest release of this book can always be found here: https://github.com/synapticloop/panl/tree/main/src/book, and the online version here: https://synapticloop.github.io/panl/)
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...
- GETTING UP TO SPEED
Start with the Quick Start - The 5 Steps section to get the Solr and Panl servers up and running and browse the Panl Results Viewer.
http://localhost:8181/panl-results-viewer/mechanical-pencils/default/
Can't wait, or just need to see what it is all about? See the Quick Preview - Running Docker section. - UNDERSTAND
The Solr Fundamentals and Panl Fundamentals section introduces you to the concepts that lay the foundations for the rest of the book. Once you have a good understanding of the configuration and functionality, then there are two example walkthroughs:
- A FULL EXAMPLE
Work through the The Bookstore Walkthrough section to gain a deeper understanding of the complete process, from schema design, indexing, and configuration of both Panl and Solr. - PROGRAMMATIC INDEXING
Work through the Filesystem Indexing And Searching Walkthrough chapter to understand how to programmatically index files and commit them to Solr.
- INTEGRATE
Use your existing Solr installation and dataset to set up Panl with Integrating An Existing Solr Schema. - REFERENCE
Need help understanding the options? See the Panl Configuration part. - UPGRADE
See the Upgrading Your Panl Server Version section.
QUICK TIP
|
|
Tip: Documentation for this book can also be read online, see:
https://synapticloop.github.io/panl/
or, to download the copy of this book for the Panl version that you are using, see:
https://github.com/synapticloop/panl/releases/
Corrections and updates to this book, when done, will always be reflected online and the main GitHub branch - see:
|
~ ~ ~ * ~ ~ ~
Copyright Notices
MECHANICAL PENCIL DATA: 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 and is used for informational purposes. The manufacturer's name, the name of the pencil (and/or model number) may be a trademark and/or is copyright of the manufacturer.
IMAGES, APPLICATIONS, AND SITE REFERENCES: Screenshots of applications and external websites are included in this book, they remain the copyright of the original owner and do not infer any association with, or endorsement of, Synapticloop, and/or vice versa.
Additional datasets may have information that is copyright or trademarked 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.
A NOTE ON URL ENCODINGS: Within this book if you are using the Firefox browser then the address bar will automatically decode any URL encoded space characters ('%20') - other browsers will keep the encoding in the address bar. Within this book, the majority of example URLs will not show the %20 encoding, however the associated href in the link will include these encodings.
~ ~ ~ * ~ ~ ~
TABLE OF CONTENTS
———————
PART 1:
ABOUT THIS BOOK
. 16
———————
PART 2:
INTRODUCTION
. 26
A Simple Faceted Search Example 29
A More Complex Faceted Search Example 30
Welcome To Synapticloop Panl 34
How Many Facets Does Panl Support? 40
In-Built Web Apps (Viewer / Explainer / Single Search Page Examples) 44
What is a LPSE (pronounced 'lapse') code? 57
Is Synapticloop Panl For Me? 59
———————
PART 3:
GETTING UP AND RUNNING
. 61
The Panl Directory Structure 63
Solr-Panl-8-x.x.x & Solr-Panl-7-x.x.x 66
Solr-Panl-6-x.x.x and earlier version 66
Quick Preview - Running Docker 68
Building The Docker Image Locally 69
Operating System Dependent Notes 72
A Note On Running The Commands 79
Solr Versions Command Line Options 82
Creating and Starting a Solr Cloud Instance 83
When Things go Horribly-Wrong 93
———————
PART 4:
FUNDAMENTALS
. 99
Solr Configuration File Changes 100
Overview of Indexed / Stored / Analysed Fields 105
Search Field Configuration 112
Specific Solr Field Keyword Search Configuration 121
———————
PART 5:
GOING DEEPER - PRACTICAL EXAMPLES
. 129
0. High Level Requirements 133
1. Understanding the Dataset 133
2. Configure the Solr Index 136
3. Configure the Panl Server 143
4. Determine the Web Pages to Render 177
The Iterative Implementation Process 178
Filesystem Indexing And Searching Walkthrough 180
Mechanical Pencils OR Facet 203
Mechanical Pencils More Facets 204
Unsupported/Partially Supported Solr Field Types 209
A Note on Prefixes, Suffixes, and Infixes 210
Understanding Solr Configuration And Panl Integration 231
The Solr Configuration File 259
———————
PART 6:
PANL CONFIGURATION IN DETAIL
. 264
The <panl_collection_url>.panl.properties file 266
The panl.properties Configuration File 268
Configuring The SolrJ Connector 269
Setting The Solr Server URL(s) 270
Enabling The Panl Results Testing URLs 271
Setting HTTP Status Message Verbosity 272
Setting The Decimal Point Separator 273
Binding Solr Collections to Panl URL Paths 273
The <panl_collection_url>.panl.properties Configuration File 277
Parameter and Operand Definitions 277
Search Queries and Search Operands 278
———————
PART 7:
INTEGRATION AND PRODUCTION
. 332
Putting It All Together (Technically) 333
Upgrading Your Panl Server Version 337
Generating SEO Friendly URLs 337
Standalone Solr Installations 339
Panl LPSE URL Paths Explained 344
Explaining A More Complex Example 353
Search Integration And The Panl Response Object 356
"response.docs" JSON Object Results Integration 364
"panl.search" Keyword Search Integration 368
"panl.search" Specific Solr Search Field Integration 371
"panl.active.facet" REGULAR facet object 378
"panl.active.facet" REGULAR (Multi-Valued) facet object 380
"panl.active.facet" BOOLEAN facet object 381
"panl.active.facet" BOOLEAN Checkbox facet object 383
"panl.active.facet" DATE Range facet object 386
"panl.active.facet" OR facet object 388
"panl.active.facet" RANGE facet object 389
"panl.active.search" JSON Object 394
"panl.active.query_operand" JSON Object 396
"panl.active.sort" JSON Array 397
"panl.available" JSON Object 400
"panl.available.date_range_facets" JSON Array 401
"panl.available.facets" JSON Array 402
"panl.available.range_facets" JSON Object 414
"panl.pagination" JSON Object 422
"panl.sorting" JSON Object 423
"response.highlighting" JSON Object 428
Single Search Page Integration And The Panl Response Object 431
The "lpse_lookup" JSON Object 433
The "lpse_order" JSON Array 434
More Facets Integration And The Panl Response Object 435
Lookahead Integration And The Panl Response Object 441
Integrating An Existing Solr Schema 445
Manually Creating the Configuration Files 449
———————
PART 8:
REFERENCE MATERIAL
. 453
SEO Friendlier Canonical URLs 454
Analysed Facets (think Word Clouds) 469
Using Panl for Dynamic Navigation Menus 475
More Like This Functionality 481
Properties Quick Reference 486
Property References Format Explained 486
panl.bool.<lpse_code>.false 487
panl.bool.<lpse_code>.true 488
panl.bool.checkbox.<lpse_code> 489
panl.collection.<solr_collection_name> 490
panl.date.<lpse_code>.days 492
panl.date.<lpse_code>.hours 493
panl.date.<lpse_code>.months 494
panl.date.<lpse_code>.next 496
panl.date.<lpse_code>.previous 497
panl.date.<lpse_code>.years 498
panl.facetsort.<lpse_code> 502
panl.form.query.operand.respondto 504
panl.include.same.number.facets 505
panl.include.single.facets 505
panl.multivalue.<lpse_code> 519
panl.multivalue.separator. <lpse_code> 519
panl.or.always.<lpse_code> 521
panl.or.separator.<lpse_code> 523
panl.param.passthrough.canonical 528
panl.range.facet.<lpse_code> 531
panl.range.infix.<lpse_code> 532
panl.range.max.<lpse_code> 533
panl.range.max.value.<lpse_code> 533
panl.range.max.wildcard.<lpse_code> 534
panl.range.min.<lpse_code> 535
panl.range.min.value.<lpse_code> 535
panl.range.min.wildcard.<lpse_code> 536
panl.range.prefix.<lpse_code> 537
panl.range.suffix.<lpse_code> 537
panl.range.suppress.<lpse_code> 538
panl.remove.solr.json.keys 540
panl.results.fields.<field_set> 540
panl.results.fields.default 541
panl.uniquekey.<lpse_code> 547
solr.default.query.operand 549
Decoding the Solr Query Parameters 555
f.<solr_field>.facet.mincount= 560
f.<solr_field_name>.facet.sort= 560
Decoding the Solr More Like This Query Parameters 568
Translating The Parameters 568
Collections And FieldSet URL Paths (CaFUPs) 574
In-Built Panl Results Testing URLs 575
Additional Functionality in the Pipeline 586
Solr Version 8 & 7 Integration Notes 611
~ ~ ~ * ~ ~ ~

