Search engine configuration

Once you have switched to Elasticsearch in your SearchEngine system preference, you’ll see a new link for Search engine configuration in the Catalog section of Administration. Here you will manage indexes, facets, and their mappings to MARC fields and subfields.

Note

Only staff with the manage_search_engine_config permission (or the superlibrarian permission) will have access to this section.

The page is separated in three tabs: search fields, bibliographic records, and authority records.

Important

If you change anything in this page, you need to completely reindex your records, otherwise, only records added or edited after the change will be affected.

Danger

Any change done through the interface will be lost if you click on ‘Reset mappings’ or if the rebuild command is run with the --reset or -r parameter. The ‘Reset mappings’ button and the --reset parameter reset the settings to the defaults.

Search fields

The search fields tab in the search engine configuration page show all the search fields used by Elasticsearch in Koha.

The table shows:

Name: the name of the search field, as defined in the mappings file.

Aliases: some fields have aliases, for example, “author” can also be “au”. These are hardcoded and cannot be changed.

Label: some fields have labels that are different from their name. These are used as the facet header when the field is used as a facet.

Type: the type influences how the data is stored and how it is searched.

Boolean: a 0 / 1 (no / yes) value.

Call Number: a call number influenced by the classification source.

Date: a date stored in ISO format.

Geo point: a geographic latitude and longitude value.

Version

The Geo point type was added to Koha in version 24.05.

ISBN: ISBN standard number.

Number: a number.

Std. Number: a number.

String: a simple string of characters.

Sum: a sum of values.

Year: a four-digit year number.

Weight: a positive numerical value assigned to that search field to make it more “important” in a simple search. The higher the value, the more “important” this field is in the relevancy sorting.

Note

Weighted search only works for bibliographic search, not authority search. It also only works for the simple search, unless the ‘Apply field weights to search’ option in the advanced search is selected.

Searchable: whether this field is used in the staff interface or the OPAC.

Adding search fields

Version

The possibility of adding search fields was added to Koha in version 24.05.

It is possible to add search fields from this table. Add the search field information in the last row of the table, and click the ‘Add’ button at the end of the row.

Deleting search fields

Version

The possibility of deleting added search fields was added to Koha in version 24.05.

It is possible to delete search fields that were added manually. The default search fields cannot be deleted because they are necessary for Koha to work properly.

To delete a search field, click the ‘Delete’ button at the end of the row.

Bibliographic records

The bibliographic records tab in the search engine configuration page shows the MARC mappings for each search field used by Elasticsearch in Koha.

Note

The default mappings are described in the Elasticsearch indexes section of the Searching chapter.

The table shows:

Search field: the corresponding search field (as defined in the search fields tab). Search fields can be repeated to include several MARC fields.

Sortable: indicates whether this mapping should be used in the sorting for this search field. For example, in MARC21, the title index has several different title fields, but only the 245 field is used for sorting.

Facetable: indicates whether this mapping can be used in the facets.

Version

Facet configuration was added to Koha in version 24.05.

Suggestible: indicates whether this mapping is used in the browse search.

Searchable: indicates whether this mapping is used for searching.

Filter: the type influences the way values are indexed.

Punctuation: removes punctuation.

None: values are indexed as they are.

Version

Filters were added to Koha in version 23.11.

Mapping: indicates the MARC field mapped to that search field.

Note

Mappings can include whole fields or only specific subfields. In the case of subfields, they can be indexed individually or as a single value.

For example:

520 will index all the contents of the 520 field. Each subfield in the field will be indexed individually.

100a will index only the contents of 100$a.

020az will index only the contents of subfields $a and $z of field 020. They will be indexed individually.

245(abp) will index only the contents of subfields $a, $b and $p of field 245. They will be indexed as one entry.

For fixed-length fields, the syntax is as follows :

leader_/6 will index position 6 of the leader (000).

007_/0 will index position 0 of field 007.

