Crate flusso_query

Expand description

flusso-query — a typed query client for a flusso-maintained search index.

Targets OpenSearch and Elasticsearch 7.x, which share the _search query DSL this crate emits; any future backend divergence is handled on the Client, not by separate crates.

This is the runtime layer described in CLIENT.md: the transport, the field-handle / Query / Search builder, and the typed SearchResponse. It is generic over the caller’s document type T.

§What this first cut covers

Client transport over OpenSearch (connect, basic_auth, search, msearch, get).
Field handles (Keyword, Text, Bool, Number, Date, Nested, Binary, Json) with operators that build a Query.
Query composition (and / or / not) and the Search bool-clause builder (query / filter / must_not / should, plus sort / from / size / raw). A Search is a plain client-free value — build it anywhere, store and reuse it; a Client appears only at the terminals: Search::send (a typed page), Search::ids (a page of bare document ids, _source: false), or Search::count (just the number of matches, via _count).
Several searches in one round-trip: Client::msearch (a tuple of &Search<T>, mixed document types, one typed response per slot) and Client::msearch_all (a slice of one type).
Combined (blended) search: FlussoMultiDocument — a caller-owned enum with one variant per document type — and its MultiSearch builder. One query across all the union’s indexes, one relevance-ranked result list, each hit decoded into the variant matching its physical _index.
Typed SearchResponse / Hit.

Also covered: optional filters (Option<Q> is a Query); object/to-one-join handles (Object); shaping returned nested arrays (Search::filter_nested with Nested::matching, via inner_hits); and scope-tagged queries — Query<S> carries the scope S it was built in (Root for the document root and flattened objects, the element type for a nested array), so a nested query must be lifted through Nested::any/Nested::all before it can join a root query; the compiler enforces it.

§Not yet built (see CLIENT.md for the endgame)

The #[derive(FlussoDocument)] and #[derive(FlussoMultiDocument)] proc-macros live in flusso-query-derive (the derive feature). Without them, document structs + handles and union impls are written by hand — exactly the calls this crate exposes (see the integration tests).
filter_nested’s keep_source() opt-out (it always replaces the array in source today) and a typed hit.nested(handle) accessor.

§Example (hand-written until the derive lands)

use flusso_query::{Client, Keyword, Number, Nested};

#[derive(serde::Deserialize)]
struct User {
    email: String,
    #[serde(rename = "orderCount")]
    order_count: i64,
}

impl User {
    fn email() -> Keyword { Keyword::at("email") }
    fn order_count() -> Number<i64> { Number::at("orderCount") }
    fn query() -> flusso_query::Search<User> {
        flusso_query::Search::new("users", "xxxxxx")
    }
}

// A query is a plain value — no client involved while building it.
let busy = User::query()
    .filter(User::email().eq("ada@example.com"))
    .filter(User::order_count().gte(5))
    .size(20);

// The client appears once, when it's time to run.
let client = Client::connect("https://localhost:9200")?;
let page = busy.send(&client).await?;
println!("{} matches", page.total);

Modules§

kind: Field-category markers for FlussoValue. Zero-size and uninhabited — they exist only as the K type parameter, so one type can be a valid value for several kinds (e.g. String is a kind::Keyword, kind::Text, and kind::Date value).

Structs§

