Crate attribute_search_engine

Expand description

Attribute Search Engine is a generic search engine for rows consisting of attributes, that can be searched using different matchers.

§Overview

use attribute_search_engine::*;
use std::collections::HashSet;

// Before we can create a new engine we need some indices.
let mut index_name = SearchIndexHashMap::<_, String>::new();
let mut index_age = SearchIndexBTreeRange::<_, u8>::new();
let mut index_address = SearchIndexPrefixTree::<_>::new();

// We add two persons:
index_name.insert(0, "Alice".into());
index_age.insert(0, 27);
index_address.insert(0, "Germany/Hamburg".into());

index_name.insert(1, "Bob".into());
index_name.insert(1, "Bobby".into()); // One row can have multiple entries
index_age.insert(1, 25);
index_address.insert(1, "Germany/Berlin".into());

// Now we create the engine and add our indices to it:
let mut engine = SearchEngine::<usize>::new();
engine.add_index("name", index_name);
engine.add_index("age", index_age);
engine.add_index("address", index_address);

// We can create queries of any complexity with the Query type.
let q = Query::And(vec![
    Query::Or(vec![
        Query::Exact("name".into(), "Alice".into()),
        Query::Exact("name".into(), "Bob".into()),
    ]),
    Query::Prefix("address".into(), "Germany/".into()),
]);
assert_eq!(engine.search(&q), Ok(HashSet::from_iter(vec![0, 1])));

// The search engine also has the ability to parse strings into
// queries. Check the documentation of SearchEngine::query_from_str
// for more details. Parsed queries are by design a lot more limited
// then manually constructed queries. The construction of queries
// can fail for example if unknown indices are referenced.
let (q, _) = engine.query_from_str("+name:Alice +address:Germany/ -age:25").unwrap();
assert_eq!(engine.search(&q), Ok(HashSet::from_iter(vec![0])));

§Search Indices

A SearchIndex saves the mapping from attribute values to primary IDs for a single attribute. These indices can then be searched using queries. If only a single attribute type is needed, a SearchIndex by itself may be enough. But normally they are added to a SearchEngine that can handle multiple indices and complex queries involving Or, And and Exclude queries.

This library provides the following types of search indices:

SearchIndexHashMap, backed by a HashMap for quick exact queries.
SearchIndexPrefixTree, backed by a prefix tree to find rows just by the prefix of an attribute.
SearchIndexBTreeRange, backed by a BTreeMap to find rows with an attribute by providing a range.

The SearchEngine can also work with custom search indices as long as they implement the SearchIndex trait.

§Queries

Queries are used to find rows in a SearchIndex or SearchEngine. Query is an enum type that defines different search behaviours. Not all Query variants are supported by all index types. Queries can be crafted manually without restrictions or with some limits from a string using a SearchEngine.

The following table shows which Query variant is supported by which index type.

Query	SearchIndexHashMap	SearchIndexPrefixTree	SearchIndexBTreeRange
Exact	Yes ✔️	Yes ✔️	Yes ✔️
Prefix	No ❌	Yes ✔️	No ❌
InRange	No ❌	No ❌	Yes ✔️
OutRange	No ❌	No ❌	Yes ✔️
Minimum	No ❌	No ❌	Yes ✔️
Maximum	No ❌	No ❌	Yes ✔️
Or	na¹ 🔷	na¹ 🔷	na¹ 🔷
And	na¹ 🔷	na¹ 🔷	na¹ 🔷
Exclude	na¹ 🔷	na¹ 🔷	na¹ 🔷

§Query String Syntax

The SearchEngine provides the function query_from_str that can be used to create queries from strings. They are much more limited than manually crafted queries but should be powerful enough for most use cases.

The following text is an example for a query:

+attr1:foo,bar +attr2:=baz +attr3:<42,>84 -attr4:69-121

As a boolean expression it will mean something like this:

   (attr1==foo || attr1==bar)
&& (attr2==baz)
&& (attr3 <= 42 || attr3 >= 84)
&& !(69 <= attr4 <= 121)

Are more in-depth description of the query syntax can be found in the documentation of the SearchEngine::query_from_str function.

Or, And & Exclude are only supported by SearchEngine and not the indices. ↩

Structs§

SearchEngine: A SearchEngine is a wrapper around a collection of search indices that can process complex queries involving multiple indices.
SearchIndexBTreeRange: SearchIndexBTreeRange is a index backed by a BTreeMap that can match Exact, InRange, OutRange, Minimum and Maximum queries.
SearchIndexHashMap: SearchIndexHashMap is a index backed by a HashMap that can match Exact queries.
SearchIndexPrefixTree: SearchIndexPrefixTree is a index backed by a prefix tree that can match Exact and Prefix queries. It can only store String attribute values.

Enums§

Query: Query is a recursive datatype that describes a query to a search index or engine.
SearchEngineError: Enum of all possible error types that the attribute search engine can throw by itself.

Constants§

SUPPORTS_EXACT: Signals that an index supports Exact queries.
SUPPORTS_INRANGE: Signals that an index supports InRange queries.
SUPPORTS_MAXIMUM: Signals that an index supports Maximum queries.
SUPPORTS_MINIMUM: Signals that an index supports Minimum queries.
SUPPORTS_OUTRANGE: Signals that an index supports OutRange queries.
SUPPORTS_PREFIX: Signals that an index supports Prefix queries.

Traits§

SearchIndex: This trait describes the minimum features an Index must support to be usable as a SearchIndex, for example in a SearchEngine.

Type Aliases§

Result: Common Result type for the attribute search engine.
SupportedQueries: Bitmask type for queries that are supported by an index.

Crate attribute_search_engineCopy item path