Skip to main content

zvec_rust_sys/
lib.rs

1//! Raw FFI bindings to the zvec C-API.
2//!
3//! This crate provides low-level Rust bindings to the zvec vector database C library.
4//! It exposes opaque pointer types, constants, and function declarations that mirror
5//! the C API exactly. For a safer, more idiomatic Rust interface, consider using the
6//! higher-level `zvec` crate which wraps these raw bindings.
7//!
8//! # Safety
9//!
10//! All functions in this crate are `unsafe` by nature as they interact with C code.
11//! Proper memory management and lifetime handling is the responsibility of the caller.
12
13#![allow(non_camel_case_types, non_upper_case_globals)]
14
15use std::os::raw::{c_char, c_int, c_void};
16
17// =============================================================================
18// Opaque Pointer Types
19// =============================================================================
20
21/// Opaque pointer to a vector collection instance.
22/// Represents an opened collection that can be used for read/write operations.
23#[repr(C)]
24pub struct zvec_collection_t {
25    _private: [u8; 0],
26}
27
28/// Opaque pointer to a collection schema definition.
29/// Defines the structure of fields and indexes in a collection.
30#[repr(C)]
31pub struct zvec_collection_schema_t {
32    _private: [u8; 0],
33}
34
35/// Opaque pointer to a field schema definition.
36/// Defines the properties of a single field including type, index, etc.
37#[repr(C)]
38pub struct zvec_field_schema_t {
39    _private: [u8; 0],
40}
41
42/// Opaque pointer to index configuration parameters.
43/// Contains settings for HNSW, IVF, or other index types.
44#[repr(C)]
45pub struct zvec_index_params_t {
46    _private: [u8; 0],
47}
48
49/// Opaque pointer to a document instance.
50/// Represents a single record with fields and values in a collection.
51#[repr(C)]
52pub struct zvec_doc_t {
53    _private: [u8; 0],
54}
55
56/// Opaque pointer to a vector query object.
57/// Configures search parameters for vector similarity queries.
58#[repr(C)]
59pub struct zvec_vector_query_t {
60    _private: [u8; 0],
61}
62
63/// Opaque pointer to a group-by vector query object.
64/// Configures grouped vector search with aggregation parameters.
65#[repr(C)]
66pub struct zvec_group_by_vector_query_t {
67    _private: [u8; 0],
68}
69
70/// Opaque pointer to collection opening options.
71/// Controls behavior like MMAP, buffer size, and read-only mode.
72#[repr(C)]
73pub struct zvec_collection_options_t {
74    _private: [u8; 0],
75}
76
77/// Opaque pointer to collection statistics data.
78/// Contains metrics like document count and index completeness.
79#[repr(C)]
80pub struct zvec_collection_stats_t {
81    _private: [u8; 0],
82}
83
84/// Opaque pointer to global configuration data.
85/// Manages memory limits, thread counts, and other system-wide settings.
86#[repr(C)]
87pub struct zvec_config_data_t {
88    _private: [u8; 0],
89}
90
91/// Opaque pointer to logging configuration.
92/// Controls log level, output type (console/file), and file rotation settings.
93#[repr(C)]
94pub struct zvec_log_config_t {
95    _private: [u8; 0],
96}
97
98/// Opaque pointer to HNSW index query parameters.
99/// Configures ef, radius, and refiner settings for HNSW searches.
100#[repr(C)]
101pub struct zvec_hnsw_query_params_t {
102    _private: [u8; 0],
103}
104
105/// Opaque pointer to IVF index query parameters.
106/// Configures nprobe, scale factor, and refiner settings for IVF searches.
107#[repr(C)]
108pub struct zvec_ivf_query_params_t {
109    _private: [u8; 0],
110}
111
112/// Opaque pointer to IVF RaBitQ index query parameters.
113/// Configures nprobe, scale factor, and refiner settings for IVF RaBitQ searches.
114#[repr(C)]
115pub struct zvec_ivf_rabitq_query_params_t {
116    _private: [u8; 0],
117}
118
119/// Opaque pointer to flat index query parameters.
120/// Configures scale factor and refiner settings for brute-force searches.
121#[repr(C)]
122pub struct zvec_flat_query_params_t {
123    _private: [u8; 0],
124}
125
126/// Opaque pointer to Vamana index query parameters.
127/// Configures ef_search, radius, and refiner settings for Vamana searches.
128#[repr(C)]
129pub struct zvec_vamana_query_params_t {
130    _private: [u8; 0],
131}
132
133/// Opaque pointer to DiskANN index query parameters.
134/// Configures list_size, radius, and refiner settings for DiskANN searches.
135#[repr(C)]
136pub struct zvec_diskann_query_params_t {
137    _private: [u8; 0],
138}
139
140/// Opaque pointer to FTS query parameters.
141/// Controls the default boolean operator for adjacent bare terms.
142#[repr(C)]
143pub struct zvec_fts_query_params_t {
144    _private: [u8; 0],
145}
146
147/// Opaque pointer to FTS query payload.
148/// Holds query_string (boolean expression) and match_string (natural-language).
149#[repr(C)]
150pub struct zvec_fts_t {
151    _private: [u8; 0],
152}
153
154/// Opaque pointer to a multi-query object.
155/// Combines multiple sub-queries with a re-ranking strategy (RRF / Weighted).
156#[repr(C)]
157pub struct zvec_multi_query_t {
158    _private: [u8; 0],
159}
160
161/// Opaque pointer to a sub-query object used inside a multi-query.
162/// Carries a per-field vector or sparse vector and index-specific parameters.
163#[repr(C)]
164pub struct zvec_sub_query_t {
165    _private: [u8; 0],
166}
167
168/// Opaque pointer to a document iterator for full collection traversal.
169/// Created by `zvec_collection_create_iterator`, released by `zvec_doc_iterator_close`.
170/// Iterates over an isolated snapshot taken at creation time.
171#[repr(C)]
172pub struct zvec_doc_iterator_t {
173    _private: [u8; 0],
174}
175
176/// Opaque pointer to document iterator options.
177/// Controls which scalar fields and whether vectors are returned.
178#[repr(C)]
179pub struct zvec_iterator_options_t {
180    _private: [u8; 0],
181}
182
183// =============================================================================
184// Type Aliases
185// =============================================================================
186
187/// Error code returned by zvec functions.
188pub type zvec_error_code_t = u32;
189/// Data type identifier for field values.
190pub type zvec_data_type_t = u32;
191/// Index algorithm type identifier.
192pub type zvec_index_type_t = u32;
193/// Distance metric type for vector similarity.
194pub type zvec_metric_type_t = u32;
195/// Quantization type for vector compression.
196pub type zvec_quantize_type_t = u32;
197/// Log severity level.
198pub type zvec_log_level_t = u32;
199/// Log output destination type.
200pub type zvec_log_type_t = u32;
201/// Document operation type (insert/update/delete).
202pub type zvec_doc_operator_t = u32;
203/// I/O backend used for DiskAnn disk reads.
204pub type zvec_io_backend_type_t = u32;
205
206// =============================================================================
207// Error Code Constants
208// =============================================================================
209
210/// Operation completed successfully.
211pub const ZVEC_OK: zvec_error_code_t = 0;
212/// Requested resource was not found.
213pub const ZVEC_ERROR_NOT_FOUND: zvec_error_code_t = 1;
214/// Resource already exists.
215pub const ZVEC_ERROR_ALREADY_EXISTS: zvec_error_code_t = 2;
216/// Invalid argument provided.
217pub const ZVEC_ERROR_INVALID_ARGUMENT: zvec_error_code_t = 3;
218/// Permission denied for the operation.
219pub const ZVEC_ERROR_PERMISSION_DENIED: zvec_error_code_t = 4;
220/// Operation failed due to unmet precondition.
221pub const ZVEC_ERROR_FAILED_PRECONDITION: zvec_error_code_t = 5;
222/// System resources exhausted.
223pub const ZVEC_ERROR_RESOURCE_EXHAUSTED: zvec_error_code_t = 6;
224/// Service is currently unavailable.
225pub const ZVEC_ERROR_UNAVAILABLE: zvec_error_code_t = 7;
226/// Internal system error occurred.
227pub const ZVEC_ERROR_INTERNAL_ERROR: zvec_error_code_t = 8;
228/// Operation is not supported.
229pub const ZVEC_ERROR_NOT_SUPPORTED: zvec_error_code_t = 9;
230/// Unknown error occurred.
231pub const ZVEC_ERROR_UNKNOWN: zvec_error_code_t = 10;
232
233// =============================================================================
234// Data Type Constants
235// =============================================================================
236
237/// Undefined data type.
238pub const ZVEC_DATA_TYPE_UNDEFINED: zvec_data_type_t = 0;
239/// Binary data type.
240pub const ZVEC_DATA_TYPE_BINARY: zvec_data_type_t = 1;
241/// String data type.
242pub const ZVEC_DATA_TYPE_STRING: zvec_data_type_t = 2;
243/// Boolean data type.
244pub const ZVEC_DATA_TYPE_BOOL: zvec_data_type_t = 3;
245/// 32-bit signed integer.
246pub const ZVEC_DATA_TYPE_INT32: zvec_data_type_t = 4;
247/// 64-bit signed integer.
248pub const ZVEC_DATA_TYPE_INT64: zvec_data_type_t = 5;
249/// 32-bit unsigned integer.
250pub const ZVEC_DATA_TYPE_UINT32: zvec_data_type_t = 6;
251/// 64-bit unsigned integer.
252pub const ZVEC_DATA_TYPE_UINT64: zvec_data_type_t = 7;
253/// 32-bit floating point.
254pub const ZVEC_DATA_TYPE_FLOAT: zvec_data_type_t = 8;
255/// 64-bit floating point.
256pub const ZVEC_DATA_TYPE_DOUBLE: zvec_data_type_t = 9;
257/// Dense vector with binary32 (float) elements.
258pub const ZVEC_DATA_TYPE_VECTOR_BINARY32: zvec_data_type_t = 20;
259/// Dense vector with binary64 (double) elements.
260pub const ZVEC_DATA_TYPE_VECTOR_BINARY64: zvec_data_type_t = 21;
261/// Dense vector with FP16 (half precision) elements.
262pub const ZVEC_DATA_TYPE_VECTOR_FP16: zvec_data_type_t = 22;
263/// Dense vector with FP32 (single precision) elements.
264pub const ZVEC_DATA_TYPE_VECTOR_FP32: zvec_data_type_t = 23;
265/// Dense vector with FP64 (double precision) elements.
266pub const ZVEC_DATA_TYPE_VECTOR_FP64: zvec_data_type_t = 24;
267/// Dense vector with INT4 quantized elements.
268pub const ZVEC_DATA_TYPE_VECTOR_INT4: zvec_data_type_t = 25;
269/// Dense vector with INT8 quantized elements.
270pub const ZVEC_DATA_TYPE_VECTOR_INT8: zvec_data_type_t = 26;
271/// Dense vector with INT16 quantized elements.
272pub const ZVEC_DATA_TYPE_VECTOR_INT16: zvec_data_type_t = 27;
273/// Dense vector with unsigned 8-bit elements (Flat reference storage).
274pub const ZVEC_DATA_TYPE_VECTOR_UINT8: zvec_data_type_t = 28;
275/// Sparse vector with FP16 elements.
276pub const ZVEC_DATA_TYPE_SPARSE_VECTOR_FP16: zvec_data_type_t = 30;
277/// Sparse vector with FP32 elements.
278pub const ZVEC_DATA_TYPE_SPARSE_VECTOR_FP32: zvec_data_type_t = 31;
279/// Array of binary values.
280pub const ZVEC_DATA_TYPE_ARRAY_BINARY: zvec_data_type_t = 40;
281/// Array of strings.
282pub const ZVEC_DATA_TYPE_ARRAY_STRING: zvec_data_type_t = 41;
283/// Array of booleans.
284pub const ZVEC_DATA_TYPE_ARRAY_BOOL: zvec_data_type_t = 42;
285/// Array of 32-bit signed integers.
286pub const ZVEC_DATA_TYPE_ARRAY_INT32: zvec_data_type_t = 43;
287/// Array of 64-bit signed integers.
288pub const ZVEC_DATA_TYPE_ARRAY_INT64: zvec_data_type_t = 44;
289/// Array of 32-bit unsigned integers.
290pub const ZVEC_DATA_TYPE_ARRAY_UINT32: zvec_data_type_t = 45;
291/// Array of 64-bit unsigned integers.
292pub const ZVEC_DATA_TYPE_ARRAY_UINT64: zvec_data_type_t = 46;
293/// Array of 32-bit floats.
294pub const ZVEC_DATA_TYPE_ARRAY_FLOAT: zvec_data_type_t = 47;
295/// Array of 64-bit doubles.
296pub const ZVEC_DATA_TYPE_ARRAY_DOUBLE: zvec_data_type_t = 48;
297
298// =============================================================================
299// Index Type Constants
300// =============================================================================
301
302/// Undefined index type.
303pub const ZVEC_INDEX_TYPE_UNDEFINED: zvec_index_type_t = 0;
304/// HNSW (Hierarchical Navigable Small World) graph index.
305pub const ZVEC_INDEX_TYPE_HNSW: zvec_index_type_t = 1;
306/// IVF (Inverted File Index) with clustering.
307pub const ZVEC_INDEX_TYPE_IVF: zvec_index_type_t = 2;
308/// Flat/brute-force index (exact search).
309pub const ZVEC_INDEX_TYPE_FLAT: zvec_index_type_t = 3;
310/// HNSW graph index with RaBitQ quantization.
311pub const ZVEC_INDEX_TYPE_HNSW_RABITQ: zvec_index_type_t = 4;
312/// DiskANN disk-based graph index.
313pub const ZVEC_INDEX_TYPE_DISKANN: zvec_index_type_t = 5;
314/// Vamana disk-based graph index.
315pub const ZVEC_INDEX_TYPE_VAMANA: zvec_index_type_t = 6;
316/// IVF index with RaBitQ quantization.
317pub const ZVEC_INDEX_TYPE_IVF_RABITQ: zvec_index_type_t = 7;
318/// Inverted index for scalar field filtering.
319pub const ZVEC_INDEX_TYPE_INVERT: zvec_index_type_t = 10;
320/// Full-text search index.
321pub const ZVEC_INDEX_TYPE_FTS: zvec_index_type_t = 11;
322
323// =============================================================================
324// Metric Type Constants
325// =============================================================================
326
327/// Undefined metric type.
328pub const ZVEC_METRIC_TYPE_UNDEFINED: zvec_metric_type_t = 0;
329/// L2 (Euclidean) distance.
330pub const ZVEC_METRIC_TYPE_L2: zvec_metric_type_t = 1;
331/// Inner product (dot product).
332pub const ZVEC_METRIC_TYPE_IP: zvec_metric_type_t = 2;
333/// Cosine similarity.
334pub const ZVEC_METRIC_TYPE_COSINE: zvec_metric_type_t = 3;
335/// MIPS converted to L2 distance.
336pub const ZVEC_METRIC_TYPE_MIPSL2: zvec_metric_type_t = 4;
337
338// =============================================================================
339// Quantize Type Constants
340// =============================================================================
341
342/// Undefined quantization type.
343pub const ZVEC_QUANTIZE_TYPE_UNDEFINED: zvec_quantize_type_t = 0;
344/// FP16 (half precision) quantization.
345pub const ZVEC_QUANTIZE_TYPE_FP16: zvec_quantize_type_t = 1;
346/// INT8 (8-bit integer) quantization.
347pub const ZVEC_QUANTIZE_TYPE_INT8: zvec_quantize_type_t = 2;
348/// INT4 (4-bit integer) quantization.
349pub const ZVEC_QUANTIZE_TYPE_INT4: zvec_quantize_type_t = 3;
350/// RaBitQ quantization.
351pub const ZVEC_QUANTIZE_TYPE_RABITQ: zvec_quantize_type_t = 4;
352
353// =============================================================================
354// Log Level Constants
355// =============================================================================
356
357/// Debug level logging (most verbose).
358pub const ZVEC_LOG_LEVEL_DEBUG: zvec_log_level_t = 0;
359/// Info level logging.
360pub const ZVEC_LOG_LEVEL_INFO: zvec_log_level_t = 1;
361/// Warning level logging.
362pub const ZVEC_LOG_LEVEL_WARN: zvec_log_level_t = 2;
363/// Error level logging.
364pub const ZVEC_LOG_LEVEL_ERROR: zvec_log_level_t = 3;
365/// Fatal level logging (least verbose, critical errors only).
366pub const ZVEC_LOG_LEVEL_FATAL: zvec_log_level_t = 4;
367
368// =============================================================================
369// Log Type Constants
370// =============================================================================
371
372/// Console output logging.
373pub const ZVEC_LOG_TYPE_CONSOLE: zvec_log_type_t = 0;
374/// File output logging.
375pub const ZVEC_LOG_TYPE_FILE: zvec_log_type_t = 1;
376
377// =============================================================================
378// Doc Operator Constants
379// =============================================================================
380
381/// Insert operation (fails if document exists).
382pub const ZVEC_DOC_OP_INSERT: zvec_doc_operator_t = 0;
383/// Update operation (fails if document doesn't exist).
384pub const ZVEC_DOC_OP_UPDATE: zvec_doc_operator_t = 1;
385/// Upsert operation (insert or update).
386pub const ZVEC_DOC_OP_UPSERT: zvec_doc_operator_t = 2;
387/// Delete operation.
388pub const ZVEC_DOC_OP_DELETE: zvec_doc_operator_t = 3;
389
390// =============================================================================
391// I/O Backend Type Constants
392// =============================================================================
393
394/// Synchronous pread(); no async I/O.
395pub const ZVEC_IO_BACKEND_TYPE_PREAD: zvec_io_backend_type_t = 0;
396/// libaio loaded at runtime via dlopen().
397pub const ZVEC_IO_BACKEND_TYPE_LIBAIO: zvec_io_backend_type_t = 1;
398/// io_uring via raw Linux kernel syscalls (zero dependency).
399pub const ZVEC_IO_BACKEND_TYPE_IO_URING: zvec_io_backend_type_t = 2;
400/// Windows overlapped I/O using per-context IOCP.
401pub const ZVEC_IO_BACKEND_TYPE_WINDOWS_OVERLAPPED: zvec_io_backend_type_t = 3;
402
403// =============================================================================
404// Non-Opaque Structures
405// =============================================================================
406
407/// A non-owning view of a string (pointer + length).
408#[repr(C)]
409pub struct zvec_string_view_t {
410    pub data: *const c_char,
411    pub length: usize,
412}
413
414/// An owning, mutable string with capacity tracking.
415#[repr(C)]
416pub struct zvec_string_t {
417    pub data: *mut c_char,
418    pub length: usize,
419    pub capacity: usize,
420}
421
422/// An array of owned strings.
423#[repr(C)]
424pub struct zvec_string_array_t {
425    pub strings: *mut zvec_string_t,
426    pub count: usize,
427}
428
429/// A view of a float array (non-owning).
430#[repr(C)]
431pub struct zvec_float_array_t {
432    pub data: *const f32,
433    pub length: usize,
434}
435
436/// A view of an int64 array (non-owning).
437#[repr(C)]
438pub struct zvec_int64_array_t {
439    pub data: *const i64,
440    pub length: usize,
441}
442
443/// A view of a byte array (non-owning).
444#[repr(C)]
445pub struct zvec_byte_array_t {
446    pub data: *const u8,
447    pub length: usize,
448}
449
450/// A mutable, owning byte array with capacity tracking.
451#[repr(C)]
452pub struct zvec_mutable_byte_array_t {
453    pub data: *mut u8,
454    pub length: usize,
455    pub capacity: usize,
456}
457
458/// Result of a write operation (insert/update/delete).
459#[repr(C)]
460pub struct zvec_write_result_t {
461    pub code: zvec_error_code_t,
462    pub message: *const c_char,
463}
464
465/// Detailed error information including source location.
466#[repr(C)]
467pub struct zvec_error_details_t {
468    pub code: zvec_error_code_t,
469    pub message: *const c_char,
470    pub file: *const c_char,
471    pub line: c_int,
472    pub function: *const c_char,
473}
474
475// =============================================================================
476// FFI Function Declarations
477// =============================================================================
478
479extern "C" {
480    // -------------------------------------------------------------------------
481    // Version
482    // Functions for retrieving library version information.
483    // -------------------------------------------------------------------------
484    pub fn zvec_get_version() -> *const c_char;
485    pub fn zvec_check_version(major: c_int, minor: c_int, patch: c_int) -> bool;
486    pub fn zvec_get_version_major() -> c_int;
487    pub fn zvec_get_version_minor() -> c_int;
488    pub fn zvec_get_version_patch() -> c_int;
489
490    // -------------------------------------------------------------------------
491    // Error
492    // Functions for error handling and retrieval.
493    // -------------------------------------------------------------------------
494    pub fn zvec_get_last_error_details(
495        error_details: *mut zvec_error_details_t,
496    ) -> zvec_error_code_t;
497    pub fn zvec_get_last_error(error_msg: *mut *mut c_char) -> zvec_error_code_t;
498    pub fn zvec_clear_error();
499    pub fn zvec_error_code_to_string(error_code: zvec_error_code_t) -> *const c_char;
500
501    // -------------------------------------------------------------------------
502    // String Management
503    // Functions for creating, manipulating, and freeing string objects.
504    // -------------------------------------------------------------------------
505    pub fn zvec_string_create(str: *const c_char) -> *mut zvec_string_t;
506    pub fn zvec_string_create_from_view(view: *const zvec_string_view_t) -> *mut zvec_string_t;
507    pub fn zvec_bin_create(data: *const u8, length: usize) -> *mut zvec_string_t;
508    pub fn zvec_string_copy(str: *const zvec_string_t) -> *mut zvec_string_t;
509    pub fn zvec_string_c_str(str: *const zvec_string_t) -> *const c_char;
510    pub fn zvec_string_length(str: *const zvec_string_t) -> usize;
511    pub fn zvec_string_compare(str1: *const zvec_string_t, str2: *const zvec_string_t) -> c_int;
512    pub fn zvec_free_string(str: *mut zvec_string_t);
513
514    // -------------------------------------------------------------------------
515    // Array Management
516    // Functions for creating and managing arrays of various types.
517    // -------------------------------------------------------------------------
518    pub fn zvec_string_array_create(count: usize) -> *mut zvec_string_array_t;
519    pub fn zvec_string_array_add(array: *mut zvec_string_array_t, idx: usize, str: *const c_char);
520    pub fn zvec_string_array_destroy(array: *mut zvec_string_array_t);
521    pub fn zvec_byte_array_create(capacity: usize) -> *mut zvec_mutable_byte_array_t;
522    pub fn zvec_byte_array_destroy(array: *mut zvec_mutable_byte_array_t);
523    pub fn zvec_float_array_create(count: usize) -> *mut zvec_float_array_t;
524    pub fn zvec_float_array_destroy(array: *mut zvec_float_array_t);
525    pub fn zvec_int64_array_create(count: usize) -> *mut zvec_int64_array_t;
526    pub fn zvec_int64_array_destroy(array: *mut zvec_int64_array_t);
527    pub fn zvec_free_uint8_array(array: *mut u8);
528
529    // -------------------------------------------------------------------------
530    // Memory
531    // Functions for memory allocation and deallocation.
532    // -------------------------------------------------------------------------
533    pub fn zvec_malloc(size: usize) -> *mut c_void;
534    pub fn zvec_free(ptr: *mut c_void);
535
536    // -------------------------------------------------------------------------
537    // Log Configuration
538    // Functions for configuring logging behavior.
539    // -------------------------------------------------------------------------
540    pub fn zvec_config_log_create_console(level: zvec_log_level_t) -> *mut zvec_log_config_t;
541    pub fn zvec_config_log_create_file(
542        level: zvec_log_level_t,
543        dir: *const c_char,
544        basename: *const c_char,
545        file_size: u32,
546        overdue_days: u32,
547    ) -> *mut zvec_log_config_t;
548    pub fn zvec_config_log_destroy(config: *mut zvec_log_config_t);
549    pub fn zvec_config_log_get_level(config: *const zvec_log_config_t) -> zvec_log_level_t;
550    pub fn zvec_config_log_set_level(
551        config: *mut zvec_log_config_t,
552        level: zvec_log_level_t,
553    ) -> zvec_error_code_t;
554    pub fn zvec_config_log_is_file_type(config: *const zvec_log_config_t) -> bool;
555    pub fn zvec_config_log_get_dir(config: *const zvec_log_config_t) -> *const c_char;
556    pub fn zvec_config_log_set_dir(
557        config: *mut zvec_log_config_t,
558        dir: *const c_char,
559    ) -> zvec_error_code_t;
560    pub fn zvec_config_log_get_basename(config: *const zvec_log_config_t) -> *const c_char;
561    pub fn zvec_config_log_set_basename(
562        config: *mut zvec_log_config_t,
563        basename: *const c_char,
564    ) -> zvec_error_code_t;
565    pub fn zvec_config_log_get_file_size(config: *const zvec_log_config_t) -> u32;
566    pub fn zvec_config_log_set_file_size(
567        config: *mut zvec_log_config_t,
568        file_size: u32,
569    ) -> zvec_error_code_t;
570    pub fn zvec_config_log_get_overdue_days(config: *const zvec_log_config_t) -> u32;
571    pub fn zvec_config_log_set_overdue_days(
572        config: *mut zvec_log_config_t,
573        days: u32,
574    ) -> zvec_error_code_t;
575
576    // -------------------------------------------------------------------------
577    // Global Configuration
578    // Functions for managing global system configuration.
579    // -------------------------------------------------------------------------
580    pub fn zvec_config_data_create() -> *mut zvec_config_data_t;
581    pub fn zvec_config_data_destroy(config: *mut zvec_config_data_t);
582    pub fn zvec_config_data_set_memory_limit(
583        config: *mut zvec_config_data_t,
584        memory_limit_bytes: u64,
585    ) -> zvec_error_code_t;
586    pub fn zvec_config_data_get_memory_limit(config: *const zvec_config_data_t) -> u64;
587    pub fn zvec_config_data_set_log_config(
588        config: *mut zvec_config_data_t,
589        log_config: *mut zvec_log_config_t,
590    ) -> zvec_error_code_t;
591    pub fn zvec_config_data_get_log_type(config: *const zvec_config_data_t) -> zvec_log_type_t;
592    pub fn zvec_config_data_set_query_thread_count(
593        config: *mut zvec_config_data_t,
594        thread_count: u32,
595    ) -> zvec_error_code_t;
596    pub fn zvec_config_data_get_query_thread_count(config: *const zvec_config_data_t) -> u32;
597    pub fn zvec_config_data_set_invert_to_forward_scan_ratio(
598        config: *mut zvec_config_data_t,
599        ratio: f32,
600    ) -> zvec_error_code_t;
601    pub fn zvec_config_data_get_invert_to_forward_scan_ratio(
602        config: *const zvec_config_data_t,
603    ) -> f32;
604    pub fn zvec_config_data_set_brute_force_by_keys_ratio(
605        config: *mut zvec_config_data_t,
606        ratio: f32,
607    ) -> zvec_error_code_t;
608    pub fn zvec_config_data_get_brute_force_by_keys_ratio(config: *const zvec_config_data_t)
609        -> f32;
610    pub fn zvec_config_data_set_fts_brute_force_by_keys_ratio(
611        config: *mut zvec_config_data_t,
612        ratio: f32,
613    ) -> zvec_error_code_t;
614    pub fn zvec_config_data_get_fts_brute_force_by_keys_ratio(
615        config: *const zvec_config_data_t,
616    ) -> f32;
617    pub fn zvec_config_data_set_optimize_thread_count(
618        config: *mut zvec_config_data_t,
619        thread_count: u32,
620    ) -> zvec_error_code_t;
621    pub fn zvec_config_data_get_optimize_thread_count(config: *const zvec_config_data_t) -> u32;
622    pub fn zvec_config_data_set_jieba_dict_dir(
623        config: *mut zvec_config_data_t,
624        dir: *const c_char,
625    ) -> zvec_error_code_t;
626    pub fn zvec_config_data_get_jieba_dict_dir(config: *const zvec_config_data_t) -> *const c_char;
627
628    // -------------------------------------------------------------------------
629    // Initialization
630    // Functions for initializing and shutting down the library.
631    // -------------------------------------------------------------------------
632    pub fn zvec_initialize(config: *const zvec_config_data_t) -> zvec_error_code_t;
633    pub fn zvec_shutdown() -> zvec_error_code_t;
634    pub fn zvec_is_initialized() -> bool;
635    pub fn zvec_set_default_jieba_dict_dir(dir: *const c_char);
636    pub fn zvec_get_default_jieba_dict_dir() -> *const c_char;
637
638    // -------------------------------------------------------------------------
639    // I/O Backend Introspection
640    // Reports the backend used for DiskAnn disk reads.
641    // -------------------------------------------------------------------------
642    pub fn zvec_get_io_backend_type() -> zvec_io_backend_type_t;
643    pub fn zvec_get_io_backend_type_name(backend_type: zvec_io_backend_type_t) -> *const c_char;
644    pub fn zvec_get_io_backend_description() -> *const c_char;
645
646    // -------------------------------------------------------------------------
647    // Index Parameters
648    // Functions for creating and configuring index parameters.
649    // -------------------------------------------------------------------------
650    pub fn zvec_index_params_create(index_type: zvec_index_type_t) -> *mut zvec_index_params_t;
651    pub fn zvec_index_params_destroy(params: *mut zvec_index_params_t);
652    pub fn zvec_index_params_get_type(params: *const zvec_index_params_t) -> zvec_index_type_t;
653    pub fn zvec_index_params_set_metric_type(
654        params: *mut zvec_index_params_t,
655        metric_type: zvec_metric_type_t,
656    ) -> zvec_error_code_t;
657    pub fn zvec_index_params_get_metric_type(
658        params: *const zvec_index_params_t,
659    ) -> zvec_metric_type_t;
660    pub fn zvec_index_params_set_quantize_type(
661        params: *mut zvec_index_params_t,
662        quantize_type: zvec_quantize_type_t,
663    ) -> zvec_error_code_t;
664    pub fn zvec_index_params_get_quantize_type(
665        params: *const zvec_index_params_t,
666    ) -> zvec_quantize_type_t;
667    pub fn zvec_index_params_set_quantizer_enable_rotate(
668        params: *mut zvec_index_params_t,
669        enable_rotate: bool,
670    ) -> zvec_error_code_t;
671    pub fn zvec_index_params_get_quantizer_enable_rotate(
672        params: *const zvec_index_params_t,
673    ) -> bool;
674    pub fn zvec_index_params_set_hnsw_params(
675        params: *mut zvec_index_params_t,
676        m: c_int,
677        ef_construction: c_int,
678    ) -> zvec_error_code_t;
679    pub fn zvec_index_params_get_hnsw_m(params: *const zvec_index_params_t) -> c_int;
680    pub fn zvec_index_params_get_hnsw_ef_construction(params: *const zvec_index_params_t) -> c_int;
681    pub fn zvec_index_params_set_ivf_params(
682        params: *mut zvec_index_params_t,
683        n_list: c_int,
684        n_iters: c_int,
685        use_soar: bool,
686    ) -> zvec_error_code_t;
687    pub fn zvec_index_params_get_ivf_params(
688        params: *const zvec_index_params_t,
689        out_n_list: *mut c_int,
690        out_n_iters: *mut c_int,
691        out_use_soar: *mut bool,
692    ) -> zvec_error_code_t;
693    pub fn zvec_index_params_set_vamana_params(
694        params: *mut zvec_index_params_t,
695        max_degree: c_int,
696        search_list_size: c_int,
697        alpha: f32,
698        saturate_graph: bool,
699        use_contiguous_memory: bool,
700    ) -> zvec_error_code_t;
701    pub fn zvec_index_params_get_vamana_params(
702        params: *const zvec_index_params_t,
703        out_max_degree: *mut c_int,
704        out_search_list_size: *mut c_int,
705        out_alpha: *mut f32,
706        out_saturate_graph: *mut bool,
707        out_use_contiguous_memory: *mut bool,
708    ) -> zvec_error_code_t;
709    pub fn zvec_index_params_set_vamana_two_pass_build(
710        params: *mut zvec_index_params_t,
711        two_pass_build: bool,
712    ) -> zvec_error_code_t;
713    pub fn zvec_index_params_get_vamana_two_pass_build(params: *const zvec_index_params_t) -> bool;
714    pub fn zvec_index_params_set_diskann_params(
715        params: *mut zvec_index_params_t,
716        max_degree: c_int,
717        list_size: c_int,
718        pq_chunk_num: c_int,
719    ) -> zvec_error_code_t;
720    pub fn zvec_index_params_get_diskann_max_degree(params: *const zvec_index_params_t) -> c_int;
721    pub fn zvec_index_params_get_diskann_list_size(params: *const zvec_index_params_t) -> c_int;
722    pub fn zvec_index_params_get_diskann_pq_chunk_num(params: *const zvec_index_params_t) -> c_int;
723    pub fn zvec_index_params_set_ivf_rabitq_params(
724        params: *mut zvec_index_params_t,
725        nlist: c_int,
726        total_bits: c_int,
727        sample_count: c_int,
728    ) -> zvec_error_code_t;
729    pub fn zvec_index_params_get_ivf_rabitq_params(
730        params: *const zvec_index_params_t,
731        out_nlist: *mut c_int,
732        out_total_bits: *mut c_int,
733        out_sample_count: *mut c_int,
734    ) -> zvec_error_code_t;
735    pub fn zvec_index_params_set_invert_params(
736        params: *mut zvec_index_params_t,
737        enable_range_opt: bool,
738        enable_wildcard: bool,
739    ) -> zvec_error_code_t;
740    pub fn zvec_index_params_get_invert_params(
741        params: *const zvec_index_params_t,
742        out_enable_range_opt: *mut bool,
743        out_enable_wildcard: *mut bool,
744    ) -> zvec_error_code_t;
745    pub fn zvec_index_params_set_fts_params(
746        params: *mut zvec_index_params_t,
747        tokenizer_name: *const c_char,
748        filters: *const zvec_string_array_t,
749        extra_params: *const c_char,
750    ) -> zvec_error_code_t;
751    pub fn zvec_index_params_get_fts_params(
752        params: *const zvec_index_params_t,
753        out_tokenizer_name: *mut *const c_char,
754        out_filters: *mut *mut zvec_string_array_t,
755        out_extra_params: *mut *const c_char,
756    ) -> zvec_error_code_t;
757
758    // -------------------------------------------------------------------------
759    // Field Schema
760    // Functions for creating and managing field schema definitions.
761    // -------------------------------------------------------------------------
762    pub fn zvec_field_schema_create(
763        name: *const c_char,
764        data_type: zvec_data_type_t,
765        nullable: bool,
766        dimension: u32,
767    ) -> *mut zvec_field_schema_t;
768    pub fn zvec_field_schema_destroy(schema: *mut zvec_field_schema_t);
769    pub fn zvec_field_schema_set_name(
770        schema: *mut zvec_field_schema_t,
771        name: *const c_char,
772    ) -> zvec_error_code_t;
773    pub fn zvec_field_schema_get_name(schema: *const zvec_field_schema_t) -> *const c_char;
774    pub fn zvec_field_schema_get_data_type(schema: *const zvec_field_schema_t) -> zvec_data_type_t;
775    pub fn zvec_field_schema_set_data_type(
776        schema: *mut zvec_field_schema_t,
777        data_type: zvec_data_type_t,
778    ) -> zvec_error_code_t;
779    pub fn zvec_field_schema_get_element_data_type(
780        schema: *const zvec_field_schema_t,
781    ) -> zvec_data_type_t;
782    pub fn zvec_field_schema_get_element_data_size(schema: *const zvec_field_schema_t) -> usize;
783    pub fn zvec_field_schema_is_vector_field(schema: *const zvec_field_schema_t) -> bool;
784    pub fn zvec_field_schema_is_dense_vector(schema: *const zvec_field_schema_t) -> bool;
785    pub fn zvec_field_schema_is_sparse_vector(schema: *const zvec_field_schema_t) -> bool;
786    pub fn zvec_field_schema_is_nullable(schema: *const zvec_field_schema_t) -> bool;
787    pub fn zvec_field_schema_set_nullable(
788        schema: *mut zvec_field_schema_t,
789        nullable: bool,
790    ) -> zvec_error_code_t;
791    pub fn zvec_field_schema_has_invert_index(schema: *const zvec_field_schema_t) -> bool;
792    pub fn zvec_field_schema_is_array_type(schema: *const zvec_field_schema_t) -> bool;
793    pub fn zvec_field_schema_get_dimension(schema: *const zvec_field_schema_t) -> u32;
794    pub fn zvec_field_schema_set_dimension(
795        schema: *mut zvec_field_schema_t,
796        dimension: u32,
797    ) -> zvec_error_code_t;
798    pub fn zvec_field_schema_get_index_type(
799        schema: *const zvec_field_schema_t,
800    ) -> zvec_index_type_t;
801    pub fn zvec_field_schema_has_index(schema: *const zvec_field_schema_t) -> bool;
802    pub fn zvec_field_schema_get_index_params(
803        schema: *const zvec_field_schema_t,
804    ) -> *const zvec_index_params_t;
805    pub fn zvec_field_schema_set_index_params(
806        schema: *mut zvec_field_schema_t,
807        index_params: *const zvec_index_params_t,
808    ) -> zvec_error_code_t;
809    pub fn zvec_field_schema_validate(
810        schema: *const zvec_field_schema_t,
811        error_msg: *mut *mut zvec_string_t,
812    ) -> zvec_error_code_t;
813
814    // -------------------------------------------------------------------------
815    // Collection Schema
816    // Functions for creating and managing collection schema definitions.
817    // -------------------------------------------------------------------------
818    pub fn zvec_collection_schema_create(name: *const c_char) -> *mut zvec_collection_schema_t;
819    pub fn zvec_collection_schema_destroy(schema: *mut zvec_collection_schema_t);
820    pub fn zvec_collection_schema_get_name(
821        schema: *const zvec_collection_schema_t,
822    ) -> *const c_char;
823    pub fn zvec_collection_schema_set_name(
824        schema: *mut zvec_collection_schema_t,
825        name: *const c_char,
826    ) -> zvec_error_code_t;
827    pub fn zvec_collection_schema_add_field(
828        schema: *mut zvec_collection_schema_t,
829        field: *const zvec_field_schema_t,
830    ) -> zvec_error_code_t;
831    pub fn zvec_collection_schema_alter_field(
832        schema: *mut zvec_collection_schema_t,
833        field_name: *const c_char,
834        new_field: *const zvec_field_schema_t,
835    ) -> zvec_error_code_t;
836    pub fn zvec_collection_schema_drop_field(
837        schema: *mut zvec_collection_schema_t,
838        field_name: *const c_char,
839    ) -> zvec_error_code_t;
840    pub fn zvec_collection_schema_has_field(
841        schema: *const zvec_collection_schema_t,
842        field_name: *const c_char,
843    ) -> bool;
844    pub fn zvec_collection_schema_get_field(
845        schema: *const zvec_collection_schema_t,
846        field_name: *const c_char,
847    ) -> *mut zvec_field_schema_t;
848    pub fn zvec_collection_schema_get_forward_field(
849        schema: *const zvec_collection_schema_t,
850        field_name: *const c_char,
851    ) -> *mut zvec_field_schema_t;
852    pub fn zvec_collection_schema_get_vector_field(
853        schema: *const zvec_collection_schema_t,
854        field_name: *const c_char,
855    ) -> *mut zvec_field_schema_t;
856    pub fn zvec_collection_schema_get_forward_fields(
857        schema: *const zvec_collection_schema_t,
858        fields: *mut *mut *mut zvec_field_schema_t,
859        count: *mut usize,
860    ) -> zvec_error_code_t;
861    pub fn zvec_collection_schema_get_forward_fields_with_index(
862        schema: *const zvec_collection_schema_t,
863        fields: *mut *mut *mut zvec_field_schema_t,
864        count: *mut usize,
865    ) -> zvec_error_code_t;
866    pub fn zvec_collection_schema_get_forward_field_names(
867        schema: *const zvec_collection_schema_t,
868        names: *mut *mut *const c_char,
869        count: *mut usize,
870    ) -> zvec_error_code_t;
871    pub fn zvec_collection_schema_get_forward_field_names_with_index(
872        schema: *const zvec_collection_schema_t,
873        names: *mut *mut *const c_char,
874        count: *mut usize,
875    ) -> zvec_error_code_t;
876    pub fn zvec_collection_schema_get_all_field_names(
877        schema: *const zvec_collection_schema_t,
878        names: *mut *mut *const c_char,
879        count: *mut usize,
880    ) -> zvec_error_code_t;
881    pub fn zvec_collection_schema_get_vector_fields(
882        schema: *const zvec_collection_schema_t,
883        fields: *mut *mut *mut zvec_field_schema_t,
884        count: *mut usize,
885    ) -> zvec_error_code_t;
886    pub fn zvec_collection_schema_get_max_doc_count_per_segment(
887        schema: *const zvec_collection_schema_t,
888    ) -> u64;
889    pub fn zvec_collection_schema_set_max_doc_count_per_segment(
890        schema: *mut zvec_collection_schema_t,
891        max_doc_count: u64,
892    ) -> zvec_error_code_t;
893    pub fn zvec_collection_schema_validate(
894        schema: *const zvec_collection_schema_t,
895        error_msg: *mut *mut zvec_string_t,
896    ) -> zvec_error_code_t;
897    pub fn zvec_collection_schema_add_index(
898        schema: *mut zvec_collection_schema_t,
899        field_name: *const c_char,
900        index_params: *const zvec_index_params_t,
901    ) -> zvec_error_code_t;
902    pub fn zvec_collection_schema_drop_index(
903        schema: *mut zvec_collection_schema_t,
904        field_name: *const c_char,
905    ) -> zvec_error_code_t;
906    pub fn zvec_collection_schema_has_index(
907        schema: *const zvec_collection_schema_t,
908        field_name: *const c_char,
909    ) -> bool;
910
911    // -------------------------------------------------------------------------
912    // Collection Options
913    // Functions for configuring collection opening options.
914    // -------------------------------------------------------------------------
915    pub fn zvec_collection_options_create() -> *mut zvec_collection_options_t;
916    pub fn zvec_collection_options_destroy(options: *mut zvec_collection_options_t);
917    pub fn zvec_collection_options_set_enable_mmap(
918        options: *mut zvec_collection_options_t,
919        enable: bool,
920    ) -> zvec_error_code_t;
921    pub fn zvec_collection_options_get_enable_mmap(
922        options: *const zvec_collection_options_t,
923    ) -> bool;
924    pub fn zvec_collection_options_set_max_buffer_size(
925        options: *mut zvec_collection_options_t,
926        size: usize,
927    ) -> zvec_error_code_t;
928    pub fn zvec_collection_options_get_max_buffer_size(
929        options: *const zvec_collection_options_t,
930    ) -> usize;
931    pub fn zvec_collection_options_set_read_only(
932        options: *mut zvec_collection_options_t,
933        read_only: bool,
934    ) -> zvec_error_code_t;
935    pub fn zvec_collection_options_get_read_only(options: *const zvec_collection_options_t)
936        -> bool;
937
938    // -------------------------------------------------------------------------
939    // Collection Statistics
940    // Functions for retrieving collection statistics.
941    // -------------------------------------------------------------------------
942    pub fn zvec_collection_stats_get_doc_count(stats: *const zvec_collection_stats_t) -> u64;
943    pub fn zvec_collection_stats_get_index_count(stats: *const zvec_collection_stats_t) -> usize;
944    pub fn zvec_collection_stats_get_index_name(
945        stats: *const zvec_collection_stats_t,
946        index: usize,
947    ) -> *const c_char;
948    pub fn zvec_collection_stats_get_index_completeness(
949        stats: *const zvec_collection_stats_t,
950        index: usize,
951    ) -> f32;
952    pub fn zvec_collection_stats_destroy(stats: *mut zvec_collection_stats_t);
953
954    // -------------------------------------------------------------------------
955    // Collection Management
956    // Functions for creating, opening, closing, and destroying collections.
957    // -------------------------------------------------------------------------
958    pub fn zvec_collection_create_and_open(
959        path: *const c_char,
960        schema: *const zvec_collection_schema_t,
961        options: *const zvec_collection_options_t,
962        collection: *mut *mut zvec_collection_t,
963    ) -> zvec_error_code_t;
964    pub fn zvec_collection_open(
965        path: *const c_char,
966        options: *const zvec_collection_options_t,
967        collection: *mut *mut zvec_collection_t,
968    ) -> zvec_error_code_t;
969    pub fn zvec_collection_close(collection: *mut zvec_collection_t) -> zvec_error_code_t;
970    pub fn zvec_collection_destroy(collection: *mut zvec_collection_t) -> zvec_error_code_t;
971    pub fn zvec_collection_flush(collection: *mut zvec_collection_t) -> zvec_error_code_t;
972    pub fn zvec_collection_get_schema(
973        collection: *const zvec_collection_t,
974        schema: *mut *mut zvec_collection_schema_t,
975    ) -> zvec_error_code_t;
976    pub fn zvec_collection_get_options(
977        collection: *const zvec_collection_t,
978        options: *mut *mut zvec_collection_options_t,
979    ) -> zvec_error_code_t;
980    pub fn zvec_collection_get_stats(
981        collection: *const zvec_collection_t,
982        stats: *mut *mut zvec_collection_stats_t,
983    ) -> zvec_error_code_t;
984    pub fn zvec_free_field_schema(field_schema: *mut zvec_field_schema_t);
985
986    // -------------------------------------------------------------------------
987    // Index Management
988    // Functions for creating, dropping, and optimizing indexes.
989    // -------------------------------------------------------------------------
990    pub fn zvec_collection_create_index(
991        collection: *mut zvec_collection_t,
992        field_name: *const c_char,
993        index_params: *const zvec_index_params_t,
994    ) -> zvec_error_code_t;
995    pub fn zvec_collection_drop_index(
996        collection: *mut zvec_collection_t,
997        field_name: *const c_char,
998    ) -> zvec_error_code_t;
999    pub fn zvec_collection_optimize(collection: *mut zvec_collection_t) -> zvec_error_code_t;
1000
1001    // -------------------------------------------------------------------------
1002    // Column Management (DDL)
1003    // Functions for adding, dropping, and altering columns (schema changes).
1004    // -------------------------------------------------------------------------
1005    pub fn zvec_collection_add_column(
1006        collection: *mut zvec_collection_t,
1007        field_schema: *const zvec_field_schema_t,
1008        expression: *const c_char,
1009    ) -> zvec_error_code_t;
1010    pub fn zvec_collection_drop_column(
1011        collection: *mut zvec_collection_t,
1012        column_name: *const c_char,
1013    ) -> zvec_error_code_t;
1014    pub fn zvec_collection_alter_column(
1015        collection: *mut zvec_collection_t,
1016        column_name: *const c_char,
1017        new_name: *const c_char,
1018        new_schema: *const zvec_field_schema_t,
1019    ) -> zvec_error_code_t;
1020
1021    // -------------------------------------------------------------------------
1022    // DML
1023    // Functions for data manipulation: insert, update, upsert, and delete operations.
1024    // -------------------------------------------------------------------------
1025    pub fn zvec_collection_insert(
1026        collection: *mut zvec_collection_t,
1027        docs: *const *const zvec_doc_t,
1028        doc_count: usize,
1029        success_count: *mut usize,
1030        error_count: *mut usize,
1031    ) -> zvec_error_code_t;
1032    pub fn zvec_collection_insert_with_results(
1033        collection: *mut zvec_collection_t,
1034        docs: *const *const zvec_doc_t,
1035        doc_count: usize,
1036        results: *mut *mut zvec_write_result_t,
1037        result_count: *mut usize,
1038    ) -> zvec_error_code_t;
1039    pub fn zvec_collection_update(
1040        collection: *mut zvec_collection_t,
1041        docs: *const *const zvec_doc_t,
1042        doc_count: usize,
1043        success_count: *mut usize,
1044        error_count: *mut usize,
1045    ) -> zvec_error_code_t;
1046    pub fn zvec_collection_update_with_results(
1047        collection: *mut zvec_collection_t,
1048        docs: *const *const zvec_doc_t,
1049        doc_count: usize,
1050        results: *mut *mut zvec_write_result_t,
1051        result_count: *mut usize,
1052    ) -> zvec_error_code_t;
1053    pub fn zvec_collection_upsert(
1054        collection: *mut zvec_collection_t,
1055        docs: *const *const zvec_doc_t,
1056        doc_count: usize,
1057        success_count: *mut usize,
1058        error_count: *mut usize,
1059    ) -> zvec_error_code_t;
1060    pub fn zvec_collection_upsert_with_results(
1061        collection: *mut zvec_collection_t,
1062        docs: *const *const zvec_doc_t,
1063        doc_count: usize,
1064        results: *mut *mut zvec_write_result_t,
1065        result_count: *mut usize,
1066    ) -> zvec_error_code_t;
1067    pub fn zvec_collection_delete(
1068        collection: *mut zvec_collection_t,
1069        pks: *const *const c_char,
1070        pk_count: usize,
1071        success_count: *mut usize,
1072        error_count: *mut usize,
1073    ) -> zvec_error_code_t;
1074    pub fn zvec_collection_delete_with_results(
1075        collection: *mut zvec_collection_t,
1076        pks: *const *const c_char,
1077        pk_count: usize,
1078        results: *mut *mut zvec_write_result_t,
1079        result_count: *mut usize,
1080    ) -> zvec_error_code_t;
1081    pub fn zvec_write_results_free(results: *mut zvec_write_result_t, result_count: usize);
1082    pub fn zvec_collection_delete_by_filter(
1083        collection: *mut zvec_collection_t,
1084        filter: *const c_char,
1085    ) -> zvec_error_code_t;
1086
1087    // -------------------------------------------------------------------------
1088    // DQL
1089    // Functions for data querying: vector search and document fetch operations.
1090    // -------------------------------------------------------------------------
1091    pub fn zvec_collection_query(
1092        collection: *const zvec_collection_t,
1093        query: *const zvec_vector_query_t,
1094        results: *mut *mut *mut zvec_doc_t,
1095        result_count: *mut usize,
1096    ) -> zvec_error_code_t;
1097    pub fn zvec_collection_multi_query(
1098        collection: *const zvec_collection_t,
1099        query: *const zvec_multi_query_t,
1100        results: *mut *mut *mut zvec_doc_t,
1101        result_count: *mut usize,
1102    ) -> zvec_error_code_t;
1103    pub fn zvec_collection_fetch(
1104        collection: *mut zvec_collection_t,
1105        primary_keys: *const *const c_char,
1106        count: usize,
1107        output_fields: *const *const c_char,
1108        output_field_count: usize,
1109        include_vector: bool,
1110        documents: *mut *mut *mut zvec_doc_t,
1111        found_count: *mut usize,
1112    ) -> zvec_error_code_t;
1113
1114    // -------------------------------------------------------------------------
1115    // Document Iterator
1116    // Functions for full collection traversal over an isolated snapshot.
1117    // -------------------------------------------------------------------------
1118    pub fn zvec_iterator_options_create() -> *mut zvec_iterator_options_t;
1119    pub fn zvec_iterator_options_destroy(options: *mut zvec_iterator_options_t);
1120    pub fn zvec_iterator_options_set_output_fields(
1121        options: *mut zvec_iterator_options_t,
1122        output_fields: *const *const c_char,
1123        count: usize,
1124    ) -> zvec_error_code_t;
1125    pub fn zvec_iterator_options_set_include_vector(
1126        options: *mut zvec_iterator_options_t,
1127        include: bool,
1128    ) -> zvec_error_code_t;
1129    pub fn zvec_collection_create_iterator(
1130        collection: *mut zvec_collection_t,
1131        options: *const zvec_iterator_options_t,
1132        out_iter: *mut *mut zvec_doc_iterator_t,
1133    ) -> zvec_error_code_t;
1134    pub fn zvec_doc_iterator_next(
1135        iter: *mut zvec_doc_iterator_t,
1136        out_doc: *mut *mut zvec_doc_t,
1137    ) -> zvec_error_code_t;
1138    pub fn zvec_doc_iterator_close(iter: *mut zvec_doc_iterator_t);
1139
1140    // -------------------------------------------------------------------------
1141    // HNSW Query Parameters
1142    // Functions for creating and configuring HNSW index query parameters.
1143    // -------------------------------------------------------------------------
1144    pub fn zvec_query_params_hnsw_create(
1145        ef: c_int,
1146        radius: f32,
1147        is_linear: bool,
1148        is_using_refiner: bool,
1149    ) -> *mut zvec_hnsw_query_params_t;
1150    pub fn zvec_query_params_hnsw_destroy(params: *mut zvec_hnsw_query_params_t);
1151    pub fn zvec_query_params_hnsw_set_ef(
1152        params: *mut zvec_hnsw_query_params_t,
1153        ef: c_int,
1154    ) -> zvec_error_code_t;
1155    pub fn zvec_query_params_hnsw_get_ef(params: *const zvec_hnsw_query_params_t) -> c_int;
1156    pub fn zvec_query_params_hnsw_set_radius(
1157        params: *mut zvec_hnsw_query_params_t,
1158        radius: f32,
1159    ) -> zvec_error_code_t;
1160    pub fn zvec_query_params_hnsw_get_radius(params: *const zvec_hnsw_query_params_t) -> f32;
1161    pub fn zvec_query_params_hnsw_set_is_linear(
1162        params: *mut zvec_hnsw_query_params_t,
1163        is_linear: bool,
1164    ) -> zvec_error_code_t;
1165    pub fn zvec_query_params_hnsw_get_is_linear(params: *const zvec_hnsw_query_params_t) -> bool;
1166    pub fn zvec_query_params_hnsw_set_is_using_refiner(
1167        params: *mut zvec_hnsw_query_params_t,
1168        is_using_refiner: bool,
1169    ) -> zvec_error_code_t;
1170    pub fn zvec_query_params_hnsw_get_is_using_refiner(
1171        params: *const zvec_hnsw_query_params_t,
1172    ) -> bool;
1173
1174    // -------------------------------------------------------------------------
1175    // IVF Query Parameters
1176    // Functions for creating and configuring IVF index query parameters.
1177    // -------------------------------------------------------------------------
1178    pub fn zvec_query_params_ivf_create(
1179        nprobe: c_int,
1180        is_using_refiner: bool,
1181        scale_factor: f32,
1182    ) -> *mut zvec_ivf_query_params_t;
1183    pub fn zvec_query_params_ivf_destroy(params: *mut zvec_ivf_query_params_t);
1184    pub fn zvec_query_params_ivf_set_nprobe(
1185        params: *mut zvec_ivf_query_params_t,
1186        nprobe: c_int,
1187    ) -> zvec_error_code_t;
1188    pub fn zvec_query_params_ivf_get_nprobe(params: *const zvec_ivf_query_params_t) -> c_int;
1189    pub fn zvec_query_params_ivf_set_scale_factor(
1190        params: *mut zvec_ivf_query_params_t,
1191        scale_factor: f32,
1192    ) -> zvec_error_code_t;
1193    pub fn zvec_query_params_ivf_get_scale_factor(params: *const zvec_ivf_query_params_t) -> f32;
1194    pub fn zvec_query_params_ivf_set_radius(
1195        params: *mut zvec_ivf_query_params_t,
1196        radius: f32,
1197    ) -> zvec_error_code_t;
1198    pub fn zvec_query_params_ivf_get_radius(params: *const zvec_ivf_query_params_t) -> f32;
1199    pub fn zvec_query_params_ivf_set_is_linear(
1200        params: *mut zvec_ivf_query_params_t,
1201        is_linear: bool,
1202    ) -> zvec_error_code_t;
1203    pub fn zvec_query_params_ivf_get_is_linear(params: *const zvec_ivf_query_params_t) -> bool;
1204    pub fn zvec_query_params_ivf_set_is_using_refiner(
1205        params: *mut zvec_ivf_query_params_t,
1206        is_using_refiner: bool,
1207    ) -> zvec_error_code_t;
1208    pub fn zvec_query_params_ivf_get_is_using_refiner(
1209        params: *const zvec_ivf_query_params_t,
1210    ) -> bool;
1211
1212    // -------------------------------------------------------------------------
1213    // IVF RaBitQ Query Parameters
1214    // Functions for creating and configuring IVF RaBitQ index query parameters.
1215    // -------------------------------------------------------------------------
1216    pub fn zvec_query_params_ivf_rabitq_create(
1217        nprobe: c_int,
1218        radius: f32,
1219        is_linear: bool,
1220        is_using_refiner: bool,
1221    ) -> *mut zvec_ivf_rabitq_query_params_t;
1222    pub fn zvec_query_params_ivf_rabitq_destroy(params: *mut zvec_ivf_rabitq_query_params_t);
1223    pub fn zvec_query_params_ivf_rabitq_set_nprobe(
1224        params: *mut zvec_ivf_rabitq_query_params_t,
1225        nprobe: c_int,
1226    ) -> zvec_error_code_t;
1227    pub fn zvec_query_params_ivf_rabitq_get_nprobe(
1228        params: *const zvec_ivf_rabitq_query_params_t,
1229    ) -> c_int;
1230    pub fn zvec_query_params_ivf_rabitq_set_scale_factor(
1231        params: *mut zvec_ivf_rabitq_query_params_t,
1232        scale_factor: f32,
1233    ) -> zvec_error_code_t;
1234    pub fn zvec_query_params_ivf_rabitq_get_scale_factor(
1235        params: *const zvec_ivf_rabitq_query_params_t,
1236    ) -> f32;
1237    pub fn zvec_query_params_ivf_rabitq_set_radius(
1238        params: *mut zvec_ivf_rabitq_query_params_t,
1239        radius: f32,
1240    ) -> zvec_error_code_t;
1241    pub fn zvec_query_params_ivf_rabitq_get_radius(
1242        params: *const zvec_ivf_rabitq_query_params_t,
1243    ) -> f32;
1244    pub fn zvec_query_params_ivf_rabitq_set_is_linear(
1245        params: *mut zvec_ivf_rabitq_query_params_t,
1246        is_linear: bool,
1247    ) -> zvec_error_code_t;
1248    pub fn zvec_query_params_ivf_rabitq_get_is_linear(
1249        params: *const zvec_ivf_rabitq_query_params_t,
1250    ) -> bool;
1251    pub fn zvec_query_params_ivf_rabitq_set_is_using_refiner(
1252        params: *mut zvec_ivf_rabitq_query_params_t,
1253        is_using_refiner: bool,
1254    ) -> zvec_error_code_t;
1255    pub fn zvec_query_params_ivf_rabitq_get_is_using_refiner(
1256        params: *const zvec_ivf_rabitq_query_params_t,
1257    ) -> bool;
1258
1259    // -------------------------------------------------------------------------
1260    // Flat Query Parameters
1261    // Functions for creating and configuring flat index query parameters.
1262    // -------------------------------------------------------------------------
1263    pub fn zvec_query_params_flat_create(
1264        is_using_refiner: bool,
1265        scale_factor: f32,
1266    ) -> *mut zvec_flat_query_params_t;
1267    pub fn zvec_query_params_flat_destroy(params: *mut zvec_flat_query_params_t);
1268    pub fn zvec_query_params_flat_set_scale_factor(
1269        params: *mut zvec_flat_query_params_t,
1270        scale_factor: f32,
1271    ) -> zvec_error_code_t;
1272    pub fn zvec_query_params_flat_get_scale_factor(params: *const zvec_flat_query_params_t) -> f32;
1273    pub fn zvec_query_params_flat_set_radius(
1274        params: *mut zvec_flat_query_params_t,
1275        radius: f32,
1276    ) -> zvec_error_code_t;
1277    pub fn zvec_query_params_flat_get_radius(params: *const zvec_flat_query_params_t) -> f32;
1278    pub fn zvec_query_params_flat_set_is_linear(
1279        params: *mut zvec_flat_query_params_t,
1280        is_linear: bool,
1281    ) -> zvec_error_code_t;
1282    pub fn zvec_query_params_flat_get_is_linear(params: *const zvec_flat_query_params_t) -> bool;
1283    pub fn zvec_query_params_flat_set_is_using_refiner(
1284        params: *mut zvec_flat_query_params_t,
1285        is_using_refiner: bool,
1286    ) -> zvec_error_code_t;
1287    pub fn zvec_query_params_flat_get_is_using_refiner(
1288        params: *const zvec_flat_query_params_t,
1289    ) -> bool;
1290
1291    // -------------------------------------------------------------------------
1292    // Vamana Query Parameters
1293    // Functions for creating and configuring Vamana query parameters.
1294    // -------------------------------------------------------------------------
1295    pub fn zvec_query_params_vamana_create(
1296        ef_search: c_int,
1297        radius: f32,
1298        is_linear: bool,
1299        is_using_refiner: bool,
1300    ) -> *mut zvec_vamana_query_params_t;
1301    pub fn zvec_query_params_vamana_destroy(params: *mut zvec_vamana_query_params_t);
1302    pub fn zvec_query_params_vamana_set_ef_search(
1303        params: *mut zvec_vamana_query_params_t,
1304        ef_search: c_int,
1305    ) -> zvec_error_code_t;
1306    pub fn zvec_query_params_vamana_get_ef_search(
1307        params: *const zvec_vamana_query_params_t,
1308    ) -> c_int;
1309    pub fn zvec_query_params_vamana_set_radius(
1310        params: *mut zvec_vamana_query_params_t,
1311        radius: f32,
1312    ) -> zvec_error_code_t;
1313    pub fn zvec_query_params_vamana_get_radius(params: *const zvec_vamana_query_params_t) -> f32;
1314    pub fn zvec_query_params_vamana_set_is_linear(
1315        params: *mut zvec_vamana_query_params_t,
1316        is_linear: bool,
1317    ) -> zvec_error_code_t;
1318    pub fn zvec_query_params_vamana_get_is_linear(
1319        params: *const zvec_vamana_query_params_t,
1320    ) -> bool;
1321    pub fn zvec_query_params_vamana_set_is_using_refiner(
1322        params: *mut zvec_vamana_query_params_t,
1323        is_using_refiner: bool,
1324    ) -> zvec_error_code_t;
1325    pub fn zvec_query_params_vamana_get_is_using_refiner(
1326        params: *const zvec_vamana_query_params_t,
1327    ) -> bool;
1328
1329    // -------------------------------------------------------------------------
1330    // DiskANN Query Parameters
1331    // Functions for creating and configuring DiskANN query parameters.
1332    // -------------------------------------------------------------------------
1333    pub fn zvec_query_params_diskann_create(list_size: c_int) -> *mut zvec_diskann_query_params_t;
1334    pub fn zvec_query_params_diskann_destroy(params: *mut zvec_diskann_query_params_t);
1335    pub fn zvec_query_params_diskann_set_list_size(
1336        params: *mut zvec_diskann_query_params_t,
1337        list_size: c_int,
1338    ) -> zvec_error_code_t;
1339    pub fn zvec_query_params_diskann_get_list_size(
1340        params: *const zvec_diskann_query_params_t,
1341    ) -> c_int;
1342    pub fn zvec_query_params_diskann_set_radius(
1343        params: *mut zvec_diskann_query_params_t,
1344        radius: f32,
1345    ) -> zvec_error_code_t;
1346    pub fn zvec_query_params_diskann_get_radius(params: *const zvec_diskann_query_params_t) -> f32;
1347    pub fn zvec_query_params_diskann_set_is_linear(
1348        params: *mut zvec_diskann_query_params_t,
1349        is_linear: bool,
1350    ) -> zvec_error_code_t;
1351    pub fn zvec_query_params_diskann_get_is_linear(
1352        params: *const zvec_diskann_query_params_t,
1353    ) -> bool;
1354    pub fn zvec_query_params_diskann_set_is_using_refiner(
1355        params: *mut zvec_diskann_query_params_t,
1356        is_using_refiner: bool,
1357    ) -> zvec_error_code_t;
1358    pub fn zvec_query_params_diskann_get_is_using_refiner(
1359        params: *const zvec_diskann_query_params_t,
1360    ) -> bool;
1361
1362    // -------------------------------------------------------------------------
1363    // FTS Query Parameters
1364    // Functions for creating and configuring FTS query parameters.
1365    // -------------------------------------------------------------------------
1366    pub fn zvec_query_params_fts_create(
1367        default_operator: *const c_char,
1368    ) -> *mut zvec_fts_query_params_t;
1369    pub fn zvec_query_params_fts_destroy(params: *mut zvec_fts_query_params_t);
1370    pub fn zvec_query_params_fts_set_default_operator(
1371        params: *mut zvec_fts_query_params_t,
1372        default_operator: *const c_char,
1373    ) -> zvec_error_code_t;
1374    pub fn zvec_query_params_fts_get_default_operator(
1375        params: *const zvec_fts_query_params_t,
1376    ) -> *const c_char;
1377
1378    // -------------------------------------------------------------------------
1379    // FTS Query Payload
1380    // Functions for creating and configuring FTS query payloads.
1381    // -------------------------------------------------------------------------
1382    pub fn zvec_fts_create() -> *mut zvec_fts_t;
1383    pub fn zvec_fts_destroy(fts: *mut zvec_fts_t);
1384    pub fn zvec_fts_set_query_string(
1385        fts: *mut zvec_fts_t,
1386        query_string: *const c_char,
1387    ) -> zvec_error_code_t;
1388    pub fn zvec_fts_set_match_string(
1389        fts: *mut zvec_fts_t,
1390        match_string: *const c_char,
1391    ) -> zvec_error_code_t;
1392    pub fn zvec_fts_get_query_string(fts: *const zvec_fts_t) -> *const c_char;
1393    pub fn zvec_fts_get_match_string(fts: *const zvec_fts_t) -> *const c_char;
1394
1395    // -------------------------------------------------------------------------
1396    // Vector Query
1397    // Functions for creating and configuring vector similarity queries.
1398    // -------------------------------------------------------------------------
1399    pub fn zvec_vector_query_create() -> *mut zvec_vector_query_t;
1400    pub fn zvec_vector_query_destroy(query: *mut zvec_vector_query_t);
1401    pub fn zvec_vector_query_set_topk(
1402        query: *mut zvec_vector_query_t,
1403        topk: c_int,
1404    ) -> zvec_error_code_t;
1405    pub fn zvec_vector_query_get_topk(query: *const zvec_vector_query_t) -> c_int;
1406    pub fn zvec_vector_query_set_field_name(
1407        query: *mut zvec_vector_query_t,
1408        field_name: *const c_char,
1409    ) -> zvec_error_code_t;
1410    pub fn zvec_vector_query_get_field_name(query: *const zvec_vector_query_t) -> *const c_char;
1411    pub fn zvec_vector_query_set_query_vector(
1412        query: *mut zvec_vector_query_t,
1413        data: *const c_void,
1414        size: usize,
1415    ) -> zvec_error_code_t;
1416    pub fn zvec_vector_query_set_filter(
1417        query: *mut zvec_vector_query_t,
1418        filter: *const c_char,
1419    ) -> zvec_error_code_t;
1420    pub fn zvec_vector_query_get_filter(query: *const zvec_vector_query_t) -> *const c_char;
1421    pub fn zvec_vector_query_set_include_vector(
1422        query: *mut zvec_vector_query_t,
1423        include: bool,
1424    ) -> zvec_error_code_t;
1425    pub fn zvec_vector_query_get_include_vector(query: *const zvec_vector_query_t) -> bool;
1426    pub fn zvec_vector_query_set_include_doc_id(
1427        query: *mut zvec_vector_query_t,
1428        include: bool,
1429    ) -> zvec_error_code_t;
1430    pub fn zvec_vector_query_get_include_doc_id(query: *const zvec_vector_query_t) -> bool;
1431    pub fn zvec_vector_query_set_output_fields(
1432        query: *mut zvec_vector_query_t,
1433        fields: *const *const c_char,
1434        count: usize,
1435    ) -> zvec_error_code_t;
1436    pub fn zvec_vector_query_get_output_fields(
1437        query: *const zvec_vector_query_t,
1438        fields: *mut *mut *const c_char,
1439        count: *mut usize,
1440    ) -> zvec_error_code_t;
1441    pub fn zvec_vector_query_set_query_params(
1442        query: *mut zvec_vector_query_t,
1443        params: *mut c_void,
1444    ) -> zvec_error_code_t;
1445    pub fn zvec_vector_query_set_hnsw_params(
1446        query: *mut zvec_vector_query_t,
1447        hnsw_params: *mut zvec_hnsw_query_params_t,
1448    ) -> zvec_error_code_t;
1449    pub fn zvec_vector_query_set_ivf_params(
1450        query: *mut zvec_vector_query_t,
1451        ivf_params: *mut zvec_ivf_query_params_t,
1452    ) -> zvec_error_code_t;
1453    pub fn zvec_vector_query_set_ivf_rabitq_params(
1454        query: *mut zvec_vector_query_t,
1455        ivf_rabitq_params: *mut zvec_ivf_rabitq_query_params_t,
1456    ) -> zvec_error_code_t;
1457    pub fn zvec_vector_query_set_flat_params(
1458        query: *mut zvec_vector_query_t,
1459        flat_params: *mut zvec_flat_query_params_t,
1460    ) -> zvec_error_code_t;
1461    pub fn zvec_vector_query_set_vamana_params(
1462        query: *mut zvec_vector_query_t,
1463        vamana_params: *mut zvec_vamana_query_params_t,
1464    ) -> zvec_error_code_t;
1465    pub fn zvec_vector_query_set_diskann_params(
1466        query: *mut zvec_vector_query_t,
1467        diskann_params: *mut zvec_diskann_query_params_t,
1468    ) -> zvec_error_code_t;
1469    pub fn zvec_vector_query_set_fts_params(
1470        query: *mut zvec_vector_query_t,
1471        fts_params: *mut zvec_fts_query_params_t,
1472    ) -> zvec_error_code_t;
1473    pub fn zvec_vector_query_set_fts(
1474        query: *mut zvec_vector_query_t,
1475        fts: *const zvec_fts_t,
1476    ) -> zvec_error_code_t;
1477    pub fn zvec_vector_query_get_fts(query: *const zvec_vector_query_t) -> *const zvec_fts_t;
1478
1479    // -------------------------------------------------------------------------
1480    // Group By Vector Query
1481    // Functions for creating and configuring grouped vector queries.
1482    // -------------------------------------------------------------------------
1483    pub fn zvec_group_by_vector_query_create() -> *mut zvec_group_by_vector_query_t;
1484    pub fn zvec_group_by_vector_query_destroy(query: *mut zvec_group_by_vector_query_t);
1485    pub fn zvec_group_by_vector_query_set_field_name(
1486        query: *mut zvec_group_by_vector_query_t,
1487        field_name: *const c_char,
1488    ) -> zvec_error_code_t;
1489    pub fn zvec_group_by_vector_query_get_field_name(
1490        query: *const zvec_group_by_vector_query_t,
1491    ) -> *const c_char;
1492    pub fn zvec_group_by_vector_query_set_group_by_field_name(
1493        query: *mut zvec_group_by_vector_query_t,
1494        field_name: *const c_char,
1495    ) -> zvec_error_code_t;
1496    pub fn zvec_group_by_vector_query_get_group_by_field_name(
1497        query: *const zvec_group_by_vector_query_t,
1498    ) -> *const c_char;
1499    pub fn zvec_group_by_vector_query_set_group_count(
1500        query: *mut zvec_group_by_vector_query_t,
1501        count: u32,
1502    ) -> zvec_error_code_t;
1503    pub fn zvec_group_by_vector_query_get_group_count(
1504        query: *const zvec_group_by_vector_query_t,
1505    ) -> u32;
1506    pub fn zvec_group_by_vector_query_set_topk_per_group(
1507        query: *mut zvec_group_by_vector_query_t,
1508        topk: u32,
1509    ) -> zvec_error_code_t;
1510    pub fn zvec_group_by_vector_query_get_topk_per_group(
1511        query: *const zvec_group_by_vector_query_t,
1512    ) -> u32;
1513    pub fn zvec_group_by_vector_query_set_query_vector(
1514        query: *mut zvec_group_by_vector_query_t,
1515        data: *const c_void,
1516        size: usize,
1517    ) -> zvec_error_code_t;
1518    pub fn zvec_group_by_vector_query_set_filter(
1519        query: *mut zvec_group_by_vector_query_t,
1520        filter: *const c_char,
1521    ) -> zvec_error_code_t;
1522    pub fn zvec_group_by_vector_query_get_filter(
1523        query: *const zvec_group_by_vector_query_t,
1524    ) -> *const c_char;
1525    pub fn zvec_group_by_vector_query_set_include_vector(
1526        query: *mut zvec_group_by_vector_query_t,
1527        include: bool,
1528    ) -> zvec_error_code_t;
1529    pub fn zvec_group_by_vector_query_get_include_vector(
1530        query: *const zvec_group_by_vector_query_t,
1531    ) -> bool;
1532    pub fn zvec_group_by_vector_query_set_output_fields(
1533        query: *mut zvec_group_by_vector_query_t,
1534        fields: *const *const c_char,
1535        count: usize,
1536    ) -> zvec_error_code_t;
1537    pub fn zvec_group_by_vector_query_get_output_fields(
1538        query: *mut zvec_group_by_vector_query_t,
1539        fields: *mut *mut *const c_char,
1540        count: *mut usize,
1541    ) -> zvec_error_code_t;
1542    pub fn zvec_group_by_vector_query_set_query_params(
1543        query: *mut zvec_group_by_vector_query_t,
1544        params: *mut c_void,
1545    ) -> zvec_error_code_t;
1546    pub fn zvec_group_by_vector_query_set_hnsw_params(
1547        query: *mut zvec_group_by_vector_query_t,
1548        hnsw_params: *mut zvec_hnsw_query_params_t,
1549    ) -> zvec_error_code_t;
1550    pub fn zvec_group_by_vector_query_set_ivf_params(
1551        query: *mut zvec_group_by_vector_query_t,
1552        ivf_params: *mut zvec_ivf_query_params_t,
1553    ) -> zvec_error_code_t;
1554    pub fn zvec_group_by_vector_query_set_ivf_rabitq_params(
1555        query: *mut zvec_group_by_vector_query_t,
1556        ivf_rabitq_params: *mut zvec_ivf_rabitq_query_params_t,
1557    ) -> zvec_error_code_t;
1558    pub fn zvec_group_by_vector_query_set_flat_params(
1559        query: *mut zvec_group_by_vector_query_t,
1560        flat_params: *mut zvec_flat_query_params_t,
1561    ) -> zvec_error_code_t;
1562    pub fn zvec_group_by_vector_query_set_vamana_params(
1563        query: *mut zvec_group_by_vector_query_t,
1564        vamana_params: *mut zvec_vamana_query_params_t,
1565    ) -> zvec_error_code_t;
1566    pub fn zvec_group_by_vector_query_set_diskann_params(
1567        query: *mut zvec_group_by_vector_query_t,
1568        diskann_params: *mut zvec_diskann_query_params_t,
1569    ) -> zvec_error_code_t;
1570
1571    // -------------------------------------------------------------------------
1572    // Multi Query / Sub Query
1573    // Functions for creating and configuring multi-queries (hybrid search with
1574    // re-ranking) and their per-field sub-queries.
1575    // -------------------------------------------------------------------------
1576    pub fn zvec_multi_query_create() -> *mut zvec_multi_query_t;
1577    pub fn zvec_multi_query_destroy(query: *mut zvec_multi_query_t);
1578    pub fn zvec_multi_query_add_sub_query(
1579        query: *mut zvec_multi_query_t,
1580        sub_query: *const zvec_sub_query_t,
1581    ) -> zvec_error_code_t;
1582    pub fn zvec_multi_query_get_sub_query_count(query: *const zvec_multi_query_t) -> usize;
1583    pub fn zvec_multi_query_set_topk(
1584        query: *mut zvec_multi_query_t,
1585        topk: c_int,
1586    ) -> zvec_error_code_t;
1587    pub fn zvec_multi_query_get_topk(query: *const zvec_multi_query_t) -> c_int;
1588    pub fn zvec_multi_query_set_filter(
1589        query: *mut zvec_multi_query_t,
1590        filter: *const c_char,
1591    ) -> zvec_error_code_t;
1592    pub fn zvec_multi_query_get_filter(query: *const zvec_multi_query_t) -> *const c_char;
1593    pub fn zvec_multi_query_set_include_vector(
1594        query: *mut zvec_multi_query_t,
1595        include: bool,
1596    ) -> zvec_error_code_t;
1597    pub fn zvec_multi_query_get_include_vector(query: *const zvec_multi_query_t) -> bool;
1598    pub fn zvec_multi_query_set_output_fields(
1599        query: *mut zvec_multi_query_t,
1600        fields: *const *const c_char,
1601        count: usize,
1602    ) -> zvec_error_code_t;
1603    pub fn zvec_multi_query_get_output_fields(
1604        query: *mut zvec_multi_query_t,
1605        fields: *mut *mut *const c_char,
1606        count: *mut usize,
1607    ) -> zvec_error_code_t;
1608    pub fn zvec_multi_query_set_rerank_rrf(
1609        query: *mut zvec_multi_query_t,
1610        rank_constant: c_int,
1611    ) -> zvec_error_code_t;
1612    pub fn zvec_multi_query_set_rerank_weighted(
1613        query: *mut zvec_multi_query_t,
1614        weights: *const f64,
1615        weight_count: usize,
1616    ) -> zvec_error_code_t;
1617
1618    pub fn zvec_sub_query_create() -> *mut zvec_sub_query_t;
1619    pub fn zvec_sub_query_destroy(query: *mut zvec_sub_query_t);
1620    pub fn zvec_sub_query_set_num_candidates(
1621        query: *mut zvec_sub_query_t,
1622        num_candidates: c_int,
1623    ) -> zvec_error_code_t;
1624    pub fn zvec_sub_query_get_num_candidates(query: *const zvec_sub_query_t) -> c_int;
1625    pub fn zvec_sub_query_set_field_name(
1626        query: *mut zvec_sub_query_t,
1627        field_name: *const c_char,
1628    ) -> zvec_error_code_t;
1629    pub fn zvec_sub_query_get_field_name(query: *const zvec_sub_query_t) -> *const c_char;
1630    pub fn zvec_sub_query_set_query_vector(
1631        query: *mut zvec_sub_query_t,
1632        data: *const c_void,
1633        size: usize,
1634    ) -> zvec_error_code_t;
1635    pub fn zvec_sub_query_set_sparse_vector(
1636        query: *mut zvec_sub_query_t,
1637        indices: *const u32,
1638        values: *const f32,
1639        count: usize,
1640    ) -> zvec_error_code_t;
1641    pub fn zvec_sub_query_set_sparse_indices(
1642        query: *mut zvec_sub_query_t,
1643        indices: *const u32,
1644        count: usize,
1645    ) -> zvec_error_code_t;
1646    pub fn zvec_sub_query_set_sparse_values(
1647        query: *mut zvec_sub_query_t,
1648        values: *const f32,
1649        count: usize,
1650    ) -> zvec_error_code_t;
1651    pub fn zvec_sub_query_set_hnsw_params(
1652        query: *mut zvec_sub_query_t,
1653        hnsw_params: *mut zvec_hnsw_query_params_t,
1654    ) -> zvec_error_code_t;
1655    pub fn zvec_sub_query_set_ivf_params(
1656        query: *mut zvec_sub_query_t,
1657        ivf_params: *mut zvec_ivf_query_params_t,
1658    ) -> zvec_error_code_t;
1659    pub fn zvec_sub_query_set_ivf_rabitq_params(
1660        query: *mut zvec_sub_query_t,
1661        ivf_rabitq_params: *mut zvec_ivf_rabitq_query_params_t,
1662    ) -> zvec_error_code_t;
1663    pub fn zvec_sub_query_set_flat_params(
1664        query: *mut zvec_sub_query_t,
1665        flat_params: *mut zvec_flat_query_params_t,
1666    ) -> zvec_error_code_t;
1667    pub fn zvec_sub_query_set_vamana_params(
1668        query: *mut zvec_sub_query_t,
1669        vamana_params: *mut zvec_vamana_query_params_t,
1670    ) -> zvec_error_code_t;
1671    pub fn zvec_sub_query_set_diskann_params(
1672        query: *mut zvec_sub_query_t,
1673        diskann_params: *mut zvec_diskann_query_params_t,
1674    ) -> zvec_error_code_t;
1675    pub fn zvec_sub_query_set_fts_params(
1676        query: *mut zvec_sub_query_t,
1677        fts_params: *mut zvec_fts_query_params_t,
1678    ) -> zvec_error_code_t;
1679    pub fn zvec_sub_query_set_fts(
1680        query: *mut zvec_sub_query_t,
1681        fts: *const zvec_fts_t,
1682    ) -> zvec_error_code_t;
1683
1684    // -------------------------------------------------------------------------
1685    // Document Operations
1686    // Functions for creating, manipulating, and serializing documents.
1687    // -------------------------------------------------------------------------
1688    pub fn zvec_doc_create() -> *mut zvec_doc_t;
1689    pub fn zvec_doc_destroy(doc: *mut zvec_doc_t);
1690    pub fn zvec_doc_clear(doc: *mut zvec_doc_t);
1691    pub fn zvec_doc_add_field_by_value(
1692        doc: *mut zvec_doc_t,
1693        field_name: *const c_char,
1694        data_type: zvec_data_type_t,
1695        value: *const c_void,
1696        value_size: usize,
1697    ) -> zvec_error_code_t;
1698    pub fn zvec_doc_remove_field(
1699        doc: *mut zvec_doc_t,
1700        field_name: *const c_char,
1701    ) -> zvec_error_code_t;
1702    pub fn zvec_docs_free(documents: *mut *mut zvec_doc_t, count: usize);
1703    pub fn zvec_doc_set_pk(doc: *mut zvec_doc_t, pk: *const c_char);
1704    pub fn zvec_doc_set_doc_id(doc: *mut zvec_doc_t, doc_id: u64);
1705    pub fn zvec_doc_set_score(doc: *mut zvec_doc_t, score: f32);
1706    pub fn zvec_doc_set_operator(doc: *mut zvec_doc_t, op: zvec_doc_operator_t);
1707    pub fn zvec_doc_set_field_null(
1708        doc: *mut zvec_doc_t,
1709        field_name: *const c_char,
1710    ) -> zvec_error_code_t;
1711    pub fn zvec_doc_get_doc_id(doc: *const zvec_doc_t) -> u64;
1712    pub fn zvec_doc_get_score(doc: *const zvec_doc_t) -> f32;
1713    pub fn zvec_doc_get_operator(doc: *const zvec_doc_t) -> zvec_doc_operator_t;
1714    pub fn zvec_doc_get_field_count(doc: *const zvec_doc_t) -> usize;
1715    pub fn zvec_doc_get_pk_pointer(doc: *const zvec_doc_t) -> *const c_char;
1716    pub fn zvec_doc_get_pk_copy(doc: *const zvec_doc_t) -> *const c_char;
1717    pub fn zvec_doc_get_field_value_basic(
1718        doc: *const zvec_doc_t,
1719        field_name: *const c_char,
1720        field_type: zvec_data_type_t,
1721        value_buffer: *mut c_void,
1722        buffer_size: usize,
1723    ) -> zvec_error_code_t;
1724    pub fn zvec_doc_get_field_value_copy(
1725        doc: *const zvec_doc_t,
1726        field_name: *const c_char,
1727        field_type: zvec_data_type_t,
1728        value: *mut *mut c_void,
1729        value_size: *mut usize,
1730    ) -> zvec_error_code_t;
1731    pub fn zvec_doc_get_field_value_pointer(
1732        doc: *const zvec_doc_t,
1733        field_name: *const c_char,
1734        field_type: zvec_data_type_t,
1735        value: *mut *const c_void,
1736        value_size: *mut usize,
1737    ) -> zvec_error_code_t;
1738    pub fn zvec_doc_is_empty(doc: *const zvec_doc_t) -> bool;
1739    pub fn zvec_doc_has_field(doc: *const zvec_doc_t, field_name: *const c_char) -> bool;
1740    pub fn zvec_doc_has_field_value(doc: *const zvec_doc_t, field_name: *const c_char) -> bool;
1741    pub fn zvec_doc_is_field_null(doc: *const zvec_doc_t, field_name: *const c_char) -> bool;
1742    pub fn zvec_doc_get_field_names(
1743        doc: *const zvec_doc_t,
1744        field_names: *mut *mut *mut c_char,
1745        count: *mut usize,
1746    ) -> zvec_error_code_t;
1747    pub fn zvec_free_str_array(array: *mut *mut c_char, count: usize);
1748    pub fn zvec_doc_serialize(
1749        doc: *const zvec_doc_t,
1750        data: *mut *mut u8,
1751        size: *mut usize,
1752    ) -> zvec_error_code_t;
1753    pub fn zvec_doc_deserialize(
1754        data: *const u8,
1755        size: usize,
1756        doc: *mut *mut zvec_doc_t,
1757    ) -> zvec_error_code_t;
1758    pub fn zvec_doc_merge(doc: *mut zvec_doc_t, other: *const zvec_doc_t);
1759    pub fn zvec_doc_memory_usage(doc: *const zvec_doc_t) -> usize;
1760    pub fn zvec_doc_to_detail_string(
1761        doc: *const zvec_doc_t,
1762        detail_str: *mut *mut c_char,
1763    ) -> zvec_error_code_t;
1764
1765    // -------------------------------------------------------------------------
1766    // Utility Functions
1767    // Helper functions for converting enums to string representations.
1768    // -------------------------------------------------------------------------
1769    pub fn zvec_data_type_to_string(data_type: zvec_data_type_t) -> *const c_char;
1770    pub fn zvec_index_type_to_string(index_type: zvec_index_type_t) -> *const c_char;
1771    pub fn zvec_metric_type_to_string(metric_type: zvec_metric_type_t) -> *const c_char;
1772}
1773
1774/// Returns the jieba dict directory discovered at build time, if any.
1775///
1776/// The build script looks for the cppjieba dictionary files next to the
1777/// resolved zvec library (prebuilt `data/jieba_dict/`, an SDK install prefix,
1778/// or a zvec source checkout) and records the path here. The high-level
1779/// `zvec` crate uses this to auto-register the default jieba dict dir.
1780pub fn build_time_jieba_dict_dir() -> Option<&'static str> {
1781    option_env!("ZVEC_RUST_JIEBA_DICT_DIR")
1782}