> ## Documentation Index > Fetch the complete documentation index at: https://docs.cyborg.co/llms.txt > Use this file to discover all available pages before exploring further. # Query Searches for nearest neighbors in the encrypted index using vector similarity search. Supports both single vector queries and batch queries with multiple vectors, as well as content-based search. ```typescript theme={null} async query({ queryVectors?: number[] | number[][] | Float32Array, // optional, required if `queryContents` not provided queryContents?: string, // optional, required if `queryVectors` not provided topK?: number, // optional, default: 100 nProbes?: number, // optional, default: undefined (auto) filters?: FilterExpression, // optional, default: {} include?: string[], // optional, default: [] (only `id` is returned) greedy?: boolean, // optional, default: false rerankMult?: number, // optional, default: undefined (server default: 10) dimension?: number // optional, required when queryVectors is Float32Array }): Promise ``` ### Parameters | Parameter | Type | Default | Description | | --------------- | ----------------------------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `queryVectors` | `number[]` \| `number[][]` \| `Float32Array` | - | Single vector `[0.1, 0.2]`, batch vectors `[[0.1, 0.2], [0.3, 0.4]]`, or typed array | | `queryContents` | `string` | - | *(Optional)* Text content to embed and search (alternative to queryVectors) | | `topK` | `number` | `undefined` (server default: 100) | *(Optional)* Number of nearest neighbors to return per query | | `nProbes` | `number` | `undefined` (auto) | *(Optional)* Number of cluster centers to search (higher = better recall). Auto-determined when undefined. | | `filters` | [`FilterExpression`](../types#filterexpression) | `undefined` | *(Optional)* Metadata filters to apply to the search (no filtering when undefined) | | `include` | `string[]` | `undefined` (server default: `[]` — only `id` is returned) | *(Optional)* Fields to include: `"distance"`, `"metadata"`, `"vector"`, `"contents"` | | `greedy` | `boolean` | `false` | *(Optional)* Use faster approximate search | | `rerankMult` | `number` | `undefined` (server default: 10) | *(Optional)* Multiplier for stage 1 retrieval in reranking indexes. Stage 1 returns `topK * rerankMult` candidates before the rerank pass narrows the result to `topK`. Higher values trade query latency for recall. Ignored by indexes that do not rerank. | | `dimension` | `number` | `-` | **Required when `queryVectors` is a `Float32Array`** — the SDK uses it to reshape the flat typed array into individual query vectors. Optional (and ignored) for `number[]` / `number[][]` inputs. | Passing a `Float32Array` as `queryVectors` uses an optimized binary transfer format for better performance. When using `Float32Array`, the `dimension` parameter is required so the SDK can correctly reshape the flat array into individual query vectors. `include` defaults differ between endpoints: `query` returns `[]` (only `id`) by default, while [`get`](./get) returns `["vector", "contents", "metadata"]`. ### Returns `Promise`: A Promise that resolves to search results. The response format depends on the query type: * **Single vector query**: `results` is a flat array of `QueryResultItem[]` * **Batch query**: `results` is a nested array of `QueryResultItem[][]` (one array per input vector) ### 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 during the search. * Throws if neither queryVectors nor queryContents is provided. * Throws if vector dimensions don't match the index configuration. * Throws if parameter values are out of valid ranges. * Throws if the `include` parameter contains invalid field names. ### Example Usage #### Basic Single Vector Query ```typescript theme={null} 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 }); // Search for similar vectors const queryVector = [0.15, 0.25, 0.35, 0.45]; try { const results = await index.query({ queryVectors: queryVector, topK: 5, include: ['distance', 'metadata'] // include defaults to [] (only `id`); request distance and metadata }); // Single vector query returns flat array console.log(`Found ${results.results.length} similar vectors:`); results.results.forEach((item, i) => { console.log(`${i + 1}. ID: ${item.id}, Distance: ${item.distance}`); if (item.metadata) { console.log(` Metadata: ${JSON.stringify(item.metadata)}`); } }); } catch (error: any) { console.error('Query failed:', error.message); } ``` #### Content-Based Search (Text Search) ```typescript theme={null} // Search by text content (requires embedding model configured on index) try { const contentResults = await index.query({ queryContents: "machine learning tutorial", // content to embed and search topK: 10, // return top 10 results include: ['distance', 'metadata'] // include defaults to [] (only `id`); request distance and metadata }); console.log('Content-based search results:'); contentResults.results.forEach((item, i) => { console.log(`${i + 1}. ${item.id}: ${item.metadata?.title}`); console.log(` Distance: ${item.distance}`); }); } catch (error: any) { console.error('Content search failed:', error.message); // May fail if no embedding model is configured for the index } ``` #### Advanced Single Query with Filters ```typescript theme={null} const queryVector = [0.1, 0.2, 0.3, 0.4]; try { const results = await index.query({ queryVectors: queryVector, topK: 10, // return top 10 results nProbes: 5, // probe 5 clusters for better accuracy filters: { category: 'research', published: true }, // only research documents include: ['distance', 'metadata', 'contents'], // return all fields greedy: false // use exact search }); console.log('Advanced query results:'); results.results.forEach((item, i) => { console.log(`${i + 1}. ${item.id}`); console.log(` Distance: ${item.distance}`); console.log(` Category: ${item.metadata?.category}`); console.log(` Content Preview: ${item.contents?.toString().substring(0, 100)}...`); }); } catch (error: any) { console.error('Advanced query failed:', error.message); } ``` #### Batch Vector Query ```typescript theme={null} // Query multiple vectors at once const queryVectors = [ [0.1, 0.2, 0.3, 0.4], // First query vector [0.5, 0.6, 0.7, 0.8], // Second query vector [0.9, 1.0, 1.1, 1.2] // Third query vector ]; try { const batchResults = await index.query({ queryVectors, topK: 3, include: ['distance'] // include defaults to [] (only `id`); request distance }); // Batch query returns nested arrays - one per input vector console.log(`Batch query completed for ${queryVectors.length} vectors:`); batchResults.results.forEach((queryResults, queryIndex) => { console.log(`\nResults for query vector ${queryIndex + 1}:`); queryResults.forEach((item, resultIndex) => { console.log(` ${resultIndex + 1}. ${item.id} (distance: ${item.distance})`); }); }); } catch (error: any) { console.error('Batch query failed:', error.message); } ``` #### Complex Metadata Filtering ```typescript theme={null} // Simple equality filter const simpleFilter = { category: 'research' }; // Complex nested filter with operators const complexFilter = { "$and": [ { "author.name": "Dr. Smith" }, { "metrics.score": { "$gte": 0.8 } }, { "tags": { "$in": ["ai", "ml", "neural-networks"] } }, { "published_date": { "$gte": "2024-01-01" } } ] }; // Range filter example const dateRangeFilter = { "created_date": { "$gte": "2024-01-01", "$lte": "2024-12-31" }, "status": "published" }; try { const filteredResults = await index.query({ queryVectors: queryVector, topK: 15, nProbes: 3, filters: complexFilter, // Use complex filter include: ['distance', 'metadata'] }); console.log(`Found ${filteredResults.results.length} filtered results`); } catch (error: any) { console.error('Filtered query failed:', error.message); } ``` ### Response Format #### Single Query Response ```typescript theme={null} { "results": [ { "id": "doc1", "distance": 0.234, "metadata": { "title": "Document 1", "category": "research" }, } ] } ``` #### Batch Query Response ```typescript theme={null} { "results": [ [ // Results for first query vector { "id": "doc1", "distance": 0.234, "metadata": {...} }, { "id": "doc2", "distance": 0.456, "metadata": {...} } ], [ // Results for second query vector { "id": "doc3", "distance": 0.123, "metadata": {...} }, { "id": "doc4", "distance": 0.567, "metadata": {...} } ] ] } ```