Java Types

The Endee Java SDK provides type-safe classes with builder patterns for full compile-time safety. This page documents all available types, enums, builders, and result classes.

Imports

Import types from the io.endee.client package:


import io.endee.client.Endee;
import io.endee.client.Index;
import io.endee.client.types.*;
import io.endee.client.exception.*;

Enums

Precision

Defines the quantization precision levels for vector storage and search.


public enum Precision {
    BINARY,
    INT8D,
    INT16D,
    FLOAT16,
    FLOAT32
}

Value	Description
`BINARY`	Binary quantization (1-bit) - smallest storage, fastest search
`INT8D`	8-bit integer quantization (default) - balanced performance
`INT16D`	16-bit integer quantization - higher precision
`FLOAT16`	16-bit floating point - good balance
`FLOAT32`	32-bit floating point - highest precision

Usage:


import io.endee.client.types.Precision;
 
CreateIndexOptions options = CreateIndexOptions.builder("my_index", 384)
    .precision(Precision.INT8D)
    .build();

SpaceType

Defines the distance metric used for similarity calculations.


public enum SpaceType {
    COSINE,
    L2,
    IP
}

Value	Description
`COSINE`	Cosine similarity - measures angle between vectors (default)
`L2`	Euclidean distance - measures straight-line distance
`IP`	Inner product - measures dot product similarity

Builder Classes

CreateIndexOptions

Options for creating a new index. Uses the builder pattern with required name and dimension parameters.

Builder:


CreateIndexOptions.builder(String name, int dimension)
    .spaceType(SpaceType)        // Default: COSINE
    .m(int)                      // Default: 16
    .efCon(int)                  // Default: 128
    .precision(Precision)        // Default: INT8D
    .sparseDimension(Integer)    // Optional, for hybrid indexes
    .build()

Property	Type	Required	Description
`name`	`String`	Yes	Unique name for the index (alphanumeric + underscore, max 48 chars)
`dimension`	`int`	Yes	Vector dimensionality (must match embedding model output, max 10,000)
`spaceType`	`SpaceType`	No	Distance metric (default: `COSINE`)
`m`	`int`	No	Graph connectivity parameter (default: 16)
`efCon`	`int`	No	Construction-time quality parameter (default: 128)
`precision`	`Precision`	No	Quantization precision (default: `INT8D`)
`sparseDimension`	`Integer`	No	Sparse vector dimension for hybrid indexes

Example:


CreateIndexOptions options = CreateIndexOptions.builder("documents", 384)
    .spaceType(SpaceType.COSINE)
    .precision(Precision.INT8D)
    .m(16)
    .efCon(128)
    .build();
 
client.createIndex(options);

VectorItem

Represents a vector to be upserted into an index. Uses the builder pattern with required id and vector parameters.

Builder:


VectorItem.builder(String id, double[] vector)
    .meta(Map<String, Object>)               // Optional
    .filter(Map<String, Object>)             // Optional
    .sparseIndices(int[])                    // Optional, for hybrid
    .sparseValues(double[])                  // Optional, for hybrid
    .build()

Property	Type	Required	Description
`id`	`String`	Yes	Unique identifier for the vector
`vector`	`double[]`	Yes	Dense embedding vector
`sparseIndices`	`int[]`	No	Non-zero term positions for hybrid search
`sparseValues`	`double[]`	No	Weights for each sparse index
`meta`	`Map<String, Object>`	No	Arbitrary metadata map
`filter`	`Map<String, Object>`	No	Key-value pairs for filtering during queries

For hybrid indexes, sparseIndices and sparseValues must have the same length, and values in sparseIndices must be within [0, sparseDimension).

Example:


List<VectorItem> vectors = List.of(
    VectorItem.builder("doc1", new double[] {0.1, 0.2, 0.3})
        .meta(Map.of("title", "Document 1"))
        .filter(Map.of("category", "tech"))
        .build(),
 
    VectorItem.builder("doc2", new double[] {0.4, 0.5, 0.6})
        .sparseIndices(new int[] {10, 50, 200})
        .sparseValues(new double[] {0.8, 0.5, 0.3})
        .meta(Map.of("title", "Document 2"))
        .build()
);
 
index.upsert(vectors);

QueryOptions

Options for querying an index. Uses the builder pattern.

Builder:


QueryOptions.builder()
    .vector(double[])                        // Required for dense search
    .topK(int)                               // Required
    .ef(int)                                 // Default: 128
    .filter(List<Map<String, Object>>)       // Optional
    .includeVectors(boolean)                 // Default: false
    .sparseIndices(int[])                    // Optional, for hybrid search
    .sparseValues(double[])                  // Optional, for hybrid search
    .build()

Property	Type	Required	Description
`vector`	`double[]`	No	Dense query vector
`topK`	`int`	Yes	Number of results to return (max: 512)
`filter`	`List<Map<String, Object>>`	No	Filter conditions (combined with AND)
`ef`	`int`	No	Search quality parameter (default: 128, max: 1024)
`includeVectors`	`boolean`	No	Include vector data in results (default: false)
`sparseIndices`	`int[]`	No	Sparse query positions for hybrid search
`sparseValues`	`double[]`	No	Sparse query weights for hybrid search

