Crate infino

Expand description

§infino

infino is a fast retrieval engine that runs SQL, full-text (BM25), and vector search over a single copy of your data on object storage. Data stays in Parquet on S3 (or Azure, GCS, or local disk) and you query it at scale — embedded in your process, with no separate search server or vector database to run.

Speed per dollar — object-storage economics at search-engine speeds; on a 1-million-document index, warm BM25 queries return in the microsecond range.
Multi-modal queries — keyword (BM25), vector, and SQL over the same rows.
Object-storage-native — snapshot-isolated reads and atomic commits over S3, Azure, GCS, or local disk.
Open format, no lock-in — spec-compliant Parquet, so anything that reads Parquet can read your data.

§Install

cargo add infino

infino installs the mimalloc global allocator by default. If you embed infino in a process that already sets a global allocator, turn it off to avoid a second one: infino = { version = "0.1", default-features = false }.

§Quickstart

use std::sync::Arc;

use infino::arrow_array::{FixedSizeListArray, Float32Array, LargeStringArray, RecordBatch};
use infino::arrow_schema::{DataType, Field, Schema};
use infino::{connect, Bm25SearchOptions, BoolMode, IndexSpec, Metric, VectorFilter};

// Tiny stand-in for your embedding model so this runs as-is — a 16-dim
// one-hot by topic. Real embeddings are dense and higher-dimensional.
fn embed(topic: usize) -> Vec<f32> {
    let mut v = vec![0.0_f32; 16];
    v[topic] = 1.0;
    v
}

// A knowledge base your agent retrieves over. "memory://" is in-process;
// use "./data" or "s3://bucket/prefix" to persist.
let db = connect("memory://")?;

let item = Arc::new(Field::new("item", DataType::Float32, true));
let schema = Arc::new(Schema::new(vec![
    Field::new("source", DataType::LargeUtf8, false),
    Field::new("body", DataType::LargeUtf8, false),
    Field::new("embedding", DataType::FixedSizeList(item.clone(), 16), false),
]));
let docs = db.create_table(
    "docs",
    schema.clone(),
    IndexSpec::new().fts("body").vector("embedding", 16, Metric::Cosine),
)?;

let flat: Vec<f32> = [0usize, 0, 1].iter().flat_map(|&t| embed(t)).collect();
docs.append(&RecordBatch::try_new(
    schema,
    vec![
        Arc::new(LargeStringArray::from(vec!["help-center", "help-center", "blog"])),
        Arc::new(LargeStringArray::from(vec![
            "To cancel a subscription, open Settings then Billing.",
            "Refunds return to the original payment method.",
            "Enable dark mode under Settings then Appearance.",
        ])),
        Arc::new(FixedSizeListArray::new(item, 16, Arc::new(Float32Array::from(flat)), None)),
    ],
)?)?;

// Retrieve context to ground the agent's next answer:
let keyword =
    docs.bm25_search("body", "cancel subscription", 5, Bm25SearchOptions::new(), None)?;
let semantic = docs.vector_search("embedding", &embed(0), 5, None, None)?;
// hybrid: BM25 + vector, fused with reciprocal-rank fusion:
let hybrid = docs.hybrid_search(
    "body", "cancel subscription", BoolMode::Or,
    "embedding", &embed(0), 5, None,
)?;
// vector kNN, restricted to rows whose body matches a keyword (pushdown filter):
let filtered = docs.vector_search(
    "embedding", &embed(0), 5,
    Some(VectorFilter { column: "body", query: "billing", mode: BoolMode::Or }), None,
)?;
let billing = db.query_sql("SELECT body FROM docs WHERE source = 'help-center'")?;
assert_eq!(keyword.iter().map(|b| b.num_rows()).sum::<usize>(), 1);   // BM25
assert!(semantic.iter().map(|b| b.num_rows()).sum::<usize>() >= 1);   // vector kNN
assert!(hybrid.iter().map(|b| b.num_rows()).sum::<usize>() >= 1);     // hybrid (BM25 + vector)
assert_eq!(filtered.iter().map(|b| b.num_rows()).sum::<usize>(), 1);  // vector + keyword filter
assert_eq!(billing.iter().map(|b| b.num_rows()).sum::<usize>(), 2);   // SQL filter

§Operations

The public surface is a small connection-and-table API. Everything except the two entry-point functions is a method on one of two handles, so the operations live on the Connection and Supertable pages:

