Basic Usage

To interact with the VectorX platform, you’ll need to authenticate using an API token.
This token is used to securely identify your workspace and authorize all actions — including index creation, vector upserts, and queries.

🔐 Generate Your API Token:
You can create and manage your authentication tokens from the VectorX Dashboard under the API Keys section.
Each token is tied to your workspace and should be kept private.

Once you have your token, you’re ready to initialize the client and begin using the SDK.

Initializing the Client

The VectorX client acts as the main interface for all vector operations — such as creating indexes, upserting vectors, and running similarity queries

You can initialize the client in just a few lines:

from vecx.vectorx import VectorX
 
# Production with specific region
vx = VectorX(token="your-token-here")

Listing all the Indexes

The vx.list_indexes() method returns a list of all the indexes currently available in your environment or workspace.
This is useful for managing, debugging, or programmatically selecting indexes for vector operations like upsert or search.

from vecx.vectorx import VectorX
 
vx = VectorX(token="your-token-here")
 
indexes = vx.list_indexes()

Create an Index

The vx.create_index() method initializes a new vector index with customizable parameters such as dimensionality, distance metric, graph construction settings, and memory optimization. These configurations determine how the index stores and retrieves high-dimensional vector data.

from vecx.vectorx import VectorX
 
vx = VectorX(token="your-token-here")
 
vx.create_index(
    name="my_custom_index",
    dimension=768,
    space_type="cosine",
    M=16,             # Graph connectivity parameter (default = 16)
    ef_con=128,       # Construction-time parameter (default = 128)
    use_fp16=True     # Use half-precision for storage optimization (default = True)
)

Ingestion of data

The index.upsert() method is used to add or update vectors (embeddings) in an existing index.
Each vector is represented as an object containing a unique identifier, the vector data itself, optional metadata, and optional filter fields for future querying.

from vecx.vectorx import VectorX
 
vx = VectorX(token="your-token-here")
 
# Accessing the index
index = vx.get_index(name="your-index-name")
 
index.upsert([
    {
        "id": "vec1",
        "vector": [...],  # Your vector
        "meta": {"title": "First document"}
        "filter": {"tags" : "important"} # Optional filter values
    },
    {
        "id": "vec2",
        "vector": [...],  # Another vector
        "meta": {"title": "second document"}
        "filter": {"visibility": "public", "tags": "important"}
    }
])

Querying the Index

The index.query() method performs a similarity search in the index using a given query vector.
It returns the closest vectors (based on the index’s distance metric) along with optional metadata and vector data.

from vecx.vectorx import VectorX
 
vx = VectorX(token="your-token-here")
 
# Accessing the index
index = vx.get_index(name="your-index-name")
 
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
)

Filtered querying

The index.query() method also supports structured filtering using the filter parameter.
This allows you to restrict search results based on metadata conditions, in addition to vector similarity. To apply multiple filter conditions, pass an array of filter objects, where each object defines a separate condition. All filters are combined with logical AND — meaning a vector must match all specified conditions to be included in the results.

index = vx.get_index(name="your-index-name")
 
filtered_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
    filter=[{"tags" : {"$eq" : "important"}},{"visibility" : {"$eq" : "public"}}]
)

Filtering Operators

The filter parameter in index.query() supports a range of comparison operators to build structured queries.
These operators allow you to include or exclude vectors based on metadata or custom fields.

Notes

• Operators are case-sensitive and must be prefixed with a $.
• Filters operate on fields provided under the filter key during vector upsert.
• The $range operator supports values only within the range [0 – 999]. If your data exceeds this range (e.g., timestamps, large scores), you should normalize or scale your values to fit within [0, 999] prior to upserting or querying.

Deletion Methods

The system supports two types of deletion operations — vector deletion and index deletion.
These allow you to remove specific vectors or entire indexes from your workspace, giving you full control over lifecycle and storage.

Vector Deletion

Vector deletion is used to remove specific vectors from an index using their unique id. This is useful when:

• A document is outdated or revoked.
• You want to update a vector by first deleting its old version.
• You’re cleaning up test data or low-quality entries.

from vecx.vectorx import VectorX
 
vx = VectorX(token="your-token-here")
 
index = vx.get_index(name="your-index-name")
 
index.delete_vector("vec1") # passing the id

Filtered Deletion

In cases where you don’t know the exact vector id, but want to delete vectors based on filter fields, you can use filtered deletion. This is especially useful for:

• Bulk deleting vectors by tag, type, or timestamp.
• Enforcing access control or data expiration policies.

from vecx.vectorx import VectorX
 
vx = VectorX(token="your-token-here")
 
index = vx.get_index(name="your-index-name")
 
index.delete_with_filter([{"tags":{"$eq" : "important"}}]) 

Index Deletion

Index deletion permanently removes the entire index and all vectors associated with it.This should be used when:

• The index is no longer needed.
• You want to re-create the index with a different configuration.
• You’re managing index rotation in batch pipelines.

from vecx.vectorx import VectorX
 
vx = VectorX(token="your-token-here")
 
vx.delete_index("your-index-name)

⚠️ Caution: Deletion operations are irreversible. Ensure you have the correct id or index name before performing deletion, especially at the index level.

You can refer to API Reference for all the methods.