GV_Database *gv_db_open(const char *filepath, size_t dimension, GV_IndexType index_type);Creates or opens a vector database.
Parameters:
filepath: Path to database file (NULL for in-memory only)dimension: Vector dimensionality (must be consistent)index_type: Index algorithm (GV_INDEX_TYPE_KDTREE,GV_INDEX_TYPE_HNSW,GV_INDEX_TYPE_IVFPQ,GV_INDEX_TYPE_SPARSE,GV_INDEX_TYPE_FLAT,GV_INDEX_TYPE_IVFFLAT,GV_INDEX_TYPE_PQ,GV_INDEX_TYPE_LSH)
Returns: Database handle or NULL on error
Example:
GV_Database *db = gv_db_open("vectors.db", 128, GV_INDEX_TYPE_HNSW);
if (db == NULL) {
fprintf(stderr, "Failed to open database\n");
return 1;
}GV_Database *gv_db_open_with_hnsw_config(const char *filepath, size_t dimension,
GV_IndexType index_type, const GV_HNSWConfig *hnsw_config);Opens database with custom HNSW parameters.
Parameters:
hnsw_config: HNSW configuration structure (NULL for defaults)
HNSW Configuration:
typedef struct {
size_t M; // Connections per node (default: 16)
size_t efConstruction; // Candidate list size during construction (default: 200)
size_t efSearch; // Candidate list size during search (default: 50)
size_t maxLevel; // Max hierarchy levels (auto-calculated if 0)
int use_binary_quant; // Enable binary quantization (default: 0)
size_t quant_rerank; // Candidates to rerank with exact distance (0 = disable)
int use_acorn; // Enable ACORN-style filtered search (default: 0)
size_t acorn_hops; // ACORN exploration depth, 1-2 (default: 1)
GV_DistanceType distance_type; // Distance metric (default: EUCLIDEAN)
} GV_HNSWConfig;GV_Database *gv_db_open_with_ivfpq_config(const char *filepath, size_t dimension,
GV_IndexType index_type, const GV_IVFPQConfig *ivfpq_config);Opens database with custom IVFPQ parameters.
IVFPQ Configuration:
typedef struct {
size_t nlist; // Coarse centroids / inverted lists (default: 256)
size_t m; // Subquantizers, must divide dimension (default: 8)
uint8_t nbits; // Bits per subquantizer code (default: 8)
size_t nprobe; // Lists to probe during search (default: 1)
size_t train_iters; // K-means iterations for codebooks
size_t default_rerank; // Rerank pool size (0 = disable)
int use_cosine; // Normalize query for cosine (default: 0)
int use_scalar_quant; // Enable scalar quantization (default: 0)
GV_ScalarQuantConfig scalar_quant_config; // Scalar quant config if enabled
float oversampling_factor; // Candidate oversampling (default: 1.0)
} GV_IVFPQConfig;void gv_db_close(GV_Database *db);Closes database and releases all resources. Safe to call with NULL.
void gv_free(void *ptr);Frees memory allocated by GigaVector (e.g. strings returned by gv_schema_to_json, gv_json_export, etc.). Safe to call with NULL.
Example:
char *json = gv_schema_to_json(schema);
// ... use json ...
gv_free(json);int gv_db_add_vector(GV_Database *db, const float *data, size_t dimension);Adds a dense vector to the database.
Returns: 0 on success, -1 on error
int gv_db_add_vector_with_metadata(GV_Database *db, const float *data, size_t dimension,
const char *metadata_key, const char *metadata_value);Adds vector with single metadata key-value pair.
int gv_db_add_vector_with_rich_metadata(GV_Database *db, const float *data, size_t dimension,
const char *const *metadata_keys,
const char *const *metadata_values,
size_t metadata_count);Adds vector with multiple metadata entries.
Example:
const char *keys[] = {"category", "author", "date"};
const char *values[] = {"article", "John Doe", "2024-01-15"};
int result = gv_db_add_vector_with_rich_metadata(db, vector, 128, keys, values, 3);int gv_db_add_sparse_vector(GV_Database *db, const uint32_t *indices, const float *values,
size_t nnz, size_t dimension,
const char *metadata_key, const char *metadata_value);Adds a sparse vector (only for GV_INDEX_TYPE_SPARSE).
Parameters:
indices: Array of dimension indicesvalues: Array of non-zero valuesnnz: Number of non-zero elements
int gv_db_search(const GV_Database *db, const float *query_data, size_t k,
GV_SearchResult *results, GV_DistanceType distance_type);Performs k-nearest neighbor search.
Parameters:
query_data: Query vectork: Number of results to returnresults: Output array (must be pre-allocated for k elements)distance_type:GV_DISTANCE_EUCLIDEANorGV_DISTANCE_COSINE
Returns: Number of results found (0 to k)
Example:
GV_SearchResult results[10];
int count = gv_db_search(db, query_vector, 10, results, GV_DISTANCE_COSINE);
for (int i = 0; i < count; i++) {
printf("Distance: %f, ID: %zu\n", results[i].distance, results[i].id);
}int gv_db_search_filtered(const GV_Database *db, const float *query_data, size_t k,
GV_SearchResult *results, GV_DistanceType distance_type,
const char *filter_key, const char *filter_value);Search with simple key-value metadata filtering.
Example:
int count = gv_db_search_filtered(db, query, 10, results, GV_DISTANCE_COSINE,
"category", "article");int gv_db_search_with_filter_expr(const GV_Database *db, const float *query_data, size_t k,
GV_SearchResult *results, GV_DistanceType distance_type,
const char *filter_expr);Search with a filter expression string (e.g., category == "article" AND price >= "50").
int gv_db_range_search(const GV_Database *db, const float *query_data, float radius,
GV_SearchResult *results, size_t max_results, GV_DistanceType distance_type);Finds all vectors within specified radius.
Parameters:
radius: Maximum distance thresholdmax_results: Maximum number of results to return
GigaVector supports metadata filtering via simple key-value matching or filter expressions:
// Simple key-value filter
int count = gv_db_search_filtered(db, query, 10, results, GV_DISTANCE_COSINE,
"category", "article");
// Complex filter expression
int count = gv_db_search_with_filter_expr(db, query, 10, results, GV_DISTANCE_COSINE,
"category == \"article\" AND date >= \"2024-01-01\"");int gv_memory_extract_candidates_from_conversation(const char *conversation,
const char *conversation_id,
int is_agent_memory,
GV_MemoryCandidate *candidates,
size_t max_candidates,
size_t *actual_count);Extracts memory candidates from conversation text using heuristic patterns.
int gv_memory_extract_candidates_from_conversation_llm(GV_LLM *llm,
const char *conversation,
const char *conversation_id,
int is_agent_memory,
const char *custom_prompt,
GV_MemoryCandidate *candidates,
size_t max_candidates,
size_t *actual_count);Extracts memories using LLM (more accurate, requires API key).
char *gv_memory_add(GV_MemoryLayer *layer, const char *content,
const float *embedding, GV_MemoryMetadata *metadata);Adds a memory to the layer. Returns memory ID string (caller must free) or NULL on failure.
int gv_memory_search(GV_MemoryLayer *layer, const float *query_embedding,
size_t k, GV_MemoryResult *results,
GV_DistanceType distance_type,
const GV_MemorySearchOptions *options);Searches memories with semantic similarity and temporal weighting.
Search Options:
typedef struct {
float temporal_weight; // 0.0=semantic only, 1.0=recency only
float importance_weight; // Weight for importance (default: 0.4)
int include_linked; // Include linked memories
float link_boost; // Score boost for linked memories
time_t min_timestamp; // Minimum creation time
time_t max_timestamp; // Maximum creation time
} GV_MemorySearchOptions;int gv_memory_consolidate(GV_Database *db, double similarity_threshold,
GV_ConsolidationStrategy strategy);Consolidates similar or redundant memories.
Strategies:
GV_CONSOLIDATION_MERGE: Merge similar memoriesGV_CONSOLIDATION_UPDATE: Update existing with new infoGV_CONSOLIDATION_LINK: Create relationship linkGV_CONSOLIDATION_ARCHIVE: Archive redundant memory
typedef struct {
GV_LLMProvider provider; // OPENAI, ANTHROPIC, GOOGLE, CUSTOM
char *api_key; // API key for authentication
char *model; // Model name (e.g., "gpt-4o-mini")
char *base_url; // Base URL (NULL for default)
double temperature; // 0.0-2.0
int max_tokens; // Maximum tokens in response
int timeout_seconds; // Request timeout
char *custom_prompt; // Custom extraction prompt
} GV_LLMConfig;GV_LLM *gv_llm_create(const GV_LLMConfig *config);Example:
GV_LLMConfig config = {
.provider = GV_LLM_PROVIDER_OPENAI,
.api_key = getenv("OPENAI_API_KEY"),
.model = "gpt-4o-mini",
.temperature = 0.7,
.max_tokens = 1000,
.timeout_seconds = 30
};
GV_LLM *llm = gv_llm_create(&config);int gv_llm_generate_response(GV_LLM *llm, const GV_LLMMessage *messages,
size_t message_count, const char *response_format,
GV_LLMResponse *response);Example:
GV_LLMMessage messages[] = {
{.role = "user", .content = "Extract key facts from: User loves Python"}
};
GV_LLMResponse response;
int result = gv_llm_generate_response(llm, messages, 1, "json_object", &response);
if (result == GV_LLM_SUCCESS) {
printf("Response: %s\n", response.content);
gv_llm_response_free(&response);
}const char *error_msg = gv_llm_get_last_error(llm);
const char *error_desc = gv_llm_error_string(error_code);typedef struct {
GV_EmbeddingProvider provider; // OPENAI, GOOGLE, HUGGINGFACE, CUSTOM
char *api_key; // API key
char *model; // Model name
char *base_url; // Base URL (NULL for default)
size_t dimension; // Output dimension
} GV_EmbeddingConfig;GV_EmbeddingService *gv_embedding_create(const GV_EmbeddingConfig *config);int gv_embedding_embed(GV_EmbeddingService *service, const char *text, float *output);int gv_embedding_embed_batch(GV_EmbeddingService *service, const char **texts,
size_t text_count, float **outputs);GV_ContextGraph *gv_context_graph_build(GV_Database *db, const char **entity_names,
size_t entity_count);Builds entity-relationship graph from database metadata.
int gv_context_graph_get_related(const GV_ContextGraph *graph, const char *entity_name,
char **related_entities, size_t max_related);void gv_graph_config_init(GV_GraphDBConfig *config);Initialize a graph database configuration with default values (node_bucket_count=4096, edge_bucket_count=8192, enforce_referential_integrity=1).
GV_GraphDB *gv_graph_create(const GV_GraphDBConfig *config);Create a new graph database. Pass NULL for default configuration. Returns NULL on error.
void gv_graph_destroy(GV_GraphDB *g);uint64_t gv_graph_add_node(GV_GraphDB *g, const char *label);Add a node with the given label. Returns node_id (>0) on success, 0 on error.
int gv_graph_remove_node(GV_GraphDB *g, uint64_t node_id);Remove a node and cascade-delete all incident edges. Returns 0 on success.
const GV_GraphNode *gv_graph_get_node(const GV_GraphDB *g, uint64_t node_id);Look up a node by ID. Returns pointer valid until next mutation, or NULL.
int gv_graph_set_node_prop(GV_GraphDB *g, uint64_t node_id, const char *key, const char *value);
const char *gv_graph_get_node_prop(const GV_GraphDB *g, uint64_t node_id, const char *key);int gv_graph_find_nodes_by_label(const GV_GraphDB *g, const char *label,
uint64_t *out_ids, size_t max_count);uint64_t gv_graph_add_edge(GV_GraphDB *g, uint64_t source, uint64_t target,
const char *label, float weight);Add a directed weighted edge. Returns edge_id (>0) on success, 0 on error.
int gv_graph_remove_edge(GV_GraphDB *g, uint64_t edge_id);int gv_graph_get_edges_out(const GV_GraphDB *g, uint64_t node_id, uint64_t *out_ids, size_t max_count);
int gv_graph_get_edges_in(const GV_GraphDB *g, uint64_t node_id, uint64_t *out_ids, size_t max_count);
int gv_graph_get_neighbors(const GV_GraphDB *g, uint64_t node_id, uint64_t *out_ids, size_t max_count);int gv_graph_bfs(const GV_GraphDB *g, uint64_t start, size_t max_depth,
uint64_t *out_ids, size_t max_count);
int gv_graph_dfs(const GV_GraphDB *g, uint64_t start, size_t max_depth,
uint64_t *out_ids, size_t max_count);int gv_graph_shortest_path(const GV_GraphDB *g, uint64_t from, uint64_t to, GV_GraphPath *path);Dijkstra's algorithm. Caller must free result with gv_graph_free_path().
int gv_graph_all_paths(const GV_GraphDB *g, uint64_t from, uint64_t to,
size_t max_depth, GV_GraphPath *paths, size_t max_paths);float gv_graph_pagerank(const GV_GraphDB *g, uint64_t node_id, size_t iterations, float damping);Iterative power method PageRank. Typical values: iterations=20, damping=0.85.
int gv_graph_connected_components(const GV_GraphDB *g, uint64_t *component_ids, size_t max_count);Returns number of distinct components. Array indexed by enumeration order.
float gv_graph_clustering_coefficient(const GV_GraphDB *g, uint64_t node_id);Local clustering coefficient in [0.0, 1.0].
int gv_graph_save(const GV_GraphDB *g, const char *path);
GV_GraphDB *gv_graph_load(const char *path);Binary format with magic "GVGR".
void gv_kg_config_init(GV_KGConfig *config);Initialize with defaults: entity_bucket_count=4096, relation_bucket_count=8192, embedding_dimension=128, similarity_threshold=0.7, link_prediction_threshold=0.8, max_entities=1000000.
GV_KnowledgeGraph *gv_kg_create(const GV_KGConfig *config);
void gv_kg_destroy(GV_KnowledgeGraph *kg);uint64_t gv_kg_add_entity(GV_KnowledgeGraph *kg, const char *name, const char *type,
const float *embedding, size_t dimension);Add an entity with optional embedding. Returns entity_id (>0) on success.
int gv_kg_remove_entity(GV_KnowledgeGraph *kg, uint64_t entity_id);Cascade-deletes all relations involving this entity.
int gv_kg_find_entities_by_type(const GV_KnowledgeGraph *kg, const char *type,
uint64_t *out_ids, size_t max_count);
int gv_kg_find_entities_by_name(const GV_KnowledgeGraph *kg, const char *name,
uint64_t *out_ids, size_t max_count);uint64_t gv_kg_add_relation(GV_KnowledgeGraph *kg, uint64_t subject,
const char *predicate, uint64_t object, float weight);Creates a (subject, predicate, object) triple. Both entities must exist.
int gv_kg_query_triples(const GV_KnowledgeGraph *kg, const uint64_t *subject,
const char *predicate, const uint64_t *object,
GV_KGTriple *out, size_t max_count);Pass NULL for any parameter to treat it as a wildcard. Free results with gv_kg_free_triples().
int gv_kg_search_similar(const GV_KnowledgeGraph *kg, const float *query_embedding,
size_t dimension, size_t k, GV_KGSearchResult *results);Cosine similarity search over entity embeddings. Free results with gv_kg_free_search_results().
int gv_kg_hybrid_search(const GV_KnowledgeGraph *kg, const float *query_embedding,
size_t dimension, const char *entity_type,
const char *predicate_filter, size_t k, GV_KGSearchResult *results);Embedding similarity filtered by entity type and/or predicate.
int gv_kg_resolve_entity(GV_KnowledgeGraph *kg, const char *name, const char *type,
const float *embedding, size_t dimension);Find existing match or create new entity. Returns entity_id.
int gv_kg_merge_entities(GV_KnowledgeGraph *kg, uint64_t keep_id, uint64_t merge_id);int gv_kg_predict_links(const GV_KnowledgeGraph *kg, uint64_t entity_id,
size_t k, GV_KGLinkPrediction *results);Predict missing links using embedding similarity and structural patterns.
int gv_kg_get_neighbors(const GV_KnowledgeGraph *kg, uint64_t entity_id,
uint64_t *out_ids, size_t max_count);
int gv_kg_traverse(const GV_KnowledgeGraph *kg, uint64_t start,
size_t max_depth, uint64_t *out_ids, size_t max_count);
int gv_kg_shortest_path(const GV_KnowledgeGraph *kg, uint64_t from,
uint64_t to, uint64_t *path_ids, size_t max_len);
int gv_kg_extract_subgraph(const GV_KnowledgeGraph *kg, uint64_t center,
size_t radius, GV_KGSubgraph *subgraph);int gv_kg_get_stats(const GV_KnowledgeGraph *kg, GV_KGStats *stats);
float gv_kg_entity_centrality(const GV_KnowledgeGraph *kg, uint64_t entity_id);
int gv_kg_get_entity_types(const GV_KnowledgeGraph *kg, char **out_types, size_t max_count);
int gv_kg_get_predicates(const GV_KnowledgeGraph *kg, char **out_predicates, size_t max_count);int gv_kg_save(const GV_KnowledgeGraph *kg, const char *path);
GV_KnowledgeGraph *gv_kg_load(const char *path);Binary format with magic "GVKG".
GV_IndexType gv_index_suggest(size_t dimension, size_t expected_count);Suggests optimal index type based on dimension and expected size.
Heuristics:
- Small datasets (≤20k) and low dimensions (≤64): KDTREE
- Very large datasets (≥500k) and high dimensions (≥128): IVFPQ
- Otherwise: HNSW
void gv_db_set_cosine_normalized(GV_Database *db, int enabled);Enables L2 normalization for cosine distance optimization.
void gv_db_get_stats(const GV_Database *db, GV_DBStats *out);Statistics Structure:
typedef struct {
size_t vector_count;
size_t dimension;
size_t memory_bytes;
uint64_t total_inserts;
uint64_t total_queries;
double avg_query_latency_ms;
} GV_DBStats;int gv_db_get_detailed_stats(const GV_Database *db, GV_DetailedStats *out);
void gv_db_free_detailed_stats(GV_DetailedStats *stats);Returns database metrics including latency histograms, throughput, memory breakdown, recall metrics, and health indicators.
Detailed Statistics Structure:
typedef struct {
GV_DBStats basic_stats; // Basic aggregated statistics
GV_LatencyHistogram insert_latency; // Insert operation latency histogram
GV_LatencyHistogram search_latency; // Search operation latency histogram
double queries_per_second; // Current QPS
double inserts_per_second; // Current IPS
GV_MemoryBreakdown memory; // Memory breakdown (SoA, index, metadata, WAL)
GV_RecallMetrics recall; // Recall metrics for approximate search
int health_status; // 0=healthy, -1=degraded, -2=unhealthy
size_t deleted_vector_count; // Number of deleted vectors
double deleted_ratio; // Ratio of deleted vectors (0.0--1.0)
} GV_DetailedStats;Example:
GV_DetailedStats stats;
if (gv_db_get_detailed_stats(db, &stats) == 0) {
printf("QPS: %.1f, Memory: %zu bytes\n",
stats.queries_per_second, stats.memory.total_bytes);
printf("Health: %d, Recall: %.2f\n",
stats.health_status, stats.recall.avg_recall);
gv_db_free_detailed_stats(&stats);
}All functions return:
0or positive value: Success-1: Generic error- Specific error codes: See function documentation
Many functions set error messages accessible via:
const char *error = gv_llm_get_last_error(llm);typedef struct {
int port; // Default: 6969
int thread_pool_size; // Default: 4
int max_connections; // Default: 100
int request_timeout_ms; // Default: 30000
size_t max_request_body_bytes; // Default: 10MB
int enable_cors; // Default: 0
int enable_logging; // Default: 1
const char *api_key; // Optional API key auth
double max_requests_per_second; // Rate limit (0 = unlimited)
size_t rate_limit_burst; // Burst size (default: 10)
} GV_ServerConfig;GV_ServerConfig config;
gv_server_config_init(&config);
config.port = 9090;
config.enable_cors = 1;
GV_Server *server = gv_server_create(db, &config);
gv_server_start(server);
// ... server runs ...
gv_server_stop(server);
gv_server_destroy(server);| Endpoint | Method | Description |
|---|---|---|
/health |
GET | Health check |
/stats |
GET | Database statistics |
/vectors |
POST | Add vector |
/vectors/:id |
GET | Get vector by ID |
/vectors/:id |
PUT | Update vector |
/vectors/:id |
DELETE | Delete vector |
/search |
POST | Vector search |
/search/range |
POST | Range search |
/search/batch |
POST | Batch search |
/compact |
POST | Trigger compaction |
/save |
POST | Save database to disk |
/namespaces |
GET/POST | Manage namespaces |
from gigavector import serve_with_dashboard
server = serve_with_dashboard(db, port=6969)
# Dashboard at http://localhost:6969/dashboard
server.wait()Combines text-based BM25 ranking with vector similarity.
GV_Tokenizer *tokenizer = gv_tokenizer_create(GV_TOKENIZER_WHITESPACE);
GV_TokenList *tokens = gv_tokenizer_tokenize(tokenizer, "hello world");
gv_token_list_free(tokens);
gv_tokenizer_destroy(tokenizer);GV_BM25Config config = {
.k1 = 1.2,
.b = 0.75
};
GV_BM25Index *index = gv_bm25_create(&config);
gv_bm25_add_document(index, doc_id, "document text content");
gv_bm25_search(index, "query terms", results, max_results);GV_HybridSearchConfig config = {
.vector_weight = 0.7,
.bm25_weight = 0.3,
.fusion_method = GV_FUSION_RRF // Reciprocal Rank Fusion
};
int count = gv_hybrid_search(db, bm25_index, query_vector, "query text",
k, &config, results);Isolate data into separate logical collections.
// Create namespace
gv_namespace_create(db, "project_a");
// Add vector to namespace
gv_namespace_add_vector(db, "project_a", vector, dim, metadata);
// Search within namespace
gv_namespace_search(db, "project_a", query, k, distance_type, results);
// List namespaces
char **names;
size_t count;
gv_namespace_list(db, &names, &count);
// Delete namespace
gv_namespace_delete(db, "project_a");Automatic expiration of vectors.
// Set TTL on vector (seconds)
gv_ttl_set(db, vector_id, 3600); // Expires in 1 hour
// Get remaining TTL
int64_t remaining = gv_ttl_get(db, vector_id);
// Remove TTL
gv_ttl_remove(db, vector_id);
// Run expiration (call periodically or use background thread)
size_t expired = gv_ttl_expire(db);# Backup database
gvbackup mydb.db backup.gvb
# Restore database
gvrestore backup.gvb restored.db
# Inspect database
gvinspect mydb.db// Create backup
GV_BackupConfig config = {
.compress = 1,
.include_wal = 1
};
gv_backup_create(db, "backup.gvb", &config);
// Restore backup
GV_Database *restored = gv_backup_restore("backup.gvb", "restored.db");GV_AuthConfig auth_config = {
.type = GV_AUTH_API_KEY,
.api_key = "your-secret-key"
};
gv_server_set_auth(server, &auth_config);GigaVector provides a fine-grained authorization system with permission flags and resource-level access control.
typedef enum {
GV_PERM_NONE = 0, // No permissions
GV_PERM_READ = 1, // Read vectors / search
GV_PERM_WRITE = 2, // Add / update vectors
GV_PERM_DELETE = 4, // Delete vectors
GV_PERM_ADMIN = 8, // Manage users / namespaces
GV_PERM_ALL = 15 // All permissions
} GV_Permission;
typedef enum {
GV_RESOURCE_GLOBAL = 0, // Database level
GV_RESOURCE_NAMESPACE = 1, // Specific namespace
GV_RESOURCE_VECTOR = 2 // Specific vector
} GV_ResourceType;GV_AuthzManager *gv_authz_create(void);
void gv_authz_destroy(GV_AuthzManager *authz);
int gv_authz_init_builtin_roles(GV_AuthzManager *authz); // creates "admin", "reader", "writer"int gv_authz_define_role(GV_AuthzManager *authz, const char *name,
uint32_t permissions, const char **namespaces,
size_t namespace_count);
int gv_authz_remove_role(GV_AuthzManager *authz, const char *name);
int gv_authz_get_role(GV_AuthzManager *authz, const char *name, GV_Role *role);
int gv_authz_list_roles(GV_AuthzManager *authz, GV_Role **roles, size_t *count);int gv_authz_assign_role(GV_AuthzManager *authz, const char *subject, const char *role_name);
int gv_authz_revoke_role(GV_AuthzManager *authz, const char *subject, const char *role_name);int gv_authz_check(GV_AuthzManager *authz, const GV_Identity *identity,
GV_Permission permission, GV_ResourceType resource_type,
const char *resource_name, GV_AuthzResult *result);
// Convenience helpers (return 1 if allowed, 0 if denied)
int gv_authz_can_read(GV_AuthzManager *authz, const GV_Identity *identity, const char *ns);
int gv_authz_can_write(GV_AuthzManager *authz, const GV_Identity *identity, const char *ns);
int gv_authz_can_delete(GV_AuthzManager *authz, const GV_Identity *identity, const char *ns);
int gv_authz_is_admin(GV_AuthzManager *authz, const GV_Identity *identity);Example:
GV_AuthzManager *authz = gv_authz_create();
gv_authz_init_builtin_roles(authz);
// Define a custom role scoped to one namespace
const char *ns[] = {"production"};
gv_authz_define_role(authz, "prod_reader", GV_PERM_READ, ns, 1);
// Assign role to a user
gv_authz_assign_role(authz, "user_123", "prod_reader");
// Check access
GV_AuthzResult result;
gv_authz_check(authz, identity, GV_PERM_READ, GV_RESOURCE_NAMESPACE, "production", &result);
if (result.allowed) { /* proceed */ }
gv_authz_destroy(authz);Requires CUDA. Enabled automatically when available.
// Check GPU availability
if (gv_gpu_available()) {
GV_GPUInfo info;
gv_gpu_get_info(&info);
printf("GPU: %s, Memory: %zu MB\n", info.name, info.memory_mb);
}
// Enable GPU for database
gv_db_enable_gpu(db, 0); // Device 0
// GPU-accelerated search
gv_db_search_gpu(db, query, k, distance_type, results);
// Batch search on GPU
gv_db_search_batch_gpu(db, queries, num_queries, k, distance_type, all_results);For large result sets or continuous queries.
// Create stream
GV_Stream *stream = gv_stream_search(db, query, GV_DISTANCE_COSINE);
// Read results incrementally
GV_SearchResult result;
while (gv_stream_next(stream, &result) == 0) {
process_result(&result);
}
gv_stream_close(stream);int graph_wal_attach(GV_GraphDB *g, const char *snapshot_path);Enables crash-safe write-ahead logging for the property graph. Every mutation
is appended to <snapshot_path>.wal and fsynced before the mutating call
returns. graph_load(snapshot_path) replays the log over the last snapshot;
graph_save to the same path truncates it (checkpoint).
int graph_wal_checkpoint(GV_GraphDB *g);Truncates and fsyncs the attached WAL. Call after saving to a different path.
int kg_wal_attach(GV_KnowledgeGraph *kg, const char *snapshot_path);
int kg_wal_checkpoint(GV_KnowledgeGraph *kg);Identical semantics for the knowledge graph (entities, relations, properties, and embeddings are all logged).
uint64_t graph_version(const GV_GraphDB *g);Monotonic mutation counter; bumps on every committed change. Use it to detect concurrent modification between reads.
GV_GraphReadTxn *txn = graph_read_txn_begin(g); /* pins a consistent snapshot */
const GV_GraphNode *n = graph_read_txn_get_node(txn, id);
int m = graph_read_txn_find_nodes_by_label(txn, "Person", ids, max);
uint64_t v = graph_read_txn_version(txn);
graph_read_txn_end(txn);Repeatable reads across multiple calls while other threads mutate; writers cannot commit until the transaction ends. Keep transactions short.
GV_GraphWriteTxn *t = graph_write_txn_begin(g);
uint64_t a = graph_write_txn_add_node(t, "Person");
uint64_t b = graph_write_txn_add_node(t, "Person");
graph_write_txn_add_edge(t, a, b, "KNOWS", 1.0f); /* may reference staged nodes */
graph_write_txn_set_node_prop(t, a, "name", "Zed");
graph_write_txn_commit(t); /* atomic: one WAL fsync + apply */
/* or: */ graph_write_txn_abort(t);All-or-nothing application; nothing is visible to other threads until commit.
int kg_expand_context(const GV_KnowledgeGraph *kg, const uint64_t *seeds,
size_t n_seeds, size_t radius,
GV_KGTriple *out, size_t max_count);GraphRAG-style multi-hop retrieval: collects every triple whose subject or
object lies within radius hops of any seed entity (deduplicated). The
query-time complement of chunk provenance joins.
int kg_remove_entity_prop(GV_KnowledgeGraph *kg, uint64_t id, const char *key);
int kg_remove_relation_prop(GV_KnowledgeGraph *kg, uint64_t id, const char *key);Delete properties outright (Cypher REMOVE n.prop uses these). Deleting a
relation's chunk_id also updates the chunk index. Both are WAL-logged.
int memory_delete_by_source(GV_MemoryLayer *layer, const char *source);Deletes every memory whose provenance (source metadata) matches; the third
leg of cross-layer rollback alongside db_delete_by_id and
kg_remove_relations_by_chunk.
int graph_betweenness_centrality_approx(const GV_GraphDB *g, int weighted,
int directed, size_t num_pivots,
GV_GraphNodeScores *out);Landmark-sampled Brandes: exact runs from num_pivots uniformly spaced pivot
sources scaled by N/K, parallel over pivots. Use for large graphs where exact
O(V·E) Brandes is too slow.
GV_CSR *m = gv_csr_build_cached(g, ctx, GV_CSR_OUT, 0);Memoized per (graph version, orientation, weighted); rebuilds only after
mutations. Cache-owned: do not free. Back-to-back algorithms over one snapshot
skip redundant construction. gv_csr_cache_clear() forces a drop.
GV_ShardConfig config = {
.num_shards = 4,
.strategy = GV_SHARD_HASH // or GV_SHARD_RANGE
};
GV_ShardedDB *sdb = gv_shard_create(config);
// Add shard
gv_shard_add(sdb, "shard_0", "host1:8080");
// Operations route automatically
gv_shard_add_vector(sdb, vector, dim, metadata);
gv_shard_search(sdb, query, k, results);GV_ReplicationConfig config = {
.mode = GV_REPL_ASYNC,
.replicas = 2
};
gv_replication_enable(db, &config);
gv_replication_add_replica(db, "replica1:8080");See C API Guide for thread safety guidelines.
typedef struct {
size_t max_memory_bytes; // Maximum memory usage (0 = unlimited)
size_t max_vectors; // Maximum number of vectors (0 = unlimited)
size_t max_concurrent_operations; // Maximum concurrent operations (0 = unlimited)
} GV_ResourceLimits;int gv_db_set_resource_limits(GV_Database *db, const GV_ResourceLimits *limits);Applies resource constraints to the database. Inserts and operations will be rejected when limits are exceeded.
Returns: 0 on success, -1 on error
void gv_db_get_resource_limits(const GV_Database *db, GV_ResourceLimits *limits);size_t gv_db_get_memory_usage(const GV_Database *db);Returns estimated memory usage in bytes.
size_t gv_db_get_concurrent_operations(const GV_Database *db);Returns the number of currently active operations.
Example:
GV_ResourceLimits limits = {
.max_memory_bytes = 1024 * 1024 * 1024, // 1GB
.max_vectors = 1000000,
.max_concurrent_operations = 100
};
gv_db_set_resource_limits(db, &limits);
size_t mem = gv_db_get_memory_usage(db);
printf("Memory usage: %zu bytes\n", mem);int gv_db_health_check(const GV_Database *db);Checks database integrity, index consistency, and resource usage.
Returns:
0: healthy-1: degraded (e.g., high deleted ratio, approaching resource limits)-2: unhealthy (e.g., corrupt index, exceeded limits)
GV_Database *gv_db_open_mmap(const char *filepath, size_t dimension, GV_IndexType index_type);Opens a database by memory-mapping an existing snapshot file. The database is read-only: WAL is disabled and modifications are not persisted. Useful for fast startup and sharing data across processes.
Returns: Database handle or NULL on error
Example:
GV_Database *db = gv_db_open_mmap("snapshot.db", 128, GV_INDEX_TYPE_HNSW);
// Search works normally
int count = gv_db_search(db, query, 10, GV_DISTANCE_COSINE, results);
// Writes are not persisted
gv_db_close(db);int gv_db_compact(GV_Database *db);Triggers immediate compaction: reclaims space from deleted vectors and compacts the WAL.
Returns: 0 on success, -1 on error
int gv_db_start_background_compaction(GV_Database *db);
void gv_db_stop_background_compaction(GV_Database *db);Starts or stops a background thread that runs compaction periodically.
void gv_db_set_compaction_interval(GV_Database *db, size_t interval_sec);Sets the interval (in seconds) between background compaction runs. Default: 300.
void gv_db_set_wal_compaction_threshold(GV_Database *db, size_t threshold_bytes);Sets the WAL size threshold that triggers compaction. Default: 10 MB.
void gv_db_set_deleted_ratio_threshold(GV_Database *db, double ratio);Sets the ratio of deleted vectors (0.0 to 1.0) that triggers compaction. Default: 0.1.
void gv_db_set_exact_search_threshold(GV_Database *db, size_t threshold);Sets the maximum collection size below which search falls back to brute-force exact scan (bypassing the index). Useful for small collections where index overhead is wasteful.
void gv_db_set_force_exact_search(GV_Database *db, int enabled);When enabled (non-zero), all searches use brute-force exact scan regardless of collection size.
int gv_db_search_ivfpq_opts(const GV_Database *db, const float *query_data, size_t k,
GV_SearchResult *results, GV_DistanceType distance_type,
size_t nprobe_override, size_t rerank_top);Performs IVF-PQ search with per-query overrides for nprobe and rerank pool size.
Parameters:
nprobe_override: Number of inverted lists to probe (0 uses default from config)rerank_top: Number of candidates to rerank with full-precision vectors (0 to disable)
Returns: Number of results found
int gv_db_save(const GV_Database *db, const char *filepath);Saves database snapshot. WAL is automatically replayed on next open.
Snapshot-isolation transactions. Declared in storage/transaction.h. A transaction reads a
consistent snapshot (commit_version at db_begin), buffers its own writes (read-your-writes),
and commits atomically with first-committer-wins write-write conflict detection.
GV_DBTxn *db_begin(GV_Database *db);Starts a transaction pinned to the current committed snapshot. Returns a handle, or NULL on error.
int db_txn_add_vector(GV_DBTxn *txn, const float *data, size_t dimension);
int db_txn_delete(GV_DBTxn *txn, size_t vector_index);
int db_txn_search(GV_DBTxn *txn, const float *query, size_t k,
GV_SearchResult *results, GV_DistanceType distance_type);Buffered write/delete and a snapshot read that also sees the transaction's own uncommitted writes.
int db_commit(GV_DBTxn *txn); /* GV_TXN_OK (0) or GV_TXN_CONFLICT (1); frees txn */
int db_rollback(GV_DBTxn *txn); /* discards buffered writes; frees txn */db_commit assigns a new commit_version, checks for write-write conflicts against concurrently
committed changes (returns GV_TXN_CONFLICT on conflict), applies the writes, and WAL-logs deletes.
int db_search_at_version(const GV_Database *db, const float *query_data, size_t k,
GV_SearchResult *results, GV_DistanceType distance_type, uint64_t snapshot);Non-transactional snapshot read: returns only vectors visible at snapshot (create_version ≤
snapshot and not yet deleted at snapshot). db_search calls this with the latest committed version.
size_t db_txn_gc(GV_Database *db, uint64_t safe_below);Reclaims tombstoned vectors no snapshot at or after safe_below can still see; returns the number
reclaimed.
Example:
GV_DBTxn *txn = db_begin(db);
db_txn_add_vector(txn, vec, dim, "label", "cat");
if (db_commit(txn) == GV_TXN_CONFLICT) { /* retry */ }Opt-in key->value store with WiscKey-style key/value separation: a uint64 key index in memory over
an append-only value log with CRC and garbage collection. Declared in storage/database.h
(the underlying primitives are in storage/vlog.h and storage/value_store.h).
int db_value_store_enable(GV_Database *db, const char *path);
int db_value_store_put(GV_Database *db, uint64_t key, const void *value, size_t len);
int db_value_store_get(GV_Database *db, uint64_t key, void **value_out, size_t *len_out); /* caller frees *value_out */
int db_value_store_delete(GV_Database *db, uint64_t key);
int db_value_store_gc(GV_Database *db); /* compact the log, dropping dead records */The index is rebuilt from the durable log on reopen. Useful for offloading large auxiliary payloads (documents, blobs) away from the dense vector store.
Access-aware hot/warm/cold tiering. Declared in storage/tiered_storage.h. Layered on the age
thresholds from gv_db_set_tiering_config, a vector is promoted by recency (accessed within a
window) or frequency (access count threshold); db_search records accesses automatically.
int gv_db_set_tiering_config(GV_Database *db, uint64_t hot_max_age_sec,
uint64_t warm_max_age_sec, size_t hot_max_vectors);
int gv_db_set_access_tiering_policy(GV_Database *db, uint64_t access_recency_window_sec,
uint32_t hot_min_access_count);
int gv_db_record_vector_access(GV_Database *db, size_t vec_id); /* no-op if tiering disabled */
int gv_db_get_vector_tier(const GV_Database *db, size_t vec_id, GV_StorageTier *out);
int gv_db_tiering_stats(const GV_Database *db, size_t *hot, size_t *warm, size_t *cold);GV_StorageTier is GV_TIER_HOT / GV_TIER_WARM / GV_TIER_COLD.
A standalone, transport-agnostic Raft implementation (leader election + log replication) in
admin/raft.h. Driven by raft_tick (clock) and raft_step (incoming message); emits outbound
messages via a caller-supplied send callback, so it can run over TCP or an in-memory simulation.
It is a self-contained core and is not yet wired into admin/replication.c.
GV_Raft *raft_create(int id, const int *peers, size_t n_peers,
const GV_RaftConfig *cfg, const GV_RaftCallbacks *cb);
void raft_tick(GV_Raft *r, uint32_t ms); /* advance clock; may elect / heartbeat */
void raft_step(GV_Raft *r, int from, const GV_RaftMsg *msg); /* handle an RPC */
int raft_submit(GV_Raft *r, const void *data, size_t len, uint64_t *index_out); /* leader only */
GV_RaftRole raft_role(const GV_Raft *r);
uint64_t raft_commit_index(const GV_Raft *r);
void raft_destroy(GV_Raft *r);Callbacks (GV_RaftCallbacks): send(ctx, to, msg), apply(ctx, index, data, len) on commit, and
optional persist(ctx, term, voted_for). Implements the Raft safety rules (up-to-date vote check,
AppendEntries log-consistency check with conflict truncation, commit restricted to current-term
entries replicated on a quorum).
See Performance Tuning for optimization guidelines.
For more examples, see Basic Usage Examples and Advanced Features.