SQLite Connector

Use the SQLite connector to create a Kumo Relational graph from a local SQLite database file. The graph represents your tables, column metadata, and relationships so that Kumo Relational can use the database for predictive queries.

Installation

Install the SDK with the relational and SQLite extras. This command includes the Arrow Database Connectivity (ADBC) driver that Kumo Relational uses to access SQLite:

pip install "kumo-relational-client[relational,sqlite]"

If the SDK is already installed, you can install only the SQLite driver:

pip install adbc_driver_sqlite

Quick Start

Pass the path to your SQLite database file to create a graph:

from kumo_relational_client import relational
graph = relational.Graph.from_sqlite("my_database.db")

This operation performs the following actions:

1. Connects to the SQLite database.
2. Discovers all tables automatically.
3. Infers column metadata, including data types, semantic types, primary keys, and time columns.
4. Detects foreign-key relationships from the database schema.
5. Prints a summary of the inferred metadata and links.

Specify Tables

By default, Kumo Relational includes every table it discovers. Use the tables parameter when you want to include a subset of tables or override an inferred setting:

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

Each entry can be a table name or a configuration dictionary with these keys:

Set the Database Path

Pass the database file path as the first argument:

graph = relational.Graph.from_sqlite("path/to/database.db")

Control Metadata Inference

By default, Graph.from_sqlite() infers metadata and links during graph creation. To defer those operations, set infer_metadata=False, then run them explicitly when you are ready:

graph = relational.Graph.from_sqlite(
    "data.db",
    infer_metadata=False,  # Skip automatic type inference
    verbose=False,         # Suppress output
)
# Run inference after creating the graph.
graph.infer_metadata()
graph.infer_links()

Specify Edges Manually

Use the edges parameter to provide relationships instead of relying on automatic link detection. Each tuple contains the source table, its foreign-key column, and the referenced table:

graph = relational.Graph.from_sqlite("data.db", edges=[
    ("ORDERS", "user_id", "USERS"),
    ("ORDERS", "item_id", "ITEMS"),
])

Pass edges=None to permit declared or inferred relationships. Pass edges=[] to create the graph without edges and suppress relationship inference.