Skip to Content
Java SDKQuickstart

Java SDK Quickstart

Get started with the Endee Java SDK to build powerful vector search applications. This guide will walk you through installation, setup, and creating your first index.

Requirements

  • Java 17 or higher
  • Endee Local server running (see Quick Start)

New to Endee? Set up your local environment first by following the Quick Start Guide.

Installation

The badge below always reflects the latest published version. The code snippets are pinned to a specific version — replace it with the version shown in the badge if a newer one is available.

Maven Central

Always verify the latest version on Maven Central  before adding the dependency.

Add the dependency to your pom.xml:

<dependency>
    <groupId>io.endee</groupId>
    <artifactId>endee-java-client</artifactId>
    <version>1.0.0</version>
</dependency>

Setup Endee and Create Index

Initialize the Client

The Endee client is the main interface for all vector operations. Initialize it to connect to your local server:

import io.endee.client.Endee;
import io.endee.client.exception.EndeeApiException;
 
public class EndeeClient {
  public static void main(String[] args) throws EndeeApiException {
    // Connect to local Endee server (defaults to localhost:8080)
    Endee client = new Endee();
  }
}

Using Authentication? If your server has NDD_AUTH_TOKEN set, pass the same token when initializing: java Endee client = new Endee("your-auth-token"); See Authentication for details.

Create a Dense Index

Create a vector index for semantic similarity search using the builder pattern:

import io.endee.client.Endee;
import io.endee.client.types.Precision;
import io.endee.client.types.SpaceType;
import io.endee.client.types.CreateIndexOptions;
import io.endee.client.exception.EndeeApiException;
 
public class CreateDenseIndex {
  public static void main(String[] args) throws EndeeApiException {
    Endee client = new Endee();
 
    CreateIndexOptions options = CreateIndexOptions.builder("my_vectors", 384)
        .spaceType(SpaceType.COSINE)
        .precision(Precision.INT8)
        .build();
 
    client.createIndex(options);
  }
}

Dense Index Parameters: (see CreateIndexOptions)

ParameterDescription
nameUnique name for your index (alphanumeric + underscore, max 48 chars)
dimensionVector dimensionality (must match your embedding model’s output, max 10,000)
spaceTypeDistance metric - COSINE, L2, or IP (see SpaceType)
mGraph connectivity - higher values increase recall but use more memory (default: 16)
efConConstruction-time parameter - higher values improve index quality (default: 128)
precisionQuantization precision (default: Precision.INT8) - see Precision

Create a Hybrid Index

Hybrid indexes combine dense vector search with sparse vector search for improved retrieval. Add the sparseDimension parameter to enable hybrid search:

CreateIndexOptions options = CreateIndexOptions.builder("hybrid_index", 384)
    .sparseDimension(30000)    // Sparse vector dimension (vocabulary size)
    .spaceType(SpaceType.COSINE)
    .precision(Precision.INT8)
    .build();
 
client.createIndex(options);

Additional Hybrid Parameter:

ParameterDescription
sparseDimensionSparse vector dimension (e.g., vocabulary size for SPLADE)

List and Access Indexes

// List all indexes (returns JSON string)
String indexes = client.listIndexes();
 
// Get reference to an existing index
Index index = client.getIndex("my_vectors");
 
// Delete an index
client.deleteIndex("my_vectors");

Complete Example

Here’s a complete example putting it all together:

import io.endee.client.Endee;
import io.endee.client.Index;
import io.endee.client.types.*;
 
import java.util.List;
import java.util.Map;
 
public class EndeeExample {
    public static void main(String[] args) {
        // Initialize client
        Endee client = new Endee();
 
        // Create a dense index
        CreateIndexOptions options = CreateIndexOptions.builder("documents", 384)
            .spaceType(SpaceType.COSINE)
            .precision(Precision.INT8)
            .build();
 
        client.createIndex(options);
 
        // Get the index
        Index index = client.getIndex("documents");
 
        // Add vectors
        List<VectorItem> vectors = List.of(
            VectorItem.builder("doc1", new double[] {0.1, 0.2, 0.3 /* ... */})
                .meta(Map.of("title", "First Document"))
                .filter(Map.of("category", "tech"))
                .build(),
 
            VectorItem.builder("doc2", new double[] {0.3, 0.4, 0.5 /* ... */})
                .meta(Map.of("title", "Second Document"))
                .filter(Map.of("category", "science"))
                .build()
        );
 
        index.upsert(vectors);
 
        // Query the index
        List<QueryResult> results = index.query(
            QueryOptions.builder()
                .vector(new double[] {0.15, 0.25 /* ... */})
                .topK(5)
                .build()
        );
 
        for (QueryResult item : results) {
            System.out.println("ID: " + item.getId() + ", Similarity: " + item.getSimilarity());
        }
    }
}

Next Steps

Now that you have your index set up, learn how to:

TypesUsage