Binary: A binary field — base64-encoded, not searchable. Only existence.
Bool: A boolean field.
BoostingQuery: A boosting clause.
Client: A connection to an OpenSearch cluster.
CombinedFieldsQuery: A combined_fields clause.
ConstantScoreQuery: A constant_score clause. Set the fixed score via boost.
Date: A date/timestamp field. Bounds are ISO-8601 strings.
DisMaxQuery: A dis_max clause.
DistanceFeatureQuery: A distance_feature clause.
EqQuery: An exact-match (term) clause for a non-string value (number, bool, date), carrying the universal boost / name modifiers.
FunctionScoreQuery: A function_score clause. Add functions with weight / function and tune combination with score_mode / boost_mode / max_boost / min_score.
FuzzyQuery: A fuzzy clause, with fuzziness / prefix_length / max_expansions / transpositions plus boost / name.
Geo: A geo_point field — distance, bounding-box, and polygon queries, plus sort-by-distance.
GeoDistanceQuery: A geo_distance clause: points within a radius of a center, with the distance_type / validation_method options plus boost / name.
GeoPoint: A geographic point — latitude/longitude in degrees.
Highlight: Match highlighting for a Search (the highlight block). Name the fields to highlight and tune the tags / fragments; pass it to Search::highlight.
Hit: One search hit: the typed document plus its envelope metadata.
IdsQuery: An ids clause.
Json: An untyped object/json field. The escape hatch: existence, or a raw clause spliced in verbatim.
Keyword: An exact, aggregatable string field (keyword, enum, uuid).
MatchQuery: A match-family clause (match, match_phrase, match_phrase_prefix, match_bool_prefix): the analyzed query value plus whichever options the kind supports, all written under the field as an object. The kind selects the wrapper and which setters are meaningful; unset options are simply omitted.
MoreLikeThisQuery: A more_like_this clause.
MultiMatchQuery: A multi_match clause: one analyzed query over several fields, with the type / operator / fuzziness / tie_breaker / minimum_should_match options plus boost / name.
MultiSearch: A typed query across every index of a FlussoMultiDocument union — the blended counterpart of Search, with the same clause builder and the same client-free shape.
Nested: A nested array of objects. E is the enclosing scope (where queries over this array land — Root at the top level, the parent element type when deeper); C is the child scope (the element type). Lifting a child query (Query<C>) through any/all produces a Query<E>.
NestedProjection: A request to shape one nested array in the results (via inner_hits).
NestedQuery: A nested clause (parents with a matching element), with the score_mode / ignore_unmapped options plus boost / name. E is the enclosing scope.
Number: A numeric field. T is the Rust scalar; S is the scope (defaults to Root, so Number<i64> is a root-scope handle).
Object: An object sub-document — a group or a to-one (belongs_to/has_one) join. Objects are flattened, so their sub-fields are queried by their own scope-S dotted-path handles directly (Account::tier()); this handle is for the object itself. S is the enclosing scope (Root at the top level).
PrefixQuery: A prefix clause, with case_insensitive / rewrite plus boost / name.
Query: A composable query clause in scope S.
QueryStringQuery: A query_string clause.
RangeQuery: A range clause with bounds plus the universal boost / name and the range-specific format / time_zone / relation modifiers.
RankFeatureQuery: A rank_feature clause.
RegexpQuery: A regexp clause, with case_insensitive / flags / max_determinized_states plus boost / name.
Root: The default query scope — the document root. Root fields and flattened object / to-one-join sub-fields share it.
ScriptQuery: A script clause.
ScriptScoreQuery: A script_score clause.
Search: A typed query against one index — a plain, client-free value.
SearchResponse: A page of search results.
SimpleQueryStringQuery: A simple_query_string clause.
Sort: A single sort key. Produced by .asc() / .desc() on a sortable handle, by Sort::score / Sort::script, or by Geo::distance_sort; chain the option setters (missing_first, mode, unmapped_type, …) onto it.
TermQuery: An exact-match (term) clause on a string field, with optional case_insensitive plus the universal boost / name.
TermsQuery: A multi-value (terms) clause, carrying boost / name. Shared by the keyword and numeric in_ operators.
Text: An analyzed full-text field (text, identifier). No exact eq.
WildcardQuery: A wildcard clause, with case_insensitive / rewrite plus boost / name.

Enums§

Error: Anything that can go wrong building a request, talking to OpenSearch, or decoding a response.
SortMode: How a multi-valued field collapses to one sort value.
SortOrder: Sort direction.

Traits§

AsQuery: Anything that can become a query clause in scope S. A clause may be absent (into_query returns None) — that’s what makes an Option<Query<S>> a first-class optional filter.
FlussoDocument: A document type bound to a flusso-maintained index — the trait that #[derive(FlussoDocument)] implements.
FlussoMultiDocument: A union of FlussoDocument types searched together — one query, one blended result list, each hit decoded into the variant matching its index.
FlussoValue: A Rust type usable where a field of kind K is expected: as the field type in a #[derive(FlussoDocument)] struct, and (for kind::Keyword) as a query value on Keyword::eq/Keyword::in_.
MsearchBundle: A bundle of searches runnable in one Client::msearch request — implemented for tuples of &Search<T> up to arity 8, each slot with its own document type. You don’t implement this; you pass tuples.

Functions§

boosting: Keep documents matching positive, but demote (don’t exclude) those that also match negative by negative_boost (0.0–1.0).
combined_fields: Term-centric full-text across several fields, treating them as one combined field (combined_fields).
constant_score: Wrap a filter so every match scores the same fixed boost (default 1.0).
dis_max: Score by the single best-matching clause, optionally crediting the others via tie_breaker.
distance_feature: Boost by proximity of a field (date or geo) to origin, decaying over pivot (distance_feature).
function_score: Recompute relevance for query via one or more scoring functions.
ids: Match documents by a list of _id values — typed get-many-by-id.
more_like_this: Find documents similar to like text(s) across fields (more_like_this).
multi_match: A cross-field full-text query over several Text fields in the same scope. Returns a MultiMatchQuery builder; weight individual fields with Text::boosted.
query_string: Full Lucene query-string syntax (power users; can error on malformed input). Target fields with default_field or fields.
rank_feature: Boost by a rank_feature / rank_features field’s stored value. The default saturation function applies unless one is chosen.
script: Keep documents for which a painless source returns true (a non-scoring filter).
script_score: Recompute query’s score with a painless source (script_score).
simple_query_string: Lenient search-bar syntax over chosen fields — never errors on bad input.

Type Aliases§

Result: A Result whose error is this crate’s Error.