Revert "Bug 20073: Move Elasticsearch configs to yaml files and improve the default...
[koha.git] / Koha / SearchEngine / Elasticsearch.pm
1 package Koha::SearchEngine::Elasticsearch;
2
3 # Copyright 2015 Catalyst IT
4 #
5 # This file is part of Koha.
6 #
7 # Koha is free software; you can redistribute it and/or modify it under the
8 # terms of the GNU General Public License as published by the Free Software
9 # Foundation; either version 3 of the License, or (at your option) any later
10 # version.
11 #
12 # Koha is distributed in the hope that it will be useful, but WITHOUT ANY
13 # WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
14 # A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
15 #
16 # You should have received a copy of the GNU General Public License along
17 # with Koha; if not, write to the Free Software Foundation, Inc.,
18 # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
19
20 use base qw(Class::Accessor);
21
22 use C4::Context;
23
24 use Koha::Database;
25 use Koha::Exceptions::Config;
26 use Koha::SearchFields;
27 use Koha::SearchMarcMaps;
28
29 use Carp;
30 use JSON;
31 use Modern::Perl;
32 use Readonly;
33 use Search::Elasticsearch;
34 use Try::Tiny;
35 use YAML::Syck;
36
37 use Data::Dumper;    # TODO remove
38
39 __PACKAGE__->mk_ro_accessors(qw( index ));
40 __PACKAGE__->mk_accessors(qw( sort_fields ));
41
42 # Constants to refer to the standard index names
43 Readonly our $BIBLIOS_INDEX     => 'biblios';
44 Readonly our $AUTHORITIES_INDEX => 'authorities';
45
46 =head1 NAME
47
48 Koha::SearchEngine::Elasticsearch - Base module for things using elasticsearch
49
50 =head1 ACCESSORS
51
52 =over 4
53
54 =item index
55
56 The name of the index to use, generally 'biblios' or 'authorities'.
57
58 =back
59
60 =head1 FUNCTIONS
61
62 =cut
63
64 sub new {
65     my $class = shift @_;
66     my $self = $class->SUPER::new(@_);
67     # Check for a valid index
68     croak('No index name provided') unless $self->index;
69     return $self;
70 }
71
72 =head2 get_elasticsearch_params
73
74     my $params = $self->get_elasticsearch_params();
75
76 This provides a hashref that contains the parameters for connecting to the
77 ElasicSearch servers, in the form:
78
79     {
80         'nodes' => ['127.0.0.1:9200', 'anotherserver:9200'],
81         'index_name' => 'koha_instance_index',
82     }
83
84 This is configured by the following in the C<config> block in koha-conf.xml:
85
86     <elasticsearch>
87         <server>127.0.0.1:9200</server>
88         <server>anotherserver:9200</server>
89         <index_name>koha_instance</index_name>
90     </elasticsearch>
91
92 =cut
93
94 sub get_elasticsearch_params {
95     my ($self) = @_;
96
97     # Copy the hash so that we're not modifying the original
98     my $conf = C4::Context->config('elasticsearch');
99     die "No 'elasticsearch' block is defined in koha-conf.xml.\n" if ( !$conf );
100     my $es = { %{ $conf } };
101
102     # Helpfully, the multiple server lines end up in an array for us anyway
103     # if there are multiple ones, but not if there's only one.
104     my $server = $es->{server};
105     delete $es->{server};
106     if ( ref($server) eq 'ARRAY' ) {
107
108         # store it called 'nodes' (which is used by newer Search::Elasticsearch)
109         $es->{nodes} = $server;
110     }
111     elsif ($server) {
112         $es->{nodes} = [$server];
113     }
114     else {
115         die "No elasticsearch servers were specified in koha-conf.xml.\n";
116     }
117     die "No elasticserver index_name was specified in koha-conf.xml.\n"
118       if ( !$es->{index_name} );
119     # Append the name of this particular index to our namespace
120     $es->{index_name} .= '_' . $self->index;
121
122     $es->{key_prefix} = 'es_';
123     return $es;
124 }
125
126 =head2 get_elasticsearch_settings
127
128     my $settings = $self->get_elasticsearch_settings();
129
130 This provides the settings provided to elasticsearch when an index is created.
131 These can do things like define tokenisation methods.
132
133 A hashref containing the settings is returned.
134
135 =cut
136
137 sub get_elasticsearch_settings {
138     my ($self) = @_;
139
140     # Ultimately this should come from a file or something, and not be
141     # hardcoded.
142     my $settings = {
143         index => {
144             analysis => {
145                 analyzer => {
146                     analyser_phrase => {
147                         tokenizer => 'icu_tokenizer',
148                         filter    => ['icu_folding'],
149                     },
150                     analyser_standard => {
151                         tokenizer => 'icu_tokenizer',
152                         filter    => ['icu_folding'],
153                     },
154                 },
155             }
156         }
157     };
158     return $settings;
159 }
160
161 =head2 get_elasticsearch_mappings
162
163     my $mappings = $self->get_elasticsearch_mappings();
164
165 This provides the mappings that get passed to elasticsearch when an index is
166 created.
167
168 =cut
169
170 sub get_elasticsearch_mappings {
171     my ($self) = @_;
172
173     # TODO cache in the object?
174     my $mappings = {
175         data => {
176             _all => {type => "string", analyzer => "analyser_standard"},
177             properties => {
178                 record => {
179                     store          => "true",
180                     include_in_all => JSON::false,
181                     type           => "text",
182                 },
183             }
184         }
185     };
186     my %sort_fields;
187     my $marcflavour = lc C4::Context->preference('marcflavour');
188     $self->_foreach_mapping(
189         sub {
190             my ( $name, $type, $facet, $suggestible, $sort, $marc_type ) = @_;
191             return if $marc_type ne $marcflavour;
192             # TODO if this gets any sort of complexity to it, it should
193             # be broken out into its own function.
194
195             # TODO be aware of date formats, but this requires pre-parsing
196             # as ES will simply reject anything with an invalid date.
197             my $es_type =
198               $type eq 'boolean'
199               ? 'boolean'
200               : 'text';
201
202             if ($es_type eq 'boolean') {
203                 $mappings->{data}{properties}{$name} = _elasticsearch_mapping_for_boolean( $name, $es_type, $facet, $suggestible, $sort, $marc_type );
204                 return; #Boolean cannot have facets nor sorting nor suggestions
205             } else {
206                 $mappings->{data}{properties}{$name} = _elasticsearch_mapping_for_default( $name, $es_type, $facet, $suggestible, $sort, $marc_type );
207             }
208
209             if ($facet) {
210                 $mappings->{data}{properties}{ $name . '__facet' } = {
211                     type  => "keyword",
212                 };
213             }
214             if ($suggestible) {
215                 $mappings->{data}{properties}{ $name . '__suggestion' } = {
216                     type => 'completion',
217                     analyzer => 'simple',
218                     search_analyzer => 'simple',
219                 };
220             }
221             # Sort is a bit special as it can be true, false, undef.
222             # We care about "true" or "undef",
223             # "undef" means to do the default thing, which is make it sortable.
224             if ($sort || !defined $sort) {
225                 $mappings->{data}{properties}{ $name . '__sort' } = {
226                     search_analyzer => "analyser_phrase",
227                     analyzer  => "analyser_phrase",
228                     type            => "text",
229                     include_in_all  => JSON::false,
230                     fields          => {
231                         phrase => {
232                             type            => "keyword",
233                         },
234                     },
235                 };
236                 $sort_fields{$name} = 1;
237             }
238         }
239     );
240     $self->sort_fields(\%sort_fields);
241     return $mappings;
242 }
243
244 =head2 _elasticsearch_mapping_for_*
245
246 Get the ES mappings for the given data type or a special mapping case
247
248 Receives the same parameters from the $self->_foreach_mapping() dispatcher
249
250 =cut
251
252 sub _elasticsearch_mapping_for_boolean {
253     my ( $name, $type, $facet, $suggestible, $sort, $marc_type ) = @_;
254
255     return {
256         type            => $type,
257         null_value      => 0,
258     };
259 }
260
261 sub _elasticsearch_mapping_for_default {
262     my ( $name, $type, $facet, $suggestible, $sort, $marc_type ) = @_;
263
264     return {
265         search_analyzer => "analyser_standard",
266         analyzer        => "analyser_standard",
267         type            => $type,
268         fields          => {
269             phrase => {
270                 search_analyzer => "analyser_phrase",
271                 analyzer        => "analyser_phrase",
272                 type            => "text",
273             },
274             raw => {
275                 type    => "keyword",
276             }
277         },
278     };
279 }
280
281 sub reset_elasticsearch_mappings {
282     my $mappings_yaml = C4::Context->config('intranetdir') . '/admin/searchengine/elasticsearch/mappings.yaml';
283     my $indexes = LoadFile( $mappings_yaml );
284
285     while ( my ( $index_name, $fields ) = each %$indexes ) {
286         while ( my ( $field_name, $data ) = each %$fields ) {
287             my $field_type = $data->{type};
288             my $field_label = $data->{label};
289             my $mappings = $data->{mappings};
290             my $search_field = Koha::SearchFields->find_or_create({ name => $field_name, label => $field_label, type => $field_type }, { key => 'name' });
291             for my $mapping ( @$mappings ) {
292                 my $marc_field = Koha::SearchMarcMaps->find_or_create({ index_name => $index_name, marc_type => $mapping->{marc_type}, marc_field => $mapping->{marc_field} });
293                 $search_field->add_to_search_marc_maps($marc_field, { facet => $mapping->{facet} || 0, suggestible => $mapping->{suggestible} || 0, sort => $mapping->{sort} } );
294             }
295         }
296     }
297 }
298
299 # This overrides the accessor provided by Class::Accessor so that if
300 # sort_fields isn't set, then it'll generate it.
301 sub sort_fields {
302     my $self = shift;
303     if (@_) {
304         $self->_sort_fields_accessor(@_);
305         return;
306     }
307     my $val = $self->_sort_fields_accessor();
308     return $val if $val;
309
310     # This will populate the accessor as a side effect
311     $self->get_elasticsearch_mappings();
312     return $self->_sort_fields_accessor();
313 }
314
315 # Provides the rules for data conversion.
316 sub get_fixer_rules {
317     my ($self) = @_;
318
319     my $marcflavour = lc C4::Context->preference('marcflavour');
320     my @rules;
321
322     $self->_foreach_mapping(
323         sub {
324             my ( $name, $type, $facet, $suggestible, $sort, $marc_type, $marc_field ) = @_;
325             return if $marc_type ne $marcflavour;
326             my $options ='';
327
328             push @rules, "marc_map('$marc_field','${name}.\$append', $options)";
329             if ($facet) {
330                 push @rules, "marc_map('$marc_field','${name}__facet.\$append', $options)";
331             }
332             if ($suggestible) {
333                 push @rules,
334                     #"marc_map('$marc_field','${name}__suggestion.input.\$append', '')"; #must not have nested data structures in .input
335                     "marc_map('$marc_field','${name}__suggestion.input.\$append')";
336             }
337             if ( $type eq 'boolean' ) {
338
339                 # boolean gets special handling, basically if it doesn't exist,
340                 # it's added and set to false. Otherwise we can't query it.
341                 push @rules,
342                   "unless exists('$name') add_field('$name', 0) end";
343             }
344             if ($type eq 'sum' ) {
345                 push @rules, "sum('$name')";
346             }
347             if ($self->sort_fields()->{$name}) {
348                 if ($sort || !defined $sort) {
349                     push @rules, "marc_map('$marc_field','${name}__sort.\$append', $options)";
350                 }
351             }
352         }
353     );
354
355     push @rules, "move_field(_id,es_id)"; #Also you must set the Catmandu::Store::ElasticSearch->new(key_prefix: 'es_');
356     return \@rules;
357 }
358
359 =head2 _foreach_mapping
360
361     $self->_foreach_mapping(
362         sub {
363             my ( $name, $type, $facet, $suggestible, $sort, $marc_type,
364                 $marc_field )
365               = @_;
366             return unless $marc_type eq 'marc21';
367             print "Data comes from: " . $marc_field . "\n";
368         }
369     );
370
371 This allows you to apply a function to each entry in the elasticsearch mappings
372 table, in order to build the mappings for whatever is needed.
373
374 In the provided function, the files are:
375
376 =over 4
377
378 =item C<$name>
379
380 The field name for elasticsearch (corresponds to the 'mapping' column in the
381 database.
382
383 =item C<$type>
384
385 The type for this value, e.g. 'string'.
386
387 =item C<$facet>
388
389 True if this value should be facetised. This only really makes sense if the
390 field is understood by the facet processing code anyway.
391
392 =item C<$sort>
393
394 True if this is a field that a) needs special sort handling, and b) if it
395 should be sorted on. False if a) but not b). Undef if not a). This allows,
396 for example, author to be sorted on but not everything marked with "author"
397 to be included in that sort.
398
399 =item C<$marc_type>
400
401 A string that indicates the MARC type that this mapping is for, e.g. 'marc21',
402 'unimarc', 'normarc'.
403
404 =item C<$marc_field>
405
406 A string that describes the MARC field that contains the data to extract.
407 These are of a form suited to Catmandu's MARC fixers.
408
409 =back
410
411 =cut
412
413 sub _foreach_mapping {
414     my ( $self, $sub ) = @_;
415
416     # TODO use a caching framework here
417     my $search_fields = Koha::Database->schema->resultset('SearchField')->search(
418         {
419             'search_marc_map.index_name' => $self->index,
420         },
421         {   join => { search_marc_to_fields => 'search_marc_map' },
422             '+select' => [
423                 'search_marc_to_fields.facet',
424                 'search_marc_to_fields.suggestible',
425                 'search_marc_to_fields.sort',
426                 'search_marc_map.marc_type',
427                 'search_marc_map.marc_field',
428             ],
429             '+as'     => [
430                 'facet',
431                 'suggestible',
432                 'sort',
433                 'marc_type',
434                 'marc_field',
435             ],
436         }
437     );
438
439     while ( my $search_field = $search_fields->next ) {
440         $sub->(
441             $search_field->name,
442             $search_field->type,
443             $search_field->get_column('facet'),
444             $search_field->get_column('suggestible'),
445             $search_field->get_column('sort'),
446             $search_field->get_column('marc_type'),
447             $search_field->get_column('marc_field'),
448         );
449     }
450 }
451
452 =head2 process_error
453
454     die process_error($@);
455
456 This parses an Elasticsearch error message and produces a human-readable
457 result from it. This result is probably missing all the useful information
458 that you might want in diagnosing an issue, so the warning is also logged.
459
460 Note that currently the resulting message is not internationalised. This
461 will happen eventually by some method or other.
462
463 =cut
464
465 sub process_error {
466     my ($self, $msg) = @_;
467
468     warn $msg; # simple logging
469
470     # This is super-primitive
471     return "Unable to understand your search query, please rephrase and try again.\n" if $msg =~ /ParseException/;
472
473     return "Unable to perform your search. Please try again.\n";
474 }
475
476 =head2 _read_configuration
477
478     my $conf = _read_configuration();
479
480 Reads the I<configuration file> and returns a hash structure with the
481 configuration information. It raises an exception if mandatory entries
482 are missing.
483
484 The hashref structure has the following form:
485
486     {
487         'nodes' => ['127.0.0.1:9200', 'anotherserver:9200'],
488         'index_name' => 'koha_instance',
489     }
490
491 This is configured by the following in the C<config> block in koha-conf.xml:
492
493     <elasticsearch>
494         <server>127.0.0.1:9200</server>
495         <server>anotherserver:9200</server>
496         <index_name>koha_instance</index_name>
497     </elasticsearch>
498
499 =cut
500
501 sub _read_configuration {
502
503     my $configuration;
504
505     my $conf = C4::Context->config('elasticsearch');
506     Koha::Exceptions::Config::MissingEntry->throw(
507         "Missing 'elasticsearch' block in config file")
508       unless defined $conf;
509
510     if ( $conf && $conf->{server} ) {
511         my $nodes = $conf->{server};
512         if ( ref($nodes) eq 'ARRAY' ) {
513             $configuration->{nodes} = $nodes;
514         }
515         else {
516             $configuration->{nodes} = [$nodes];
517         }
518     }
519     else {
520         Koha::Exceptions::Config::MissingEntry->throw(
521             "Missing 'server' entry in config file for elasticsearch");
522     }
523
524     if ( defined $conf->{index_name} ) {
525         $configuration->{index_name} = $conf->{index_name};
526     }
527     else {
528         Koha::Exceptions::Config::MissingEntry->throw(
529             "Missing 'index_name' entry in config file for elasticsearch");
530     }
531
532     return $configuration;
533 }
534
535 1;
536
537 __END__
538
539 =head1 AUTHOR
540
541 =over 4
542
543 =item Chris Cormack C<< <chrisc@catalyst.net.nz> >>
544
545 =item Robin Sheat C<< <robin@catalyst.net.nz> >>
546
547 =item Jonathan Druart C<< <jonathan.druart@bugs.koha-community.org> >>
548
549 =back
550
551 =cut