> ## Documentation Index
> Fetch the complete documentation index at: https://doc.lucidworks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Index Stage SDK

export const LwTemplate = ({title = "Key questions to get you started", icon = "sparkles", cta = "Powered by Agent Studio", linkHref = "https://lucidworks.com/demo/?utm_source=docs&utm_medium=referral&utm_campaign=docs_cta_ai"}) => {
  const [isLoaded, setIsLoaded] = useState(false);
  useEffect(() => {
    const timer = setTimeout(() => {
      setIsLoaded(true);
    }, 500);
    return () => clearTimeout(timer);
  }, []);
  return <div className="lw-template-container">
      <Card title={title} icon={icon}>
        {isLoaded && <span dangerouslySetInnerHTML={{
    __html: `<lw-template id="a029c1a9-28be-427e-b0e1-5d918920246a"></lw-template
            >`
  }} />}
        <Link href={linkHref} className="agent-studio-link text-left text-gray-600 gap-2 dark:text-gray-400 text-sm font-medium flex flex-row items-center hover:text-primary dark:hover:text-primary-light group-hover:text-primary group-hover:dark:text-primary-light">Powered by Lucidworks Agent Studio</Link>
      </Card>
    </div>;
};

[localhost link]: http://localhost:3000/docs/5/fusion/dev-portal/index-stage-sdk

[mintlify link]: https://doc.lucidworks.com/docs/5/fusion/dev-portal/index-stage-sdk

[old doc.lw link]: https://doc.lucidworks.com/fusion/5.9/159

