Skip to main content

Class: SqlVectorStore

Defined in: packages/agentos/src/rag/vector_stores/SqlVectorStore.ts:223

SQL-backed vector store implementation.

Uses @framers/sql-storage-adapter for cross-platform persistence. Stores embeddings as base64-encoded Float32 payloads and computes similarity in application code.

Implements​

Example​

const store = new SqlVectorStore();

await store.initialize({
  id: 'sql-vector-store',
  type: 'sql',
  storage: {
    filePath: './vectors.db',
    priority: ['better-sqlite3', 'sqljs']
  },
  enableFullTextSearch: true
});

// Create a collection
await store.createCollection('documents', 1536);

// Upsert documents
await store.upsert('documents', [{
  id: 'doc-1',
  embedding: [...], // 1536-dim vector
  textContent: 'Example document content',
  metadata: { author: 'Alice', category: 'tech' }
}]);

// Query by similarity
const results = await store.query('documents', queryEmbedding, { topK: 5 });

Implements​

Constructors​

Constructor​

new SqlVectorStore(): SqlVectorStore

Defined in: packages/agentos/src/rag/vector_stores/SqlVectorStore.ts:245

Constructs a SqlVectorStore instance. The store is not operational until initialize() is called.

Returns​

SqlVectorStore

Methods​

checkHealth()​

checkHealth(): Promise<{ details?: any; isHealthy: boolean; }>

Defined in: packages/agentos/src/rag/vector_stores/SqlVectorStore.ts:1190

Checks the health of the vector store.

Returns​

Promise<{ details?: any; isHealthy: boolean; }>

Health status

Implementation of​

IVectorStore.checkHealth

collectionExists()​

collectionExists(collectionName): Promise<boolean>

Defined in: packages/agentos/src/rag/vector_stores/SqlVectorStore.ts:425

Checks if a collection exists.

Parameters​

collectionName​

string

Collection name to check

Returns​

Promise<boolean>

True if collection exists

Implementation of​

IVectorStore.collectionExists

createCollection()​

createCollection(collectionName, dimension, options?): Promise<void>

Defined in: packages/agentos/src/rag/vector_stores/SqlVectorStore.ts:378

Creates a new collection for storing vectors.

Parameters​

collectionName​

string

Unique name for the collection

dimension​

number

Vector embedding dimension

options?​

CreateCollectionOptions

Creation options

Returns​

Promise<void>

Implementation of​

IVectorStore.createCollection

delete()​

delete(collectionName, ids?, options?): Promise<DeleteResult>

Defined in: packages/agentos/src/rag/vector_stores/SqlVectorStore.ts:1102

Deletes documents from a collection.

Parameters​

collectionName​

string

Collection to delete from

ids?​

string[]

Specific document IDs to delete

options?​

DeleteOptions

Delete options (filter, deleteAll)

Returns​

Promise<DeleteResult>

Deletion result

Implementation of​

IVectorStore.delete

deleteCollection()​

deleteCollection(collectionName): Promise<void>

Defined in: packages/agentos/src/rag/vector_stores/SqlVectorStore.ts:441

Deletes a collection and all its documents.

Parameters​

collectionName​

string

Collection to delete

Returns​

Promise<void>

Implementation of​

IVectorStore.deleteCollection

getStats()​

getStats(collectionName?): Promise<Record<string, any>>

Defined in: packages/agentos/src/rag/vector_stores/SqlVectorStore.ts:1251

Gets statistics for a collection or the entire store.

Parameters​

collectionName?​

string

Specific collection, or all if omitted

Returns​

Promise<Record<string, any>>

Statistics

Implementation of​

IVectorStore.getStats

hybridSearch()​

hybridSearch(collectionName, queryEmbedding, queryText, options?): Promise<QueryResult>

Defined in: packages/agentos/src/rag/vector_stores/SqlVectorStore.ts:849

Performs hybrid search combining vector similarity with keyword matching.

Parameters​

collectionName​

string

Collection to search

queryEmbedding​

number[]

Query vector for semantic search

queryText​

string

Text query for keyword search

options?​

QueryOptions & object

Search options

Returns​

Promise<QueryResult>

Combined search results

Example​

const results = await store.hybridSearch(
  'documents',
  queryEmbedding,
  'machine learning tutorial',
  { topK: 10, alpha: 0.7 } // 70% vector, 30% keyword
);

Implementation of​

IVectorStore.hybridSearch

initialize()​

initialize(config): Promise<void>

Defined in: packages/agentos/src/rag/vector_stores/SqlVectorStore.ts:257

Initializes the vector store with the provided configuration.

Creates necessary tables and indexes if they don't exist.

Parameters​

config​

VectorStoreProviderConfig

Configuration object

Returns​

Promise<void>

Throws​

If configuration is invalid or initialization fails

Implementation of​

IVectorStore.initialize

query()​

query(collectionName, queryEmbedding, options?): Promise<QueryResult>

Defined in: packages/agentos/src/rag/vector_stores/SqlVectorStore.ts:627

Queries a collection for similar documents.

Parameters​

collectionName​

string

Collection to query

queryEmbedding​

number[]

Query vector

options?​

QueryOptions

Query options

Returns​

Promise<QueryResult>

Query results sorted by similarity

Implementation of​

IVectorStore.query

scanByMetadata()​

scanByMetadata(collectionName, options?): Promise<MetadataScanResult>

Defined in: packages/agentos/src/rag/vector_stores/SqlVectorStore.ts:781

Optional: Enumerates documents using metadata-only filtering without requiring a query embedding.

Parameters​

collectionName​

string

options?​

MetadataScanOptions

Returns​

Promise<MetadataScanResult>

Implementation of​

IVectorStore.scanByMetadata

shutdown()​

shutdown(): Promise<void>

Defined in: packages/agentos/src/rag/vector_stores/SqlVectorStore.ts:1226

Gracefully shuts down the vector store.

Returns​

Promise<void>

Implementation of​

IVectorStore.shutdown

upsert()​

upsert(collectionName, documents, options?): Promise<UpsertResult>

Defined in: packages/agentos/src/rag/vector_stores/SqlVectorStore.ts:501

Upserts documents into a collection.

Parameters​

collectionName​

string

Target collection

documents​

VectorDocument[]

Documents to upsert

options?​

UpsertOptions

Upsert options

Returns​

Promise<UpsertResult>

Result of the upsert operation

Implementation of​

IVectorStore.upsert