008_/39 will index position 39 of field 008.

008_/15-17 will index positions 15 to 17 of field 008, as one entity.

Adding mappings

To add a mapping, add the information in the last row of the table and click the ‘Add’ button at the end of the row.

Important

Remember that if you change anything in this page, you need to completely reindex your records, otherwise, only records added or edited after the change will be affected.

Danger

Any change done through the interface will be lost if you click on ‘Reset mappings’ or if the rebuild command is run with the --reset or -r parameter. The ‘Reset mappings’ button and the --reset parameter reset the settings to the defaults.

Deleting mappings

To delete a mapping, click the ‘Delete’ button at the end of the row.

Some mappings are necessary for Koha to function properly and cannot be deleted.

Important

Remember that if you change anything in this page, you need to completely reindex your records, otherwise, only records added or edited after the change will be affected.

Danger

Any change done through the interface will be lost if you click on ‘Reset mappings’ or if the rebuild command is run with the --reset or -r parameter. The ‘Reset mappings’ button and the --reset parameter reset the settings to the defaults.

Facet order

This section allows you to customize the facets, as displayed in the search results in the OPAC and staff interface.

Search field: the corresponding search field (as defined in the search fields tab).

Label: the search field’s label (as defined in the search fields tab).

Version

This column was added to Koha in version 23.11.

Authorized value category: for some facets, it is possible to define an authorized value category that will manage the text displayed for the facet items. Some facets have hardcoded authorized value categories, such as LOC for location and CCODE for collections.

Version

This option was added to Koha in version 23.11.

To reorder the facets, simply drag and drop the row where you want it.

To rename facets, you need to change the label in the search fields tab.

To delete a facet, click the ‘Delete’ button.

Attention

In Koha versions 23.11 and earlier, it is not possible to delete facets. But it is possible to uncheck the ‘Display’ checkbox to hide them from the search results.

To add a new facet,

first, add the search field,

then add mappings to that search field, making sure to set ‘Facetable’ to ‘Yes’,

finally, add the facet in the facet order table, using the last row to enter the values, and click the ‘Add’ button at the end of the row.

Version

The option to add facets was added to Koha in version 24.05.

Authorities

The authorities tab in the search engine configuration page shows the MARC mappings for authority search fields used by Elasticsearch in Koha.

Note

The default mappings are described in the Elasticsearch indexes section of the Searching chapter.

The table shows:

Search field: the corresponding search field (as defined in the search fields tab). Search fields can be repeated to include several MARC fields.

Sortable: indicates whether this mapping should be used in the sorting for this search field.

Facetable: indicates whether this mapping can be used in the facets.

Note

There are no facets in authority search, therefore this column should always be set to ‘No’ for authorities.

Suggestible: indicates whether this mapping is used in the browse search.

Note

There is no browse search for authorities, therefore this column should always be set to ‘No’ for authorities.

Searchable: indicates whether this mapping is used for searching.

Filter: the type influences the way values are indexed.

Punctuation: removes punctuation.

None: values are indexed as they are.

Version

Filters were added to Koha in version 23.11.

Mapping: indicates the MARC field mapped to that search field.

Note

Mappings can include whole fields or only specific subfields. In the case of subfields, they can be indexed individually or as a single value.

For example:

520 will index all the contents of the 520 field. Each subfield in the field will be indexed individually.

100a will index only the contents of 100$a.

020az will index only the contents of subfields $a and $z of field 020. They will be indexed individually.

245(abp) will index only the contents of subfields $a, $b and $p of field 245. They will be indexed as one entry.

For fixed-length fields, the syntax is as follows :

leader_/6 will index position 6 of the leader (000).

007_/0 will index position 0 of field 007.

008_/39 will index position 39 of field 008.

008_/15-17 will index positions 15 to 17 of field 008, as one entity.

You can add mappings and delete mappings for authorities, the process is the same as for bibliographic records (see above).