Skip to main content

FulltextEngine

Trait FulltextEngine 

Source
pub trait FulltextEngine {
    type Options;
    type SearchOptions;
    type Error;
    type Score: PartialOrd;
    type Address;
    type Connection;
    type WriteBuffer: ColumnWriter;
    type ReadBuffer: ColumnReader<Error = Self::Error>;

    // Required methods
    fn buffer() -> Self::WriteBuffer;
    fn finalize(buf: Self::WriteBuffer) -> Self::Address;
    fn open(address: Self::Address) -> Self::ReadBuffer;
}
Expand description

A full-text index (Tantivy, an FTS5 virtual table, a Postgres tsvector column) — R-FREE.

It names no record, no key and no document type of the declaration’s. What crosses it is the engine’s OWN vocabulary: an Address it addresses entries by, a Score it ranks them in, and the Doc its write face builds them in. The TYPING is the emission’s — the declaration flattens its record into the Doc, reports its id and its key as COLUMNS, and reads a hit’s Address back into its own key type. This trait says what an engine SPEAKS, and it says it with no opinion about what an entry means.

§It is the BASE, and a base has no verbs

What lives here is that vocabulary together with the ADDRESS LIFECYCLE that turns a key into one of this engine’s addresses and back. The verbs are on the four faces (FulltextRead / AsyncFulltextRead, FulltextWrite / AsyncFulltextWrite), each naming this trait as a supertrait and each holding the LEASE its own direction spends.

So a bound asks for exactly the half it uses. A query type that only spells an Address and a Score binds THIS and inherits no search; a retrieve binds a read face; a drainer binds a write one; and an engine that only reads — a snapshot, a replica, a served index — is spellable, which it was not while one trait carried every verb.

THERE IS NO GAT LEFT HERE. Both leases moved onto the faces that spend them, so nothing a query type or a walk binds carries borrowing machinery, and the read/write scopes are free to be two different types on the two modes — an async transaction ticket is not a blocking searcher’s.

§Why the record parameter went, and what it was costing

FulltextDb<R> carried the record so its signatures could project R::Key, R::Document and R::Id. Three prices came with it, all of them paid by callers rather than by backends:

  • The ORPHAN WALL. A record-generic engine trait needs a per-engine bound on what it addresses entries by (R::Id: TantivyKey), and that bound is a trait over FOREIGN types, so every member of the id vocabulary had to be implemented FROM this crate — impl TantivyKey for i64 in a declaring crate is E0117. The COLUMN LANGUAGE takes the axis away entirely: a key’s row (Field) names no engine at all, so there is nothing left for an orphan rule to be about.
  • An unrequirable bound in an expansion. A method-level where R: … that an expansion cannot satisfy is E0277 — add #![feature(trivial_bounds)] — at a span the declaration’s author cannot edit. An R-free seam has no such where to satisfy.
  • Inference. Every call had to name the record (FulltextDb::<Caption>::search(…)) because a query string names no record — E0284 otherwise. There is nothing left to name.

§THE ADDRESS LIFECYCLE — three functions, and the phase each one ends

An address is a KEY’S IDENTITY in this engine’s own vocabulary, and it is built and read in phases that cannot be confused for one another:

buffer() ─► WriteBuffer ─(the key reports its columns)─► finalize(buf) ─► Address
Address ─► open(address) ─► ReadBuffer ─(the key takes its columns)─► ColumnReader::finish

WriteBuffer is a ColumnWriter and ReadBuffer is a ColumnReader, so what crosses between a key and an engine is TYPED COLUMNS — never an intermediate encoding both sides then decode. That is what makes a key’s row engine-blind and costs a new engine no row at all.

All three are ASSOCIATED FUNCTIONS rather than methods: minting a buffer, sealing it and opening an address ask nothing of a handle, so E::open(…) is spellable wherever E is — which is what keyed, the framework’s full-text read walk, needs of it. The WRITE half has no framework walk of its own yet, for the reason retrieve::address’ module doc states: this family’s by-key read has no grammar, so the only caller that builds an address is a backend’s own entry builder, spelling the three phases where the engine is concrete.

§THE SAME-BYTES LAW

The column sequence a key reports into a WriteBuffer is the sequence it takes back off the ReadBuffer open mints from the finished address. An address built by the write walk and an address a hit arrives under are THE SAME BYTES for the same key, which is the whole correspondence a keyed replace stands on.

§SearchOptions and the LEASE are two different seats, and only one of them is here

