Skip to main content

​
Overview

The SolVecCollection class represents a single vector collection. It provides methods for upserting, querying, and managing vectors with a Pinecone-compatible API. Vectors are stored encrypted in Shadow Drive with Merkle roots posted to Solana for integrity verification.

​
Getting a Collection

You don’t instantiate SolVecCollection directly. Use the collection() method on your SolVec client: 
import { SolVec } from 'solvec';

const sv = new SolVec({ network: 'devnet' });
const col = sv.collection('my-vectors', { dimensions: 1536 });

​
Methods

​
upsert()

Insert or update vectors in the collection. If a vector with the same ID exists, it will be overwritten. 
const response = await col.upsert(records);
​
records
UpsertRecord[]
required
Array of vector records to upsert
​
returns
Promise<UpsertResponse>
Response object containing the number of vectors upserted

​
Example

const col = sv.collection('agent-memory', { dimensions: 1536 });

await col.upsert([
  {
    id: 'mem_001',
    values: [0.1, 0.2, ...], // 1536 dimensions
    metadata: {
      text: 'User prefers dark mode',
      timestamp: Date.now(),
      category: 'preference'
    }
  },
  {
    id: 'mem_002',
    values: [0.3, 0.4, ...],
    metadata: {
      text: 'User is located in San Francisco',
      timestamp: Date.now()
    }
  }
]);
When a wallet is configured, upsert operations automatically update the on-chain Merkle root for integrity verification.

​
Error Conditions

Throws an error if vector dimensions don’t match the collection’s configured dimensions:
// Collection expects 1536 dimensions
await col.upsert([{ id: 'bad', values: [1, 2, 3] }]);
// Error: Dimension mismatch: collection expects 1536, got 3 for id "bad"

​
query()

Search for nearest neighbor vectors using semantic similarity. 
const response = await col.query(options);
​
options
QueryOptions
required
Query configuration object
​
returns
Promise<QueryResponse>
Query results containing matched vectors

​
Example

const col = sv.collection('agent-memory', { dimensions: 1536 });

// Query for top 5 most similar vectors
const { matches } = await col.query({
  vector: [0.1, 0.2, ...], // 1536-dim query vector
  topK: 5,
  includeMetadata: true,
  includeValues: false
});

matches.forEach(match => {
  console.log(`ID: ${match.id}`);
  console.log(`Score: ${match.score}`);
  console.log(`Text: ${match.metadata?.text}`);
});

​
Query Performance

Queries execute in-memory using HNSW index with typical latency under 5ms for collections up to 1M vectors.

​
Error Conditions

// Dimension mismatch
await col.query({ vector: [1, 2], topK: 5 });
// Error: Query dimension mismatch: expected 1536, got 2

// Empty collection returns empty results (not an error)
const emptyCol = sv.collection('empty', { dimensions: 4 });
const { matches } = await emptyCol.query({ vector: [1, 0, 0, 0], topK: 5 });
console.log(matches); // []

​
delete()

Delete vectors from the collection by their IDs. 
await col.delete(ids);
​
ids
string[]
required
Array of vector IDs to delete
​
returns
Promise<void>
Returns nothing on success

​
Example

// Delete single vector
await col.delete(['mem_001']);

// Delete multiple vectors
await col.delete(['mem_001', 'mem_002', 'mem_003']);

// Verify deletion
const stats = await col.describeIndexStats();
console.log(`Remaining vectors: ${stats.vectorCount}`);
When a wallet is configured, delete operations automatically update the on-chain Merkle root.

​
describeIndexStats()

Get collection statistics and metadata. 
const stats = await col.describeIndexStats();
​
returns
Promise<CollectionStats>
Collection statistics object

​
Example

const col = sv.collection('agent-memory', { dimensions: 1536 });

await col.upsert([{ id: 'a', values: [...] }]);

const stats = await col.describeIndexStats();
console.log(`Collection: ${stats.name}`);
console.log(`Vectors: ${stats.vectorCount}`);
console.log(`Dimensions: ${stats.dimension}`);
console.log(`Metric: ${stats.metric}`);
console.log(`Merkle Root: ${stats.merkleRoot}`);
console.log(`Last Updated: ${new Date(stats.lastUpdated).toISOString()}`);

​
verify()

Verify collection integrity by comparing local Merkle root against on-chain state. 
const result = await col.verify();
​
returns
Promise<VerificationResult>
Verification result with proof details

​
Example

const col = sv.collection('agent-memory', { dimensions: 1536 });

await col.upsert([{ id: 'a', values: [...] }]);

const result = await col.verify();

if (result.verified) {
  console.log('✓ Collection integrity verified');
  console.log(`Vector count: ${result.vectorCount}`);
  console.log(`View on Solana: ${result.solanaExplorerUrl}`);
} else {
  console.error('✗ Verification failed');
  console.error(`Local root:    ${result.localRoot}`);
  console.error(`On-chain root: ${result.onChainRoot}`);
}
Verification provides cryptographic proof that your vectors haven’t been tampered with. The Merkle root is stored on Solana’s blockchain, making it immutable and auditable.

​
Complete Example

import { SolVec } from 'solvec';

// Initialize client and collection
const sv = new SolVec({ network: 'devnet' });
const col = sv.collection('product-search', {
  dimensions: 768,
  metric: 'cosine'
});

// Insert product embeddings
await col.upsert([
  {
    id: 'prod_001',
    values: [0.1, 0.2, ...], // 768-dim embedding
    metadata: {
      name: 'Wireless Headphones',
      category: 'electronics',
      price: 79.99
    }
  },
  {
    id: 'prod_002',
    values: [0.3, 0.4, ...],
    metadata: {
      name: 'USB-C Cable',
      category: 'accessories',
      price: 12.99
    }
  }
]);

// Search for similar products
const queryEmbedding = [0.15, 0.25, ...]; // from user search
const { matches } = await col.query({
  vector: queryEmbedding,
  topK: 10,
  includeMetadata: true
});

// Display results
matches.forEach(match => {
  console.log(`${match.metadata.name} - Score: ${match.score.toFixed(3)}`);
});

// Get collection stats
const stats = await col.describeIndexStats();
console.log(`Total products indexed: ${stats.vectorCount}`);

// Verify integrity
const verification = await col.verify();
if (verification.verified) {
  console.log('Data integrity verified on Solana');
}

​
Type Reference

See the Types documentation for detailed type definitions.

Build docs developers (and LLMs) love

Get started for freeTalk to us