Skip to main content

MossClient

Local semantic search client for vector similarity operations.

Example

const client = new MossClient('your-project-id', 'your-project-key');

// Create an index with documents
await client.createIndex('docs', [
  { id: '1', text: 'Machine learning fundamentals' },
  { id: '2', text: 'Deep learning neural networks' }
], 'moss-minilm');

// Query the index
const results = await client.query('docs', 'AI and neural networks');

Constructors

Constructor

new MossClient(projectId, projectKey): MossClient
Creates a new MossClient instance for local operations.

Parameters

projectId
string Your project identifier.
projectKey
string Your project authentication key.

Returns

MossClient

Methods

createIndex()

createIndex(indexName, docs, modelId?): Promise<boolean>
Creates a new index with the provided documents.

Parameters

indexName
string Name of the index to create.
docs
DocumentInfo[] Initial documents to add to the index.
modelId?
string The model ID to use for embeddings.

Returns

Promise<boolean> Promise that resolves to true if successful.

Throws

If the index already exists or creation fails.

Example

const success = await client.createIndex('knowledge-base', [
  { id: 'doc1', text: 'Introduction to AI' },
  { id: 'doc2', text: 'Machine learning basics' }
], 'moss-minilm');

getIndex()

getIndex(indexName): Promise<IndexInfo>
Gets information about a specific index.

Parameters

indexName
string Name of the index to retrieve.

Returns

Promise<IndexInfo> Promise that resolves to IndexInfo object.

Throws

If the index does not exist.

Example

const info = await client.getIndex('knowledge-base');
console.log(`Index has ${info.docCount} documents`);

listIndexes()

listIndexes(): Promise<IndexInfo[]>
Lists all available indexes.

Returns

Promise<IndexInfo[]> Promise that resolves to array of IndexInfo objects.

Example

const indexes = await client.listIndexes();
indexes.forEach(index => {
  console.log(`${index.name}: ${index.docCount} docs`);
});

deleteIndex()

deleteIndex(indexName): Promise<boolean>
Deletes an index and all its data.

Parameters

indexName
string Name of the index to delete.

Returns

Promise<boolean> Promise that resolves to true if successful.

Throws

If the index does not exist.

Example

const deleted = await client.deleteIndex('old-index');

addDocs()

addDocs(indexName, docs, options?): Promise<{ added: number; updated: number; }>
Adds or updates documents in an index.

Parameters

indexName
string Name of the target index.
docs
DocumentInfo[] Documents to add or update.
options?
AddDocumentsOptions Optional configuration for the operation.

Returns

Promise<{ added: number; updated: number; }> Promise that resolves to operation result with counts.

Throws

If the index does not exist.

Example

const result = await client.addDocs('knowledge-base', [
  { id: 'new-doc', text: 'New content to index' }
], { upsert: true });
console.log(`Added: ${result.added}, Updated: ${result.updated}`);

deleteDocs()

deleteDocs(indexName, docIds): Promise<{ deleted: number; }>
Deletes documents from an index by their IDs.

Parameters

indexName
string Name of the target index.
docIds
string[] Array of document IDs to delete.

Returns

Promise<{ deleted: number; }> Promise that resolves to operation result with count.

Throws

If the index does not exist.

Example

const result = await client.deleteDocs('knowledge-base', ['doc1', 'doc2']);
console.log(`Deleted ${result.deleted} documents`);

getDocs()

getDocs(indexName, options?): Promise<DocumentInfo[]>
Retrieves documents from an index.

Parameters

indexName
string Name of the target index.
options?
GetDocumentsOptions Optional configuration for retrieval.

Returns

Promise<DocumentInfo[]> Promise that resolves to array of documents.

Throws

If the index does not exist.

Example

// Get all documents
const allDocs = await client.getDocs('knowledge-base');

// Get specific documents
const specificDocs = await client.getDocs('knowledge-base', {
  docIds: ['doc1', 'doc2']
});

loadIndex()

loadIndex(indexName, options?): Promise<string>
Downloads an index from the cloud into memory for fast local querying. How it works:
  1. Fetches the index assets from the cloud
  2. Loads the embedding model for generating query embeddings
  3. Executes a local similarity match between the query embedding and the retrieved index.
Why use this?
  • Without loadIndex(): Every query() call goes to the cloud API (~100-500ms network latency)
  • With loadIndex(): Queries run entirely in-memory (~1-10ms)
Reload behavior: If the index is already loaded, calling loadIndex() again will:
  • Stop any existing auto-refresh polling
  • Download a fresh copy from the cloud
  • Replace the in-memory index
Auto-refresh (optional): Enable autoRefresh: true to periodically poll the cloud for updates. When a newer version is detected, the index is automatically hot-swapped without interrupting queries.

Parameters

indexName
string Name of the index to load.
options?
LoadIndexOptions Optional configuration including auto-refresh settings.

Returns

Promise<string> Promise that resolves to the index name.

Throws

If the index does not exist in the cloud or loading fails.

Example

// Simple load - enables fast local queries
await client.loadIndex('my-index');

// Now queries run locally (fast, no network calls)
const results = await client.query('my-index', 'search text');

// Load with auto-refresh to keep index up-to-date
await client.loadIndex('my-index', {
  autoRefresh: true,
  pollingIntervalInSeconds: 300, // Check cloud every 5 minutes
});

// Stop auto-refresh by reloading without the option
await client.loadIndex('my-index');

query()

query(indexName, query, options?): Promise<SearchResult>
Performs a semantic similarity search against the specified index.

Parameters

indexName
string Name of the target index to search.
query
string The search query text.
options?
QueryOptions Optional query configuration including topK (default: 5) and embedding overrides.

Returns

Promise<SearchResult> Promise that resolves to SearchResult with matching documents.

Throws

If the specified index does not exist.

Example

const results = await client.query('knowledge-base', 'machine learning');
results.docs.forEach(doc => {
  console.log(`${doc.id}: ${doc.text} (score: ${doc.score})`);
});