# Write Custom Plugins

Pinot allows user to easily create and use new plugins to support custom needs. The developer needs to implement a few standard interfaces specific to the type of plugins in Java.

Once the code is ready, you can put the complete JAR file in pinot `/plugins` directory. All the classes in plugins directory are loaded at pinot's startup.

As of Apache Pinot 1.3.0 there's an additional support for a new structure:

```
 /plugins
    /my-custom-plugin
       /classes/... or /my-custon-plugin-1.0.0.jar
       /com-2.3.1.jar
       /foo-1.2.1.jar
       /bar-3.1.1.jar
       /pinot-plugin.properties
```

This way there's no need to shade classes anymore, because Pinot will ensure isolation and proper ordered loading of these classes. Pinot will only expose the classes in pinot-spi. The `classes`-directory or `my-custon-plugin-1.0.0.jar` will contain custom compiled Java-code of the plugin. The only difference is that the `classes` will always be loaded first. The jars are added afterward as ordered by the OS. Next to these `classes` are all the runtime required dependencies, but without the pinot-jars. The `pinot-plugin.properties` is currently a placeholder to recognize this new structure. In the future this file will be used to store metadata for the plugin.

Currently the following keys are supported:

parent.realmIdSpecify the id of the parent realm. The parentRealm is the final classloader to look for classes. If not defined, then there's no parent realmimportFrom.\[realmId]Comma separated list of packaged that the plugin imports from another realm. When looking for a class, these imports are verified first. The following is used by all plugins and cannot be replaced: `importFrom.pinot=org.apache.pinot.spi`

Users of [Apache Maven](http://maven.apache.org) can use the pinot assembly descriptor to generate this new structure. This can be done by added the following to the `pom.xml`.

```
  <plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-assembly-plugin</artifactId>
    <version>3.7.1</version>
    <dependencies>
      <dependency>
        <groupId>org.apache.pinot</groupId>
        <artifactId>assembly-descriptor</artifactId>
        <version>1.3.0</version> <!-- should match pinot version -->
      </dependency>
    </dependencies>
    <executions>
      <execution>
        <id>make-assembly</id>
        <phase>package</phase>
        <goals>
          <goal>single</goal>
        </goals>
        <configuration>
          <descriptorRefs>
            <descriptorRef>pinot-plugin</descriptorRef>
          </descriptorRefs>
        </configuration>
      </execution>
    </executions>
  </plugin>
```

Alternative you can use the old structure where your plugin is packaged in a single shaded jar or uberjar:

```
 /plugins
    /my-custom-plugin
       /my-custom-plugin-1.0.0-shaded.jar
```

Plugins using this structure will be able to use all classes provided by Pinot, so dependencies that are not provided by Pinot (the ones you don't import as provided) must be *shaded*. Plugins using the old structure are encourage to *relocate* (i.e. rename the original package name) commonly used dependencies such as `guava`, `jackson` using a plugin specific prefix to prevent class collisions with Pinot.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.pinot.apache.org/develop-and-contribute/plugin-architecture/write-custom-plugins.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.