Lucidworks provides an Index Stage SDK in a public repository on [GitHub](https://github.com/lucidworks/index-stage-sdk) with all the resources you need to develop custom index stages with Java.

<LwTemplate />

## Get started

Clone the repository to get started:

```bash theme={"dark"}
git clone https://github.com/lucidworks/index-stage-sdk
```

Ensure you are using the correct SDK version for your Fusion version:

|      Fusion versions | Index Stage SDK version | Required JDK |
| -------------------: | :---------------------: | :----------: |
|               5.9.15 |          2.0.0          |      11      |
| 5.4.0 through 5.9.14 |          1.2.0          |       8      |

See [Gradle quickstart](https://docs.gradle.org/current/userguide/tutorial_java_projects.html) documentation for more information on Java Projects.

## Concepts

### Index stage configuration

The [index stage configuration file](https://github.com/lucidworks/index-stage-sdk/blob/master/index-stage-plugin-sdk/src/main/java/com/lucidworks/indexing/config/IndexStageConfig.java) defines configuration options specific to the index stage instance. The options defined in this configuration file are available to the user in the Fusion UI and the API. The plugin configuration class extends the index stage configuration file and is annotated with `@RootScheme`.

Adding `@Property` and type annotations to your stage configuration interface methods defines metadata and type requirements for your plugin configuration fields. This is similar to Fusion’s [connector configuration schema](/docs/5/fusion/dev-portal/connectors-sdk/java-sdk).

### APIs

The Index Stage SDK includes several APIs for communication with other Fusion components via the [Fusion](https://github.com/lucidworks/index-stage-sdk/blob/master/index-stage-plugin-sdk/src/main/java/com/lucidworks/indexing/api/fusion/Fusion.java) object. This object is passed to the stage during initialization.

* **RestCall**: The [RestCall API](https://github.com/lucidworks/index-stage-sdk/blob/master/index-stage-plugin-sdk/src/main/java/com/lucidworks/indexing/api/fusion/RestCall.java) provides access to the [Fusion REST API](/docs/5/fusion/dev-portal/rest-apis). You can find an [example](https://github.com/lucidworks/index-stage-sdk/blob/master/examples/sample-plugin-stage/src/main/java/com/lucidworks/sample/query/ExternalQueryStage.java) of its usage in the Index Stage SDK repository.

* **Blobs**: The [Blobs API](https://github.com/lucidworks/index-stage-sdk/blob/master/index-stage-plugin-sdk/src/main/java/com/lucidworks/indexing/api/fusion/Blobs.java) enables interactions with the [Blob Store API](/api-reference/blobs/get-blob-store-service-status).

* **Documents**: The [Documents API](https://github.com/lucidworks/index-stage-sdk/blob/master/index-stage-plugin-sdk/src/main/java/com/lucidworks/indexing/api/fusion/Documents.java) provides a method for creating new document instances. This is useful for custom stages that [output multiple documents](#index-stage-configuration) from a single input document.

### Plugins

A plugin is a ZIP file that contains one or more index stage implementations. The file contains JAR files for stage definitions and additional dependencies. It also contains a manifest file that holds the metadata Fusion uses to run the plugin.

#### Add a plugin to Fusion

Plugins are uploaded to the Blob store:

1. Navigate to **System > Blobs**.
2. Click **Add**.
3. Select **Index Stage Plugin**.
   <Frame caption="Add an index stage plugin.">
     <img src="https://mintcdn.com/lucidworks/1FfsxYVDR4XL56q9/assets/images/5.1/java-stage-sdk-upload.png?fit=max&auto=format&n=1FfsxYVDR4XL56q9&q=85&s=a8e36a9a4425044cece2ec35cfd481c6" alt="Index stage plugin" width="1280" height="657" data-path="assets/images/5.1/java-stage-sdk-upload.png" />
   </Frame>
4. Select your plugin file.
5. Click **Upload**.

Plugin stage classes must implement the [`com.lucidworks.indexing.api.IndexStage`](https://github.com/lucidworks/index-stage-sdk/blob/master/index-stage-plugin-sdk/src/main/java/com/lucidworks/indexing/api/IndexStage.java) interface and be annotated with [`com.lucidworks.indexing.api.Stage`](https://github.com/lucidworks/index-stage-sdk/blob/master/index-stage-plugin-sdk/src/main/java/com/lucidworks/indexing/api/Stage.java) annotation. For additional convenience, stage implementation can extend the [`com.lucidworks.indexing.api.IndexStageBase`](https://github.com/lucidworks/index-stage-sdk/blob/master/index-stage-plugin-sdk/src/main/java/com/lucidworks/indexing/api/IndexStageBase.java) class, which already contains initialization logic and some helpful methods.

### Lifecycle

#### Creation and initialization

Fusion begins by creating an `IndexStage` instance. After the index stage is created, it is initialized using the `init(T config, Fusion fusion)` method. This allows for the creation of internal storage instructions and the validation of the configuration.

Initialization occurs immediately after the stage configuration is saved in Fusion. The stage can be maintained and used by Fusion for extensive periods of time, even if no documents are being processed through the stage. This should be considered when making decisions on resource allocation.

#### Document processing

Once the initialization process completes, Fusion calls the `process` method for each document the index pipeline processes.

In most use cases, index stages process a single input document and emit a single output document. For these cases, the `process(Document document, Context context)` method should be used.

In other cases, index stages process a single input document but emit multiple output documents. For these cases, the `process(Document document, Context context, Consumer<Document> output)` method should be used. The output documents are sent by calling `output.accept(doc)`.

A single stage instance can be used to process multiple documents, and the `process` method can be called from multiple concurrently running threads. Additionally, Fusion can initialize and maintain multiple stage instances with the same configuration in separate indexing service nodes. Therefore, it’s important to ensure the plugin stage implementation is thread-safe and the processing logic is stateless.

<Note>
  If the index stage throws an exception while processing a document, that document will not be processed further. It does not prevent other documents from being processed. Check the logs for information regarding the exception.
</Note>

#### Logging

The Index Stage SDK uses the SLF4J Reporter logging API.

#### Index Stage SDK Javadocs

See the [Javadocs](https://javadoc.lucidworks.com/index-sdk-javadocs/2.0.0/) for complete details about all packages and classes.