Python API Reference

The BenoStreamDB Python package provides a high-level, Pandas-compatible interface for managing tables, executing hybrid searches, and integrating with data catalogs.

Table

class benostreamdb.Table(uri, inner_table=None, device=None, index_all=False, primary_key=None, explain=False)

Bases: object

BenoStreamDB Table — Apache Iceberg/Parquet-compatible columnar vector store.

Default behaviour (v0.4.1+)

• index_all = False — Vector indexes are not built automatically. Call table.index_all = True or table.add_index(column, 'hnsw') to enable indexing for a specific session or column.

• autocommit = False — Writes accumulate in an in-memory buffer. Call table.commit() (or await table.commit_async()) to persist data to Parquet and advance the Iceberg snapshot.

These defaults exist for performance: automatic indexing previously caused silent 15-18 s HNSW build latency on every commit() for tables with vector columns, even when the user had not requested an index.

Parameters:

• uri (str) – Table location (file:///path or cloud URI).

• inner_table (Table | None) – Internal — do not pass directly.

• device (Any | None) – Optional compute device for GPU-accelerated index builds.

• index_all (bool) – Enable automatic indexing of all compatible columns. Defaults to False. Set True to restore legacy behaviour.

• primary_key (str | None) – Column name (or list) to use as primary key.

• explain (bool) – If True, return query plans instead of results.

classmethod create(uri, schema, device=None)

Create a new table with an explicit schema.

Parameters:

• uri (str)

• device (Any | None)

Return type:

Table

classmethod create_partitioned(uri, schema, partition_spec, device=None)

Create a new table with an explicit schema and partitioning.

Parameters:

• uri (str)

• partition_spec (Dict[str, Any])

• device (Any | None)

Return type:

Table

classmethod register_external(uri, iceberg_metadata_uri, device=None)

Register an existing Iceberg table.

Parameters:

• uri (str)

• iceberg_metadata_uri (str)

• device (Any | None)

Return type:

Table

classmethod mount_external_iceberg(table_uri, overlay_storage_uri, device=None)

Mount an external, read-only Iceberg table with a detached overlay index catalog.

Parameters:

• table_uri (str)

• overlay_storage_uri (str)

• device (Any | None)

Return type:

Table

classmethod from_arrow(uri, table, device=None)

Create (and commit) a table at uri from a pyarrow Table, inferring the schema from the Arrow table.

The write-side complement of to_arrow() — together they form the Arrow interchange boundary for this table.

Parameters:

• uri (str)

• table (Table)

• device (Any | None)

Return type:

Table

classmethod from_pandas(uri, df, device=None)

Create a table at uri from a pandas DataFrame (via Arrow).

Parameters:

• uri (str)

• df (DataFrame)

• device (Any | None)

Return type:

Table

classmethod from_polars(uri, df, device=None)

Create a table at uri from a polars DataFrame (zero-copy Arrow).

Parameters:

• uri (str)

• df (DataFrame)

• device (Any | None)

Return type:

Table

property columns: List[str]

Return the list of column names in the table.

property schema

Return the table schema as PyArrow Schema.

property index_columns: List[str]

Return the columns that currently have an index configured.

Populated from the manifest on open, so a reopened table reports the indexes its segments were built with.

set_default_device(device)

Set the default device for index builds (e.g. "cpu" or "cuda").

Applies to columns without an explicit per-index device, including configs restored from the manifest on reopen.

Parameters:

device (str | None)

Return type:

None

personalized_pagerank(seeds, damping=0.85, alpha=None, iterations=30, directed=False, seed_weights=None)

Calculate Personalized PageRank (PPR) biased towards seed nodes. Supports both alpha (NetworkX convention) and damping parameter names. Optionally accepts continuous seed_weights (HippoRAG-style) to modulate teleportation probabilities.

Parameters:

• seeds (List[int])

• damping (float)

• alpha (float | None)

• iterations (int)

• directed (bool)

• seed_weights (List[float] | None)

subgraph(seeds, hops=1, directed=False, graph_column=None, allowed_relations=None, time_column=None, time_start=None, time_end=None, max_degree=None, max_nodes=None)

Extract multi-hop induced subgraph starting from seed nodes.

If graph_column is provided, uses the memory-mapped CSR graph index built on that column (the index’s source column) and returns a table of the induced edges with their payload columns. The CSR is forward-directed (out-neighbours); for directed=False a reverse CSR is used when the table has a graph index on the other endpoint column, otherwise the call transparently falls back to the SQL BFS path so undirected results are unchanged.

If allowed_relations is provided, filters edge traversals to only the specified relations/predicates. If time_column/time_start/time_end are provided, filters edges by timestamp window.

max_degree enables max-degree truncation on the CSR fast path: any node whose degree exceeds this threshold (e.g. Wikipedia “super-nodes” such as United States) is reported but not expanded, bounding the frontier explosion at each hop. It is ignored by the SQL BFS fallback.

max_nodes is a hard token-budget cap on the total visited set (seeds included) on the CSR fast path: once reached, expansion stops. Unlike max_degree it bounds memory regardless of graph density. It is ignored by the SQL BFS fallback.

Parameters:

• seeds (List[int])

• hops (int)

• directed (bool)

• graph_column (str | None)

• allowed_relations (List[str] | None)

• time_column (str | None)

• time_start (str | None)

• time_end (str | None)

• max_degree (int | None)

• max_nodes (int | None)

connecting_paths(seeds, directed=False, max_depth=None, graph_column=None)

Extract pairwise shortest connecting paths between seed nodes. Auto-routes to the memory-mapped CSR graph index fast path when available, falling back to SQL BFS otherwise. Returns ConnectingPathsResult (iterable list of (u, v) tuples with .to_pandas()).

Parameters:

• seeds (List[int])

• directed (bool)

• max_depth (int | None)

• graph_column (str | None)

Return type:

ConnectingPathsResult

louvain_communities(resolution=1.0)

Run Louvain community detection returning community groupings. Returns Arrow Table / DataFrame with ‘community’ column (lists of node IDs).

Parameters:

resolution (float)

Return type:

Any

leiden_communities(resolution=1.0)

Run Leiden community detection returning community groupings.

Leiden adds a connectivity-refinement phase on top of Louvain’s greedy modularity local move, so every returned community is internally connected. Returns Arrow Table / DataFrame with a ‘community’ column (lists of node IDs).

Parameters:

resolution (float)

Return type:

Any

communities(resolution=1.0, algorithm='leiden', graph_column=None)

Run community detection with a selectable algorithm.

Parameters:

• resolution (float) – Modularity resolution parameter.

• algorithm (str) – ‘leiden’ (default) or ‘louvain’. Leiden guarantees connected communities; Louvain is faster.

• graph_column (str | None) – Optional CSR graph column. When given — or when the table already has a graph index on source — community detection runs over the memory-mapped CSR, keeping only O(V) state resident instead of buffering every edge in RAM. Falls back to the SQL UDAF when no CSR is available.

Return type:

Any

update_communities(previous=None, resolution=1.0, algorithm='leiden', graph_column=None)

Recompute communities, preserving stable community IDs across updates.

Parameters:

• previous (Any | None) – The result of a prior call (a DataFrame or pyarrow Table with community_id and community columns). Communities that do not change keep their IDs. When None, a full computation assigns IDs 0..n-1.

• resolution (float) – Modularity resolution parameter.

• algorithm (str) – ‘leiden’ (default) or ‘louvain’.

• graph_column (str | None) – Optional CSR graph column (defaults to ‘source’ when a graph index exists).

Returns:

pyarrow Table / DataFrame with community_id and community (list of node IDs) columns. Warm-starting works with a persisted graph index and, for edge tables without one, by building a temporary CSR on disk — so IDs stay stable either way.

Return type:

Any

degree_centrality()

Calculate degree centrality for all nodes in the edge table. Returns Arrow Table / DataFrame with ‘node’ and ‘degree’ columns.

Return type:

Any

execute_sql(query)

Execute an arbitrary SQL query against this table (registered as ‘t’) using DataFusion, with full access to vector and graph aggregate UDFs.

Parameters:

query (str)

Return type:

Any

pagerank(damping=0.85, iterations=30)

Calculate PageRank for all nodes in the edge table. Returns Arrow Table / DataFrame with ‘node’ and ‘pagerank’ columns.

Parameters:

• damping (float)

• iterations (int)

Return type:

Any

shortest_path(start_node, end_node, directed=True, graph_column=None)

Find the shortest path between two nodes using BFS. Auto-routes to the memory-mapped CSR graph index fast path when available, falling back to SQL BFS otherwise. Returns a PathResult which behaves both as a list of node IDs and as a Table/DataFrame with .to_pandas().

Parameters:

• start_node (int)

• end_node (int)

• directed (bool)

• graph_column (str | None)

Return type:

PathResult

connected_components()

Find weakly connected components in the graph. Returns Arrow Table / DataFrame with ‘component’ column (component ID per node).

Return type:

Any

strongly_connected_components()

Find strongly connected components in a directed graph (Tarjan’s algorithm). Returns Arrow Table / DataFrame with ‘scc_id’ column.

Return type:

Any

topological_sort()

Topological ordering of nodes in a directed acyclic graph (DAG). Returns Arrow Table / DataFrame with ‘node’ column in topological order.

Return type:

Any

graph_neighbors(node, hops=1, graph_column=None, max_degree=None, max_nodes=None)

Find all nodes reachable from node within hops steps. Auto-routes to the memory-mapped CSR graph index fast path when available, falling back to SQL BFS otherwise. Returns GraphNeighborsResult (iterable list of neighbor IDs with .to_pandas()).

Parameters:

• node (int)

• hops (int)

• graph_column (str | None)

• max_degree (int | None)

• max_nodes (int | None)

Return type:

GraphNeighborsResult

subgraph_nodes(seeds, hops=1, directed=False, graph_column=None, max_degree=None, max_nodes=None)

Return the BFS visited node IDs reachable from seeds within hops, without materializing the induced edges.

Same traversal as subgraph (CSR fast path, else frontier SQL BFS). Use this to compute a neighbourhood set without loading millions of edges into memory — Graph RAG’s local mode does exactly this.

Parameters:

• seeds (List[int])

• hops (int)

• directed (bool)

• graph_column (str | None)

• max_degree (int | None)

• max_nodes (int | None)

Return type:

List[int]

subgraph_edges(seeds, hops=1, directed=False, max_degree=None, max_nodes=None, graph_column=None)

Extract the induced subgraph edges around seed nodes within hops. Zero-copy CSR fast path when index is present, falling back to SQL BFS. Returns ConnectingPathsResult (iterable list of (u, v) tuples with .to_pandas()).

Parameters:

• seeds (List[int])

• hops (int)

• directed (bool)

• max_degree (int | None)

• max_nodes (int | None)

• graph_column (str | None)

Return type:

ConnectingPathsResult

regional_drift_search(query, seeds, top_k=5, hops=1, n_depth=1, k_followups=2, mode='auto')

Experimental. Execute regional DRIFT search around query seeds over this edge table.

Regional DRIFT is a BenoStreamDB-specific variant. The standard GraphRAG DRIFT search is global — see drift_search() and graph_rag_search() with mode="global". This regional form restricts the traversal to the hops-neighborhood of seeds and is kept for experimentation; prefer the global search for production use.

mode selects the graph backend:

• "auto" (default): in-memory when the regional subgraph fits the DRIFT memory budget (BSDB_DRIFT_MEMORY_MB, else the derived budget), else out-of-core.

• "in_memory": materialize the regional subgraph (fastest per hop).

• "out_of_core": walk the mmap CSR directly (no materialization).

• "cached": CSR backing with a bounded in-memory neighbor cache.

Parameters:

• query (str)

• seeds (List[int])

• top_k (int)

• hops (int)

• n_depth (int)

• k_followups (int)

• mode (str)

Return type:

Dict[str, Any]

find_entities(query, limit=10, text_column='title', id_column='id')

Fast entity lookup by exact or partial string matching. Uses full-text search index if present on text_column, otherwise SQL ILIKE.

Parameters:

• query (str)

• limit (int)

• text_column (str)

• id_column (str)

Return type:

Any

lookup_entities(ids, text_column='title', id_column='id')

Fast bulk entity resolution by ID list. Returns a dictionary mapping id -> name.

Parameters:

• ids (List[int])

• text_column (str)

• id_column (str)

Return type:

Dict[int, str]

label_propagation_communities()

Run Label Propagation community detection. Returns Arrow Table / DataFrame with ‘community’ column.

Return type:

Any

modularity()

Calculate Newman’s modularity score for the current community assignment. Requires ‘source_community’ and ‘target_community’ columns in the edge table.

Return type:

Any

adamic_adar(node1, node2)

Calculate Adamic-Adar link prediction score between two nodes. Higher scores indicate more common neighbors with low degree.

Parameters:

• node1 (int)

• node2 (int)

Return type:

Any

preferential_attachment(node1, node2)

Calculate Preferential Attachment link prediction score between two nodes. Score = degree(node1) * degree(node2).

Parameters:

• node1 (int)

• node2 (int)

Return type:

Any

resource_allocation(node1, node2)

Calculate Resource Allocation Index between two nodes. Sum of 1/degree(w) for each common neighbor w.

Parameters:

• node1 (int)

• node2 (int)

Return type:

Any

resource_allocation_index(node1, node2)

Alias for resource_allocation().

Parameters:

• node1 (int)

• node2 (int)

Return type:

Any

jaccard_coefficient(node1, node2)

Calculate Jaccard coefficient between the neighbor sets of two nodes. Returns |N(u) ∩ N(v)| / |N(u) ∪ N(v)|.

Parameters:

• node1 (int)

• node2 (int)

Return type:

Any

clustering_coefficient()

Calculate the local clustering coefficient for each node. Measures how clustered each node’s neighborhood is (ratio of triangles to possible triangles). Returns Arrow Table / DataFrame with ‘node’ and ‘clustering_coefficient’ columns.

Return type:

Any

to_graphviz()

Export the edge table as a Graphviz DOT string. Returns Arrow Table / DataFrame with a single ‘dot’ column containing the DOT representation.

Return type:

Any

export_graph_gml(filepath)

Export the edge table to a GML format file. Iterates over the underlying PyArrow data in batches.

Parameters:

filepath (str)

export_graph_graphml(filepath)

Export the edge table to a GraphML format file.

Parameters:

filepath (str)

graph_density()

Calculate graph density: 2|E| / (|V| x (|V| - 1)) for undirected graphs. Returns a float in [0.0, 1.0] where 1.0 is a complete graph.

Return type:

float

avg_path_length(sample_size=100, graph_column=None)

Estimate the average shortest path length by BFS from a sample of nodes. Uses the CSR graph index when graph_column is given (or when the table has one on ‘source’), else the SQL shortest_path UDF, on sampled node pairs. Returns the mean path length across sampled reachable pairs.

Parameters:

• sample_size (int)

• graph_column (str | None)

Return type:

float

export_subgraph(seeds=None, hops=2, format='graphml', output_path=None, node_labels=None)

Export a subgraph for visualization and interop with external graph tools.

Parameters:

• seeds (List[int] | None) – Starting node IDs (None = export entire graph).

• hops (int) – Neighborhood depth from seeds.

• format (str) – Output format (‘graphml’, ‘json_ld’, ‘dot’, ‘edge_list’).

• output_path (str | None) – File path to write output (None = return as string).

• node_labels (Table | None) – Optional Table to enrich nodes with metadata.

Returns:

Serialized graph as a string.

Return type:

str

graph_rag_search(query, edge_table=None, doc_table=None, mode='local', vector_column='embedding', id_column=None, top_k=5, hops=2, alpha=0.85, directed=False, resolution=1.0, community_table=None, max_nodes=50, device=None, allowed_relations=None, seed_weights=None, search_edges=False, edge_vector_column='embedding', time_column=None, time_start=None, time_end=None, max_degree=None, traversal_max_nodes=None, community_algorithm='leiden', llm_router=None, relevance_threshold=0.0, rerank_vector=False, rerank_k=None, embed=None)

Execute end-to-end Graph RAG search combining vector retrieval and topological graph reasoning.

Supports two search paradigms: - Local Search (mode=’local’):

1. Discovers seed entities using vector/keyword similarity on doc_table (and optionally edge_table if search_edges=True).

2. Extracts multi-hop induced subgraph from edge_table around seed entities (optionally filtered by allowed_relations).

3. Computes Personalized PageRank (PPR) rooted at seeds with continuous seed weights (HippoRAG-style) for topological grounding.

4. Retrieves enriched context documents sorted by PageRank score.

• Global Search (mode=’global’): 1. Detects communities in edge_table via multi-resolution Louvain clustering (or uses community_table). 2. Evaluates community relevance against query seeds and graph centrality. 3. Synthesizes macro-level corpus context across top communities.

Parameters:

• query (List[float] | str) – Query vector (List[float]) or keyword text string.

• edge_table (Table | None) – Edge table containing graph topology. Defaults to self if self.is_edge_table().

• doc_table (Table | None) – Document/entity table. Defaults to self if not an edge table.

• mode (str) – ‘local’ (seed discovery + subgraph + PPR) or ‘global’ (community clustering + synthesis).

• vector_column (str) – Name of vector/embedding column in doc_table.

• id_column (str | None) – Name of node/entity ID column in doc_table. If None, auto-detected.

• top_k (int) – Number of seeds (local mode) or top communities (global mode) to retrieve.

• hops (int) – Max hops for multi-hop induced subgraph extraction.

• alpha (float) – Personalized PageRank restart probability (default 0.85).

• directed (bool) – Whether graph traversal is directed.

• resolution (float) – Louvain modularity resolution parameter (global mode).

• community_table (Table | None) – Optional pre-computed materialized community Iceberg table.

• max_nodes (int) – Maximum number of enriched nodes to return.

• device (Any | None) – Optional compute device.

• allowed_relations (List[str] | None) – Optional list of relationship types to restrict subgraph exploration.

• seed_weights (List[float] | None) – Optional explicit continuous seed weights for HippoRAG-style PPR.

• search_edges (bool) – If True, executes Dual Vector-Graph RAG by searching edge embeddings in parallel.

• edge_vector_column (str) – Embedding column name in edge_table when search_edges=True.

• max_degree (int | None) – Optional out-degree cap for the CSR subgraph fast path. Nodes above the cap (Wikipedia “super-nodes”) are reported but not expanded, preventing the 2-hop frontier from exploding to tens of millions of rows. Ignored when the SQL BFS fallback is used (relation/time filters).

• traversal_max_nodes (int | None) – Optional hard token-budget cap on the total visited set during subgraph extraction (seeds included). Once reached, the CSR traversal stops expanding. Unlike max_degree it bounds memory regardless of graph density. Distinct from max_nodes, which caps the number of enriched nodes returned. Ignored by the SQL fallback.

• community_algorithm (str) – Community detection algorithm for global mode: ‘leiden’ (default) or ‘louvain’ (connected communities).

• llm_router (Any | None) – Optional callable llm_router(query, community_summary) -> float used in global mode to rate each community’s relevance before descending. Communities scoring below relevance_threshold are pruned, so irrelevant subtrees are never expanded. When None, the existing seed_overlap/member_count heuristic is used.

• relevance_threshold (float) – Minimum router score for a community to be kept (default 0.0). Only used when llm_router is provided.

• embed (Any | None) – Optional callable embed(texts: List[str]) -> List[List[float]] used in global mode to embed the query for vector search over the community report embeddings. When the community table has an embedding column and either query is already a vector or embed is provided, communities are selected by vector similarity and the hierarchy is descended recursively (Neo4j-style). When None, the llm_router/seed_overlap/member_count heuristic is used.

• time_column (str | None)

• time_start (str | None)

• time_end (str | None)

• rerank_vector (bool)

• rerank_k (int | None)

Returns:

GraphRagResult object with .nodes, .edges, .seeds, and .format_context() for prompt injection.

Return type:

GraphRagResult

summarize_communities(doc_table, target_uri, id_column=None, content_column=None, resolution=1.0, resolutions=None, hierarchical=False, top_entities_per_comm=5, device=None, algorithm='leiden', llm=None, embed=None, report_column='report')

Summarize communities in this edge table using text context from doc_table, and materialize the results as an Apache Iceberg table at target_uri.

Supports both single-level clustering and hierarchical multi-resolution Louvain pyramids (with level and parent_community_id tracking for Microsoft GraphRAG parity).

Parameters:

• doc_table (Table) – Document/entity Table containing text descriptions.

• target_uri (str) – Target URI where the community Iceberg table will be materialized.

• id_column (str | None) – Node/entity identifier column in doc_table. Auto-detected if None.

• content_column (str | None) – Text content column in doc_table. Auto-detected if None.

• resolution (float) – Single-resolution modularity parameter (used when hierarchical=False).

• resolutions (List[float] | None) – List of resolutions across hierarchical levels (defaults to [0.5, 1.0, 2.0] if hierarchical=True).

• hierarchical (bool) – Whether to build a multi-level hierarchical community tree.

• top_entities_per_comm (int) – Number of top central entities to feature per community.

• device (Any | None) – Optional compute device.

• algorithm (str) – Community detection algorithm: ‘leiden’ (default) or ‘louvain’.

• llm (Any | None) – Optional callable llm(prompt: str) -> str that generates a model-authored report per community (Microsoft GraphRAG parity). The report is stored in report_column.

• embed (Any | None) – Optional callable embed(texts: List[str]) -> List[List[float]] that embeds the reports (or summaries when llm is None). When provided, an embedding column is written and an HNSW index is built on it, making community reports first-class vector-retrieval units.

• report_column (str) – Column name for the generated report (default ‘report’).

Returns:

Table instance pointing to the newly materialized Iceberg community table.

Return type:

Table

extract_graph(doc_table, target_uri, llm, id_column=None, content_column=None, claims_uri=None, max_docs=None, device=None)

Extract a knowledge graph (entities, relationships, claims) from a document table using an LLM, and materialize it as an edge table.

llm(prompt: str) -> str must return JSON of the form:

{
  "entities": ["Name", ...],
  "relationships": [{"source": "A", "target": "B",
                     "relation": "rel", "weight": 1.0}, ...],
  "claims": [{"subject": "A", "object": "B",
              "claim": "text", "confidence": 0.9}, ...]
}

Entity names are mapped to stable uint64 node IDs via SHA-256, so the graph is reproducible across runs. The document’s own id_column value is used as the node ID for the document itself.

Parameters:

• doc_table (Table) – Document/entity Table containing text.

• target_uri (str) – Target URI for the materialized edge table.

• llm (Any) – Callable llm(prompt) -> json_string.

• id_column (str | None) – Node/entity identifier column in doc_table. Auto-detected.

• content_column (str | None) – Text content column in doc_table. Auto-detected.

• claims_uri (str | None) – Optional target URI for a claims table (subject, object, claim, source_doc, confidence).

• max_docs (int | None) – Optional cap on the number of documents processed.

• device (Any | None) – Optional compute device.

Returns:

The materialized edge Table (with a graph index on source).

Return type:

Table

drift_search(query, community_table, follow_up_llm=None, n_depth=2, k_followups=3, top_k=5, hops=2, confidence_threshold=0.0, mode='auto', graph_column=None)

Execute a global DRIFT (Dynamic Reasoning and Inference with Flexible Traversal) search over the whole graph.

Parameters:

• query (str) – The initial query string.

• community_table (Table) – A Table containing community summaries (e.g. from summarize_communities).

• follow_up_llm (Any | None) – Optional LLM callback (must be callable) for generating follow-up queries.

• n_depth (int) – Maximum search depth for follow-ups.

• k_followups (int) – Number of top-scored follow-ups to explore per round.

• top_k (int) – Number of top communities to select for the primer phase.

• hops (int) – Max hops for multi-hop induced subgraph extraction.

• confidence_threshold (float) – Minimum confidence score to continue exploring a follow-up.

• mode (str) –

  Graph backend for the traversal: - "auto" (default): out-of-core (mmap CSR) when the edge table

  has a graph index, else in-memory.

  • "in_memory": build the full adjacency in RAM from the edge rows.

  • "out_of_core": walk the mmap CSR directly (no materialization).

• graph_column (str | None) – Explicit CSR graph column. Overrides the auto-detected "source" when mode is "auto"/"out_of_core".

Returns:

Dictionary containing ‘all_discovered_nodes’ and ‘actions’.

Return type:

Dict[str, Any]

resolve_entities(relation='same_as', source_col=None, target_col=None)

Compute transitive equivalence closure over alias / same_as edges in this edge table.

Uses Disjoint Set Union (Union-Find) with path compression to partition alias nodes into connected components, electing the minimal node ID as the canonical representative.

Parameters:

• relation (str) – Edge relationship string to treat as equivalence (default: ‘same_as’).

• source_col (str | None) – Source node column name. Auto-detected if None.

• target_col (str | None) – Target node column name. Auto-detected if None.

Returns:

canonical_id}.

