Python SDK Usage

This guide covers the core operations for working with vectors in Endee: upserting, querying, and deleting data.

Upserting Vectors

The index.upsert() method adds or updates vectors in an existing index. Each vector contains a unique identifier, the vector data, optional metadata, and optional filter fields.


from endee.endee_client import Endee
 
client = Endee(token="your-token-here")
 
# Get reference to your index
index = client.get_index(name="your-index-name")
 
# Insert multiple vectors in a batch
index.upsert([
    {
        "id": "vec1",
        "vector": [...],  # Your vector
        "meta": {"title": "First document"},
        "filter": {"tags": "important"}
    },
    {
        "id": "vec2",
        "vector": [...],  # Another vector
        "meta": {"title": "Second document"},
        "filter": {"visibility": "public", "tags": "important"}
    }
])

Vector Object Fields:

Field	Required	Description
`id`	Yes	Unique identifier for the vector
`vector`	Yes	Array of floats representing the embedding
`meta`	No	Arbitrary metadata object for storing additional information
`filter`	No	Key-value pairs for structured filtering during queries

Querying the Index

The index.query() method performs a similarity search using a query vector. It returns the closest vectors based on the index’s distance metric.


index = client.get_index(name="your-index-name")
 
# Query with custom parameters
results = index.query(
    vector=[...],         # Query vector
    top_k=5,              # Number of results to return
    ef=128,               # Runtime parameter for search quality
    include_vectors=True  # Include vector data in results
)
 
# Process results
for item in results:
    print(f"ID: {item['id']}, Similarity: {item['similarity']}")
    print(f"Metadata: {item['meta']}")

Query Parameters:

Parameter	Description
`vector`	Query vector (must match index dimension)
`top_k`	Number of nearest neighbors to return
`ef`	Runtime search parameter - higher values improve recall but increase latency
`include_vectors`	Whether to return the actual vector data in results

Filtered Querying

The index.query() method supports structured filtering using the filter parameter. This restricts search results based on filter conditions in addition to vector similarity.

Pass an array of filter objects where each object defines a condition. All filters are combined with logical AND — a vector must match all conditions to be included.


index = client.get_index(name="your-index-name")
 
# Query with multiple filter conditions (AND logic)
filtered_results = index.query(
    vector=[...],
    top_k=5,
    ef=128,
    include_vectors=True,
    filter=[
        {"tags": {"$eq": "important"}},
        {"visibility": {"$eq": "public"}}
    ]
)

Filtering Operators

Operator	Description	Supported Type	Example
`$eq`	Matches values that are equal	String, Number	`{"status": {"$eq": "published"}}`
`$in`	Matches any value in the provided list	String	`{"tags": {"$in": ["ai", "ml"]}}`
`$range`	Matches values between start and end (inclusive)	Number	`{"score": {"$range": [70, 95]}}`

Important Notes:

Operators are case-sensitive and must be prefixed with $
Filters operate on fields provided under the filter key during upsert
The $range operator supports values only within [0 – 999]. Normalize larger values before upserting

Filter Examples


# Equal operator - exact match
filter=[{"status": {"$eq": "published"}}]
 
# In operator - match any value in list
filter=[{"tags": {"$in": ["ai", "ml", "data-science"]}}]
 
# Range operator - numeric range (inclusive)
filter=[{"score": {"$range": [70, 95]}}]
 
# Combined filters (AND logic)
filter=[
    {"status": {"$eq": "published"}},
    {"tags": {"$in": ["ai", "ml"]}},
    {"score": {"$range": [80, 100]}}
]

Deletion Methods

Vector Deletion

Remove specific vectors from an index using their unique id:


index = client.get_index(name="your-index-name")
 
# Delete a single vector by ID
index.delete_vector("vec1")

Filtered Deletion

Delete vectors based on filter fields when you don’t know the exact vector id:


index = client.get_index(name="your-index-name")
 
# Delete all vectors matching filter conditions
index.delete_with_filter([{"tags": {"$eq": "important"}}])

Index Deletion

Permanently remove an entire index and all its vectors:


# Delete an entire index
client.delete_index("your-index-name")

⚠️ Caution: Deletion operations are irreversible. Ensure you have the correct id or index name before deleting.

Additional Operations

Get Vector by ID


# Retrieve a specific vector by its ID
vector = index.get_vector("vec1")

Describe Index


# Get index statistics and configuration info
info = index.describe()

API Reference

Endee Class

Method	Description
`create_index(name, dimension, space_type, M, ef_con, use_fp16)`	Create a new index
`list_indexes()`	List all indexes
`delete_index(name)`	Delete an index
`get_index(name)`	Get reference to an index
`get_user()`	Get user management instance

Index Class

Method	Description
`upsert(input_array)`	Insert or update vectors
`query(vector, top_k, filter, ef, include_vectors)`	Search for similar vectors
`delete_vector(id)`	Delete a vector by ID
`delete_with_filter(filter)`	Delete vectors matching a filter
`get_vector(id)`	Get a specific vector by ID
`describe()`	Get index statistics and info