Bug 40986 - Add some reindexing examples to rebuild_elasticsearch.pl
Summary: Add some reindexing examples to rebuild_elasticsearch.pl
Status: Needs Signoff
Alias: None
Product: Koha
Classification: Unclassified
Component: Searching - Elasticsearch (show other bugs)
Version: Main
Hardware: All All
: P5 - low enhancement
Assignee: Thomas Klausner
QA Contact: Testopia
URL:
Keywords:
Depends on:
Blocks:
 
Reported: 2025-10-09 16:56 UTC by Thomas Klausner
Modified: 2025-10-09 18:49 UTC (History)
0 users

See Also:
GIT URL:
Change sponsored?: Sponsored
Patch complexity: Trivial patch
Documentation contact:
Documentation submission:
Text to go in the release notes:
Version(s) released in:
Circulation function:


Attachments
Bug 40986: add examples to rebuild_elasticsearch.pl --man (7.79 KB, patch)
2025-10-09 18:47 UTC, Thomas Klausner
Details | Diff | Splinter Review

Note You need to log in before you can comment on or make changes to this bug.
Description Thomas Klausner 2025-10-09 16:56:13 UTC
I want to document some examples of "advanced" usage of rebuild_elasticsearch.pl using --where SQL

I think the best place is to add them to the POD of the script itself (because in my experience this has the highest success rate of keeping it up to date)

We could then add to the docs / the wiki etc instructions on how to show this examples (i.e. `rebuild_elasticsearch.pl --help`)
Comment 1 Thomas Klausner 2025-10-09 18:47:48 UTC
Created attachment 187703 [details] [review]
Bug 40986: add examples to rebuild_elasticsearch.pl --man

This commit adds a bunch of example to rebuild_elasticsearch.pl --man, mostly about passing custom sql via --where.

It also fixes a few trivial issues in rebuild_elasticsearch.pl and adds a note to debian/scripts/koha-elasticsearch to point people to the extended docs

Test plan(s):

1: No examples in detailed help

* run: misc/search_tools/rebuild_elasticsearch.pl --man
* After OPTIONS (scroll down a bit with the down-arrow or hit space) the section IMPLEMENTATION is shown.
* No EXAMPLES section

2: Ugly error message:

* run: misc/search_tools/rebuild_elasticsearch.pl --processes 2 --authid 123
* output: "Argument p|processes cannot be combined with bn|bnumber or ai|authid at misc/search_tools/rebuild_elasticsearch.pl line 163."
* Notice "at misc/search_tools/rebuild_elasticsearch.pl line 163"

3: Warning:

* run: misc/search_tools/rebuild_elasticsearch.pl -v --biblios --where 'biblionumber = -1'
* output:
[9574] Checking state of biblios index
[9574] Indexing biblios
[9574] Committing final records...
Use of uninitialized value in string eq at misc/search_tools/rebuild_elasticsearch.pl line 365.
[9574] Total 0 records indexed

* Notice the warning "Use of uninitialized value.."

4: Error when using --where without -b or -a

* run: misc/search_tools/rebuild_elasticsearch.pl -v --where 'biblionumber = 1'
* output:
misc/search_tools/rebuild_elasticsearch.pl -v --where 'biblionumber = 420'
...
DBIx::Class::Storage::DBI::_dbh_execute(): DBI Exception: DBD::mysql::st execute failed: Unknown column 'biblionumber' in 'where clause' at /kohadevbox/koha/Koha/MetadataRecord/Authority.pm line 239

* The script dies, because auth_header has not column biblionumber and we where running --where on both tables.

5: No hint about reindex_elasticsearch in koha-elasticsearch

* run: debian/scripts/koha-elasticsearch --help
* There is no hint about reindex_elasticsearch.pl

Now apply the patch. No need to restart anything

1: examples are shown in detailed help

* run: misc/search_tools/rebuild_elasticsearch.pl --man
* after OPTIONS you will find a EXAMPLES section listing various use cases

2: Ugly error message is not ugly anymore

* run: misc/search_tools/rebuild_elasticsearch.pl --processes 2 --authid 123
* output: Argument p|processes cannot be combined with bn|bnumber or ai|authid
* no more "at blabla line ..."

3: Warning:

* run: misc/search_tools/rebuild_elasticsearch.pl -v --biblios --where 'biblionumber = -1'
* output:
[9574] Checking state of biblios index
[9574] Indexing biblios
[9574] Committing final records...
[9574] Total 0 records indexed

* Notice the warning "Use of uninitialized value.." is gone

4: Error when using --where without -b or -a

* run: misc/search_tools/rebuild_elasticsearch.pl -v --where 'biblionumber = 1'
* output: Argument w|where must be combined with either b|biblios or a|authorities
* and the script aborts.

5: koha-elasticsearch mentions reindex_elasticsearch.pl

* run: debian/scripts/koha-elasticsearch --help
* There **is** a hint about reindex_elasticsearch.pl

Now apply the patch. No need to restart anything

Sponsored-by: HKS3
Sponsored-by: Koha DACH Hackfest