SQLite Connector

KumoRFM can connect directly to SQLite databases, automatically inferring table metadata and relationships from the database schema.

Installation

The SQLite backend requires the ADBC SQLite driver:

$
pip install kumoai[sqlite]

Or install the driver directly:

$
pip install adbc_driver_sqlite

Quick Start

The simplest way to create a graph from a SQLite database:

1
import kumoai.rfm as rfm
2
3
graph = rfm.Graph.from_sqlite("my_database.db")

This will:

1. Connect to the SQLite database
2. Discover all tables automatically
3. Infer column metadata (data types, semantic types, primary keys, time columns)
4. Detect foreign key relationships from the database schema
5. Print a summary of the inferred metadata and links

Specifying Tables

You can control which tables to include and customize their configuration:

1
graph = rfm.Graph.from_sqlite("data.db", tables=[
2
    "USERS",                                      # Include by name
3
    dict(name="ORDERS", source_name="ORDERS_V2"), # Rename source table
4
    dict(name="ITEMS", primary_key="ITEM_ID"),    # Override primary key
5
])

Table configuration options:

Connection Options

You can pass a file path or an existing ADBC connection:

1
# From a file path (string or Path):
2
graph = rfm.Graph.from_sqlite("path/to/database.db")
3
4
# From an existing ADBC connection:
5
from kumoai.rfm.backend.sqlite import connect
6
conn = connect("path/to/database.db")
7
graph = rfm.Graph.from_sqlite(conn)

Controlling Metadata Inference

By default, Graph.from_sqlite() infers metadata and links. You can disable this for manual configuration:

1
graph = rfm.Graph.from_sqlite(
2
    "data.db",
3
    infer_metadata=False,  # Skip automatic type inference
4
    verbose=False,         # Suppress output
5
)
6
7
# Manually configure metadata afterwards:
8
graph.infer_metadata()
9
graph.infer_links()

Manual Edge Specification

Override automatic link detection by providing edges explicitly:

1
graph = rfm.Graph.from_sqlite("data.db", edges=[
2
    ("ORDERS", "user_id", "USERS"),
3
    ("ORDERS", "item_id", "ITEMS"),
4
])

Optimizing Performance

When initializing KumoRFM with a SQLite-backed graph, the optimize=True flag creates database indices for faster context sampling:

1
model = rfm.KumoRFM(graph, optimize=True)

This is recommended for larger databases where sampling performance matters. Note that this requires write access to the database file.