@hajewski/latticedb 0.5.0 → 0.6.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +49 -1
- package/dist/database.d.ts +18 -1
- package/dist/database.d.ts.map +1 -1
- package/dist/database.js +22 -2
- package/dist/database.js.map +1 -1
- package/dist/ffi/bindings.d.ts +14 -0
- package/dist/ffi/bindings.d.ts.map +1 -1
- package/dist/ffi/bindings.js +101 -0
- package/dist/ffi/bindings.js.map +1 -1
- package/dist/ffi/index.d.ts +31 -0
- package/dist/ffi/index.d.ts.map +1 -1
- package/dist/ffi/index.js +135 -0
- package/dist/ffi/index.js.map +1 -1
- package/dist/ffi/library.d.ts +12 -1
- package/dist/ffi/library.d.ts.map +1 -1
- package/dist/ffi/library.js +53 -7
- package/dist/ffi/library.js.map +1 -1
- package/dist/index.d.ts +1 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1 -1
- package/dist/index.js.map +1 -1
- package/dist/transaction.d.ts +36 -3
- package/dist/transaction.d.ts.map +1 -1
- package/dist/transaction.js +128 -1
- package/dist/transaction.js.map +1 -1
- package/dist/types.d.ts +8 -0
- package/dist/types.d.ts.map +1 -1
- package/dist/types.js.map +1 -1
- package/lib/darwin-arm64/liblattice.dylib +0 -0
- package/lib/darwin-x64/liblattice.dylib +0 -0
- package/lib/linux-arm64/liblattice.so +0 -0
- package/lib/linux-x64/liblattice.so +0 -0
- package/package.json +8 -4
- package/include/lattice.h +0 -682
package/include/lattice.h
DELETED
|
@@ -1,682 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* Lattice: Embedded Knowledge Graph Database
|
|
3
|
-
*
|
|
4
|
-
* A single-file knowledge graph database for AI/RAG applications.
|
|
5
|
-
* Combines property graph storage, HNSW vector search, and BM25 full-text search.
|
|
6
|
-
*
|
|
7
|
-
* This is the stable C API. All language bindings wrap this interface.
|
|
8
|
-
*/
|
|
9
|
-
|
|
10
|
-
#ifndef LATTICE_H
|
|
11
|
-
#define LATTICE_H
|
|
12
|
-
|
|
13
|
-
#include <stddef.h>
|
|
14
|
-
#include <stdint.h>
|
|
15
|
-
#include <stdbool.h>
|
|
16
|
-
|
|
17
|
-
#ifdef __cplusplus
|
|
18
|
-
extern "C" {
|
|
19
|
-
#endif
|
|
20
|
-
|
|
21
|
-
/* Version information */
|
|
22
|
-
#define LATTICE_VERSION "0.5.0"
|
|
23
|
-
#define LATTICE_VERSION_MAJOR 0
|
|
24
|
-
#define LATTICE_VERSION_MINOR 5
|
|
25
|
-
#define LATTICE_VERSION_PATCH 0
|
|
26
|
-
|
|
27
|
-
/* Opaque handle types */
|
|
28
|
-
typedef struct lattice_database lattice_database;
|
|
29
|
-
typedef struct lattice_txn lattice_txn;
|
|
30
|
-
typedef struct lattice_query lattice_query;
|
|
31
|
-
typedef struct lattice_result lattice_result;
|
|
32
|
-
typedef struct lattice_vector_result lattice_vector_result;
|
|
33
|
-
typedef struct lattice_fts_result lattice_fts_result;
|
|
34
|
-
typedef struct lattice_edge_result lattice_edge_result;
|
|
35
|
-
|
|
36
|
-
/* ID types */
|
|
37
|
-
typedef uint64_t lattice_node_id;
|
|
38
|
-
typedef uint64_t lattice_edge_id;
|
|
39
|
-
|
|
40
|
-
/* Error codes */
|
|
41
|
-
typedef enum {
|
|
42
|
-
LATTICE_OK = 0,
|
|
43
|
-
LATTICE_ERROR = -1,
|
|
44
|
-
LATTICE_ERROR_IO = -2,
|
|
45
|
-
LATTICE_ERROR_CORRUPTION = -3,
|
|
46
|
-
LATTICE_ERROR_NOT_FOUND = -4,
|
|
47
|
-
LATTICE_ERROR_ALREADY_EXISTS = -5,
|
|
48
|
-
LATTICE_ERROR_INVALID_ARG = -6,
|
|
49
|
-
LATTICE_ERROR_TXN_ABORTED = -7,
|
|
50
|
-
LATTICE_ERROR_LOCK_TIMEOUT = -8,
|
|
51
|
-
LATTICE_ERROR_READ_ONLY = -9,
|
|
52
|
-
LATTICE_ERROR_FULL = -10,
|
|
53
|
-
LATTICE_ERROR_VERSION_MISMATCH = -11,
|
|
54
|
-
LATTICE_ERROR_CHECKSUM = -12,
|
|
55
|
-
LATTICE_ERROR_OUT_OF_MEMORY = -13,
|
|
56
|
-
LATTICE_ERROR_UNSUPPORTED = -14
|
|
57
|
-
} lattice_error;
|
|
58
|
-
|
|
59
|
-
/* Transaction modes */
|
|
60
|
-
typedef enum {
|
|
61
|
-
LATTICE_TXN_READ_ONLY = 0,
|
|
62
|
-
LATTICE_TXN_READ_WRITE = 1
|
|
63
|
-
} lattice_txn_mode;
|
|
64
|
-
|
|
65
|
-
/* Value types. */
|
|
66
|
-
typedef enum {
|
|
67
|
-
LATTICE_VALUE_NULL = 0,
|
|
68
|
-
LATTICE_VALUE_BOOL = 1,
|
|
69
|
-
LATTICE_VALUE_INT = 2,
|
|
70
|
-
LATTICE_VALUE_FLOAT = 3,
|
|
71
|
-
LATTICE_VALUE_STRING = 4,
|
|
72
|
-
LATTICE_VALUE_BYTES = 5,
|
|
73
|
-
LATTICE_VALUE_VECTOR = 6,
|
|
74
|
-
LATTICE_VALUE_LIST = 7,
|
|
75
|
-
LATTICE_VALUE_MAP = 8
|
|
76
|
-
} lattice_value_type;
|
|
77
|
-
|
|
78
|
-
typedef struct lattice_value lattice_value;
|
|
79
|
-
typedef struct lattice_list lattice_list;
|
|
80
|
-
typedef struct lattice_map_entry lattice_map_entry;
|
|
81
|
-
typedef struct lattice_map lattice_map;
|
|
82
|
-
|
|
83
|
-
/* Recursive list container for nested values. */
|
|
84
|
-
struct lattice_list {
|
|
85
|
-
lattice_value* items; /* nullable when len == 0 */
|
|
86
|
-
size_t len;
|
|
87
|
-
};
|
|
88
|
-
|
|
89
|
-
/* Recursive map container for nested values. */
|
|
90
|
-
struct lattice_map {
|
|
91
|
-
lattice_map_entry* entries; /* nullable when len == 0 */
|
|
92
|
-
size_t len;
|
|
93
|
-
};
|
|
94
|
-
|
|
95
|
-
/* Property value. LIST and MAP use pointer-indirected containers so values can
|
|
96
|
-
* nest recursively. */
|
|
97
|
-
struct lattice_value {
|
|
98
|
-
lattice_value_type type;
|
|
99
|
-
union {
|
|
100
|
-
bool bool_val;
|
|
101
|
-
int64_t int_val;
|
|
102
|
-
double float_val;
|
|
103
|
-
struct {
|
|
104
|
-
const char* ptr;
|
|
105
|
-
size_t len;
|
|
106
|
-
} string_val;
|
|
107
|
-
struct {
|
|
108
|
-
const uint8_t* ptr;
|
|
109
|
-
size_t len;
|
|
110
|
-
} bytes_val;
|
|
111
|
-
struct {
|
|
112
|
-
const float* ptr;
|
|
113
|
-
uint32_t dimensions;
|
|
114
|
-
} vector_val;
|
|
115
|
-
lattice_list* list_val;
|
|
116
|
-
lattice_map* map_val;
|
|
117
|
-
} data;
|
|
118
|
-
};
|
|
119
|
-
|
|
120
|
-
/* A single map entry (key/value pair) for nested values. */
|
|
121
|
-
struct lattice_map_entry {
|
|
122
|
-
const char* key; /* nullable when key_len == 0 */
|
|
123
|
-
size_t key_len;
|
|
124
|
-
lattice_value value;
|
|
125
|
-
};
|
|
126
|
-
|
|
127
|
-
/* Open options */
|
|
128
|
-
typedef struct {
|
|
129
|
-
bool create; /* Create if not exists */
|
|
130
|
-
bool read_only; /* Open in read-only mode */
|
|
131
|
-
uint32_t cache_size_mb; /* Cache size in MB (default: 100) */
|
|
132
|
-
uint32_t page_size; /* Page size in bytes (default: 4096) */
|
|
133
|
-
bool enable_vector; /* Enable vector storage for embeddings */
|
|
134
|
-
uint16_t vector_dimensions; /* Vector dimensions (default: 128) */
|
|
135
|
-
} lattice_open_options;
|
|
136
|
-
|
|
137
|
-
/* Default open options */
|
|
138
|
-
#define LATTICE_OPEN_OPTIONS_DEFAULT { false, false, 100, 4096, false, 128 }
|
|
139
|
-
|
|
140
|
-
/*
|
|
141
|
-
* Database operations
|
|
142
|
-
*/
|
|
143
|
-
|
|
144
|
-
/* Open a database file */
|
|
145
|
-
lattice_error lattice_open(
|
|
146
|
-
const char* path,
|
|
147
|
-
const lattice_open_options* options,
|
|
148
|
-
lattice_database** db_out
|
|
149
|
-
);
|
|
150
|
-
|
|
151
|
-
/* Close a database */
|
|
152
|
-
lattice_error lattice_close(lattice_database* db);
|
|
153
|
-
|
|
154
|
-
/*
|
|
155
|
-
* Transaction operations
|
|
156
|
-
*/
|
|
157
|
-
|
|
158
|
-
/* Begin a transaction */
|
|
159
|
-
lattice_error lattice_begin(
|
|
160
|
-
lattice_database* db,
|
|
161
|
-
lattice_txn_mode mode,
|
|
162
|
-
lattice_txn** txn_out
|
|
163
|
-
);
|
|
164
|
-
|
|
165
|
-
/* Commit a transaction */
|
|
166
|
-
lattice_error lattice_commit(lattice_txn* txn);
|
|
167
|
-
|
|
168
|
-
/* Rollback a transaction */
|
|
169
|
-
lattice_error lattice_rollback(lattice_txn* txn);
|
|
170
|
-
|
|
171
|
-
/*
|
|
172
|
-
* Node operations
|
|
173
|
-
*/
|
|
174
|
-
|
|
175
|
-
/* Create a node with an optional single label.
|
|
176
|
-
* Pass NULL or "" to create an unlabeled node. */
|
|
177
|
-
lattice_error lattice_node_create(
|
|
178
|
-
lattice_txn* txn,
|
|
179
|
-
const char* label,
|
|
180
|
-
lattice_node_id* node_out
|
|
181
|
-
);
|
|
182
|
-
|
|
183
|
-
/* Add a label to an existing node */
|
|
184
|
-
lattice_error lattice_node_add_label(
|
|
185
|
-
lattice_txn* txn,
|
|
186
|
-
lattice_node_id node_id,
|
|
187
|
-
const char* label
|
|
188
|
-
);
|
|
189
|
-
|
|
190
|
-
/* Remove a label from an existing node */
|
|
191
|
-
lattice_error lattice_node_remove_label(
|
|
192
|
-
lattice_txn* txn,
|
|
193
|
-
lattice_node_id node_id,
|
|
194
|
-
const char* label
|
|
195
|
-
);
|
|
196
|
-
|
|
197
|
-
/* Delete a node */
|
|
198
|
-
lattice_error lattice_node_delete(
|
|
199
|
-
lattice_txn* txn,
|
|
200
|
-
lattice_node_id node_id
|
|
201
|
-
);
|
|
202
|
-
|
|
203
|
-
/* Set a property on a node.
|
|
204
|
-
* The value tree is borrowed for the duration of the call only.
|
|
205
|
-
* STRING/BYTES/VECTOR pointers may be NULL only when their lengths are zero.
|
|
206
|
-
* LIST/MAP container pointers must be non-NULL; empty containers use len=0. */
|
|
207
|
-
lattice_error lattice_node_set_property(
|
|
208
|
-
lattice_txn* txn,
|
|
209
|
-
lattice_node_id node_id,
|
|
210
|
-
const char* key,
|
|
211
|
-
const lattice_value* value
|
|
212
|
-
);
|
|
213
|
-
|
|
214
|
-
/* Get a property from a node.
|
|
215
|
-
* Ownership of the full returned value tree transfers to the caller.
|
|
216
|
-
* Release any owned storage with lattice_value_free() after consuming it. */
|
|
217
|
-
lattice_error lattice_node_get_property(
|
|
218
|
-
lattice_txn* txn,
|
|
219
|
-
lattice_node_id node_id,
|
|
220
|
-
const char* key,
|
|
221
|
-
lattice_value* value_out
|
|
222
|
-
);
|
|
223
|
-
|
|
224
|
-
/* Check if a node exists */
|
|
225
|
-
lattice_error lattice_node_exists(
|
|
226
|
-
lattice_txn* txn,
|
|
227
|
-
lattice_node_id node_id,
|
|
228
|
-
bool* exists_out
|
|
229
|
-
);
|
|
230
|
-
|
|
231
|
-
/* Get labels for a node (comma-separated string, caller must free) */
|
|
232
|
-
lattice_error lattice_node_get_labels(
|
|
233
|
-
lattice_txn* txn,
|
|
234
|
-
lattice_node_id node_id,
|
|
235
|
-
char** labels_out
|
|
236
|
-
);
|
|
237
|
-
|
|
238
|
-
/* Free a string allocated by lattice (e.g., from lattice_node_get_labels) */
|
|
239
|
-
void lattice_free_string(char* str);
|
|
240
|
-
|
|
241
|
-
/* Free heap-backed storage inside a lattice_value returned by an owning API.
|
|
242
|
-
* LIST/MAP values are released recursively.
|
|
243
|
-
* Safe to call on null/bool/int/float values.
|
|
244
|
-
*
|
|
245
|
-
* Ownership currently transfers from lattice_node_get_property() and
|
|
246
|
-
* lattice_edge_get_property().
|
|
247
|
-
* Values returned by lattice_result_get() are borrowed from the result handle
|
|
248
|
-
* and must not be passed to lattice_value_free().
|
|
249
|
-
*/
|
|
250
|
-
void lattice_value_free(lattice_value* value);
|
|
251
|
-
|
|
252
|
-
/* Set a vector on a node */
|
|
253
|
-
lattice_error lattice_node_set_vector(
|
|
254
|
-
lattice_txn* txn,
|
|
255
|
-
lattice_node_id node_id,
|
|
256
|
-
const char* key,
|
|
257
|
-
const float* vector,
|
|
258
|
-
uint32_t dimensions
|
|
259
|
-
);
|
|
260
|
-
|
|
261
|
-
/*
|
|
262
|
-
* Batch insert operations
|
|
263
|
-
*/
|
|
264
|
-
|
|
265
|
-
/* Node spec for batch insert: label + vector */
|
|
266
|
-
typedef struct {
|
|
267
|
-
const char* label;
|
|
268
|
-
const float* vector;
|
|
269
|
-
uint32_t dimensions;
|
|
270
|
-
} lattice_node_with_vector;
|
|
271
|
-
|
|
272
|
-
/* Create multiple nodes with vectors in a single call.
|
|
273
|
-
* On success, node_ids_out[0..count_out] contains created node IDs.
|
|
274
|
-
* On partial failure, count_out indicates how many succeeded;
|
|
275
|
-
* caller should rollback the transaction.
|
|
276
|
-
*/
|
|
277
|
-
lattice_error lattice_batch_insert(
|
|
278
|
-
lattice_txn* txn,
|
|
279
|
-
const lattice_node_with_vector* nodes,
|
|
280
|
-
uint32_t count,
|
|
281
|
-
lattice_node_id* node_ids_out, /* caller-allocated, size count */
|
|
282
|
-
uint32_t* count_out /* nodes successfully created */
|
|
283
|
-
);
|
|
284
|
-
|
|
285
|
-
/*
|
|
286
|
-
* Vector search operations
|
|
287
|
-
*
|
|
288
|
-
* Search for similar vectors using HNSW index:
|
|
289
|
-
* 1. Call lattice_vector_search() with query vector
|
|
290
|
-
* 2. Get result count with lattice_vector_result_count()
|
|
291
|
-
* 3. Iterate results with lattice_vector_result_get()
|
|
292
|
-
* 4. Free with lattice_vector_result_free()
|
|
293
|
-
*
|
|
294
|
-
* Example:
|
|
295
|
-
* float query[128] = { ... };
|
|
296
|
-
* lattice_vector_result* results;
|
|
297
|
-
* lattice_vector_search(db, query, 128, 10, 64, &results);
|
|
298
|
-
* uint32_t count = lattice_vector_result_count(results);
|
|
299
|
-
* for (uint32_t i = 0; i < count; i++) {
|
|
300
|
-
* lattice_node_id node_id;
|
|
301
|
-
* float distance;
|
|
302
|
-
* lattice_vector_result_get(results, i, &node_id, &distance);
|
|
303
|
-
* }
|
|
304
|
-
* lattice_vector_result_free(results);
|
|
305
|
-
*/
|
|
306
|
-
|
|
307
|
-
/* Search for similar vectors */
|
|
308
|
-
lattice_error lattice_vector_search(
|
|
309
|
-
lattice_database* db,
|
|
310
|
-
const float* vector,
|
|
311
|
-
uint32_t dimensions,
|
|
312
|
-
uint32_t k, /* Number of results to return */
|
|
313
|
-
uint16_t ef_search, /* HNSW ef parameter (0 for default) */
|
|
314
|
-
lattice_vector_result** result_out
|
|
315
|
-
);
|
|
316
|
-
|
|
317
|
-
/* Get the number of results */
|
|
318
|
-
uint32_t lattice_vector_result_count(lattice_vector_result* result);
|
|
319
|
-
|
|
320
|
-
/* Get a result by index */
|
|
321
|
-
lattice_error lattice_vector_result_get(
|
|
322
|
-
lattice_vector_result* result,
|
|
323
|
-
uint32_t index,
|
|
324
|
-
lattice_node_id* node_id_out,
|
|
325
|
-
float* distance_out
|
|
326
|
-
);
|
|
327
|
-
|
|
328
|
-
/* Free vector search results */
|
|
329
|
-
void lattice_vector_result_free(lattice_vector_result* result);
|
|
330
|
-
|
|
331
|
-
/*
|
|
332
|
-
* Full-text search operations
|
|
333
|
-
*
|
|
334
|
-
* BM25-scored full-text search:
|
|
335
|
-
* 1. Index documents with lattice_fts_index()
|
|
336
|
-
* 2. Search with lattice_fts_search()
|
|
337
|
-
* 3. Get result count with lattice_fts_result_count()
|
|
338
|
-
* 4. Iterate results with lattice_fts_result_get()
|
|
339
|
-
* 5. Free with lattice_fts_result_free()
|
|
340
|
-
*
|
|
341
|
-
* Example:
|
|
342
|
-
* // Index a document
|
|
343
|
-
* const char* text = "The quick brown fox jumps over the lazy dog";
|
|
344
|
-
* lattice_fts_index(txn, node_id, text, strlen(text));
|
|
345
|
-
*
|
|
346
|
-
* // Search
|
|
347
|
-
* lattice_fts_result* results;
|
|
348
|
-
* lattice_fts_search(db, "quick fox", 9, 10, &results);
|
|
349
|
-
* uint32_t count = lattice_fts_result_count(results);
|
|
350
|
-
* for (uint32_t i = 0; i < count; i++) {
|
|
351
|
-
* lattice_node_id node_id;
|
|
352
|
-
* float score;
|
|
353
|
-
* lattice_fts_result_get(results, i, &node_id, &score);
|
|
354
|
-
* }
|
|
355
|
-
* lattice_fts_result_free(results);
|
|
356
|
-
*/
|
|
357
|
-
|
|
358
|
-
/* Index a text document for full-text search */
|
|
359
|
-
lattice_error lattice_fts_index(
|
|
360
|
-
lattice_txn* txn,
|
|
361
|
-
lattice_node_id node_id,
|
|
362
|
-
const char* text,
|
|
363
|
-
size_t text_len
|
|
364
|
-
);
|
|
365
|
-
|
|
366
|
-
/* Search for documents matching a text query */
|
|
367
|
-
lattice_error lattice_fts_search(
|
|
368
|
-
lattice_database* db,
|
|
369
|
-
const char* query,
|
|
370
|
-
size_t query_len,
|
|
371
|
-
uint32_t limit,
|
|
372
|
-
lattice_fts_result** result_out
|
|
373
|
-
);
|
|
374
|
-
|
|
375
|
-
/* Search with fuzzy matching (typo tolerance).
|
|
376
|
-
* max_distance: max Levenshtein edit distance (0 = default 2)
|
|
377
|
-
* min_term_length: min term length for fuzzy expansion (0 = default 4) */
|
|
378
|
-
lattice_error lattice_fts_search_fuzzy(
|
|
379
|
-
lattice_database* db,
|
|
380
|
-
const char* query,
|
|
381
|
-
size_t query_len,
|
|
382
|
-
uint32_t limit,
|
|
383
|
-
uint32_t max_distance,
|
|
384
|
-
uint32_t min_term_length,
|
|
385
|
-
lattice_fts_result** result_out
|
|
386
|
-
);
|
|
387
|
-
|
|
388
|
-
/* Get the number of FTS results */
|
|
389
|
-
uint32_t lattice_fts_result_count(lattice_fts_result* result);
|
|
390
|
-
|
|
391
|
-
/* Get a result by index (returns node_id and BM25 score) */
|
|
392
|
-
lattice_error lattice_fts_result_get(
|
|
393
|
-
lattice_fts_result* result,
|
|
394
|
-
uint32_t index,
|
|
395
|
-
lattice_node_id* node_id_out,
|
|
396
|
-
float* score_out
|
|
397
|
-
);
|
|
398
|
-
|
|
399
|
-
/* Free FTS search results */
|
|
400
|
-
void lattice_fts_result_free(lattice_fts_result* result);
|
|
401
|
-
|
|
402
|
-
/*
|
|
403
|
-
* Embedding operations
|
|
404
|
-
*/
|
|
405
|
-
|
|
406
|
-
typedef struct lattice_embedding_client lattice_embedding_client;
|
|
407
|
-
|
|
408
|
-
typedef enum {
|
|
409
|
-
LATTICE_EMBEDDING_OLLAMA = 0,
|
|
410
|
-
LATTICE_EMBEDDING_OPENAI = 1
|
|
411
|
-
} lattice_embedding_api_format;
|
|
412
|
-
|
|
413
|
-
typedef struct {
|
|
414
|
-
const char* endpoint;
|
|
415
|
-
const char* model;
|
|
416
|
-
lattice_embedding_api_format api_format;
|
|
417
|
-
const char* api_key; /* NULL for no auth */
|
|
418
|
-
uint32_t timeout_ms; /* 0 = default 30s */
|
|
419
|
-
} lattice_embedding_config;
|
|
420
|
-
|
|
421
|
-
/* Generate a hash embedding (built-in, no external service).
|
|
422
|
-
* Caller must free with lattice_hash_embed_free(). */
|
|
423
|
-
lattice_error lattice_hash_embed(
|
|
424
|
-
const char* text, size_t text_len,
|
|
425
|
-
uint16_t dimensions,
|
|
426
|
-
float** vector_out, uint32_t* dims_out
|
|
427
|
-
);
|
|
428
|
-
|
|
429
|
-
/* Free a hash embedding vector */
|
|
430
|
-
void lattice_hash_embed_free(float* vector, uint32_t dimensions);
|
|
431
|
-
|
|
432
|
-
/* Create an HTTP embedding client */
|
|
433
|
-
lattice_error lattice_embedding_client_create(
|
|
434
|
-
const lattice_embedding_config* config,
|
|
435
|
-
lattice_embedding_client** client_out
|
|
436
|
-
);
|
|
437
|
-
|
|
438
|
-
/* Generate an embedding via HTTP.
|
|
439
|
-
* Caller must free with lattice_hash_embed_free(). */
|
|
440
|
-
lattice_error lattice_embedding_client_embed(
|
|
441
|
-
lattice_embedding_client* client,
|
|
442
|
-
const char* text, size_t text_len,
|
|
443
|
-
float** vector_out, uint32_t* dims_out
|
|
444
|
-
);
|
|
445
|
-
|
|
446
|
-
/* Free an HTTP embedding client */
|
|
447
|
-
void lattice_embedding_client_free(lattice_embedding_client* client);
|
|
448
|
-
|
|
449
|
-
/*
|
|
450
|
-
* Edge operations
|
|
451
|
-
*/
|
|
452
|
-
|
|
453
|
-
/* Create an edge between two nodes */
|
|
454
|
-
lattice_error lattice_edge_create(
|
|
455
|
-
lattice_txn* txn,
|
|
456
|
-
lattice_node_id source,
|
|
457
|
-
lattice_node_id target,
|
|
458
|
-
const char* edge_type,
|
|
459
|
-
lattice_edge_id* edge_out
|
|
460
|
-
);
|
|
461
|
-
|
|
462
|
-
/* Delete an edge between two nodes */
|
|
463
|
-
lattice_error lattice_edge_delete(
|
|
464
|
-
lattice_txn* txn,
|
|
465
|
-
lattice_node_id source,
|
|
466
|
-
lattice_node_id target,
|
|
467
|
-
const char* edge_type
|
|
468
|
-
);
|
|
469
|
-
|
|
470
|
-
/* Set a property on an edge by stable edge ID.
|
|
471
|
-
* The value tree is borrowed for the duration of the call only. */
|
|
472
|
-
lattice_error lattice_edge_set_property(
|
|
473
|
-
lattice_txn* txn,
|
|
474
|
-
lattice_edge_id edge_id,
|
|
475
|
-
const char* key,
|
|
476
|
-
const lattice_value* value
|
|
477
|
-
);
|
|
478
|
-
|
|
479
|
-
/* Get a property from an edge by stable edge ID.
|
|
480
|
-
* Ownership of the full returned value tree transfers to the caller.
|
|
481
|
-
* Release any owned storage with lattice_value_free() after consuming it. */
|
|
482
|
-
lattice_error lattice_edge_get_property(
|
|
483
|
-
lattice_txn* txn,
|
|
484
|
-
lattice_edge_id edge_id,
|
|
485
|
-
const char* key,
|
|
486
|
-
lattice_value* value_out
|
|
487
|
-
);
|
|
488
|
-
|
|
489
|
-
/* Remove a property from an edge by stable edge ID */
|
|
490
|
-
lattice_error lattice_edge_remove_property(
|
|
491
|
-
lattice_txn* txn,
|
|
492
|
-
lattice_edge_id edge_id,
|
|
493
|
-
const char* key
|
|
494
|
-
);
|
|
495
|
-
|
|
496
|
-
/*
|
|
497
|
-
* Edge traversal operations
|
|
498
|
-
*
|
|
499
|
-
* Get edges connected to a node:
|
|
500
|
-
* 1. Call lattice_edge_get_outgoing() or lattice_edge_get_incoming()
|
|
501
|
-
* 2. Get result count with lattice_edge_result_count()
|
|
502
|
-
* 3. Iterate results with lattice_edge_result_get()
|
|
503
|
-
* 4. Free with lattice_edge_result_free()
|
|
504
|
-
*
|
|
505
|
-
* Example:
|
|
506
|
-
* lattice_edge_result* edges;
|
|
507
|
-
* lattice_edge_get_outgoing(txn, node_id, &edges);
|
|
508
|
-
* uint32_t count = lattice_edge_result_count(edges);
|
|
509
|
-
* for (uint32_t i = 0; i < count; i++) {
|
|
510
|
-
* lattice_node_id source, target;
|
|
511
|
-
* const char* type;
|
|
512
|
-
* uint32_t type_len;
|
|
513
|
-
* lattice_edge_result_get(edges, i, &source, &target, &type, &type_len);
|
|
514
|
-
* }
|
|
515
|
-
* lattice_edge_result_free(edges);
|
|
516
|
-
*/
|
|
517
|
-
|
|
518
|
-
/* Get all outgoing edges from a node */
|
|
519
|
-
lattice_error lattice_edge_get_outgoing(
|
|
520
|
-
lattice_txn* txn,
|
|
521
|
-
lattice_node_id node_id,
|
|
522
|
-
lattice_edge_result** result_out
|
|
523
|
-
);
|
|
524
|
-
|
|
525
|
-
/* Get all incoming edges to a node */
|
|
526
|
-
lattice_error lattice_edge_get_incoming(
|
|
527
|
-
lattice_txn* txn,
|
|
528
|
-
lattice_node_id node_id,
|
|
529
|
-
lattice_edge_result** result_out
|
|
530
|
-
);
|
|
531
|
-
|
|
532
|
-
/* Get the number of edges in a result set */
|
|
533
|
-
uint32_t lattice_edge_result_count(lattice_edge_result* result);
|
|
534
|
-
|
|
535
|
-
/* Get the stable edge ID for a result by index */
|
|
536
|
-
lattice_error lattice_edge_result_get_id(
|
|
537
|
-
lattice_edge_result* result,
|
|
538
|
-
uint32_t index,
|
|
539
|
-
lattice_edge_id* edge_id_out
|
|
540
|
-
);
|
|
541
|
-
|
|
542
|
-
/* Get an edge from a result set by index */
|
|
543
|
-
lattice_error lattice_edge_result_get(
|
|
544
|
-
lattice_edge_result* result,
|
|
545
|
-
uint32_t index,
|
|
546
|
-
lattice_node_id* source_out,
|
|
547
|
-
lattice_node_id* target_out,
|
|
548
|
-
const char** edge_type_out,
|
|
549
|
-
uint32_t* edge_type_len_out
|
|
550
|
-
);
|
|
551
|
-
|
|
552
|
-
/* Free an edge result set */
|
|
553
|
-
void lattice_edge_result_free(lattice_edge_result* result);
|
|
554
|
-
|
|
555
|
-
/*
|
|
556
|
-
* Query operations
|
|
557
|
-
*
|
|
558
|
-
* Queries use a prepare/bind/execute pattern:
|
|
559
|
-
* 1. Prepare the query with lattice_query_prepare()
|
|
560
|
-
* 2. Bind parameters with lattice_query_bind() (optional)
|
|
561
|
-
* 3. Execute with lattice_query_execute()
|
|
562
|
-
* 4. Iterate results with lattice_result_next() / lattice_result_get()
|
|
563
|
-
* 5. Free resources with lattice_query_free() and lattice_result_free()
|
|
564
|
-
*
|
|
565
|
-
* Example:
|
|
566
|
-
* lattice_query* query;
|
|
567
|
-
* lattice_query_prepare(db, "MATCH (n) WHERE n.name = $name RETURN n", &query);
|
|
568
|
-
* lattice_value val = { .type = LATTICE_VALUE_STRING, .data.string_val = {"Alice", 5} };
|
|
569
|
-
* lattice_query_bind(query, "name", &val);
|
|
570
|
-
* lattice_query_execute(query, txn, &result);
|
|
571
|
-
*/
|
|
572
|
-
|
|
573
|
-
/* Query diagnostic stage returned by lattice_query_last_error_stage() */
|
|
574
|
-
typedef enum {
|
|
575
|
-
LATTICE_QUERY_STAGE_NONE = 0,
|
|
576
|
-
LATTICE_QUERY_STAGE_PARSE = 1,
|
|
577
|
-
LATTICE_QUERY_STAGE_SEMANTIC = 2,
|
|
578
|
-
LATTICE_QUERY_STAGE_PLAN = 3,
|
|
579
|
-
LATTICE_QUERY_STAGE_EXECUTION = 4
|
|
580
|
-
} lattice_query_error_stage;
|
|
581
|
-
|
|
582
|
-
/* Prepare a Cypher query for execution */
|
|
583
|
-
lattice_error lattice_query_prepare(
|
|
584
|
-
lattice_database* db,
|
|
585
|
-
const char* cypher,
|
|
586
|
-
lattice_query** query_out
|
|
587
|
-
);
|
|
588
|
-
|
|
589
|
-
/* Bind a parameter to a prepared query (use $name in Cypher).
|
|
590
|
-
* The value tree is borrowed for the duration of the call only. */
|
|
591
|
-
lattice_error lattice_query_bind(
|
|
592
|
-
lattice_query* query,
|
|
593
|
-
const char* name, /* Parameter name without $ prefix */
|
|
594
|
-
const lattice_value* value
|
|
595
|
-
);
|
|
596
|
-
|
|
597
|
-
/* Bind a vector parameter to a prepared query */
|
|
598
|
-
lattice_error lattice_query_bind_vector(
|
|
599
|
-
lattice_query* query,
|
|
600
|
-
const char* name,
|
|
601
|
-
const float* vector,
|
|
602
|
-
uint32_t dimensions
|
|
603
|
-
);
|
|
604
|
-
|
|
605
|
-
/* Execute a prepared query and get results */
|
|
606
|
-
lattice_error lattice_query_execute(
|
|
607
|
-
lattice_query* query,
|
|
608
|
-
lattice_txn* txn,
|
|
609
|
-
lattice_result** result_out
|
|
610
|
-
);
|
|
611
|
-
|
|
612
|
-
/* Last query diagnostics for a prepared query handle.
|
|
613
|
-
* Populated when lattice_query_execute() fails.
|
|
614
|
-
* Cleared automatically before each execute call.
|
|
615
|
-
*/
|
|
616
|
-
lattice_query_error_stage lattice_query_last_error_stage(lattice_query* query);
|
|
617
|
-
const char* lattice_query_last_error_message(lattice_query* query);
|
|
618
|
-
const char* lattice_query_last_error_code(lattice_query* query); /* nullable */
|
|
619
|
-
bool lattice_query_last_error_has_location(lattice_query* query);
|
|
620
|
-
uint32_t lattice_query_last_error_line(lattice_query* query); /* 1-based, 0 if unavailable */
|
|
621
|
-
uint32_t lattice_query_last_error_column(lattice_query* query); /* 1-based, 0 if unavailable */
|
|
622
|
-
uint32_t lattice_query_last_error_length(lattice_query* query); /* token span length, 0 if unavailable */
|
|
623
|
-
|
|
624
|
-
/* Free a prepared query (call after done with results) */
|
|
625
|
-
void lattice_query_free(lattice_query* query);
|
|
626
|
-
|
|
627
|
-
/*
|
|
628
|
-
* Result operations
|
|
629
|
-
*/
|
|
630
|
-
|
|
631
|
-
/* Get next row from result set */
|
|
632
|
-
bool lattice_result_next(lattice_result* result);
|
|
633
|
-
|
|
634
|
-
/* Get column count */
|
|
635
|
-
uint32_t lattice_result_column_count(lattice_result* result);
|
|
636
|
-
|
|
637
|
-
/* Get column name */
|
|
638
|
-
const char* lattice_result_column_name(lattice_result* result, uint32_t index);
|
|
639
|
-
|
|
640
|
-
/* Get column value.
|
|
641
|
-
* The full returned value tree is borrowed from the result handle and stays
|
|
642
|
-
* valid until lattice_result_free(). Do not pass it to lattice_value_free().
|
|
643
|
-
*/
|
|
644
|
-
lattice_error lattice_result_get(
|
|
645
|
-
lattice_result* result,
|
|
646
|
-
uint32_t index,
|
|
647
|
-
lattice_value* value_out
|
|
648
|
-
);
|
|
649
|
-
|
|
650
|
-
/* Free a result set */
|
|
651
|
-
void lattice_result_free(lattice_result* result);
|
|
652
|
-
|
|
653
|
-
/*
|
|
654
|
-
* Query cache operations
|
|
655
|
-
*/
|
|
656
|
-
|
|
657
|
-
/* Clear the query cache */
|
|
658
|
-
lattice_error lattice_query_cache_clear(lattice_database* db);
|
|
659
|
-
|
|
660
|
-
/* Get query cache statistics */
|
|
661
|
-
lattice_error lattice_query_cache_stats(
|
|
662
|
-
lattice_database* db,
|
|
663
|
-
uint32_t* entries_out,
|
|
664
|
-
uint64_t* hits_out,
|
|
665
|
-
uint64_t* misses_out
|
|
666
|
-
);
|
|
667
|
-
|
|
668
|
-
/*
|
|
669
|
-
* Utility functions
|
|
670
|
-
*/
|
|
671
|
-
|
|
672
|
-
/* Get version string */
|
|
673
|
-
const char* lattice_version(void);
|
|
674
|
-
|
|
675
|
-
/* Get last error message */
|
|
676
|
-
const char* lattice_error_message(lattice_error code);
|
|
677
|
-
|
|
678
|
-
#ifdef __cplusplus
|
|
679
|
-
}
|
|
680
|
-
#endif
|
|
681
|
-
|
|
682
|
-
#endif /* LATTICE_H */
|