Skip to main content
Retrieves vectors from the encrypted index by their IDs, with options to specify which fields to include in the results. 
async get({
    ids: string[],     // required
    include?: string[]  // optional, default: ["vector", "contents", "metadata"]
}): Promise<Array<object>>

​
Parameters

ParameterTypeDefaultDescription
idsstring[]-Array of vector IDs to retrieve from the index
includestring[]["vector", "contents", "metadata"](Optional) Fields to include in the response. Valid options: "vector", "contents", "metadata"

​
Returns

Promise<Array<object>>: A Promise that resolves to an array of retrieved vector items, each containing the requested fields based on the include parameter.

​
Exceptions

  • Throws if the API request fails due to network connectivity issues.
  • Throws if authentication fails (invalid API key).
  • Throws if the encryption key is invalid for the specified index.
  • Throws if there are internal server errors preventing the retrieval.
  • Throws if the ids parameter is null, undefined, or empty.
  • Throws if the include parameter contains invalid field names.

​
Example Usage

import { Client } from 'cyborgdb';

const client = new Client({ baseUrl: 'http://localhost:8000', apiKey: 'your-api-key' });

// Load an existing index
const indexKey = new Uint8Array(Buffer.from('your-stored-hex-key', 'hex'));
const index = await client.loadIndex({ indexName: 'my-vector-index', indexKey });

// Add some vectors first
await index.upsert({
    items: [
        { 
            id: 'doc1', 
            vector: [0.1, 0.2, 0.3, 0.4], 
            contents: 'This is the first document content',
                metadata: { title: 'Document 1', category: 'research', date: '2024-01-15' }
        },
        { 
            id: 'doc2', 
            vector: [0.4, 0.5, 0.6, 0.7], 
            contents: 'This is the second document content',
            metadata: { title: 'Document 2', category: 'tutorial', date: '2024-01-16' }
        }
    ]
});

// Retrieve vectors with all fields (default behavior)
try {
    const vectors = await index.get({ ids: ['doc1', 'doc2'] });

    vectors.forEach(item => {
        console.log(`ID: ${item.id}`);
        console.log(`Vector dimensions: ${item.vector?.length}`);
        console.log(`Contents: ${item.contents}`);
        console.log(`Metadata: ${JSON.stringify(item.metadata)}`);
        console.log('---');
    });
    
} catch (error: any) {
    console.error('Failed to retrieve vectors:', error.message);
}

​
Response Format

The method returns an array of objects with the following structure: 
// Example response with all fields
[
    {
        "id": "doc1",
        "vector": [0.1, 0.2, 0.3, 0.4],
        "contents": Buffer, // Always returned as Buffer (bytes)
        "metadata": {
            "title": "Document 1",
            "category": "research",
            "date": "2024-01-15"
        }
    },
    {
        "id": "doc2",
        "vector": [0.4, 0.5, 0.6, 0.7],
        "contents": Buffer, // Always returned as Buffer (bytes)
        "metadata": {
            "title": "Document 2",
            "category": "tutorial",
            "date": "2024-01-16"
        }
    }
]
The contents field is always returned as a Buffer (bytes), regardless of whether it was originally stored as a string or Buffer. All contents are encoded to bytes and encrypted before storage.

​
Response Item Fields

FieldTypeDescription
idstringUnique identifier of the vector (always included)
vectornumber[]The vector data (included if "vector" in include array)
contentsBufferThe content data as Buffer (bytes), always returned as bytes (included if "contents" in include array)
metadataanyAssociated metadata object (included if "metadata" in include array)