TypeScript SDK Usage

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

Setting Up Your Domain

The Endee client allows you to configure a custom domain URL and port (default port is 8080):


import { Endee } from 'endee';
 
// Initialize with your API token
const client = new Endee();
 
// Set custom base URL
client.setBaseUrl('http://0.0.0.0:8081/api/v1');

Use setBaseUrl() when running on a non-default port.

Upserting Vectors

The index.upsert() method adds or updates vectors in an existing index.


import { Endee } from 'endee';
 
const client = new Endee();
const index = await client.getIndex('my_index');
 
await index.upsert([
  {
    id: 'vec1',
    vector: [...],
    meta: { title: 'First document' },
    filter: { category: 'tech' },
  },
  {
    id: 'vec2',
    vector: [...],
    meta: { title: 'Second document' },
    filter: { category: 'science' },
  },
]);

Vector Object Fields: (see VectorItem)

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

Querying the Index

The index.query() method performs a similarity search using a query vector.


const results = await index.query({
  vector: [...],
  topK: 5,
  ef: 128,
  includeVectors: true,
});
 
for (const item of results) {
  console.log(`ID: ${item.id}, Similarity: ${item.similarity}`);
}

Query Parameters: (see QueryOptions)

Parameter	Description
`vector`	Query vector (must match index dimension)
`topK`	Number of results to return (default: 10, max: 512)
`ef`	Search quality parameter (default: 128, max: 1024)
`includeVectors`	Include vector data in results (default: false)

Results are returned as an array of QueryResult objects.

Filtered Querying

Use the filter parameter to restrict results based on filter conditions. All filters are combined with logical AND.


const results = await index.query({
  vector: [...],
  topK: 5,
  filter: [
    { category: { $eq: 'tech' } },
    { score: { $range: [80, 100] } },
  ],
});

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

The $range operator supports values within [0 – 999]. Normalize larger values before upserting.

Hybrid Search

Hybrid indexes combine dense and sparse vector search. Create a hybrid index by specifying sparseDimension:


await client.createIndex({
  name: 'hybrid_index',
  dimension: 384,
  sparseDimension: 30000,
  spaceType: 'cosine',
});

Upserting Hybrid Vectors

Provide both dense vectors and sparse vector representations using sparseIndices and sparseValues:


const index = await client.getIndex('hybrid_index');
 
await index.upsert([
  {
    id: 'doc1',
    vector: [0.1, 0.2, ...],          // Dense vector
    sparseIndices: [10, 50, 200],      // Non-zero term positions
    sparseValues: [0.8, 0.5, 0.3],     // Weights for each position
    meta: { title: 'Document 1' },
  },
  {
    id: 'doc2',
    vector: [0.3, 0.4, ...],
    sparseIndices: [15, 100, 500],
    sparseValues: [0.9, 0.4, 0.6],
    meta: { title: 'Document 2' },
  },
]);

Hybrid Vector Fields: (see VectorItem)

Field	Required	Description
`id`	Yes	Unique identifier
`vector`	Yes	Dense embedding vector
`sparseIndices`	Yes (hybrid)	Non-zero term positions in sparse vector
`sparseValues`	Yes (hybrid)	Weights for each sparse index
`meta`	No	Metadata dictionary
`filter`	No	Filter fields

sparseIndices and sparseValues must have the same length. Values in sparseIndices must be within [0, sparseDimension).

Querying Hybrid Index

Provide both dense and sparse query vectors:


const results = await index.query({
  vector: [0.15, 0.25, ...],           // Dense query
  sparseIndices: [10, 100, 300],        // Sparse query positions
  sparseValues: [0.7, 0.5, 0.4],        // Sparse query weights
  topK: 5,
});
 
for (const item of results) {
  console.log(`ID: ${item.id}, Similarity: ${item.similarity}`);
}

You can also query with:

Dense only: Provide only vector
Sparse only: Provide only sparseIndices and sparseValues
Hybrid: Provide all three for combined results

Deletion Methods

Delete by ID


await index.deleteVector('vec1');

Delete by Filter

Delete all vectors matching specific filters:


await index.deleteWithFilter([{ category: { $eq: 'tech' } }]);

Delete Index


await client.deleteIndex('my_index');

Deletion operations are irreversible.

Additional Operations

Get Vector by ID

Returns a VectorInfo object:


const vector = await index.getVector('vec1');

Describe Index

Returns an IndexDescription object:


const info = index.describe();
console.log(info);
// { name, spaceType, dimension, sparseDimension, isHybrid, count, precision, M }

Precision Options

Endee supports different quantization precision levels via the Precision enum:


import { Precision } from 'endee';
 
Precision.BINARY;   // Binary quantization (1-bit) - smallest storage, fastest search
Precision.INT8D;    // 8-bit integer quantization (default) - balanced performance
Precision.INT16D;   // 16-bit integer quantization - higher precision
Precision.FLOAT16;  // 16-bit floating point - good balance
Precision.FLOAT32;  // 32-bit floating point - highest precision

Choosing Precision:

BINARY: Best for very large datasets where speed and storage are critical
INT8D (default): Recommended for most use cases - good balance of accuracy and performance
INT16D: When you need better accuracy than INT8D but less storage than FLOAT32
FLOAT16: Good compromise between precision and storage for embeddings
FLOAT32: When you need maximum precision and storage is not a concern

See the Types Reference for complete details.

TypeScript Types

The package includes comprehensive TypeScript types. See the Types Reference for complete documentation of all types:


import type {
  VectorItem,
  QueryOptions,
  QueryResult,
  CreateIndexOptions,
  IndexDescription,
  SpaceType,
  Precision,
} from 'endee';

Type	Description
`SpaceType`	Distance metric options
`Precision`	Quantization precision levels
`CreateIndexOptions`	Index creation parameters
`VectorItem`	Vector for upserting
`QueryOptions`	Query parameters
`QueryResult`	Single query result
`IndexDescription`	Index description
`VectorInfo`	Single vector information

API Reference

Endee Class

Method	Description
`createIndex(options)`	Create a new index - accepts `CreateIndexOptions`
`listIndexes()`	List all indexes - returns `IndexInfo[]`
`deleteIndex(name)`	Delete an index
`getIndex(name)`	Get reference to an index
`setBaseUrl(url)`	Set a custom base URL

Index Class

Method	Description
`upsert(vectors)`	Insert or update vectors - accepts `VectorItem[]`
`query(options)`	Search for similar vectors - accepts `QueryOptions`, returns `QueryResult[]`
`deleteVector(id)`	Delete a vector by ID
`deleteWithFilter(filter)`	Delete vectors by filter
`getVector(id)`	Get a vector by ID - returns `VectorInfo`
`describe()`	Get index info - returns `IndexDescription`