For hybrid queries, you can provide vector only (dense search), sparseIndices/sparseValues only (sparse search), or all three (hybrid search).

Example:


QueryOptions options = QueryOptions.builder()
    .vector(new double[] {0.15, 0.25})
    .topK(10)
    .ef(128)
    .includeVectors(true)
    .filter(List.of(
        Map.of("category", Map.of("$eq", "tech")),
        Map.of("score", Map.of("$range", List.of(80, 100)))
    ))
    .build();
 
List<QueryResult> results = index.query(options);

Result Classes

QueryResult

Represents a single result from a query.

Property	Type	Description
`id`	`String`	Vector identifier
`similarity`	`double`	Similarity score (higher is more similar)
`distance`	`double`	Distance value (1 - similarity)
`meta`	`Map<String, Object>`	Metadata attached to the vector
`filter`	`Map<String, Object>`	Filter fields attached to the vector
`norm`	`double`	Normalization factor
`vector`	`double[]`	Vector data (only if `includeVectors` was true)

Getter Methods: getId(), getSimilarity(), getDistance(), getMeta(), getFilter(), getNorm(), getVector()

Example:


List<QueryResult> results = index.query(
    QueryOptions.builder()
        .vector(new double[] {0.15, 0.25})
        .topK(5)
        .build()
);
 
for (QueryResult result : results) {
    System.out.println("ID: " + result.getId());
    System.out.println("Similarity: " + result.getSimilarity());
    System.out.println("Meta: " + result.getMeta());
}

IndexDescription

Description of an index returned by index.describe().

Property	Type	Description
`name`	`String`	Index name
`spaceType`	`SpaceType`	Distance metric
`dimension`	`int`	Vector dimensionality
`sparseDimension`	`int`	Sparse vector dimension
`isHybrid`	`boolean`	Whether the index supports hybrid search
`count`	`long`	Number of vectors in the index
`precision`	`Precision`	Quantization precision
`m`	`int`	Graph connectivity parameter

Getter Methods: getName(), getSpaceType(), getDimension(), getSparseDimension(), isHybrid(), getCount(), getPrecision(), getM()

Example:


IndexDescription info = index.describe();
 
System.out.println("Index: " + info.getName());
System.out.println("Vectors: " + info.getCount());
System.out.println("Hybrid: " + info.isHybrid());
System.out.println("Precision: " + info.getPrecision());

VectorInfo

Detailed information about a single vector returned by index.getVector().

Property	Type	Description
`id`	`String`	Vector identifier
`vector`	`double[]`	The full vector data
`meta`	`Map<String, Object>`	Metadata attached to the vector
`filter`	`Map<String, Object>`	Filter fields attached to the vector
`norm`	`double`	Normalization factor

Getter Methods: getId(), getVector(), getMeta(), getFilter(), getNorm()

Example:


VectorInfo vectorInfo = index.getVector("doc1");
 
System.out.println("ID: " + vectorInfo.getId());
System.out.println("Norm: " + vectorInfo.getNorm());
System.out.println("Meta: " + vectorInfo.getMeta());
System.out.println("Vector: " + Arrays.toString(vectorInfo.getVector()));

Exception Classes

EndeeException

Base exception class for all client-side errors (network issues, serialization failures, etc.).


import io.endee.client.exception.EndeeException;
 
try {
    client.createIndex(options);
} catch (EndeeException e) {
    System.err.println("Client Error: " + e.getMessage());
}

EndeeApiException

Exception for API-specific errors. Extends EndeeException and provides HTTP status code and error body.

Method	Return Type	Description
`getStatusCode()`	`int`	HTTP status code
`getErrorBody()`	`String`	Error response body
`getMessage()`	`String`	Error message


import io.endee.client.exception.EndeeApiException;
 
try {
    client.createIndex(options);
} catch (EndeeApiException e) {
    System.err.println("Status: " + e.getStatusCode());
    System.err.println("Body: " + e.getErrorBody());
}

Common HTTP Status Codes:

Code	Description
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid or missing authentication
403	Forbidden - Insufficient permissions
404	Not Found - Index or vector doesn’t exist
409	Conflict - Index already exists
500	Internal Server Error

Index Class

The Index class is returned by client.getIndex(name) and provides methods for vector operations.

Method	Return Type	Description
`upsert(List<VectorItem>)`	`String`	Insert or update vectors
`query(QueryOptions)`	`List<QueryResult>`	Search for similar vectors
`deleteVector(String id)`	`String`	Delete a vector by ID
`deleteWithFilter(List<Map>)`	`String`	Delete vectors by filter
`getVector(String id)`	`VectorInfo`	Get a vector by ID
`describe()`	`IndexDescription`	Get index metadata
`isHybrid()`	`boolean`	Check if index is hybrid

Type Summary

Type	Kind	Description
`SpaceType`	Enum	Distance metric options
`Precision`	Enum	Quantization precision levels
`CreateIndexOptions`	Builder Class	Index creation parameters
`VectorItem`	Builder Class	Vector for upserting
`QueryOptions`	Builder Class	Query parameters
`QueryResult`	Result Class	Single query result
`IndexDescription`	Result Class	Index description
`VectorInfo`	Result Class	Single vector information
`EndeeException`	Exception	Client-side errors
`EndeeApiException`	Exception	API-specific errors