Notebook Usage

The repository includes notebooks under notebooks/. They use the same public APIs described in this documentation.

Available notebooks include:

  • 01_graphdb_basics.ipynb for core node and edge operations.

  • 02_loading_large_graph.ipynb for bulk graph loading patterns.

  • 03_property_graph_api.ipynb for attributed property graph usage.

  • 04_typed_path_sampling.ipynb for typed traversal and sampling.

  • 05_columnar_ingestion_benchmark.ipynb for Arrow/Polars columnar ingestion compared with LevelDB object batch ingestion.

  • 09_graph_visualization.ipynb for offline interactive visualization: visualize_* entrypoints, Cypher highlighting, typed sampling, caps, property labels/styling, selectable multigraph relationships, directed exploration, themes, browser SVG/PNG and saved-view exports, direct Python SVG layouts/coordinates, and sampler-batch inspection. It retrieves the visualization guide shipped with the installed library. The optional saved-coordinate cell skips cleanly until a local view-state file is supplied.

  • 10_sherlock_temporal_knowledge_graph.ipynb for extracting a temporal, epistemic narrative graph with a local Ollama model and explaining what Sherlock Holmes could know at a selected scene without later-story leakage.

Choose the Correct Kernel

For LMDB-only notebooks, any supported Python version with lmdb installed is enough. For LevelDB notebooks, use a CPython version that can install plyvel. Python 3.12 is a safe default.

uv python install 3.12
uv venv --python 3.12
uv sync --extra leveldb --extra lmdb
uv add --dev notebook ipykernel
.venv/bin/python -m ipykernel install --user --name gestaltdb-py312 --display-name "GestaltDB Python 3.12"

Minimal Notebook Cell

from gestaltdb.graphdb import Edge, GraphDB, Node
from gestaltdb.kvstores import LevelDBStore
from gestaltdb.serializers import PickleSerializer

graph_db = GraphDB(LevelDBStore("/tmp/leveldb_notebook_example"), PickleSerializer())

graph_db.put_node(Node(node_id="drug-1"))
graph_db.put_node(Node(node_id="protein-1"))
graph_db.put_edge(Edge(
    edge_id="drug-1-protein-1",
    source="drug-1",
    target="protein-1",
    properties={"type": "drug-to-protein"},
))

graph_db.neighbors_by_edge_type("drug-1", "drug-to-protein")

Close Stores Between Runs

Repeated notebook execution can keep database files open. Close the graph before rerunning setup cells that recreate stores.

graph_db.close()

Troubleshooting plyvel

If LevelDBStore raises a missing dependency error after installing extras, check the kernel interpreter:

import sys
print(sys.executable)
print(sys.version)

If it is Python 3.14 or a free-threaded build, switch the notebook to a Python 3.12 kernel and install gestaltdb[leveldb] there.