Skip to main content
This guide will get you from zero to your first working vector query in under 5 minutes.

​
Prerequisites

Make sure you have completed the installation steps first.

​
1. Initialize the Client

import { SolVec } from 'solvec';

const sv = new SolVec({ network: 'devnet' });
We’re using the devnet network for this quickstart. This connects to Solana’s development network where transactions are free.

​
2. Create a Collection

A collection is where you store your vectors. You need to specify the dimensionality (e.g., 1536 for OpenAI embeddings). 
const collection = sv.collection('my-first-collection', { 
  dimensions: 1536,
  metric: 'cosine' // optional, default is 'cosine'
});

​
3. Insert Vectors

Let’s insert some vectors with metadata: 
await collection.upsert([
  {
    id: 'vec_1',
    values: new Array(1536).fill(0).map(() => Math.random()),
    metadata: { text: 'User prefers dark mode', category: 'preference' }
  },
  {
    id: 'vec_2',
    values: new Array(1536).fill(0).map(() => Math.random()),
    metadata: { text: 'User is interested in AI', category: 'interest' }
  },
  {
    id: 'vec_3',
    values: new Array(1536).fill(0).map(() => Math.random()),
    metadata: { text: 'User lives in San Francisco', category: 'location' }
  }
]);

console.log('✅ Upserted 3 vectors');
In a real application, you would use actual embeddings from OpenAI, Cohere, or another embedding model instead of random numbers.

​
4. Query for Similar Vectors

Now let’s search for the most similar vectors: 
const queryVector = new Array(1536).fill(0).map(() => Math.random());

const results = await collection.query({
  vector: queryVector,
  topK: 2,
  includeMetadata: true
});

console.log('Top matches:');
results.matches.forEach(match => {
  console.log(`- ${match.id}: ${match.score.toFixed(3)} - ${match.metadata?.text}`);
});
Expected output: 
Top matches:
- vec_2: 0.847 - User is interested in AI
- vec_1: 0.823 - User prefers dark mode

​
5. Verify On-Chain Integrity

One of VecLabs’ unique features is cryptographic verification. After every write, a Merkle root is posted to Solana: 
const proof = await collection.verify();

console.log('Collection verified!');
console.log(`Vector count: ${proof.vectorCount}`);
console.log(`Merkle root: ${proof.localRoot.slice(0, 16)}...`);
console.log(`View on Solana Explorer: ${proof.solanaExplorerUrl}`);
The verification proof URL takes you to Solana Explorer where you can see the on-chain Merkle root. This provides cryptographic proof that your collection hasn’t been tampered with.

​
6. Get Collection Stats

const stats = await collection.describeIndexStats();

console.log(`Collection: ${stats.name}`);
console.log(`Vectors: ${stats.vectorCount}`);
console.log(`Dimensions: ${stats.dimension}`);
console.log(`Metric: ${stats.metric}`);

​
Complete Working Example

import { SolVec } from 'solvec';

async function main() {
  // 1. Initialize client
  const sv = new SolVec({ network: 'devnet' });
  
  // 2. Create collection
  const collection = sv.collection('quickstart-demo', { dimensions: 1536 });
  
  // 3. Upsert vectors
  await collection.upsert([
    {
      id: 'vec_1',
      values: new Array(1536).fill(0).map(() => Math.random()),
      metadata: { text: 'AI agent memory example' }
    },
    {
      id: 'vec_2',
      values: new Array(1536).fill(0).map(() => Math.random()),
      metadata: { text: 'Vector database for agents' }
    }
  ]);
  
  // 4. Query
  const results = await collection.query({
    vector: new Array(1536).fill(0).map(() => Math.random()),
    topK: 2,
    includeMetadata: true
  });
  
  console.log('Query results:', results.matches);
  
  // 5. Verify
  const proof = await collection.verify();
  console.log('Verified:', proof.match);
}

main();

​
Next Steps

Guides

Deep dive into TypeScript and Python SDK usage

Architecture

Understand how VecLabs works under the hood

API Reference

Explore the complete API documentation

Examples

See real-world usage examples

​
Troubleshooting

Make sure all vectors in your collection have the same number of dimensions. The dimensions parameter when creating a collection must match the length of your vector arrays.
// ❌ Wrong - dimension mismatch
collection.upsert([{ id: 'vec_1', values: [0.1, 0.2] }]); // Error: expected 1536

// ✅ Correct
collection.upsert([{ id: 'vec_1', values: new Array(1536).fill(0.1) }]);
If you’re having trouble connecting to Solana devnet, you can specify a custom RPC endpoint:
const sv = new SolVec({ 
  network: 'devnet',
  rpcUrl: 'https://api.devnet.solana.com'
});
To use actual embeddings from OpenAI or other providers:
import OpenAI from 'openai';

const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

const response = await openai.embeddings.create({
  model: 'text-embedding-3-small',
  input: 'Your text here'
});

const embedding = response.data[0].embedding; // 1536 dimensions

await collection.upsert([{
  id: 'doc_1',
  values: embedding,
  metadata: { text: 'Your text here' }
}]);

Build docs developers (and LLMs) love

Get started for freeTalk to us