TypeScript 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.


import { Endee } from "endee";
 
const endee = new Endee("user_id:api_token:region");
 
// Get reference to your index
const index = await endee.getIndex("your-index-name");
 
// Insert multiple vectors in a batch
await 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 numbers 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.


const index = await endee.getIndex("your-index-name");
 
// Query with custom parameters
const results = await index.query({
  vector: [/* ... */],      // Query vector
  topK: 5,                  // Number of results to return
  ef: 128,                  // Runtime parameter for search quality
  includeVectors: true      // Include vector data in results
});
 
// Process results
for (const item of results) {
  console.log(`ID: ${item.id}, Similarity: ${item.similarity}`);
  console.log(`Metadata:`, item.meta);
}

Query Parameters:

Parameter	Description
`vector`	Query vector (must match index dimension)
`topK`	Number of nearest neighbors to return
`ef`	Runtime search parameter - higher values improve recall but increase latency
`includeVectors`	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.


const index = await endee.getIndex("your-index-name");
 
// Query with filter conditions
const filteredResults = await index.query({
  vector: [/* ... */],
  topK: 5,
  ef: 128,
  includeVectors: true,
  filter: { tags: { "$eq": "important" } }
});

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:

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] } }

Deletion Methods

Vector Deletion

Remove specific vectors from an index using their unique id:


const index = await endee.getIndex("your-index-name");
 
// Delete a single vector by ID
await index.deleteVector("vec1");

Filtered Deletion

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


const index = await endee.getIndex("your-index-name");
 
// Delete all vectors matching filter conditions
await index.deleteWithFilter({ visibility: {"$eq":"public"} });

Index Deletion

Permanently remove an entire index and all its vectors:


// Delete an entire index
await endee.deleteIndex("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
const vector = await index.getVector("vec1");

Describe Index


// Get index statistics and configuration info
const description = await index.describe();
console.log(description);

API Reference

Endee Class

Method	Description
`createIndex(options)`	Create a new index
`listIndexes()`	List all indexes
`deleteIndex(name)`	Delete an index
`getIndex(name)`	Get reference to an index

Index Class

Method	Description
`upsert(vectors)`	Insert or update vectors
`query(options)`	Search for similar vectors
`deleteVector(id)`	Delete a vector by ID
`deleteWithFilter(filter)`	Delete vectors matching a filter
`getVector(id)`	Get a specific vector by ID
`describe()`	Get index statistics and info