API reference.

The full Python surface for Feather v0.10.0 — DB lifecycle, records, context graph, and search. For the v0.10 REST + Admin endpoints, see Cloud Edition → REST API.

Database

DB.open(filename, dim)

Opens an existing .feather file, or creates a new one at the given path. dim is fixed for the lifetime of the file.

from feather_db import DB
db = DB.open("vectors.feather", dim=384)

Parameters

filenamestrPath to the .feather file
dimintVector dimension (immutable after creation)

Records

db.add(id, vec, meta=None)

Insert a vector under a given entity ID. Reuse the same ID to update. Metadata carries importance, namespace, and arbitrary attributes.

from feather_db import Metadata

meta = Metadata()
meta.importance = 0.85
meta.set_attribute("type", "brief")

db.add(id=1001, vec=vector, meta=meta)

Parameters

idintEntity ID — reuse to update the vector in place
vecnp.ndarrayFloat32 array of length dim
metaMetadata?Optional metadata: importance, namespace, attributes

db.link(from_id, to_id, rel_type, weight=1.0)

Creates a typed, weighted edge between two records. The graph is bidirectional in the index but the edge itself is directional.

db.link(from_id=1001, to_id=1002, rel_type="informed_by", weight=0.9)

Parameters

rel_typestrEdge label — "informed_by", "contradicts", etc.
weightfloatEdge weight used during BFS traversal

Retrieval

BM25 Hybrid · since v0.8

db.hybrid_search(vec, query, k=10, rrf_k=60)

Fuses dense vector similarity with Okapi BM25 keyword matching via Reciprocal Rank Fusion — the same RRF formula used by Qdrant, Weaviate, and Elasticsearch. Inverted index is auto-built at load() from metadata content, fully backward-compatible with v3–v6 files.

# Hybrid — dense + BM25 fused via RRF
results = db.hybrid_search(
    vec=query_vec,
    query="adaptive memory decay",
    k=10,
    rrf_k=60,
)

# Or pure BM25 keyword search
results = db.keyword_search("adaptive memory decay", k=10)

Parameters

vecnp.ndarrayDense query vector (embedding)
querystrKeyword query — tokenized, stop-word filtered, lowercased
kintTop-k results after fusion
rrf_kintRRF damping constant. Default 60 — same as industry standard
filterSearchFilterOptional — namespace/entity/attribute filters apply to both dense and sparse legs

Added in v0.7.0

db.context_chain(query, k=5, hops=2)

Seeded semantic vector search, followed by N-hop BFS expansion across the typed graph. Returns the full context neighbourhood — not just nearest neighbours.

results = db.context_chain(query_vec, k=5, hops=2)

for r in results:
    print(r.id, r.score, r.meta.get_attribute("type"))

Parameters

querynp.ndarraySeed query vector
kintTop-k for the initial semantic search
hopsintBFS expansion depth across typed edges

db.search(query, k=10, filter=None)

Pure approximate nearest neighbour search. Use this when you just want top-k vectors without graph traversal. Combine with a FilterBuilder for multi-tenant workloads.

from feather_db import FilterBuilder

f = (FilterBuilder()
        .namespace("nike")
        .attribute("channel", "instagram")
        .importance_gte(0.5)
        .build())

results = db.search(query, k=5, filter=f)

Persistence

db.save()

Flushes the in-memory HNSW graph and metadata to the .feather file. Safe to call from a background thread.

Quickstart

Integrations