Skip to content
Feeding a clanker? Grab this page as raw .md →

Neo4jWidget API#

Neo4jWidget showing a Cypher query result as a graph of movie and person nodes joined by ACTED_IN relationships, with label filter chips above

Neo4jWidget takes a neo4j driver (or a uri plus auth), reads the database's labels, relationship types and property keys up front, and puts a Cypher input above a graph view of whatever the query returns. Clicking a node runs a follow-up query to pull in its neighbors, so you can walk outward from a small result instead of writing ever-longer Cypher. What is on screen stays readable from Python via nodes, relationships, selected_nodes and selected_relationships.

It talks to a real database, so this page has no in-browser demo — run it on molab against your own server instead. See also: GraphWidget for graphs you build in Python, EdgeDraw for sketching one by hand, and Treemap for hierarchies rather than graphs.

Bases: AnyWidget

Interactive Neo4j graph explorer with Cypher query input.

Examples:

import marimo as mo
from neo4j import GraphDatabase
from wigglystuff import Neo4jWidget

driver = GraphDatabase.driver("bolt://localhost:7687", auth=("neo4j", "password"))
widget = mo.ui.anywidget(Neo4jWidget(driver))
widget
Source code in wigglystuff/neo4j_widget.py 
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
def __init__(
    self,
    driver=None,
    *,
    uri: Optional[str] = None,
    auth: Optional[tuple] = None,
    database: Optional[str] = None,
    width: int = 800,
    height: int = 500,
    max_nodes: int = 300,
    initial_query: Optional[str] = None,
    **kwargs: Any,
) -> None:
    if driver is not None:
        self._driver = driver
    elif uri is not None:
        from neo4j import GraphDatabase

        self._driver = GraphDatabase.driver(uri, auth=auth)
    else:
        raise ValueError("Provide either a neo4j Driver or uri (+ auth).")
    self._database = database
    self._max_nodes = max_nodes
    schema = self._extract_schema()
    super().__init__(width=width, height=height, schema=schema, **kwargs)
    if initial_query:
        self._execute_query(initial_query)

clear #

clear() -> None

Clear the graph display and selection.

Source code in wigglystuff/neo4j_widget.py 
231
232
233
234
235
236
237
def clear(self) -> None:
    """Clear the graph display and selection."""
    self.nodes = []
    self.relationships = []
    self.selected_nodes = []
    self.selected_relationships = []
    self.error = ""

get_selected_node_data #

get_selected_node_data() -> List[dict]

Return full node dicts for currently selected nodes.

Source code in wigglystuff/neo4j_widget.py 
221
222
223
224
def get_selected_node_data(self) -> List[dict]:
    """Return full node dicts for currently selected nodes."""
    selected = set(self.selected_nodes)
    return [n for n in self.nodes if n["element_id"] in selected]

get_selected_relationship_data #

get_selected_relationship_data() -> List[dict]

Return full relationship dicts for currently selected relationships.

Source code in wigglystuff/neo4j_widget.py 
226
227
228
229
def get_selected_relationship_data(self) -> List[dict]:
    """Return full relationship dicts for currently selected relationships."""
    selected = set(self.selected_relationships)
    return [r for r in self.relationships if r["element_id"] in selected]

run_query #

run_query(query: str) -> None

Execute a Cypher query and merge results into the graph.

Source code in wigglystuff/neo4j_widget.py 
217
218
219
def run_query(self, query: str) -> None:
    """Execute a Cypher query and merge results into the graph."""
    self._execute_query(query)

Synced traitlets#

Traitlet Type Notes
width int Widget width in pixels (default: 800).
height int Widget height in pixels (default: 500).
schema dict Auto-extracted node labels, relationship types, and property keys.
nodes list List of node dicts currently displayed.
relationships list List of relationship dicts currently displayed.
error str Last error message (empty when no error).
query_running bool Whether a query is currently executing.
selected_nodes list Element IDs of currently selected nodes.
selected_relationships list Element IDs of currently selected relationships.