connect / connect_with open a Connection. The backend follows the URI scheme (s3://, az://, gs://, file://, bare path, memory://); credentials are passed via ConnectOptions::with_storage_option (object_store’s aws_* / azure_* / google_* keys), never read from the environment.
Connection — the catalog: create_table, open_table, drop_table, list_tables, and query_sql.
Supertable — a single table:
- Search — bm25_search, vector_search, hybrid_search, token_match, exact_match, and count. Each search returns Arrow rows as Vec<RecordBatch>.
- Write — append, update, delete.
- Maintain — optimize, gc, and schema.

Supporting types: IndexSpec, Metric, BoolMode, VectorFilter, ConnectOptions, MutationStats, GcReport, and the InfinoError, OptimizeError, and GcError error enums.

§Cargo features

default — enables the bundled mimalloc global allocator. Disable with default-features = false if your process already installs a global allocator.

§Other languages

infino also ships Python (pip install infino) and Node.js (npm install @infino-ai/infino) bindings. For concepts, guides, and multi-language examples, see the full documentation at infino.ai/docs.

Re-exports§

pub use arrow_array;
pub use arrow_schema;

Structs§

Bm25SearchOptions: Value types named by the public method signatures. Options for a BM25 search: the boolean mode and the corpus-statistics stats. Set fields with the with_* builders; Default is BoolMode::Or with Bm25Stats::PerSuperfile.
CompactionSettings: Compaction settings: target size, fill floor, and memory budget.
ConnectOptions: Catalog entry points and handle: open a Connection, then create / open / drop / list tables. Storage configuration for connect_with.
Connection: Catalog entry points and handle: open a Connection, then create / open / drop / list tables. A catalog connection. Cheap to clone (one Arc); clones share the same catalog.
GcReport: Outcome of a crate::Supertable::gc sweep: what was reclaimed and what was intentionally kept.
GcSettings: Gc settings used by optimize()’s bundled gc sweep.
IndexSpec: Catalog entry points and handle: open a Connection, then create / open / drop / list tables. Declares the search indexes to build over a table’s columns.
MutationStats: Per-call outcome from one delete / update. Returned by the public Supertable::update / Supertable::delete (which fold writer + commit) and carried, one per buffered mutation, in CommitResult.outcomes.
OptimizeOptions: Options for crate::Supertable::optimize.
Supertable: Single-table handle: append / update / delete / bm25_search / vector_search / schema. The public handle is the catalog wrapper, which serves a local or a hosted table behind one type; the engine’s concrete handle stays internal (reachable as supertable::Supertable only under test-helpers). A single-table handle: append / update / delete, the search surface (bm25_search / vector_search / hybrid_search / token_match / exact_match), count, schema, optimize, and gc. Cheap to clone (one Arc); clones share the same table.
VectorFilter: An optional text-predicate filter for vector kNN search. When supplied, kNN is ranked only among rows matching the predicate (pushdown, not post-filter). Built from an FTS-indexed column, a query string, and a BoolMode.

Enums§

Bm25Stats: Value types named by the public method signatures. Which BM25 collection statistics to score term rarity (idf) with across the superfiles a query fans out over.
BoolMode: Value types named by the public method signatures. Default operator for a query’s bare (sigil-less) terms. Terms carrying an explicit clause sigil keep their polarity regardless of mode: +term is a must (every hit contains it), -term a must-not (hard exclusion).
ColdFetchMode: Catalog entry points and handle: open a Connection, then create / open / drop / list tables. How a disk-cache miss is serviced when reading cold superfiles from object storage. The cache-servicing modes need a cache (ConnectOptions::with_cache_dir); RangeOnly is the cacheless path and does not currently use a disk cache.
Consistency: Read-path freshness policy — how an open handle picks up superfiles committed (by this or another process) after it opened.
GcError: Errors raised by crate::Supertable::gc.
InfinoError: The single public error type for the curated API. Coarse, stable error type returned by every public infino method.
Metric: Value types named by the public method signatures. Distance metric for a vector index. Stored per-column in inf.vec.columns JSON, applied at query time.
OptimizeError: Errors raised by crate::Supertable::optimize.

Constants§

BUILDER_ID: Compile-time-baked writer identification, written to inf.builder KV. Format: infino/<crate-version>+<git-short-hash>[-dirty], or …+unknown when built outside a git checkout (e.g. crates.io). Captured at build time by build.rs; not user-overridable.

Functions§

connect: Catalog entry points and handle: open a Connection, then create / open / drop / list tables. Open (or create) a catalog rooted at uri.
connect_with: Catalog entry points and handle: open a Connection, then create / open / drop / list tables. Open (or create) a catalog rooted at uri with explicit storage configuration (credentials / region / endpoint the URI can’t carry).

Crate infino

Crate infino Copy item path

§infino

§Install

§Quickstart

§Operations

§Cargo features

§Other languages

Re-exports§

Structs§

Enums§

Constants§

Functions§

Crate infino