SearchOptions is the BACKEND’s own per-query knobs and stays on the base because a wire face carries it: an emitted engine variant’s options row is typed on it, so the type must be nameable from a bound that spends no verb. The LEASE is the half a request cannot carry — a committed snapshot, a reader’s ticket — and it went with the verbs, onto FulltextRead::ReadContext and its three siblings.

§What is NOT here, and where each of them went

put/get stay the ARTIFACT family’s own. A blob store derives nothing and holds no index: it is handed a key and gives bytes back, so its verbs name a store rather than a replace.

The write is also NOT the socket a storing node writes through — see AsyncLands. That is one layer up, it answers per ITEM rather than per entry, and the layering is the whole reason there are two names: a lane IMPLEMENTS the socket and CALLS the face’s verb. Two parallel write verbs at one layer would be the duplication that arrangement exists to refuse.

Required Associated Types§

Source

type Options

PER-SLOT CREATION INPUT — the knobs an author states for ONE home this engine makes.

§It has a spender now, and the spender is LAYER TWO

The seat was reserved and honest about being reserved: a reserved extension point, () where a backend needs none. What it was waiting for is the initialization walk. A slot maker CREATES the home a blueprint describes, and the half of that description a DECLARATION cannot state is the deployment’s — a tokenizer, an analyzer chain, an ef, a replication factor. Those arrive at BOOT and belong to nobody but the engine, so the walk’s own per-slot table is typed on this member and the value crosses at the store’s own create_slot door, one per corpus — see the shipped tantivy backend, where the first one is written.

§Why it is not on the blueprint

A Describe blueprint is a const, so a descriptor built per boot is a schema that could differ between two of them. A knob a document decides is exactly such a value, which is why it lives on the VISITOR — see Habitat, where the split is written down.

§() where a backend needs none

Still the shipped answer, and the reservation still buys what it bought: adding the member LATER would break every engine impl there is, and adding a value to it now is purely additive.

Source

type SearchOptions

PER-QUERY tuning — the knobs one search runs under, in this engine’s own vocabulary. () where a backend has none.

VectorEngine::SearchOptions carries the whole argument — the same three divisions (against Options, which is spent once at construction; against FulltextRead::ReadContext, which is a scope a request cannot carry; and the third party’s wire duty at the emitted options row) — and this face states it in the vocabulary a full-text engine tunes in: an analyzer choice, a per-field boost, a fuzziness, a conjunction default.

The SHIPPED engine answers () — see TantivyFulltext for the measurement, which found exactly one per-query knob and found it to be a UNIVERSAL one.

Source

type Error

This backend’s failure — ONE error for the engine, whatever raised it.

It is the read phase’s error too: ReadBuffer is tied to it (ColumnReader<Error = Self::Error>), so a column a key could not take and a search that could not run refuse in one type. That tie is what puts ColumnError on this member in practice — a ROW has refusals of its own and no way to name this type, so the floor is what lets it word them.

Source

type Score: PartialOrd

The currency search scores in — f32 for a BM25 engine, f64 for a face whose driver hands back double precision, a fused or composite shape for a layer that ranks rather than measures.

§PartialOrd and nothing else, and the FLOOR is the site that bought it

The member was bound by NOTHING while nothing above the seam compared a score. That site now exists: every retrieve carries a MANDATORY minimum score, and the framework’s portable backstop compares each hit against it — see FulltextQuery. A comparison needs an ordering, so the contract grows the ordering and stops there.

PartialOrd rather than Ord: f32 is the currency the shipped engine scores in, and a total order would refuse it. What partiality costs is one decision, made once at the walk — a score that will not compare against the floor reads as below it, which is the conservative answer and the honest one.

Source

type Address

The engine’s OWN address vocabulary — what a key’s columns seal into on the way in, and what a hit’s stored address arrives as on the way out.

ONE type for both directions, because it is one correspondence: an address written by a key has to be readable by that same key’s type, and two members would let a backend supply one half and not the other — which is exactly how a stored address becomes unreadable by the code that wrote it.

OWNED, not a borrow of the engine’s buffers: a search hands these back inside the hits, so a borrowing form would tie every result to the searcher that produced it.

Source

type Connection

The shared connection-manager (the AsyncFulltextStore that opened it), reached via ctx.connection() — the slot’s index and its reader, held ONCE, not reopened per call. PLAIN, not a GAT.

Source

type WriteBuffer: ColumnWriter

THE WRITE PHASE — the buffer a key reports its columns into, before there is an address at all.

