DokuWiki

You've loaded an old revision of the document! If you save it, you will create a new version with this data.

====== elasticsearch Plugin ======

---- plugin ----
description: Integrate Elasticsearch engine
author     : Andreas Gohr, Anna Dabrowska 
email      : dokuwiki@cosmocode.de 
type       : action
lastupdate : 2021-04-27
compatible : Greebo, Hogfather
depends    : 
conflicts  : 
similar    : 
tags       : search

downloadurl: https://github.com/cosmocode/dokuwiki-plugin-elasticsearch/zipball/master
bugtracker : https://github.com/cosmocode/dokuwiki-plugin-elasticsearch/issues
sourcerepo : https://github.com/cosmocode/dokuwiki-plugin-elasticsearch/
donationurl:

screenshot_img : 
----

===== Installation =====

[[https://www.cosmocode.de/en/open-source/dokuwiki-plugins/|{{ http://cosmocode.de/static/img/dokuwiki/dwplugins.png?recache|A CosmoCode Plugin}}]]

:!: **External requirements:** This plugin requires the following additional components that must be installed separately: 
  * [[https://www.elastic.co/products/elasticsearch|Elasticsearch]] instance (latest supported version 7.1)

Install the plugin using the [[plugin:plugin|Plugin Manager]] and the download URL above, which points to latest version of the plugin. Refer to [[:Plugins]] on how to install plugins manually.

Configure and setup the plugin as outlined under [[#Configuration]] below.

===== Examples/Usage =====

Once installed, the plugin will automatically react on the ?do=search action, replacing DokuWiki's builtin search.

All [[acl|access rights]] are respected, so users will only find pages for which they have at least read privileges.

You can use the Advanced Search Tools to filter the results by namespace and date of the last modification.

If the [[plugin:text|text plugin]] is installed, the rendered content of pages will be indexed in addition to raw wiki syntax. By default, search uses both fields. If you want to disable search in syntax, change the ''searchSyntax'' setting in the plugin's configuration.
===== Configuration and Settings =====

To integrate this plugin, you will need to do some configuration and run a few commands on the command line.

- enter the configuration of your Elasticsearch server in the [[plugin:config|Configuration Settings]]
  - create the Index
  - create the Language Mappings
  - index your pages

==== Creating the Index ====

You can use the tools provided by ElasticSearch to create the index or simply run the provided command line tool to do so:

<code>
./bin/plugin.php elasticsearch createindex
</code>

The name of the index is determined by the configuration.

=== Re-creating the index ===

Sometimes it is necessary to throw away the old index and replace it with a new one. This can be done via the same DokuWiki script with an additional parameter:

<code>
./bin/plugin.php elasticsearch createindex --clear
</code>
==== Languages and fuzzy search ====

One of the main reasons for using a dedicated search engine is that it provides advanced features, such as fuzzy search. To enable it, the pages must be indexed using a linguistic analyzer in the appropriate language. Make sure to create the language mapping using the CLI tool **before** filling the index.

<code>
./bin/plugin.php elasticsearch createlangmapping
</code>

If you have configured multiple languages using the [[plugin:translation|Translation plugin]], they will be mapped as well.

At present there is no special filter that would let the user search in a particular language only. However, it is possible to filter the results by language namespaces.

==== Index management ====

The pages will be indexed automatically when browsed, just like with the DokuWiki builtin mechanism. When a page is updated, its entry in the index will be updated as well.

You can also force indexing the whole Wiki at once using the CLI tool. This is recommended when you build the index for the first time or when you have made extensive changes (like moving pages or updating the [[:acl|ACLs]]).

<code>
./bin/plugin.php elasticsearch index
</code>

===== Other plugins =====

The [[plugin:tagging|tagging plugin]] integrates well with Elasticsearch. You can search for tags explicitly using ''#sometag'' search terms. If any of the results are tagged, a tag filter will be added to Advanced Search Tools.

===== Development =====

==== Plugin integration ====

Elasticsearch emits several events that can be used by other plugins to put their own data into the search index. Take a look at the implementation [[plugin:tagging|tagging]] to see how those events can be used.

* ''PLUGIN_ELASTICSEARCH_CREATEMAPPING'': Triggered when creating the index. Plugins may add their own fields and mappings via event data.
  * ''PLUGIN_ELASTICSEARCH_INDEXPAGE'': While indexing a page, plugins can provide their own data.
  * ''PLUGIN_ELASTICSEARCH_FILTERS'': Adds search configurations provided by plugins.
  * ''PLUGIN_ELASTICSEARCH_SEARCHFIELDS'': Lets plugins add their own fields to the list of search fields included in the Elastic query.
  * ''PLUGIN_ELASTICSEARCH_QUERY'': Lets plugins append their data to the query string.

==== Commit-Ticker ====

{{rss>https://github.com/cosmocode/dokuwiki-plugin-elasticsearch/commits/master.atom date}}

**Releases:**
{{rss>https://github.com/cosmocode/dokuwiki-plugin-elasticsearch/releases.atom description author}}

=== ToDo/Wish List ===

* search a specific language
  * exact match (non-fuzzy search)

Please fill all the letters into the box to prove you're human. D L G R S Please keep this field empty:

Edit summary

Note: By editing this page you agree to license your content under the following license: CC Attribution-Share Alike 4.0 International