Concepts

Understanding the core concepts of Endee Vector Database.

Indexes

Indexes are the vector stores where your data lives. Endee supports two types of indexes:

Dense Indexes: For semantic similarity search using vector embeddings
Hybrid Indexes: Combine dense vectors with sparse vector search

Both index types are optimized for fast Approximate Nearest Neighbor (ANN) searches using the HNSW algorithm.

Dense Indexes

Dense indexes enable semantic search — finding items based on meaning rather than exact keyword matches. Use dense indexes when you want to:

Find semantically similar documents
Power recommendation systems
Enable image/video similarity search

Hybrid Indexes

Hybrid indexes combine dense vector search with sparse vector search. To create a hybrid index, specify the sparse_dim parameter:


client.create_index(
    name="my_hybrid_index",
    dimension=384,        # Dense vector dimension
    sparse_dim=30000,     # Sparse vector dimension
    space_type="cosine"
)

Use hybrid indexes for document retrieval in RAG pipelines where you need both semantic and keyword matching.

Index Parameters

Parameter	Description	Default
`name`	Unique name for your index	Required
`dimension`	Dense vector dimensionality (max 10000)	Required
`space_type`	Distance metric: `"cosine"`, `"l2"`, or `"ip"`	Required
`sparse_dim`	Sparse vector dimension (enables hybrid search)	None
`M`	HNSW graph connectivity	16
`ef_con`	HNSW construction parameter	128
`precision`	Vector quantization precision	`INT8D`

Precision Options

The precision parameter controls how vectors are stored:

Precision	Description	Storage	Speed	Accuracy
`BINARY`	1-bit quantization	Smallest	Fastest	Lower
`INT8D`	8-bit integer (default)	Small	Fast	Good
`INT16D`	16-bit integer	Medium	Medium	Higher
`FLOAT16`	16-bit float	Medium	Medium	High
`FLOAT32`	32-bit float	Largest	Slower	Highest

Query Parameters

Dense Query

Parameter	Description	Default
`vector`	Query vector (must match index dimension)	Required
`top_k`	Number of results to return (max 512)	10
`ef`	Search quality parameter (max 1024)	128
`include_vectors`	Include vector data in results (dense only)	False
`filter`	Filter criteria (array of filter objects)	None

Hybrid Query

For hybrid indexes, include sparse query components:

Parameter	Description	Default
`sparse_indices`	Non-zero term positions in sparse query	Required (hybrid)
`sparse_values`	Weights for sparse query terms	Required (hybrid)

Result Fields

Field	Description
`id`	Vector identifier
`similarity`	Similarity score
`distance`	Distance score (1.0 - similarity)
`meta`	Metadata dictionary
`norm`	Vector norm
`vector`	Dense Vector data (if `include_vectors=True`)

Vectors

Vectors are the fundamental data units stored in an index.

Dense Vector Fields

Field	Required	Description
`id`	Yes	Unique identifier
`vector`	Yes	Dense embedding array
`meta`	No	Arbitrary metadata object
`filter`	No	Key-value pairs for filtering

Hybrid Vector Fields

For hybrid indexes, include sparse vector components:

Field	Required	Description
`sparse_indices`	Yes	Non-zero term positions in sparse vector
`sparse_values`	Yes	Weights for each sparse index

sparse_indices and sparse_values must have the same length. Values in sparse_indices must be within [0, sparse_dim).

Note: Maximum batch size is 1000 vectors per upsert call.

Filtering

Use the filter parameter to restrict search results based on conditions.

Operators

Operator	Description	Example
`$eq`	Exact match	`{"status": {"$eq": "published"}}`
`$in`	Match any in list	`{"tags": {"$in": ["ai", "ml"]}}`
`$range`	Numeric range (inclusive)	`{"score": {"$range": [70, 95]}}`

Notes:

Operators are case-sensitive and must be prefixed with $
All filters are combined with logical AND
$range supports values within [0 – 999]

Authentication

By default, Endee runs without authentication for easy local development. To secure your instance, set the NDD_AUTH_TOKEN environment variable when starting the server.

Enabling Authentication

In your docker-compose.yml:


environment:
  NDD_AUTH_TOKEN: "your-secret-token"

Using Authentication

When authentication is enabled, you must provide the same token in two places:

1. Dashboard Access

Enter the token in the dashboard login to access the web interface at http://localhost:8080.

2. Python SDK

Pass the token when initializing the client:


from endee import Endee
 
# With authentication
client = Endee("your-secret-token")

3. REST API

Include the token in the Authorization header:


curl -X GET http://localhost:8080/api/v1/index/list \
  -H "Authorization: Bearer your-secret-token"

Important: All API requests will fail if the token doesn’t match the server’s NDD_AUTH_TOKEN. Keep your token secure and never expose it in client-side code.