A ColumnWriter, so what it is handed is one TYPED column at a time and it lands each in whatever this storage natively has: a tantivy term, an FTS5 bound parameter, a tsvector literal. Nothing is encoded to a shared form on the way, which is the whole economy of the language.

Source

type ReadBuffer: ColumnReader<Error = Self::Error>

THE READ PHASE — the cursor an address is opened into, which a key takes its columns back off.

OWNED, with no lifetime of its own: it is minted by open from an address it CONSUMES, so it borrows nothing and a walk holding one is not tied to whatever the address came out of. That is what keeps the base free of GATs.

Its error IS this engine’s error, tied here rather than left to agree by convention: a column a key could not take and a search that could not run are one backend’s refusals, and a caller unwrapping the walk should not have two types to name.

Required Methods§

Source

fn buffer() -> Self::WriteBuffer

Open a WRITE PHASE — an empty buffer, positioned before the first column.

§NOT Self::WriteBuffer: Default, and the difference is a real one

A bound would have cost no function and would have been WRONG for a whole class of engine: an address that is a row id or a uuid has a Default that is a perfectly valid ADDRESS — row zero, the nil uuid — and a key reporting its columns into one would be appending to a location rather than starting at an empty one. The shipped engine’s own address is exactly that coincidence: TantivyAddress::default() is the empty byte string, which is what would have made the bound look right. A named function states the contract the bound could only imply.

The phase split makes that confusion unrepresentable rather than merely refused: what this mints is not an address and has no address’s type, so there is no empty address for an empty start to be mistaken for. What the argument still buys is the FUNCTION — an engine whose buffer is a handle, a pooled arena or a builder carrying schema is minting rather than defaulting.

Source

fn finalize(buf: Self::WriteBuffer) -> Self::Address

SEAL a write phase into the address its columns spell.

It CONSUMES the buffer, which is the typestate half of the same argument: a key that has reported itself is done reporting, so there is no buffer left beside the address for a second column to be appended to. What comes back is the engine’s own Address — the same bytes a hit for that key arrives under.

Source

fn open(address: Self::Address) -> Self::ReadBuffer

Open a READ PHASE over address — the cursor a key takes its columns back off.

BY VALUE. The address is consumed rather than borrowed, and that is the phase saying what it means: an address handed to this is being SPENT as one key’s identity, so there is no half-read address left behind for a second reader to start over on. It also frees the reader from the address’s storage — a buffer that wants to take the bytes rather than walk them may.

§The SURPLUS is asked at the other end, and it is the engine’s own fact

Whether the key took ALL of the columns is ColumnReader::finish’s question, asked once by the walk that owns the reader. A surplus is a fact about THIS ENGINE’s own vocabulary, which is why the engine answers it — tolerating one would let (7, 42) pose as the address of (7, 42, 3), a hit carrying the wrong entity, silently.

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementations on Foreign Types§

Source§

impl FulltextEngine for ()

The unused full-text face.

FULLY UNBOUNDED, which it was not before: the record-generic seam needed R: Transformer and R::Key: Send on the impl block, because the key rode search’s output and an RPITIT + Send return demanded it. An R-free seam projects nothing off anything, so the whole where clause is gone — the poverty dividend, visible as a deletion.

Every member is (): an address vocabulary with no values and a face with no scoring vocabulary, which is the honest answer for a store that never ranks anything.

The whole address lifecycle is the UNIT, in all three phases: the column language’s own unused pair (ColumnWriter for (), ColumnReader for ()) accepts every column and drops it, and refuses every read for the honest reason that nothing was ever landed. So Error = NoColumns rather than Infallible: the read phase is tied to this member, and a key asking a face that holds nothing for a column has to be answered. The face still cannot fail at a VERB — see the four face impls, every one of which answers.

Source§

type SearchOptions = ()

(), the seam’s own word for no per-query knobs — a face that searches nothing is tuned by nothing, and it is named by no declaration’s typed word, so no wire duty is owed.

Source§

fn finalize(_buf: Self::WriteBuffer) -> Self::Address

Address = (), so a sealed buffer IS the unit — a face that stores nothing addresses nothing, and () is the one value it can hand back.

Source§

type Options = ()

Source§

type Error = NoColumns

Source§

type Score = ()

Source§

type Address = ()

Source§

type Connection = ()

Source§

type WriteBuffer = ()

Source§

type ReadBuffer = ()

Source§

fn buffer() -> Self::WriteBuffer

Source§

fn open(_address: Self::Address) -> Self::ReadBuffer

Implementors§