Crate implements a plugin loading infrastructure making it possible to develop plugins for crate.

A plugin must at least:

  • implement the io.crate.Plugin interface
  • register its implementation at META-INF/services/io.crate.Plugin so crate plugin load can find it.

See our example crate plugin for details about that.

Plugin Crate Dependency

In order to develop a plugin against a crate release, a dependency to the crate’s server libraries must be set up.


Define bintray (jCenter) repository:

repositories {

Add crate to compile dependencies:

dependencies {
    compile 'io.crate:crate:<VERSION>'


Add bintray (jCenter) as a repository to your maven settings.xml:



Add crate as a dependency:


Plugin Loading

Loading of plugins is done by crate for searching all class path element resources for a META-INF/services/io.crate.Plugin file.

Inside this file just one line is allowed defining the full qualified class name which is implementing the Plugin interface. This is almost the same like you may know from Java’s ServiceLoader.

Constructor with Settings argument

Crate passes a Settings instance to the plugin implementation constructor if such a constructor exists. Otherwise an empty constructor is used. By using the Settings instance, a plugin can process existing settings and/or implement it’s own custom setting entries.

The example crate plugin makes use of that to implement a custom setting.

Plugin Interface

Crate uses Guice module binding concept and so does a plugin. As described at the io.crate.Plugin interface, a plugin can load serveral module types by implementing relevant methods:

  • lifecycle services
  • node level modules
  • index level modules
  • shard level modules

Besides of implementing own modules, a plugin can also listen to other’s module bindings. For example, as our example crate plugin does, to the binding of the ScalarFunctionModule in order to register scalar functions. This can be achieved by implementing a related onModule(AnyModule module) method:

public void onModule(ScalarFunctionModule module) {

Again, checkout the example crate plugin to see this in action.

AbstractPlugin Class

A good start for developing an own plugin is to extend the implementation from io.crate.plugin.AbstractPlugin, which already implements all methods required by the Plugin interface. So one must just overwrite the relevant ones:

public class MyAwesomePlugin extends AbstractPlugin {

    public String name() {
        return "myawesome-plugin";

    public String description() {
        return "A really awesome crate plugin";

    public Settings additionalSettings() {
        Settings.Builder builder = Settings.builder();
        // This plugin enables ``stats`` by default
        builder.put("stats.enabled", true);

Methods name and description must be always implemented, anything else is already implemented by the abstract plugin class.

Installing a Plugin

Installing a plugin is simply done by copying the plugin’s JAR file(s) somewhere into the class path or to one of the following places:

  • <CRATE_HOME>/plugins/
  • <CRATE_HOME>/plugins/<SOME_PLUGIN_NAME>/lib/