Return type:

Dict mapping each node ID to its canonical resolved node ID {node_id

hybrid_search(text_column, query_text, vector_column, query_vector, k=10, rrf_k=60, filter=None, columns=None, device=None)

Perform hybrid search combining vector similarity and BM25 keyword search using Reciprocal Rank Fusion (RRF).

RRF Score: score = sum(1.0 / (rrf_k + rank + 1.0))

Parameters:

• text_column (str) – Text column for BM25 keyword search.

• query_text (str) – Keyword or query string.

• vector_column (str) – Embedding column for dense vector search.

• query_vector (List[float]) – Dense float vector.

• k (int) – Number of fused top results to return.

• rrf_k (int) – RRF smoothing constant (default: 60).

• filter (str | None) – Optional SQL filter expression.

• columns (List[str] | None) – Optional list of columns to return.

• device (Any | None) – Optional compute device.

Returns:

pandas.DataFrame of top results sorted by rrf_score descending.

Return type:

Any

is_edge_table()

Check whether this table is declared (or conforms) as an edge table.

Metadata-first: a table with table_type=’edge’ is an edge table regardless of column names; otherwise the standard name convention is used.

Return type:

bool

edge_endpoints()

Return the (source, target) column names for this edge table.

Metadata-first (src_col/dst_col), then the standard name candidates.

Return type:

tuple

has_graph_index(column='source')

Return True if a CSR graph index exists on column.

The CSR index is built on the index’s source column, so column should be the source endpoint (e.g. “source”). Used to decide whether the memory-mapped CSR fast path is available before opting into it.

Parameters:

column (str)

Return type:

bool

classmethod create_edge_table(uri, schema=None, directed=True, node_id_type='uint64', with_relation=True, with_weight=True, embedding_dim=None, index_endpoints=True, index_embedding=True, partition_by_relation=False, device=None)

Create a new edge table following the standard Iceberg edge table schema convention: - source: UInt64 or String node identifier - target: UInt64 or String node identifier - relation: String relationship type (e.g. ‘cites’, ‘mentions’, ‘related_to’) - weight: Float64 edge weight (defaults to 1.0) - embedding: Optional List of Float32 for semantic edge search

Parameters:

• uri (str) – Table location.

• schema (Any | None) – Optional explicit pyarrow.Schema.

• directed (bool) – Whether graph is directed.

• node_id_type (str) – ‘uint64’ (default, optimal for graph UDAFs) or ‘string’.

• with_relation (bool) – Include ‘relation’ string column.

• with_weight (bool) – Include ‘weight’ float64 column.

• embedding_dim (int | None) – Optional vector dimension for edge embeddings.

• index_endpoints (bool) – Automatically configure sidecar Bitmap indexes on ‘source’ and ‘target’.

• index_embedding (bool) – Automatically configure HNSW index on ‘embedding’ if present.

• partition_by_relation (bool) – Partition Iceberg table by relation type.

• device (Any | None) – Compute device.

Return type:

Table

classmethod create_node_table(uri, schema=None, id_col='id', label_col='name', embedding_dim=None, index_id=True, index_embedding=True, device=None)

Create a node/entity table with table_type=’node’ metadata.

Parameters:

• uri (str) – Table location.

• schema (Any | None) – Optional explicit pyarrow.Schema.

• id_col (str) – Node identifier column (default ‘id’).

• label_col (str | None) – Optional label/name column (default ‘name’).

• embedding_dim (int | None) – Optional vector dimension for node embeddings.

• index_id (bool) – Configure a Bitmap index on the id column.

• index_embedding (bool) – Configure an HNSW index on ‘embedding’ if present.

• device (Any | None) – Compute device.

Return type:

Table

classmethod from_networkx(uri, graph, device=None, mode='append', index_endpoints=True, index_embedding=True, partition_by_relation=False)

Create or append to an edge table from a NetworkX graph (Graph, DiGraph, MultiGraph, MultiDiGraph).

Converts NetworkX graph edges and edge attributes to columnar Arrow/Iceberg format. Preserves edge weights, relations, embeddings, and arbitrary edge attributes. Automatically enables sidecar Roaring Bitmap indexes on ‘source’ and ‘target’, and HNSW vector index on ‘embedding’ if present.

Parameters:

• uri (str)

• device (Any | None)

• mode (str)

• index_endpoints (bool)

• index_embedding (bool)

• partition_by_relation (bool)

Return type:

Table

to_networkx(create_using=None, directed=True, multigraph=False, source='source', target='target', weight='weight', edge_attr=True, filter_expr=None)

Export this BenoStreamDB edge table to a NetworkX Graph, DiGraph, MultiGraph, or MultiDiGraph.

Parameters:

• create_using – NetworkX graph class or instance. If None, uses nx.MultiDiGraph, nx.DiGraph, nx.MultiGraph, or nx.Graph based on directed & multigraph args.

• directed (bool) – Whether the output graph is directed (default: True). Ignored if create_using is provided.

• multigraph (bool) – Whether the output graph allows multiple edges between node pairs (default: False).

• source (str) – Source node column name (default ‘source’, auto-checks ‘source_id’ or ‘u’).

• target (str) – Target node column name (default ‘target’, auto-checks ‘target_id’ or ‘v’).

• weight (str) – Edge weight column name (default ‘weight’).

• edge_attr (bool | List[str]) – List of column names to include as edge attributes, or True for all other columns.

• filter_expr (str | None) – Optional SQL WHERE clause to filter edges before export (e.g. “weight > 0.5”).

Returns:

networkx.Graph, networkx.DiGraph, networkx.MultiGraph, or networkx.MultiDiGraph.

define_embedding(column, function=None, vector_column=None, model=None)

Link a source column to an embedding function or model for automatic vectorization.

Parameters:

• column (str) – The source text column.

• function (str | EmbeddingFunction | None) – Registered function name or EmbeddingFunction instance.

• vector_column (str | None) – Target vector column name (defaults to {column}_vector).

• model (str | None) – Alias for function (e.g. model=”BAAI/bge-large-en-v1.5”).

write(data, device=None, mode='append')

Write data to the table, automatically generating embeddings for configured columns.

Parameters:

• data (Any) – pandas.DataFrame, pyarrow.Table, polars.DataFrame, numpy.ndarray, torch.Tensor, or List[Dict].

• device (Any | None) – Optional Device for GPU acceleration.

• mode (str) – ‘append’ (default) or ‘overwrite’ (clears table first).

insert(data, device=None)

Alias for write() for compatibility with common vector DB APIs.

Parameters:

• data (Any)

• device (Any | None)

write_pandas(df, device=None)

High-level Pandas ingestion with auto-vectorization.

Parameters:

• df (DataFrame)

• device (Any | None)

write_arrow(table, device=None)

High-level Arrow ingestion with auto-vectorization.

Parameters:

• table (Table)

• device (Any | None)

upsert(data, key_column, mode='merge_on_read', device=None)

Update or insert data using a key column (or list of columns) to avoid duplicates.

Parameters:

• data (Any)

• key_column (str | List[str])

• mode (str)

• device (Any | None)

commit()

Commit temporary segments to the table.

truncate()

Clear all data from the table while keeping the schema.

vacuum(retention_versions=1)

Physically delete unreferenced data and manifest files to reclaim space.

Parameters:

retention_versions (int) – Number of snapshots to keep (default 1).

property autocommit: bool

Get or set the autocommit state of the table.

property format_version

Iceberg table format version (1, 2, or 3). v3 enables row lineage.

wait_for_background_tasks()

Wait for all background tasks (like index building) to complete.

delete(filter)

Delete rows matching the filter expression.

Parameters:

filter (str)

to_pandas(filter=None, vector_filter=None, columns=None, device=None, **kwargs)

Read table to Pandas with auto-vectorization of search queries and flexible parameters.

Parameters:

• filter (str | None) – Optional scalar WHERE clause (e.g., “category = ‘news’”)

• vector_filter (Dict[str, Any] | List[float] | None) – Dict with vector search params: - column: str (required) - vector column name - query: list (required) - query vector - k: int (required) - number of results - metric: str (optional) - ‘l2’|’cosine’|’innerproduct’|’l1’|’hamming’|’jaccard’ (default: l2) - ef_search: int (optional) - HNSW ef parameter for tuning - probes: int (optional) - IVF probes parameter for tuning

• columns (List[str] | None) – Optional list of column names to select

• device (Any | None) – Optional compute device (GPU/CPU)

• **kwargs – Extra params (merged into vector_filter if present)

Example:

# Vector search with cosine metric
df = table.to_pandas(vector_filter={
    "column": "embedding",
    "query": [1.0, 2.0, 3.0],
    "k": 5,
    "metric": "cosine",
    "ef_search": 200  # Tune HNSW search quality
})

to_arrow(filter=None, vector_filter=None, columns=None, device=None, **kwargs)

Read table to Arrow Table with auto-vectorization of search queries and flexible parameters.

Parameters:

• filter (str | None) – Optional scalar WHERE clause (e.g., “category = ‘news’”)

• vector_filter (Dict[str, Any] | List[float] | None) – Dict with vector search params: - column: str (required) - vector column name - query: list (required) - query vector - k: int (required) - number of results - metric: str (optional) - ‘l2’|’cosine’|’innerproduct’|’l1’|’hamming’|’jaccard’ (default: l2) - ef_search: int (optional) - HNSW ef parameter for tuning - probes: int (optional) - IVF probes parameter for tuning

• columns (List[str] | None) – Optional list of column names to select

• device (Any | None) – Optional compute device (GPU/CPU)

• **kwargs – Extra params (merged into vector_filter if present)

to_arrow_stream(filter=None, vector_filter=None, columns=None, device=None, **kwargs)

Return a pyarrow.RecordBatchReader over the result — the streaming primitive recommended for datasets that do not fit in memory.

to_arrow() is to_arrow_stream().read_all(). Arrow is the single interchange surface: to get a pandas or polars frame, materialize Arrow and convert there (pl.from_arrow(table.to_arrow()) is zero-copy). Rust never emits a dataframe directly.

Parameters:

• filter (str | None)

• vector_filter (Dict[str, Any] | List[float] | None)

• columns (List[str] | None)

• device (Any | None)

to_polars(filter=None, vector_filter=None, columns=None, device=None, **kwargs)

Return the result as a polars.DataFrame.

Python-side adapter over the Arrow boundary: polars.from_arrow(...) is zero-copy for Arrow-backed data, and the Rust layer only ever emits Arrow — polars never enters the binding.

Parameters:

• filter (str | None)

• vector_filter (Dict[str, Any] | List[float] | None)

• columns (List[str] | None)

• device (Any | None)

explain(filter=None, vector_filter=None)

Return the engine’s query plan, including why segments were pruned.

Parameters:

• filter (str | None) – optional scalar WHERE clause

• vector_filter (Dict[str, Any] | None) – optional vector-search params dict (same shape as to_pandas())

Returns:

The plan as a string, with a per-reason pruning breakdown.

Return type:

str

Example:

print(table.explain("id BETWEEN 100 AND 105"))
#   -> Pruning Activity: 2 segments pruned via Partition/Stats mapping
#        - 2 segment(s): column max < filter min

sql(query)

Execute a SQL query against the table. The table is registered as ‘t’.

Parameters:

query (str)

Return type:

Any

query()

Start a fluent query.

Return type:

Query

read(filter=None, vector_filter=None, columns=None, device=None, **kwargs)

Read table to Arrow Table (alias for to_arrow).

Parameters:

• filter (str | None)

• vector_filter (Dict[str, Any] | List[float] | None)

• columns (List[str] | None)

• device (Any | None)

vector_search_scored(column, query, k=10, metric=None, ef_search=None)

Vector search returning only (segment_id, row_id, score).

Reads nothing but the HNSW/BM25 index — no Parquet I/O. Use this for seed discovery, RRF fusion, or candidate reranking, then fetch rows only for the winners with to_pandas()/vector_search().

Returns a pandas DataFrame with columns segment_id, row_id, score.

Parameters:

• column (str)

• query (List[float])

• k (int)

• metric (str | None)

• ef_search (int | None)

vector_search(column, query, k=10, filter=None, columns=None, device=None, **kwargs)

Backward compatibility alias for to_pandas with vector filter.

Parameters:

• column (str)

• query (List[float])

• k (int)

• filter (str | None)

• columns (List[str] | None)

• device (Any | None)

search(column, query, k=10, filter=None, columns=None, device=None, **kwargs)

Alias for vector_search.

Parameters:

• column (str)

• query (List[float])

• k (int)

• filter (str | None)

• columns (List[str] | None)

• device (Any | None)

filter(expr=None, vector_filter=None, **kwargs)

Start a fluent query or apply immediate filters.

Parameters:

• expr (str | None)

• vector_filter (Dict[str, Any] | List[float] | None)

Return type:

Query

property primary_key

Get the current primary key column.

property index_all

Whether to build HNSW/BM25 indexes for all compatible columns on commit.

Defaults to False (opt-in). Setting this to True triggers background index builds after every commit() call — useful when you want fast ANN search but be aware of the additional commit latency (~15 s per 100 K rows with 768-dim vectors on CPU).

For selective indexing, prefer table.add_index(column, 'hnsw').

property row_count: int

Get total row count in the table.

property statistics

Get full table statistics.

add_index_columns(columns, tokenizer=None)

Add columns to the indexing configuration.

Parameters:

• columns (List[str]) – List of column names to index.

• tokenizer (str | None) –

  Optional tokenizer name from the registry. Available options include:

  • ”default” (or “standard”): The default tokenizer. Splits on any non-alphanumeric character and lowercases tokens. Good for general English text, but not optimal for specialized corpora like code repos (destroys camelCase/symbols), legal documents (strips exact punctuation), or CJK languages (no spaces).

  • ”whitespace”: Splits only on whitespace characters.

  • ”identity”: Returns the exact string as a single token (useful for exact/category matching).

  • ”analyzer:english”: Standard tokenization plus English stop-word removal.

set_index_config(column, enabled=True, tokenizer=None, device=None)

Set indexing configuration for a specific column. (Legacy compatibility wrapper)

Parameters:

• column (str)

• enabled (bool)

• tokenizer (str | None)

• device (str | None)

set_index_columns(config)

Update indexing specifications for multiple columns at once. Supports both simple strings and advanced configuration dictionaries.

Example:

table.set_index_columns({
    "embedding": IndexType.HNSW,
    "content": ["hnsw", "bm25"],
    "category": "bitmap"
})

Parameters:

config (Dict[str, str | List[str | Dict[str, Any]] | Dict[str, Any]])

rewrite_data_files(min_file_size_bytes=None)

Compact small segments into larger ones (Iceberg-style rewrite).

Parameters:

min_file_size_bytes (int | None) – segments smaller than this are compaction candidates; the target output size is 2x this value. Defaults to the engine’s 384 MB / 512 MB pair.

Return type:

None

compact(min_file_size_bytes=None)

Alias for rewrite_data_files.

Parameters:

min_file_size_bytes (int | None)

Return type:

None

snapshot_version()

Return the latest committed manifest version (MVCC snapshot id).

Every commit is a monotonically increasing v{N}.json written with an atomic create, so this value is a stable snapshot identifier. Pin it to reason about a consistent view while other writers commit.

Return type:

int

preload_indexes(max_memory_bytes=None, include_vector=True, include_inverted=True, include_graph=True, spill_to_disk=True)

Warm the read-path index caches so the first query is instant.

Loads every index file in the current manifest through the same cache path a query would use — HNSW/IVF vector, inverted/BM25, CSR graph, and the manifest/parquet metadata caches. This is the Dgraph-style “in-memory posting list” residency, but on demand and bounded.

Indexes are warmed into RAM until max_memory_bytes is exhausted; the remainder spills into the mmap disk cache (BSDB_DISK_CACHE_DIR) for out-of-core serving when spill_to_disk is true. The bounded caches evict by LRU/TinyLFU + TTI, so overflow evicts the least-recently-used entries.

Parameters:

• max_memory_bytes (int | None) – In-memory warm budget. Defaults to 4 GiB.

• include_vector (bool) – Warm vector (HNSW/IVF/TQ) indexes.

• include_inverted (bool) – Warm inverted (BM25/exact) indexes.

• include_graph (bool) – Warm CSR graph indexes.

• spill_to_disk (bool) – Warm the overflow into the mmap disk cache.

Returns:

A dict with indexes_seen, indexes_warmed, indexes_skipped, bytes_in_memory, bytes_on_disk, and elapsed_ms.

Return type:

Dict[str, Any]

ingest(paths, chunk_rows=None, parallelism=None, index_all=False, resume=True, compact_after=False, memory_budget_gb=None, coordinate=False, lease_ttl_secs=300)

Native bulk ingest of parquet files (plan → parallel execute → commit).

Runs entirely inside the engine: the input set is planned into row-range work units, a bounded pool of workers builds a private segment (with its indexes) per unit, and completed segments are committed via the OCC manifest CAS. Completed units are recorded in a sidecar, so an interrupted load resumes at the unit boundary.

Parameters:

• paths (str | List[str]) – one parquet path or a list of them.

• chunk_rows (int | None) – rows per work unit (default 1,000,000).

• parallelism (int | None) – max work units in flight (default 4).

• index_all (bool) – build indexes for every column (else only configured ones).

• resume (bool) – skip units already recorded as complete (default True).

• compact_after (bool) – run rewrite_data_files after the ingest so segment and manifest counts stay bounded at TB scale.

• memory_budget_gb (float | None) – return freed heap pages to the OS after a unit once RSS exceeds this budget (GB). Falls back to the BSDB_INGEST_MEMORY_BUDGET_GB env var when unset; disabled if neither is set.

• coordinate (bool) – multi-machine mode — claim units from a shared object-store lease queue instead of a fixed local list. Run on N machines with the same paths to split the work; a dead node’s lease expires and another node steals its unit.

• lease_ttl_secs (int) – lease TTL for coordinate (default 300).

Returns:

units_total, units_skipped, units_committed, rows_ingested, segments.

Return type:

A report dict

add_index(column, algorithm='hnsw', **kwargs)

Add an indexing strategy to a column.

Parameters:

• column (str)

• algorithm (str | Dict[str, Any])

drop_index(column)

Remove all indexing strategies from a column.

Parameters:

column (str)

set_primary_key(columns)

Set or replace the table’s primary key columns.

Parameters:

columns (str | List[str])

get_primary_key()

Get the table’s primary key columns.

Return type:

List[str]

add_primary_key(column)

Atomically add a column to the primary key. This performs a validation check for duplicates across all existing data. If validation fails, the change is NOT committed.

Parameters:

column (str)

drop_primary_key(column)

Atomically remove a column from the primary key.

Parameters:

column (str)

sync_detached_overlay()

Synchronize this detached overlay with the upstream Iceberg table. Returns True when a new upstream snapshot was imported, False otherwise.

Return type:

bool

start_detached_sync_worker(interval_seconds=60)

Start a background worker that periodically syncs the detached overlay with the upstream Iceberg table.

Parameters:

interval_seconds (int)

Return type:

None

detached_catalog()

Return the detached overlay catalog metadata as a dict, or None if not an overlay.

Return type:

Dict[str, Any] | None

recover_indexes()

Re-indexes data files that are missing overlay index sidecars. Returns the count of data files indexed.

Return type:

int

add_column(name, data_type)

Add a new column to the table. data_type can be a string (e.g., ‘int32’, ‘float64’, ‘string’) or a pyarrow.DataType.

Parameters:

• name (str)

• data_type (str | Any)

drop_column(name)

Drop an existing column from the table.

Parameters:

name (str)

rename_column(old_name, new_name)

Rename an existing column.

Parameters:

• old_name (str)

• new_name (str)

update_column_type(name, new_type)

Update the type of a column (Type Promotion). Example: update_column_type(‘id’, ‘long’)

Parameters:

• name (str)

• new_type (str)

move_column(name, new_index)

Move a column to a new 0-based index position.

Parameters:

• name (str)

• new_index (int)

set_sort_order(columns, ascending)

Set the table’s default sort order for future data writes.

Parameters:

• columns (List[str])

• ascending (List[bool])

set_partition_spec(spec)

Update the table’s partition specification.

Parameters:

spec (List[Dict[str, Any]]) – List of partition fields, each being a dict with: - source_id: int (or source_ids: List[int]) - name: str - transform: str - field_id: int (optional)

Query

class benostreamdb.Query(table, filter_expr=None)

Bases: object

Fluent Query interface for BenoStreamDB.

Parameters:

filter_expr (str | None)

filter(expr)

Apply a SQL-like filter expression.

Parameters:

expr (str)

Return type:

Query

vector_search(query, column=None, k=10, **kwargs)

Apply a vector search filter.

Parameters:

• query (List[float] | str) – The query vector (list of floats) or a string to be vectorized.

• column (str | None) – The vector column to search against.

• k (int) – Number of nearest neighbors to return.

• **kwargs – Additional parameters (e.g., n_probe).

Return type:

Query

select(columns)

Select specific columns to return.

Parameters:

columns (List[str])

Return type:

Query

to_pandas(device=None)

Execute the query and return results as a Pandas DataFrame.

Parameters:

device (Any | None)

to_arrow(device=None)

Execute the query and return results as an Arrow Table.

Parameters:

device (Any | None)

execute(device=None, to_arrow=False)

Execute the query and return results as a Pandas DataFrame (default) or Arrow Table.

Parameters:

• device (Any | None)

• to_arrow (bool)

Session

class benostreamdb.Session(memory_mb=None, warehouse=None)

Bases: object

BenoStreamDB Query Session with integration for Python Table objects.

Parameters:

• memory_mb (int | None)

• warehouse (str | None)

register(name, table)

Register a table in the session for SQL queries.

Parameters:

• name (str)

• table (Table | Table)

sql(query)

Execute a SQL query against the table (registered as ‘t’).

Parameters:

query (str)

Return type:

Any

list_graph_tables(schema=None)

List the graph tables (node/edge) registered in the session.

Returns a list of dicts: {name, table_type, source_column, target_column, id_column, label_column}. This is the discovery primitive an MCP agent uses to find the graph without being told the column names.

Parameters:

schema (str | None)

Return type:

List[Dict[str, Any]]

graph_neighbors(table, seed, hops=1)

Find all neighbors reachable from seed within hops. Returns a pandas DataFrame.

Parameters:

• table (str)

• seed (int | str)

• hops (int)

Return type:

Any

shortest_path(table, start, end)

Find shortest path between start and end nodes. Returns a pandas DataFrame.

Parameters:

• table (str)

• start (int | str)

• end (int | str)

Return type:

Any

pagerank(table, damping=0.85, iterations=30)

Compute PageRank scores over the given edge table. Returns a pandas DataFrame.

Parameters:

• table (str)

• damping (float)

• iterations (int)

Return type:

Any

louvain(table, resolution=1.0)

Compute Louvain community assignments. Returns a pandas DataFrame.

Parameters:

• table (str)

• resolution (float)

Return type:

Any

hybrid_search(table, text, vector_col, k=10, text_col=None, query_vector=None, rrf_k=60)

Hybrid BM25 + dense vector search with Reciprocal Rank Fusion. Returns a pandas DataFrame.

Parameters:

• table (str)

• text (str)

• vector_col (str)

• k (int)

• text_col (str | None)

• query_vector (List[float] | None)

• rrf_k (int)

Return type:

Any

catalog_policy()

Return the authoritative warehouse catalog policy as a dictionary, or None.

Return type:

Dict[str, Any] | None

set_schema_access(schema, read_only=True)

Set read-only vs read-write access for a specific schema on the warehouse.

Parameters:

• schema (str)

• read_only (bool)

Return type:

Dict[str, Any]

lock_all_read_only()

Lock down all persistent schemas to read-only mode.

Return type:

Dict[str, Any]

Embedding Registry

class benostreamdb.embeddings.EmbeddingFunction

Bases: ABC

Abstract base class for all embedding functions.

class benostreamdb.embeddings.HuggingFaceFunction(model_name='BAAI/bge-small-en-v1.5', device='cpu', **kwargs)

Bases: EmbeddingFunction

Local embedding function using Sentence Transformers (supports all Hugging Face models). Defaults to the retrieval-tuned BAAI/bge-small-en-v1.5 (384-d). Examples: ‘BAAI/bge-small-en-v1.5’, ‘BAAI/bge-large-en-v1.5’, ‘intfloat/multilingual-e5-small’, ‘Qwen/Qwen-7B-Chat’ (if supported by ST)

Parameters:

• model_name (str)

• device (str)

class benostreamdb.embeddings.OpenAIEmbeddingFunction(model_name='text-embedding-3-small', api_key=None, **kwargs)

Bases: EmbeddingFunction

Embedding function using the OpenAI API.

Parameters:

• model_name (str)

• api_key (str | None)

class benostreamdb.embeddings.AnthropicEmbeddingFunction(model_name='voyage-2', api_key=None, **kwargs)

Bases: EmbeddingFunction

Embedding function using Anthropic/Claude (placeholder as Anthropic doesn’t have a direct embedding API yet). Often used in conjunction with Voyage AI or similar.

Parameters:

• model_name (str)

• api_key (str | None)

class benostreamdb.embeddings.GeminiEmbeddingFunction(model_name='models/embedding-001', api_key=None, **kwargs)

Bases: EmbeddingFunction

Embedding function using Google’s Gemini API.

Parameters:

• model_name (str)

• api_key (str | None)

class benostreamdb.embeddings.EmbeddingRegistry

Bases: object

Registry to manage and retrieve embedding functions.

register(name, func)

Register a new embedding function.

Parameters:

• name (str)

• func (EmbeddingFunction)

get(name)

Retrieve a registered embedding function.

Parameters:

name (str)

Return type:

EmbeddingFunction | None

benostreamdb.embeddings.get_registry()

Access the global embedding registry.