How to Use Infino: The Beginner's Guide

CodexFuse Team · 2026-11-03T17:51:27.437Z · 12 min read min read

If you are building an AI agent that needs to remember things — support docs, chat history, product catalogs, code — you need retrieval: keyword search for exact terms, vector search for meaning, and SQL for filtering and joins. Learning how to use Infino is the fastest route I know to all three in one place. Infino (infino.ai) is an open-source retrieval engine that keeps one copy of your data as Apache Parquet files — on local disk or S3 — and runs full-text (BM25), vector, hybrid, and SQL search over those same rows from a single embedded library. There is no server to run and no cluster to operate. You can even poke the live read-only sandbox with a REST API tester before installing anything. For a related take on search built for coding agents, see the xerj beginner guide.

What Is Infino, Exactly?

Infino is an open-source (Apache-2.0) embedded retrieval library for AI agents. It stores your data once as Parquet files and lets you search those same rows with keyword search, vector search, hybrid search, and SQL — no separate search cluster, vector database, and warehouse. Its tagline from the November 2026 Product Hunt launch says it plainly: "Search, vectors and SQL over one Parquet copy, for agents." The core engine is written in Rust with Python and Node bindings; the GitHub repo (infino-ai/infino) had 145 stars and 27 forks as of November 3, 2026, with release v0.11.20 published that same day.

One important disambiguation, said once and early: the Infino in this guide is the retrieval engine at infino.ai — install it with pip install infino, built by the infino-ai GitHub org. A different product called infino-sdk ships from a separate company (the infinohq GitHub org): it is a query layer that talks to Elasticsearch, OpenSearch, and Snowflake in place, using access keys and secret keys against api.infino.ws. If your code connects to api.infino.ws, that is the other product — not this one.

How Does Infino Work Under the Hood?

Infino keeps one copy of your data in standard Parquet files, with BM25 and vector indexes stored inside those same files — then every query mode reads from that one copy. The vendor calls the unit a "superfile": a single Apache Parquet file with embedded BM25 and vector (IVF + RaBitQ) indexes spliced in. It is immutable once written, and it is still a valid Parquet file, so anything that reads Parquet can read your data. That last part is the exit strategy built into the format: the pricing FAQ states that DuckDB, pandas, and Spark keep opening your tables after the last Infino process shuts down. A DuckDB beginner guide is the natural companion if you want to inspect those files yourself.

The engine runs in-process as an embedded library — the PyPI description is explicit that there is no daemon, no cluster, and no managed service to operate. The vendor's core model for it: "one Parquet copy, indexed and queried four ways."

How Do I Install Infino?

Installation is a single package-manager command in every supported language. There is no server process to start afterward — the engine lives inside your program.

1. Python: pip install infino (or uv pip install infino). Requires Python 3.9 or newer. Version 0.11.17 was current on PyPI as of November 3, 2026; the license is Apache-2.0, and the repo's LICENSE file is the standard text unmodified, per the vendor's pricing FAQ.
2. Node: npm install @infino-ai/infino. Requires Node 18 or newer; examples use ESM import, so your file must be a module.
3. CLI: brew install infino-ai/tap/infino-cli on macOS/Linux, npm install -g @infino-ai/infino-cli (or npx @infino-ai/infino-cli), the shell installer from the infino-cli releases page, or cargo install infino-cli.
4. Rust: cargo add infino.

How Do I Build My First Infino Table?

The quickstart arc from the official docs takes about five minutes and teaches the whole mental model — it is the core of how to use Infino day to day. Follow it in order; each step builds on the one before.

