Collections
Collections are the object stores where your data lives. Every object you upsert belongs to a collection.
Collection Types
Endee supports two types of collections:
Dense Collections
Dense collections enable semantic search: finding items based on meaning rather than exact keyword matches. Each object contains a vector field a list of numbers, one number per dimension representing the meaning of your content.
Use dense collections when you want to:
- Find semantically similar documents
- Power recommendation systems
- Enable image/video similarity search
Python
from endee import Endee, Precision
client = Endee()
client.create_collection(
name="my_collection",
dimension=384, # must match your embedding model's output size
space_type="cosine",
precision=Precision.INT16
)Hybrid Collections
Hybrid collections combine dense vector search with sparse vector search (e.g keyword matching). This gives you the best of both worlds: semantic similarity and exact term matching in a single query.
Use hybrid collections for:
- Document retrieval in RAG pipelines
- Search where both meaning and keywords matter
- Any use case where dense-only search misses exact terminology
Python
client.create_collection(
name="hybrid_collection",
dimension=384,
sparse_model="endee_bm25", # enables hybrid search with BM25
space_type="cosine",
precision=Precision.INT16
)See the Sparse Vectors (BM25) guide for installing endee-model and generating BM25 embeddings.
Sparse Model Options:
| Model | Description |
|---|---|
| default | Bring your own sparse vectors (you provide custom indices and values) |
| endee_bm25 | Use Endee’s BM25 model via the endee-model package to generate sparse vectors. See Sparse Vectors (BM25) |
The sparse_model parameter
For sparse_model you have two options depending on which sparse model you use:
sparse_model="endee_bm25"- use this when your sparse vectors come fromendee/bm25. Endee holds the IDF weights on its server and applies them automatically, so you only need to send the TF weights from your client.sparse_model="default"- use this for SPLADE models or any other BM25 model. In this case Endee treats the values you send as final scores and does no further calculation. If you are using another BM25 model (notendee/bm25), you must compute the full IDF scores yourself on the client before sending them.
Collection Parameters
When creating a collection, configure the following parameters:
| Parameter | Description | Default |
|---|---|---|
| Name | Unique name for your collection | Required |
| Dimension | Dense vector dimensionality (max 10,000) | Required |
| Space Type | Distance metric: cosine, l2, or ip (inner product) | Required |
| Sparse Model | Enables hybrid search: default or endee_bm25 | None |
| M | HNSW graph connectivity (higher values improve recall, more memory) | 16 |
| EF Construction | HNSW build-time parameter (higher values improve collection quality) | 128 |
| Precision | Vector quantization level (see Precision) | INT8 |
Python
# All parameters explicitly set
client.create_collection(
name="my_collection",
dimension=768,
space_type="cosine",
M=32, # higher connectivity = better recall, more memory
ef_con=200, # higher = better index quality, slower build
precision=Precision.FLOAT32
)Distance Metrics
Choose the appropriate distance metric based on your embedding model and use case:
| Metric | Value | Description | Best For |
|---|---|---|---|
| Cosine | cosine | Measures the angle between vectors (direction only) | Text embeddings, normalized vectors |
| L2 | l2 | Euclidean distance (magnitude and direction) | Image embeddings, spatial data |
| Inner Product | ip | Dot product similarity | Maximum inner product search (e.g., recommendation) |
Most embedding models (e.g., Sentence Transformers, OpenAI) produce normalized objects. Use cosine by default.
HNSW Algorithm
Both collection types use the HNSW (Hierarchical Navigable Small World) algorithm for Approximate Nearest Neighbor (ANN) searches. The two build-time parameters (M and EF Construction) control the quality vs. memory/build-time trade-off.
| Parameter | Effect of Increasing |
|---|---|
| M | Higher recall, more memory usage |
| EF Construction | Better collection quality, slower build time |
The defaults (M=16, EF Construction=128) are good starting points for most workloads.
EF Construction is a build-time parameter set when creating the collection — it controls collection quality and cannot be changed without recreating the collection. EF (also called ef_search) is a separate query-time parameter that controls how many candidates are explored per search query. The two are independent. See Search: Query Parameters.
Collection Management
List Collections
Python
collections = client.list_collections()
for col in collections:
print(col)Get Collection
Returns a handle to an existing collection for querying and upserting.
Python
collection = client.get_collection("my_collection")Delete Collection
Deletion is irreversible. All objects in the collection are permanently removed.
Python
client.delete_collection("my_collection")