SearchEngine
The SearchEngine class is the core entry point for all operations. It manages the full lifecycle: analyzing data structure, configuring fields, loading data, indexing, and searching.
Lifecycle
Init(stream) → Configure fields → Load(stream) → Index() → Search(query)After Index() the engine is in Ready state and can be searched continuously. Dynamic operations (InsertJsonRecord, UpdateJsonRecord, DeleteJsonRecord) keep the index in sync without requiring a full Index() rebuild.
Constructor
// Default — works for most cases (ConfigurationParameters.Default)
var engine = new SearchEngine();
// With license file
var engine = new SearchEngine("indx-developer.license");
// With logging and an explicit configuration
var engine = new SearchEngine(
logPrefix: "MyApp",
factory: loggerFactory,
configuration: ConfigurationParameters.Default,
licenseFileName: "indx-developer.license"
);
// Vary one thing and state the rest by name, rather than hand-copying every parameter
var dense = new SearchEngine(
logPrefix: "MyApp",
factory: loggerFactory,
configuration: ConfigurationParameters.Default.With(filterCacheSize: 50_000),
licenseFileName: "indx-developer.license"
);Basic Usage
using Indx.Api;
var engine = new SearchEngine();
// 1. Analyze JSON structure
using var stream = File.OpenRead("products.json");
engine.Init(stream);
// 2. Configure fields
engine.GetField("name")!.WordMatching = true;
engine.GetField("name")!.PatternMatching = PatternMatchingSetup.Default;
engine.GetField("name")!.Weight = 2.0f;
engine.GetField("description")!.WordMatching = true;
engine.GetField("description")!.PatternMatching = PatternMatchingSetup.Default;
engine.GetField("category")!.Filterable = true;
engine.GetField("price")!.Sortable = true;
// 3. Load and index
stream.Position = 0;
engine.Load(stream);
engine.Index();
// 4. Search
var result = engine.Search(new Query("wireless headphones", 20));Lifecycle Methods
| Method | Description |
|---|---|
Init(Stream, ...) | Analyze the JSON stream and discover fields. Must be called first |
Load(Stream, ...) | Parse and store documents. Call after configuring fields |
Index(...) | Build the inverted index. Call after Load |
Search(Query) | Run a query. Engine must be in Ready state |
Search(Query[]) | Several queries in one call, one Result each in their order: run at once on the search slots no search holds, one after the other when none is free |
Hibernate(out string) | Release index memory, keep documents in RAM — the engine returns to Loaded |
WakeUp() | Rebuild the index and reload filters — the way out of Loaded |
Unload(out string) | Remove documents and reset to Created state |
Dispose() | Free all resources |
Field Access
| Method | Returns | Description |
|---|---|---|
GetField(string) | Field? | Get a field by name. Returns null if not found |
GetFieldList() | List<Field> | All discovered fields |
GetFieldConfiguration() | FieldProxy[] | Full configuration snapshot of all fields |
TrySetFieldConfiguration(FieldProxy[], out string) | bool | Apply a field configuration. false with the reason when any part is refused, and nothing is applied |
TryValidateFieldConfiguration(FieldProxy[], out string) | bool | Whether TrySetFieldConfiguration would accept the same argument, changing nothing |
SetFieldConfiguration(FieldProxy[]) | string? | Obsolete: use TrySetFieldConfiguration. Returns an error message or null on success |
Dynamic Operations
Insert, update, and delete documents after indexing without rebuilding from scratch. In BM25F mode the shared index is updated incrementally. A periodic full Index() re-normalises avgdl drift that accumulates over many mutations.
A field the configuration does not know is refused.
InsertJsonRecord(s)andUpdateJsonRecord(s)returnfalsewith "... the document has field(s) not in the field configuration: 'color'" (nested fields by path,'meta.batch'), and change nothing: a batch with one such record is refused whole, and an update leaves the document as it was. To add a field, rebuild:Init, configure,Load,Index(in Indx,replace). Missing non-key fields are treated as null; a missing key field fails the batch.
| Method | Description |
|---|---|
InsertJsonRecord(string json, out string error) | Insert a single JSON document. Returns false on error |
InsertJsonRecords(IEnumerable<string>, ProcessMonitor?, out string error) | Batch insert from a collection |
InsertJsonRecords(Stream, ProcessMonitor?, out string error) | Batch insert from a JSON stream |
UpdateJsonRecord(string json, out string error) | Replace a document by key |
UpdateJsonRecords(IEnumerable<string>, ProcessMonitor?, out string error) | Batch update from a collection |
UpdateJsonRecords(Stream, ProcessMonitor?, out string error) | Batch update from a JSON stream |
DeleteJsonRecord(long id) | Remove a single document by key |
DeleteJsonRecords(IEnumerable<long>, ProcessMonitor?) | Remove multiple documents |
DeleteRecordsInFilter(Filter) | Remove all documents matching a filter |
UpdateField(long id, string fieldName, object? value, out string error) | Update a single field value on one document |
UpdateFieldInFilter(Filter, string fieldName, object value, out string error) | Update a field on all documents matching a filter. Returns count updated |
// Insert a new document
bool ok = engine.InsertJsonRecord(
"""{"id": 999, "name": "New Product", "price": 49.99}""",
out string error);
// Update a field value on one document
engine.UpdateField(documentKey, "price", 39.99, out _);
// Delete a document
engine.DeleteJsonRecord(documentKey);Data Retrieval
| Method | Returns | Description |
|---|---|---|
GetJsonDataOfKey(long) | string | Full JSON of a document by key |
Filters
| Method | Returns | Description |
|---|---|---|
CreateValueFilter(string fieldName, object value, out string? error) | Filter? | Match documents where field equals value. The field must not hold numbers ( null + error on failure) |
CreateValueFilter(string fieldName, object value, bool isCaseSensitive, out string? error) | Filter? | As above, choosing case sensitivity. Off by default |
CreateRangeFilter(string fieldName, double min, double max, out string? error) | Filter? | Match documents where field falls within an inclusive range. The field must hold numbers; equal limits are numeric equality ( null + error on failure) |
CreateInFilter(string fieldName, IEnumerable<object> values, out string? error) | Filter? | Match documents whose value is one of a set: one filter, far faster than an OR of value filters. Numbers compare as numbers on a numeric field; an overload takes isCaseSensitive |
CreatePositionFilter(string fieldName, GeoPosition position, float withinMeter, out string? error) | Filter? | Match documents within a distance, in metres, of a position. The field is an object {"latitude", "longitude"} whose two numbers are Filterable |
CreateDateFilter(...), CreateDateRangeFilter(...) | Filter? | On a field holding Unix time, taking DateTimes (extension methods) |
CreateFilter(string expression, out IReadOnlyList<FilterExpressionError> errors) | Filter? | The filter an expression describes: brand IN ["nike", "puma"] AND price BETWEEN 100 AND 2000. An overload takes $name placeholders |
CreateCustomFilter<T>(string fieldName, FieldValueReader<T> read, Func<T, bool> passed, out string? error) | Filter? | A filter you define, kept current through inserts and updates; exists only in this engine |
CreateBoost(Filter, BoostStrength, out string? error), CreateBury(Filter, BuryStrength, out string? error) | Boost?, Bury? | For Query.Ranking.Boosts and Buries |
GetFilterFromKey(string key, out string? error) | Filter? | The filter a key ( Filter.SerializedKey, an HTTP hashString) describes; null with the reason when it cannot be honoured |
LoadAllFilters(...) | — | Pre-load all filterable fields for faster repeated filtering |
LoadFilters(Filter[]) | bool | Pre-load specific filters |
DeleteFilter(Filter) | bool | Release a cached filter |
DeleteAllFilters() | — | Release all cached filters |
PreLoadedFilters | IReadOnlyDictionary<...> | Access filters cached via Field.PreloadFilters = true |
Persistence
| Method | Description |
|---|---|
SaveFieldConfiguration(string path) | Save field config to a JSON file |
LoadFieldConfiguration(string path) | Restore field config from a JSON file |
Properties
| Property | Type | Description |
|---|---|---|
Status | SystemStatus | Current engine state, counters, and error flags |
ScoringMode | ScoringMode | BM25F or BM25PerField, as the configuration chose |
Scoring | ScoringSetup | The scoring mode and BM25F's k1, from ConfigurationParameters.Scoring |
DocumentFields | DocumentFields | Field metadata discovered by Init() |
NumberOfFilters | int | Number of currently cached filters |
PreLoadedFilters | IReadOnlyDictionary<...> | Filters preloaded via Field.PreloadFilters |
ScoringMode
The scoring mode is chosen in the configuration the engine is built with, ConfigurationParameters.Scoring, and is fixed for the engine's life:
| Mode | k1 | Behaviour |
|---|---|---|
BM25F (default) | One for the engine, ScoringSetup.BM25FK1 | One inverted index over all searchable fields; a single saturation step on the weighted, length-normalised frequency summed over the fields |
BM25PerField | Each field's own Field.BM25k1 | The same index once per searchable field, each with its own k1 and b; scores merged by Field.Weight |
With one searchable field the two modes are the same index and score alike.
var engine = new SearchEngine(string.Empty, null,
ConfigurationParameters.Default.With(scoringSetup: new ScoringSetup(ScoringMode.BM25PerField)));
Console.WriteLine(engine.ScoringMode); // BM25PerFieldConstructors
SearchEngine(string logPrefix, ILoggerFactory factory, ConfigurationParameters configuration, string licenseFileName = "")stringlogPrefixILoggerFactoryfactoryConfigurationParametersconfigurationstringlicenseFileName— Default: ""
SearchEngine(string licenseFileName = "")DefaultInitializes the search engine withand an optional license file path.
stringlicenseFileName— Default: ""
Properties
| Name | Type | Access | Description |
|---|---|---|---|
DocumentFields | DocumentFields | get | Field metadata discovered after Init() completes. Contains all fields with their type and configuration flags. |
NumberOfFilters | int | get | Returns the number of filters currently held in the filter cache. |
Persistence | IPersistence | get/set | Persistence provider used for hibernation and wake-up serialization. Assigned by a host with a database; null in standalone use. |
PreLoadedFilters | IReadOnlyDictionary<string, IReadOnlyDictionary<string, Filter>> | get | Provides access to all value filters that were pre-loaded during Load.
Only fields marked with Field.PreloadFilters = true appear here.
The outer key is the field name; the inner key is the filter value as a string.
Populated after Load completes. |
Status | SystemStatus | get/set | Returns the current state and health of the search engine.
Includes document count, version, license information, and errors
from the most recent Init or Load operation.
Recoverable and unrecoverable errors from the last operation are available
via Status.RecoverableErrors and Status.UnrecoverableErrors even after
the ProcessMonitor reference has been discarded. |
ScoringMode | ScoringMode | get | How this engine scores its searchable fields, as its configuration says:. Fixed for the engine's life. |
Scoring | ScoringSetup | get | How this engine scores its searchable fields -or- and BM25F's k1. Chosen in thethe engine was built with
() and fixed for its life. |
SynonymList | SynonymList | get/set | Optional synonym list applied to every subsequent search. When set, the engine expands
the query text throughbefore scoring — matching
terms are appended to the text, separated by spaces. The query is cut into words using
the engine's own, so punctuation attached to a
word does not stop it matching. The expansion runs on the engine's own copy of the, so the instance passed tois never modified. |
IsDisposed | bool | get | True once this engine has been disposed. A disposed engine must not be searched and itsmust not be read (that can throw).
Hosting layers probe this to report a stale instance instead of mistaking its last-known
state for a live one. |
EmbeddingFields | IReadOnlyDictionary<string, IEmbeddingIndex> | get | EmbeddableRead-only view of the HNSW embedding indexes, one per field
that hasset to true. |
Methods
CreateInMemoryClone
fieldOverridesBuilds an independent SearchEngine with the same in-memory state as this instance: same field configuration, same documents, freshly built index. Does not touch persistence — works for class-library clients that never configured a database. The clone has its own native-memory pools and can be mutated/disposed independently of the original. The clone is built by emitting the current document store as a JSON array, feeding it through Init/Load on the new instance, and rebuilding the index. Deleted documents are skipped. An application that wants to change an engine without stopping its searches can build on this: clone, change, swap, dispose. Behaviour mirrors:(optional) is applied after the clone has mirrored this engine's configuration but beforeruns. This is the supported way to change WordMatching/PatternMatching/Embeddable/BM25b/BM25k1 on a copy: those flags are read during Load to build the index, so they must be set before Load to take effect. Throwswith the reason when an override is onerefuses: a field that does not exist, a value out of range, a role the field cannot have. Vectors follow the documents. Where the store does not keep them () the documents carry none and the clone takes each from this engine's graph, which is then the graph's copy of it: with the graph on 16-bit integers, the original to about four digits.
SearchEngine CreateInMemoryClone(ProcessMonitor monitor = null, FieldProxy[] fieldOverrides = null)ProcessMonitormonitor— Default: nullFieldProxy[]fieldOverrides— Default: null
Returns: SearchEngine
ValidateRanking
rankingWhether a search can be run with: the faults in its, one sentence each, or an empty list. A search with any of them returns no records and names them in.
IReadOnlyList<string> ValidateRanking(RankingSetup ranking)RankingSetupranking
Returns: IReadOnlyList<string>
Search
Executes a search and returns ranked results. Requires that Init, field configuration, Load, and Index have all completed successfully. The query controls the search text via Query.Text, the maximum number of results via Query.MaxNumberOfRecordsToReturn, optional filtering via Query.Filter, the ranking and its boosts via Query.Ranking, field-based sorting via Query.SortBy, facet histograms via Query.EnableFacets and Query.FacetFields, and the candidates ranked via Query.Candidates. Search is thread-safe and can be called concurrently from multiple threads. Searching an engine that is not Ready — one that is loading, indexing or hibernated — returns an empty result with Result.DidTimeOut set, so it can be told apart from a search that ran and found nothing. Check that flag before showing "no results" to anyone: a dataset being reloaded would otherwise look like a dataset with nothing in it.
Result Search(Query searchQueryIn)QuerysearchQueryIn
Returns: Result
DeleteJsonRecord
String@)Deletes the document with the given key. The document is immediately removed from search results. This is a blocking call. Returns false if no document with that key exists, and also when the engine is not Ready or an index build is under way;says which.
bool DeleteJsonRecord(long id)longid
Returns: bool
DeleteRecordsInFilter
Deletes all documents that match the given filter. Equivalent to iterating the filter mask and calling DeleteJsonRecord for each matching document.
void DeleteRecordsInFilter(Filter filter)Filterfilter
GetJsonDataOfKey
Returns the raw JSON string for the document with the given key, or null if no document with that key exists.
string GetJsonDataOfKey(long key)longkey
Returns: string
GetJsonDataOfKeys
string[] GetJsonDataOfKeys(long[] keys, int start = 0, int? length = null)long[]keysintstart— Default: 0int?length— Default: null
Returns: string[]
InsertJsonRecord
Inserts a single JSON record without requiring a full reload. The document key is extracted from the JSON using the configured key field. The record is immediately searchable after this call returns. Returns false and populates error if the JSON is invalid or the key is missing.
bool InsertJsonRecord(string jsonData, String& error)stringjsonDataString&error
Returns: bool
UpdateJsonRecord
Replaces an existing record identified by the document key found in the JSON. If no record with that key exists the call fails and error is populated. The updated record is immediately searchable after this call returns.
bool UpdateJsonRecord(string jsonData, String& error)stringjsonDataString&error
Returns: bool
InsertJsonRecords
Inserts multiple JSON records from a stream containing a JSON array. If monitor is null this is a blocking call. If a monitor is provided, insertion runs asynchronously on a background thread. In that case the caller must keep the stream alive until ProcessMonitor.IsCompleted is true.
bool InsertJsonRecords(Stream jsonStream, ProcessMonitor monitor, String& error)StreamjsonStreamProcessMonitormonitorString&error
Returns: bool
UpdateJsonRecords
Replaces multiple records from a stream containing a JSON array. If monitor is null this is a blocking call. If a monitor is provided, the operation runs asynchronously and the stream must be kept alive until ProcessMonitor.IsCompleted is true.
bool UpdateJsonRecords(Stream jsonStream, ProcessMonitor monitor, String& error)StreamjsonStreamProcessMonitormonitorString&error
Returns: bool
DeleteJsonRecords
bool DeleteJsonRecords(IEnumerable<long> ids, ProcessMonitor monitor = null)IEnumerable<long>idsProcessMonitormonitor— Default: null
Returns: bool
UpdateField
Updates a single field within an existing document without replacing the entire record. Supports nested fields using dot notation, for example "address.city", and array element access using index notation, for example "tags[0]". Type compatibility is enforced: the new value must match the type of the existing field value. Returns false and populates error on failure.
bool UpdateField(long id, string fieldName, object value, String& error)longid— The document key of the record to update.stringfieldName— The field to update. Use dot notation for nested fields and bracket notation for array elements, for example "address.city" or "tags[1]".objectvalue— The new value. Must be a primitive type: string, int, long, double, or bool. When updating an array field, an array of primitives is also accepted.String&error— Error description if the update failed, otherwise empty.
Returns: bool
UpdateFieldInFilter
Setstoon every document admitted by. The filter is loaded automatically if it has not been loaded yet. Returns the number of documents successfully updated.
int UpdateFieldInFilter(Filter filter, string fieldName, object value, String& error)Filterfilter— The filter that selects which documents to update.stringfieldName— The field to update. Supports dot notation for nested fields and bracket notation for array elements, for example "address.city" or "tags[1]".objectvalue— The new value. Must be a primitive type: string, int, long, double, or bool.String&error— On failure describes the first error encountered; empty on full success.
Returns: Number of documents that were updated.
SaveEmbeddings
Writes the search graph of every vector field to a file, with its vectors as the graph holds them, so that a laterof the same documents can take the graphs from there in place of building them (). Building is the slow part of loading a dataset with vectors: 9 s for 43 000 vectors of 1 536 numbers and four minutes for 1.2 million of 100 on four cores, where reading the file is copying arrays.
bool SaveEmbeddings(string path, String& error)stringpathString&error
Returns: errorFalse, with the reason in, when no vector field
has a graph or the file could not be written.
LoadEmbeddings
Reads graphs written by, for the nextto take in place of building them. Call it after the field configuration is set and before.
bool LoadEmbeddings(string path, String& error)stringpathString&error
Returns: errorFalse, with the reason in, when the file is not
there, cannot be read, or is not a file of graphs this version reads. Nothing is
kept from it then, and the next Load builds.
GetFacetableFieldList
Returns all fields currently marked as Facetable.
List<Field> GetFacetableFieldList()Returns: List<Field>
GetField
Returns the field with the given name, or null if not found.
Field GetField(string fieldName)stringfieldName
Returns: Field
GetFieldList
Returns all detected fields.
List<Field> GetFieldList()Returns: List<Field>
GetFilterableFieldList
Returns all fields currently marked as Filterable.
List<Field> GetFilterableFieldList()Returns: List<Field>
TrySetFieldConfiguration
errorApplies a batch of per-field configuration in one call. Nullable properties onhave replace semantics:leaves the existing value untouched; any non-null value (including) overwrites. Returnson success. On,says why — a proposed field the engine does not have (named in the message), a value or a combination of roles it refuses, or no field configuration at all because Init has not run — and nothing was applied. The caller is responsible for callingafterwards if any reindex-requiring property changed — useto check.
bool TrySetFieldConfiguration(FieldProxy[] fields, String& error)FieldProxy[]fieldsString&error
Returns: bool
SetFieldConfiguration
String@)The previous shape of, and the one member of this surface wheremeant success: returns the name of the first proposed field the engine does not have,when there is no field configuration, orwhen it applied. Behaves exactly as before.
string SetFieldConfiguration(FieldProxy[] fields)FieldProxy[]fields
Returns: string
TryValidateFieldConfiguration
String@)Says whetherwould accept, and changes nothing. The same answer in the same way: false with the reason in.
bool TryValidateFieldConfiguration(FieldProxy[] fields, String& error)FieldProxy[]fieldsString&error
Returns: bool
GetFieldConfiguration
FieldProxyReturns the complete configuration of every field as aarray, including all flags, weights and BM25F parameters.
FieldProxy[] GetFieldConfiguration()Returns: FieldProxy[]
LoadFieldConfiguration
Loads field configuration previously saved by SaveFieldConfiguration, restoring Searchable, Filterable, Facetable, Sortable and other field settings. Call this after Init to avoid manually reconfiguring each field. Returns false if the file does not exist or cannot be parsed. Use theoverload to learn which.
bool LoadFieldConfiguration(string configurationFile)stringconfigurationFile
Returns: bool
SaveFieldConfiguration
Saves the current field configuration to a file so it can be restored later with LoadFieldConfiguration. Returns false if DocumentFields is null or the file cannot be written. Use theoverload to learn which.
bool SaveFieldConfiguration(string configurationFile)stringconfigurationFile
Returns: bool
LoadSynonyms
Loads a synonym list from a file previously written byand makes it the engine's active, replacing any list already set. Every search from then on is widened through it. Returns false if the file does not exist or cannot be parsed, in which case the previously active list is left untouched. Use theoverload to learn which.
bool LoadSynonyms(string synonymFile)stringsynonymFile
Returns: bool
SaveSynonyms
Saves the engine's activeto a file so it can be restored later with. Returns false if no list is set or the file cannot be written. Use theoverload to learn which.
bool SaveSynonyms(string synonymFile)stringsynonymFile
Returns: bool
SetDocumentFieldsInternal
Replaces the field configuration. For a host whose field configuration comes from elsewhere, such as IndxServer's database.
void SetDocumentFieldsInternal(DocumentFields documentFields)DocumentFieldsdocumentFields— The field configuration to use.
CreateBoost
errorCreates a boost that increases the score of documents matching the given filter. Must be called after Load completes. Pass the resulting Boost instance to Query.Boosts before calling Search. Returns null, with the reason in, for a null filter or a strength that is not Low, Med or High (a number cast to the enum, or read from JSON).
Boost CreateBoost(Filter filter, BoostStrength strength, String& error)FilterfilterBoostStrengthstrengthString&error
Returns: Boost
CreateBury
errorCreates a bury, the counterpart of a boost: the documents the filter holds are scored lower by the strength, nobody else moves. Must be called after Load completes. Pass the resulting Bury to Query.Buries and set Query.EnableBury before calling Search. Returns null, with the reason in, for a null filter or a strength that is not Low, Med or High.
Bury CreateBury(Filter filter, BuryStrength strength, String& error)FilterfilterBuryStrengthstrengthString&error
Returns: Bury
CreateRangeFilter
Creates a filter matching documents where fieldName falls within the inclusive numeric range from lowerInclusiveLimit to upperInclusiveLimit. The field must be marked as Filterable and hold numbers: a number stored as a JSON string is text, and a range filter on such a field is refused with the fix in error (store the values as numbers and load again). Equal limits make it an equality filter, which is the right way to ask for one value of a numeric field. A range has no culture: the limits are doubles, and the documents' values are JSON numbers. Returns null if the engine is not initialized, the field is not found, not filterable, not numeric, or the range is invalid — in which case error describes the exact cause; error is null on success.
Filter CreateRangeFilter(string fieldName, double lowerInclusiveLimit, double upperInclusiveLimit, String& error)stringfieldNamedoublelowerInclusiveLimitdoubleupperInclusiveLimitString&error
Returns: Filter
CreateValueFilter
Creates a case-insensitive filter matching documents where fieldName equals filterValue, compared as text. The field must be marked as Filterable and must not hold numbers: on a numeric field a text comparison is wrong (129 is not 129.0) and cannot use the field's index, so it is refused with the alternative in error - a range filter with equal limits. Returns null if the engine is not initialized, the field is not found, not filterable, numeric, or the value is unusable — in which case error describes the exact cause; error is null on success.
Filter CreateValueFilter(string fieldName, object filterValue, String& error)stringfieldNameobjectfilterValueString&error
Returns: Filter
CreateFilter
Filter CreateFilter(string expression, IReadOnlyList`1& errors)stringexpressionIReadOnlyList`1&errors
Returns: Filter
CreateInFilter
Filter CreateInFilter(string fieldName, IEnumerable<object> values, String& error)stringfieldNameIEnumerable<object>valuesString&error
Returns: Filter
CreatePositionFilter
Creates a filter matching documents whose position inlies withinmetres of- "a shop within 1 km". The field is an object with two numbers in decimal degrees,, so the dataset holds it as the Number fieldsand: both must be marked Filterable, andis the object's name. One position per document; a position in an array is refused.Returns null if the engine is not initialized, the fields are missing, not numbers, not filterable or in an array, the position is not on the Earth (latitude within ±90, longitude within ±180), or the distance is negative or not a number - in which case error describes the cause; error is null on success.
Filter CreatePositionFilter(string fieldName, GeoPosition position, float withinMeter, String& error)stringfieldNameGeoPositionpositionfloatwithinMeterString&error
Returns: Filter
CreateCustomFilter
Filter CreateCustomFilter(string fieldName, FieldValueReader<T> read, Func<T, bool> passed, String& error)stringfieldNameFieldValueReader<T>readFunc<T, bool>passedString&error
Returns: Filter
DeleteAllFilters
Removes all filters from the filter cache. Any query referencing a deleted filter will return empty results.
void DeleteAllFilters()DeleteFilter
Removes a single filter from the filter cache. Does not cascade to filters derived from this one via boolean operators. Returns false if not found.
bool DeleteFilter(Filter filter)Filterfilter
Returns: bool
GetFilterFromKey
Retrieves or reconstructs a filter from its serialized key string. For a client that holds the key across requests, such as over HTTP, where the filter object may have been evicted from the cache in between.
Filter GetFilterFromKey(string key, String& reason)stringkeyString&reason
Returns: Filter
LoadAllFilters
Loads all filters in the cache using all available CPU cores. A filter created with CreateValueFilter or CreateRangeFilter is not usable in a query until it has been loaded. If a monitor is provided the operation runs asynchronously.
void LoadAllFilters(ProcessMonitor monitor = null)ProcessMonitormonitor— Default: null
LoadFilters
Loads a specific set of filters. Filters not in the array are unaffected. Returns false if the engine is not in a state that allows filter loading, or if the load failed. Use theoverload to learn which.
bool LoadFilters(Filter[] filterList)Filter[]filterList
Returns: bool
Dispose
Dispose.
void Dispose()Hibernate
Frees index memory while retaining document data, returning the engine to the Loaded state — one step back along the lifecycle, from which Index (or WakeUp) rebuilds search capability without reloading data. Returns false if the engine is not in the Ready state.
bool Hibernate(String& errorMessage)String&errorMessage
Returns: bool
Index
Builds the search indexes required for Search. Must be called after Load completes and at least one field has been marked as Searchable. The BM25 parameters have sensible defaults:per field, and k1 assays - one for the engine in,per field in. If a monitor is provided, indexing runs asynchronously. Callto block until done.
void Index(ProcessMonitor monitor = null)ProcessMonitormonitor— If provided, indexing runs asynchronously. Call ProcessMonitor.WaitForCompletion to block until done.
Init
Scans the JSON stream to detect the field structure of the data. Must be called before configuring fields and before Load. The stream position is reset to zero after Init completes so the same stream instance can be passed directly to Load. Recoverable parse errors such as control characters or trailing commas are silently sanitized unless ProcessMonitor.MaxRecoveryAttempts is exceeded, in which case the operation aborts and ProcessMonitor.Succeeded is set to false. Unrecoverable parse errors always abort immediately. If a monitor is provided the error is recorded in ProcessMonitor.UnrecoverableErrors and Succeeded is false. If no monitor is provided a JsonException is thrown.
void Init(Stream jsonStream, string nameOfKeyField, ProcessMonitor monitor = null, bool optimizeBM25b = true)StreamjsonStream— A readable stream containing a JSON array of objects. The stream position is reset to zero after Init completes.stringnameOfKeyField— The name of the field used as the document key. The value must be parseable as a long. If the field is absent, keys are auto-generated as 0, 1, 2 and so on. To default it to "id", call the two-argument overload below.ProcessMonitormonitor— Optional. If provided, Init runs asynchronously on a background thread. Call ProcessMonitor.WaitForCompletion to block until done. Set ProcessMonitor.MaxRecoveryAttempts before calling Init to control how many recoverable parse errors are tolerated. Defaults to int.MaxValue, meaning fully tolerant. If null, Init runs synchronously and throws on unrecoverable errors.booloptimizeBM25b— BM25bTrue (the default): each text field'sis set from its mean length in the analyzed documents, 0.3 for a field of names and titles (up to 100 characters) rising to 0.75 for a text (from 300). Set beforeandlike any field setting, and saved with the field configuration; a value set afterwards, or a saved configuration applied, overrides it. False: every field 0.75.
Load
Loads JSON data into the search engine. Must be called after Init and field configuration, and before Index. The stream position is reset to zero before reading, so the same stream used for Init can be passed here directly. Recoverable parse errors such as control characters or trailing commas are silently sanitized and counted. Each distinct error, grouped by source and message, is recorded once in ProcessMonitor.RecoverableErrors with an occurrence count. The ParseResult details and originating exception are captured from the first occurrence only. If the number of recoverable errors exceeds ProcessMonitor.MaxRecoveryAttempts the load is aborted, Succeeded is set to false, and the error that caused the limit to be exceeded is also added to ProcessMonitor.UnrecoverableErrors. Unrecoverable parse errors always abort the load immediately. The error is added to ProcessMonitor.UnrecoverableErrors and Succeeded is set to false. If no monitor is provided a JsonException is thrown instead. After Load completes, all error details are mirrored to Status.RecoverableErrors and Status.UnrecoverableErrors so they remain accessible after the monitor reference is discarded.
void Load(Stream jsonStream, ProcessMonitor monitor = null)StreamjsonStream— A readable stream containing a JSON array of objects. The stream position is reset to zero before reading begins.ProcessMonitormonitor— Optional. If provided, Load runs asynchronously on a background thread. Call ProcessMonitor.WaitForCompletion to block until done. Set ProcessMonitor.MaxRecoveryAttempts to control how many recoverable parse errors are tolerated before the load is aborted. Defaults to int.MaxValue, meaning fully tolerant. If null, Load runs synchronously and throws on unrecoverable errors.
LoadAsync
Loads documents from a stream asynchronously, for a host that holds a request stream (an HTTP upload). Usein other cases.
Task LoadAsync(Stream jsonStream, ProcessMonitor monitor = null)StreamjsonStream— The JSON documents.ProcessMonitormonitor— Default: null
Returns: Task
LoadDocumentFieldsFromDb
Reads the field configuration from the persistence provider, for a host with a database (IndxServer).
bool LoadDocumentFieldsFromDb()Returns: Whether a configuration was read.
LoadFromDatabaseSync
Loads the documents from the persistence provider, for a host with a database (IndxServer). Usein other cases.
void LoadFromDatabaseSync(ProcessMonitor monitor)ProcessMonitormonitor
Unload
Unloads all documents, indexes, and filters from memory. The engine returns to its initial state (Created) and must go through Load and Index again before searching. Returns false if the engine is not in the Ready state, in which case errorMessage describes the reason.
bool Unload(String& errorMessage)String&errorMessage
Returns: bool
WakeUp
String@)Rebuilds all indexes and reloads all filters — the transition out of Loaded, packaged as one call. The convenience counterpart to Hibernate. Uses all available CPU cores. Returns false if the engine is not in the Loaded state, or if the index build or the filter load did not succeed. Useto learn which.
bool WakeUp()Returns: bool