QGraph (Quantized Graph) uses a Hierarchical Navigable Small World (HNSW) graph structure with optional quantization. Configure the build and search parameters below to balance performance, recall rate, and index size for your workload.
Index build parameters
Build parameters are set at index creation time. Changing them requires rebuilding the index.
| Parameter | Type | Default | Description |
|---|---|---|---|
proxima.hnsw.builder.max_neighbor_count | uint32 | 100 | Maximum number of neighbors per graph node. Higher values improve graph connectivity but increase construction time and index size. |
proxima.hnsw.builder.efconstruction | uint32 | 500 | Size of the neighbor scan area during graph construction. Higher values produce a higher-quality graph but slow down index construction. Start with 400. |
proxima.hnsw.builder.thread_count | uint32 | 0 | Number of threads used during construction. 0 uses the number of available CPU cores. |
proxima.qgraph.builder.quantizer_class | string | None | Quantizer applied to the index. Options: Int4QuantizerConverter, Int8QuantizerConverter, HalfFloatConverter. See Choose a quantizer. |
Index search parameters
Search parameters can be adjusted without rebuilding the index.
| Parameter | Type | Default | Description |
|---|---|---|---|
proxima.hnsw.searcher.ef | uint32 | 500 | Number of nearest-neighbor candidates scanned during an online search. Higher values improve recall rate but reduce search performance. Set in the range [100, 1000]. |
proxima.hnsw.searcher.max_scan_ratio | float | None | Proportion of points scanned during an online search. Higher values improve recall rate but reduce search performance. |
proxima.hnsw.searcher.brute_force_threshold | uint32 | None | Minimum number of points scanned during an online search. When this value exceeds the document count in a shard, the search switches to brute force. |
Choose a quantizer
Quantization reduces index size and improves search performance at the cost of recall rate. Choose based on your memory budget and accuracy requirements.
| Quantizer class | Index size | Search performance | Recall rate |
|---|---|---|---|
Int4QuantizerConverter | Smallest | Highest | Lowest |
Int8QuantizerConverter | Medium | Medium | Medium |
HalfFloatConverter | Close to unquantized | Close to unquantized | Close to unquantized |
Note: Due to CPU instruction set constraints,HalfFloatConverterdelivers performance and recall rate nearly identical to no quantization. UseInt8QuantizerConverterfor a meaningful size reduction, orInt4QuantizerConverterfor the smallest index.
Tuning guide
The right configuration depends on your query throughput, write frequency, and recall target. Use this table as a starting point.
| Query throughput | Write frequency | Recall target | Recommended configuration |
|---|---|---|---|
| Low | Low | Low | Keep efconstruction and ef low. A smaller machine is sufficient. |
| Low | Low | High | Increase efconstruction and ef until recall meets your target. |
| Low | High | Low | Keep efconstruction low. Tune ef upward to reach the desired recall rate. |
| Low | High | High | Keep efconstruction low. Increase ef significantly. |
| High | Low | Low | High query throughput requires low ef. Low recall allows low efconstruction. |
| High | Any | High | The most demanding scenario. Keep efconstruction and ef as low as possible while meeting your recall target. |
General principles:
efis the primary search-time tuning knob. Increase it to improve recall rate; decrease it to improve search performance.max_scan_ratioandbrute_force_thresholdprovide additional scan controls for advanced use cases.