Overview
Complete TypeScript type definitions for the VecLabs SDK. All types are exported from the main package.
import type {
Network,
DistanceMetric,
SolVecConfig,
UpsertRecord,
QueryOptions,
QueryMatch,
QueryResponse,
UpsertResponse,
CollectionStats,
VerificationResult,
CollectionConfig
} from 'solvec';
Configuration Types
Network
Solana network identifier.
type Network = "mainnet-beta" | "devnet" | "localnet";
Solana production network
Solana development/testing network (recommended for development)
Local Solana test validator
DistanceMetric
Vector similarity metric.
type DistanceMetric = "cosine" | "euclidean" | "dot";
Cosine similarity (recommended for most use cases). Range: [-1, 1], where 1 = identical direction.
Euclidean (L2) distance. Measures absolute distance in vector space.
Dot product similarity. Fast but sensitive to vector magnitude.
SolVecConfig
Configuration for initializing the SolVec client.
interface SolVecConfig {
network: Network;
walletPath?: string;
rpcUrl?: string;
}
Solana network to connect to
Path to Solana wallet keypair JSON file. Required for write operations.
Custom RPC endpoint URL. Falls back to default URLs if not provided.
Example
const config: SolVecConfig = {
network: 'devnet',
walletPath: './wallet.json',
rpcUrl: 'https://api.devnet.solana.com'
};
CollectionConfig
Configuration for creating or accessing a collection.
interface CollectionConfig {
dimensions?: number;
metric?: DistanceMetric;
}
Vector dimensionality. Common values:
1536: OpenAI text-embedding-ada-002768: sentence-transformers/all-mpnet-base-v2384: sentence-transformers/all-MiniLM-L6-v2
metric
DistanceMetric
default:"cosine"
Distance metric for similarity calculations
Example
const config: CollectionConfig = {
dimensions: 768,
metric: 'cosine'
};
const col = sv.collection('embeddings', config);
Vector Operation Types
UpsertRecord
A vector record to insert or update.
interface UpsertRecord {
id: string;
values: number[];
metadata?: Record<string, unknown>;
}
Unique identifier for the vector. Used for updates and retrieval.
Vector embedding values. Length must match collection dimensions.
Optional metadata object. Can contain any JSON-serializable values.
Example
const record: UpsertRecord = {
id: 'doc_123',
values: [0.1, 0.2, 0.3, ...],
metadata: {
text: 'The quick brown fox',
source: 'document.pdf',
page: 5,
timestamp: Date.now(),
tags: ['important', 'reviewed']
}
};
await col.upsert([record]);
UpsertResponse
Response from an upsert operation.
interface UpsertResponse {
upsertedCount: number;
}
Number of vectors successfully upserted
Example
const response: UpsertResponse = await col.upsert(records);
console.log(`Inserted ${response.upsertedCount} vectors`);
QueryOptions
Options for querying nearest neighbors.
interface QueryOptions {
vector: number[];
topK: number;
filter?: Record<string, unknown>;
includeMetadata?: boolean;
includeValues?: boolean;
}
Query vector to find neighbors for. Must match collection dimensions.
Number of nearest neighbors to return
Metadata filters (not yet implemented)
Whether to include metadata in results
Whether to include vector values in results
Example
const options: QueryOptions = {
vector: [0.1, 0.2, ...],
topK: 10,
includeMetadata: true,
includeValues: false
};
const response = await col.query(options);
QueryMatch
A single matching vector from a query.
interface QueryMatch {
id: string;
score: number;
metadata?: Record<string, unknown>;
values?: number[];
}
Similarity score. For cosine metric: 1.0 = identical, 0.0 = orthogonal, -1.0 = opposite.
Vector metadata (only present if includeMetadata: true)
Vector values (only present if includeValues: true)
Example
const { matches } = await col.query({ vector: [...], topK: 5 });
matches.forEach((match: QueryMatch) => {
console.log(`ID: ${match.id}`);
console.log(`Score: ${match.score.toFixed(4)}`);
if (match.metadata) {
console.log(`Text: ${match.metadata.text}`);
}
});
QueryResponse
Complete response from a query operation.
interface QueryResponse {
matches: QueryMatch[];
namespace: string;
}
Array of matching vectors, sorted by similarity score (highest first)
Collection name that was queried
Example
const response: QueryResponse = await col.query({
vector: [0.1, 0.2, ...],
topK: 5
});
console.log(`Searched in: ${response.namespace}`);
console.log(`Found ${response.matches.length} matches`);
CollectionStats
Statistics and metadata about a collection.
interface CollectionStats {
vectorCount: number;
dimension: number;
metric: DistanceMetric;
name: string;
merkleRoot: string;
lastUpdated: number;
isFrozen: boolean;
}
Total number of vectors in the collection
Distance metric used for similarity calculations
Current Merkle root hash (64-character hex string)
Unix timestamp in milliseconds
Whether the collection is frozen (immutable)
Example
const stats: CollectionStats = 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()}`);
console.log(`Frozen: ${stats.isFrozen}`);
VerificationResult
Result of collection integrity verification.
interface VerificationResult {
verified: boolean;
onChainRoot: string;
localRoot: string;
match: boolean;
vectorCount: number;
solanaExplorerUrl: string;
timestamp: number;
}
Whether verification succeeded (true if roots match)
Whether local and on-chain Merkle roots match
Locally computed Merkle root hash
Merkle root stored on Solana blockchain
Number of vectors included in verification
URL to view the collection on Solana Explorer
Unix timestamp in milliseconds when verification was performed
Example
const result: VerificationResult = await col.verify();
if (result.verified && result.match) {
console.log('✓ Collection integrity verified');
console.log(`Verified ${result.vectorCount} vectors`);
console.log(`View proof: ${result.solanaExplorerUrl}`);
} else {
console.error('✗ Verification failed');
console.error(`Local: ${result.localRoot}`);
console.error(`On-chain: ${result.onChainRoot}`);
}
Type Guards
You can create type guards for runtime type checking:
function isQueryMatch(obj: unknown): obj is QueryMatch {
return (
typeof obj === 'object' &&
obj !== null &&
'id' in obj &&
'score' in obj &&
typeof (obj as QueryMatch).id === 'string' &&
typeof (obj as QueryMatch).score === 'number'
);
}
function isValidNetwork(value: string): value is Network {
return ['mainnet-beta', 'devnet', 'localnet'].includes(value);
}
Complete Type Reference
Import All Types
import type {
// Configuration
Network,
DistanceMetric,
SolVecConfig,
CollectionConfig,
// Vector Operations
UpsertRecord,
UpsertResponse,
QueryOptions,
QueryMatch,
QueryResponse,
// Metadata & Stats
CollectionStats,
VerificationResult
} from 'solvec';
Common Dimension Sizes
OpenAI
text-embedding-ada-002: 1536 dimensions
Sentence Transformers
all-mpnet-base-v2: 768 dimensionsall-MiniLM-L6-v2: 384 dimensions
Cohere
embed-english-v3.0: 1024 dimensions
Custom
Any dimension size supported