1. Connect. db = infino.connect("memory://") opens an in-memory database for experiments. Point the same call at "./data" for local persistence, "s3://bucket/prefix" for durable object storage, or "https://<host>/<database>" plus an API key for Infino Cloud.
2. Declare the schema and indexes. docs = db.create_table("docs", schema, infino.IndexSpec().fts("body").vector("embedding", 16, "cosine")) — this puts a full-text index on the text column and a vector index on the embedding column. Vector dimensions must be in the range 16 to 4096.
3. Append rows. docs.append([...]) — one append is one atomic commit. When the call returns, the rows are searchable and committed; an independent dev.to benchmark specifically verified this behavior.
4. Search four ways. The same table answers docs.bm25_search("body", "cancel subscription", 5), docs.vector_search("embedding", my_vector, 5), docs.hybrid_search("body", "cancel subscription", "embedding", my_vector, 5), and db.query_sql("SELECT body FROM docs WHERE source = 'help-center'").
5. Go further. Use the CLI (table create, row insert, query) for terminal work, or the MCP server to hand the whole thing to an AI agent — both covered below.

What Are the Four Ways to Search in Infino?

Every table answers four query shapes, and the right choice depends on the question you are asking. This decision table is the one to bookmark:

How Does Infino Hybrid Search Work?

Infino hybrid search runs BM25 keyword search and vector search together and fuses the two rankings with reciprocal-rank fusion (RRF) in a single query — keyword precision plus semantic recall, one call. The vendor describes it as "RRF in one query, one pass": you don't run two searches and merge them in application code. This is the query mode to reach for whenever a user's question has both exact terms worth matching and meaning worth capturing — which, for agent retrieval, is most questions.

How Does Infino Parquet Vector Search Work?

Infino stores its vector index (IVF + RaBitQ quantization) inside the same Parquet file as your data — the "superfile" — so vector search runs over plain object storage with no separate vector database to operate. The vendor's comparison page states the indexing strategy as HNSW when the index is pinned in RAM, and OPANN + Sq16 on object storage. Because the index lives inside standard Parquet, there is no proprietary format to be locked into.

Independent numbers exist for this. A September 2026 dev.to benchmark by Ashish Mishra tested Infino's 4-bit quantized flat scan over 100,000 1,536-dimension OpenAI embeddings: recall@10 of 0.963 at p50 1.50 ms, against turbovec (0.948 / 1.59 ms) and FAISS flat PQ (0.950 / 45.5 ms), with a public repro repo at github.com/infino-ai/retrievalbench. A companion piece reported 0.99 recall@10 on Cohere-10M "with zero knobs touched." Treat these as third-party engineering measurements, not vendor marketing — and note the vendor's own ClickBench claim separately: "Filtered to the search engines on the board, Infino ranks #1 for SQL analytics (combined metric), ahead of Quickwit, Elasticsearch, SigLens and ParadeDB," a claim the vendor attributes to the public ClickBench board ("Run by ClickBench, not by us") with a November 2, 2026 snapshot.

How Do I Connect Infino to an AI Agent?

Point the Infino MCP server at your database and your agent gets keyword, semantic, hybrid, and SQL search as tools — over stdio, with no changes to the agent's code. The server package is @infino-ai/mcp-server; your MCP client launches it with npx -y @infino-ai/mcp-server and configures it through environment variables. It works with Claude Code, Claude Desktop, Cursor, VS Code, and any other MCP client — the Claude Code beginner guide covers the agent side if you are new to that tool.

