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 i64in a declaring crate isE0117. 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 isE0277— add#![feature(trivial_bounds)]— at a span the declaration’s author cannot edit. An R-free seam has no suchwhereto satisfy. - Inference. Every call had to name the record (
FulltextDb::<Caption>::search(…)) because a query string names no record —E0284otherwise. 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::finishWriteBuffer 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§
Sourcetype Options
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.
Sourcetype SearchOptions
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.
Sourcetype Error
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.
Sourcetype Score: PartialOrd
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.
Sourcetype Address
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.
Sourcetype Connection
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.
Sourcetype WriteBuffer: ColumnWriter
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.
Sourcetype ReadBuffer: ColumnReader<Error = Self::Error>
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§
Sourcefn buffer() -> Self::WriteBuffer
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.
Sourcefn finalize(buf: Self::WriteBuffer) -> Self::Address
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.
Sourcefn open(address: Self::Address) -> Self::ReadBuffer
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.
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 = ()
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
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.
type Options = ()
type Error = NoColumns
type Score = ()
type Address = ()
type Connection = ()
type WriteBuffer = ()
type ReadBuffer = ()
fn buffer() -> Self::WriteBuffer
fn open(_address: Self::Address) -> Self::ReadBuffer
Implementors§
Source§impl FulltextEngine for TantivyFulltext
Available on crate feature tantivy only.
impl FulltextEngine for TantivyFulltext
tantivy only.