Functional Filter API
Relevant source files
The following files were used as context for generating this wiki page:
The Functional Filter API in EdgeVec provides a high-level, composable TypeScript interface for creating metadata filter expressions. It allows developers to build complex query logic using standalone functions rather than raw string concatenation, ensuring type safety and correct syntax for the underlying Rust-based filtering engine. This API acts as a functional wrapper around the core Filter class, facilitating cleaner code and better integration with search operations.
Sources: pkg/filter-functions.ts:1-40, pkg/filter.ts:1-12
API Architecture and Data Flow
The architecture follows a layered approach where high-level TypeScript functions delegate to a static Filter factory, which in turn communicates with the WebAssembly (WASM) boundary to parse and validate expressions.
The diagram above illustrates the transformation of a functional call into a compiled FilterExpression object containing a JSON AST representation.
Sources: pkg/filter-functions.ts:42-50, pkg/filter.ts:100-115, src/wasm/filter.rs:48-60
Functional Composition
The API provides standalone functions categorized by their logical purpose, allowing for deeply nested and complex filter definitions.
Comparison Functions
These functions handle basic equality and numeric range comparisons between metadata fields and literal values.
| Function | Logic | Example |
|---|---|---|
eq(field, value) | field = value | eq('category', 'gpu') |
ne(field, value) | field != value | ne('status', 'deleted') |
gt(field, value) | field > value | gt('price', 100) |
lt(field, value) | field < value | lt('price', 1000) |
ge(field, value) | field >= value | ge('rating', 4.0) |
le(field, value) | field <= value | le('stock', 100) |
between(field, low, high) | low <= field <= high | between('price', 100, 500) |
Sources: pkg/filter-functions.ts:47-104, pkg/filter.ts:215-285
String and Array Operators
Specialized operators for string pattern matching and array membership.
- String Operators:
contains,startsWith,endsWith, andlike(supports%wildcards). - Array Operators:
inArray: Checks if a field value exists in a provided list.any: Checks if an array field contains a specific value.all: Checks if an array field contains all values in a list.none: Checks if an array field contains none of the values in a list.
Sources: pkg/filter-functions.ts:114-177, pkg/filter.ts:300-380
Logical Combinators
Logical functions allow merging multiple FilterExpression objects into a single query.
The and and or functions accept variadic arguments, automatically handling the necessary grouping and operator precedence for the final filter string.
Sources: pkg/filter-functions.ts:205-240, pkg/filter.ts:420-460
Filter Compilation and Validation
When a filter is constructed, it is represented internally by the FilterImpl class. This class maintains the JSON AST generated by the Rust backend.
FilterExpression Interface
All functional API results implement the FilterExpression interface, providing metadata about the compiled filter.
| Property/Method | Type | Description |
|---|---|---|
_json | string | The raw JSON representation of the AST. |
isTautology | boolean | True if the filter always evaluates to true (e.g., LiteralBool: true). |
isContradiction | boolean | True if the filter always evaluates to false. |
complexity | number | An estimated complexity score (1-10). |
toString() | string | Reconstructs the human-readable string representation. |
Sources: pkg/filter.ts:32-60, pkg/filter.ts:116-140, pkg/filter.d.ts:21-36
The Validation Flow
The API supports proactive validation via Filter.validate(query), which returns structured error objects from the WASM layer if the syntax is incorrect.
Internal Logic: String Reconstruction
The FilterImpl class includes a recursive _reconstructString method. This is critical for converting the Rust enum-style JSON AST back into a valid EdgeVec filter string when required for search operations. It handles nodes like Eq, Ne, And, Or, Between, and array operators by traversing the AST and applying the correct infix or functional syntax.
Sources: pkg/filter.ts:145-200, pkg/filter.js:45-120
Summary
The Functional Filter API provides a robust bridge between high-level TypeScript development and the performance-critical Rust filtering engine. By offering standalone functions like eq, and, and inArray, it simplifies the creation of complex metadata queries while maintaining the strictness required by the underlying vector database search strategies (pre-filtering, post-filtering, and hybrid). This system ensures that filters are parsed, validated, and analyzed for complexity before they are ever executed against the index.
Sources: pkg/filter-functions.ts:1-35, pkg/filter.ts:1-10, src/wasm/filter.rs:1-30