The key settings are INFINO_MCP_URI — where the data lives (~/.infino/mcp by default, or a local path, s3://…, az://…, or an Infino Cloud URL with INFINO_API_KEY) — and INFINO_MCP_EMBED_MODEL, which defaults to Xenova/all-MiniLM-L6-v2 running locally on Hugging Face with no key. That second one is the beginner gotcha: the embed model must match the model that produced the table's stored vectors, or your rankings will be garbage. The server exposes ten tools — list/describe tables, keyword, semantic and hybrid search, token and exact match, count, SQL, table management, and document add/update/delete — and rows added without a vector get embedded from their text in one batch.

Two shortcuts make the agent connection nearly zero-config. The playground page publishes a read-only MCP config block (with the embed model pinned to Xenova/bge-small-en-v1.5, the model behind that corpus) so your agent can search the live arXiv-abstracts sandbox immediately. And infino skills install writes skill files to ~/.claude/skills so Claude Code and Cursor can drive the CLI itself in natural language.

Should I Self-Host Infino or Use Infino Cloud?

Start self-hosted and free: the Apache-2.0 engine runs embedded in your process or behind the CLI against local disk. Move to Infino Cloud when you want a managed database — it has a free tier, then pay-as-you-go, with no credit card to start, in the vendor's exact FAQ wording. The cloud meters storage, write tokens, read tokens, and returned bytes, plus an account minimum; numeric free-tier limits are not published, so don't plan around numbers you haven't seen. The console lives at platform.infino.ws, endpoints look like https://api.platform.infino.ws/<database>, and API keys begin with inf_. For compliance-sensitive teams, the vendor states Infino Cloud is SOC 2 Type II. All pricing facts here are as of November 3, 2026 — launch-era terms move fast, so re-check the pricing page before you commit.

Infino vs Qdrant: Which Should I Choose?

Choose Infino when vector search is one part of a broader retrieval workload and you want BM25, vectors, and SQL over the same rows in one engine. Choose Qdrant when you need a dedicated, clustered vector database and nothing else. The vendor's own comparison page lays out the differences:

The vendor's FAQ answers "Does Infino replace Qdrant or Pinecone?" with a flat "Yes." If you are migrating, their stated path is: export the vectors and the metadata you filter on, append them into Infino tables, dual-run, then move reads. The same vs-section covers Elasticsearch/OpenSearch, Postgres/ClickHouse, Snowflake/Databricks, and Iceberg/Hudi comparisons.

What Are the 5 Beginner Mistakes to Avoid?

These are the traps beginners actually fall into, drawn from the docs' own warnings and the two sourced gotchas:

Sources

Facts in this guide were verified on November 3, 2026 against: the Infino docs (quickstart, core concepts, CLI, and MCP integration pages at infino.ai/docs); the Infino playground's read-only sandbox (infino.ai/playground); the official PyPI JSON API for the infino package (version 0.11.17, Apache-2.0, Python ≥3.9); the GitHub API for infino-ai/infino releases (v0.11.20, published November 3, 2026); the Product Hunt launch listing ("Infino AI: Search, vectors and SQL over one Parquet copy, for agents," launched November 2, 2026); two independent dev.to engineering benchmarks (September 1 and August 7, 2026); and Infino's pricing, security, benchmarks, and vs/qdrant-pinecone pages. Pricing and version numbers are launch-era and move fast — re-check before you commit.

Frequently Asked Questions

Do I need to generate embeddings myself to use Infino?

With the SDK and CLI, yes — they never embed text for you, so you bring your own embedding model and pass vectors in. The MCP server is the exception: rows added without a vector get embedded from their text in one batch using its configured model. The quickstart's 16-dimension embed() helper is a toy stand-in so the example runs on its own; your own embeddings will be dense and higher-dimensional (the supported range is 16 to 4096 dimensions).

Is Infino really free?

The engine is Apache-2.0 open source and free forever when you self-host it. Infino Cloud adds a managed option with a free tier, then pay-as-you-go pricing, and no credit card required to start — but the vendor does not publish numeric free-tier limits, so verify the current terms on the pricing page before planning around them.

Is this the same Infino as infino-sdk on PyPI?

No. They are different products from different companies that share a name. infino-sdk (infinohq GitHub org) is a governed query layer that talks to Elasticsearch, OpenSearch, and Snowflake in place using access keys against api.infino.ws. This guide's Infino (infino-ai GitHub org, infino.ai) is the embedded Parquet retrieval engine — pip install infino, connect with infino.connect("memory://"), no credentials needed locally.

Does Infino replace Elasticsearch or Qdrant?

For combined keyword-plus-vector-plus-SQL workloads, the vendor's answer is yes — their FAQ says so directly. Keep Qdrant if you need a dedicated clustered vector database and nothing else; keep Elasticsearch if you depend on its text-analysis pipelines and ecosystem. Infino publishes migration guides for both, plus Postgres/ClickHouse, Snowflake/Databricks, and Iceberg/Hudi.

Can I read Infino's files with other tools?

Yes. The indexes live inside spec-compliant Parquet files, so DuckDB, pandas, and Spark open your tables normally after Infino stops. That is deliberate: your data is never locked into a proprietary engine format.