API Reference

Database Class

Constructor

constructor(options: DatabaseOptions)

DatabaseOptions

interface DatabaseOptions {
  vectorSize?: number;
  cacheSize?: number;
  maxConcurrentSearches?: number;
  indexing: IndexingConfiguration;
  partitioning: PartitioningConfiguration;
  persistence: PersistenceOptions;
  monitoring?: MonitoringConfiguration;
}

Core Methods

addVector

async addVector(
  id: string | number,
  vector: number[] | Float32Array,
  metadata?: Record<string, any>
): Promise<void>

bulkAdd

async bulkAdd(
  vectors: Array<{
    id: string | number;
    vector: number[] | Float32Array;
    metadata?: Record<string, any>;
  }>
): Promise<BulkAddResult>

search / findNearest

async search(
  query: number[] | Float32Array,
  options?: SearchOptions
): Promise<SearchResult[]>

getMetadata

async getMetadata(
  id: string | number
): Promise<Record<string, any> | null>

Index Management

buildIndexes

async buildIndexes(
  options?: BuildIndexOptions
): Promise<void>

saveIndex

async saveIndex(
  filepath: string
): Promise<void>

Database Management

save

async save(): Promise<void>

close

async close(): Promise<void>

Advanced Methods

extractRelationships

async extractRelationships(
  threshold: number,
  options?: {
    metric?: 'cosine' | 'euclidean';
    includeMetadata?: boolean;
  }
): Promise<Array<{
  vector1: { id: string | number; metadata?: any };
  vector2: { id: string | number; metadata?: any };
  distance: number;
}>>

getStats

async getStats(): Promise<DatabaseStats>

Events

The Database class extends EventEmitter and emits the following events:

interface DatabaseEvents {
  'vector:add': { id: string | number; dimensions: number };
  'vectors:bulkAdd': { count: number; ids: Array<string | number> };
  'search:complete': { duration: number; resultCount: number };
  'search:error': { error: Error; duration: number };
  'index:build': { method: string; duration: number };
  'save:complete': { type: 'config' | 'indices' | 'all' };
  'error': { message: string; context: string; error: Error };
}

Type Definitions

SearchOptions

interface SearchOptions {
  k: number;
  includeMetadata?: boolean;
  includeVectors?: boolean;
  filter?: (id: string | number, metadata?: Record<string, any>) => boolean;
  filters?: FilterConfig[];
  useHNSW?: boolean;
  efSearch?: number;
  distanceMetric?: 'cosine' | 'euclidean';
  maxDistance?: number;
  partitionIds?: string[];
}

SearchResult

interface SearchResult {
  id: string | number;
  score: number;
  distance: number;
  metadata?: Record<string, any>;
  vector?: number[] | Float32Array;
}

DatabaseStats

interface DatabaseStats {
  vectorCount: number;
  partitionCount: number;
  memoryUsage: number;
  indices: {
    hnsw?: HNSWStats;
    lsh?: LSHStats;
  };
  search: {
    totalQueries: number;
    averageResponseTime: number;
    queriesPerSecond: number;
  };
  cache: {
    size: number;
    hitRate: number;
  };
}