Exploration UI¶

Quine's Exploration UI is an interactive canvas for exploring specific sub-graphs of data. While Quine overall is a streaming graph interpreter, the Exploration UI gives a user the ability to explore subsets of data in a style more similar to a database. This tool is particularly useful for investigating specific data found via the streaming capabilities built into the rest of the system. It facilitates an ad hoc, interactive exploration of small subsets of data.

Note

The Exploration UI is fully supported in Chrome. Other browsers are likely to work for most cases, but may experience some unusual behavior. In particular, Safari occassionaly does not update or garbles text values returned in the interactive documentation. Safari also renders nodes more slowly than Chrome, so animating the layout of many nodes is likely to be slow in Safari.

Components¶

The Exploration UI is composed of a toolbar along the top and a main canvas in white taking of most of the page. Data represented as nodes and edges will be rendered on the canvas in response to queries issued in the toolbar. A navigation bar along the left side will take you away from the Exploration UI to other views of the system.

Query Bar: A Cypher editor with syntax highlighting. Type a query here to render data into the canvas. If sample queries are defined, a drop-down menu listing them appears here.
Query Button: Click to run the query. The arrow beside it opens a menu of more query actions, described below.
Undo: Click to undo the last change to the canvas. Right-click for more options, including jumping to the previous checkpoint.
Animate: Click to animate the layout of nodes in the canvas. Click again to stop animation.
Redo: Click to redo the canvas change which was previously undone. Right-click for more options, including jumping to the next checkpoint.
Checkpoint: Click to save the current canvas contents as a checkpoint. Right-click to list all available checkpoints and jump to a chosen checkpoint.
Download: Click to download the current canvas (and canvas history) as a JSON object. Right-click for more options, including uploading a previously downloaded file to restore its state to the canvas.
Historical Query: Click to set a historical moment to query the underlying data as it was at that moment. This will set all queries issued in the Exploration UI to query only that historical moment.
Tree or Graph: Click to choose between rendering the nodes in the canvas in a free-form graph, or a hierarchical tree. Note: tree organization is not customizable.
Recenter: Click to return the canvas viewport to the center position.
Settings and Maintenance: The gear at the far right, providing access to the Exploration UI Settings and maintenance actions like clearing the canvas.

After a query completes, the number of nodes and edges it returned is shown briefly in the top right corner below the toolbar.

The arrow on the right side of the Query button opens a menu with more query actions:

Run as text query: Run the query and display the results in tabular form in the results panel below, instead of displaying nodes in the graph view.
Multi-line editing: Expand the query bar into a multi-line editor for longer queries. Pressing Shift+Enter in the query bar does the same thing.
Bookmark as sample query: Save the current query into the sample query drop-down. Saving asks for confirmation, since sample queries are a global setting and changes apply to all users.
Standing Query Inspection: Open a live view onto a running standing query, described below.

Canvas¶

Query results are rendered onto the shared space of the canvas. New results do not replace the content on the canvas, but rather add to it. All edges between two nodes on the canvas will automatically be drawn on the canvas; nodes rendered on the canvas may have edges that are not drawn when the node at the edge's other endpoint is not rendered.

Nodes often contain properties, which can be viewed and edited. Queries in progress that have not yet returned results cause a spinner to display in the top right corner of the canvas. Nodes rendered in the UI represent the data on each node -at the time it was returned-. Updating the state of a node is accomplished by returning that node again (or using the "Refresh" quick query).

When new results are returned to the canvas, the canvas animates briefly to layout all results. Nodes can be selected and moved around the canvas. Dragging a node automatically pins it to the canvas so that it does not move when the canvas is animated. Additional, contextually relevant queries can be easily initiated by right-clicking a node and choosing the appropriate query.

Queries that return tabular results render into the results panel instead of the canvas, described in Viewing Tabular Results.

Node appearances, quick queries, and default sample queries in the query bar can be customized in the Exploration UI Settings editor, or via the corresponding API calls documented under the heading of "UI Styling".

How to Use the Exploration UI¶

Running Queries¶

Queries are issued in one of three ways:

Typed into the Query Bar and executed by pressing Enter or clicking the "Query" button.
Chosen from the "Quick Query" context menu found by right-clicking a node (when defined). Note that this actually adds the query to the query bar and executes it.
Executed on page load when the URL for the Exploration UI ends with a hash (#) followed by a query.

Warning

Because the Exploration UI generates a snapshot of the graph, it can give Quine the appearance of database. This is just a convenient way to explore the data structures but make no mistake: Quine is a streaming graph interpreter designed to process what are effectively infinite streams of data. Quine is run without indices by default. If Quine is managing a large amount of data, some queries which require scanning all nodes can take a very long time and slow down other functionality. It is strongly recommended to use a node ID in each query or use built in functions like idFrom(…) or recentNodes() to efficiently pull out small amounts of data. See this page for more guidance on querying infinite data.

Queries are written in Cypher. Most Cypher syntax is supported, and queries can be entered directly into the query bar. The Up and Down arrow keys step back through your query history. For longer queries, choose "Multi-line editing" from the query menu (or press Shift+Enter) to expand the editor across multiple lines; Cmd+Enter (Ctrl+Enter on Windows and Linux) runs the query from any mode.

The Exploration UI can be configured with any set of queries pre-programmed and available via a drop-down menu from the query bar. These sample queries can be configured in the Exploration UI Settings editor, saved directly from the query menu with "Bookmark as sample query", or configured through the REST API. Sample queries can be parameterized with easily completed values to make pulling out complex patterns very easy when the proper starting value is identified.

By default, queries issued in the Exploration UI are expected to return nodes (and only nodes). Nodes returned from queries will be rendered in the canvas. After computing the nodes returned from a query, the Exploration UI automatically resolves the edges to display in the canvas. Edges which connect nodes rendered in the canvas (previously rendered nodes and newly returned node results) will all be displayed.

One query is issued at a time, but any number of queries can be executing simultaneously. As new queries are issued, the in-progress spinner on the right reports the number of currently executing queries. Hovering the mouse over the spinner/counter will turn it into an "X" which can be clicked to cancel all in-progress queries. Since some queries can continue forever (e.g. wiretapping a Standing Query), clicking the "X" that appears in the progress spinner is the only way to gracefully end the query.

Quine includes many utility functions built in, and the ability to add in custom user-defined queries. To list all available functions which can be included in queries, you can execute the text query CALL help.functions() or CALL help.procedures() to print out the name, signature, and documentation for all currently supported functions and procedures.

Viewing Tabular Results¶

In addition to the canvas, the results panel is another way to view the results of ad-hoc queries. The results panel displays results as a table rather than an interactive graph. While the canvas can only display the results of queries that return nodes, the results panel can display the results of any query. To run a query and display its results in the results panel, choose "Run as text query" from the query menu, or press Ctrl+Shift+Enter.

The results panel can be resized vertically by dragging its top edge. Only one panel is open at a time, and the open panel covers the minimized results, so minimize the current panel before opening another. Each panel shows the query it came from; the edit button loads that query back into the query bar for refinement, and re-running the same ad-hoc query reuses its existing panel instead of opening a duplicate. Results can continue to stream into a panel in perpetuity for long-running queries.

Minimized results collect at the bottom right corner of the canvas, listed with a search box to filter them, so past results stay reachable without cluttering the canvas.

Query and system errors are reported the same way, in a results panel marked as an error.

Inspecting Standing Queries¶

Choosing "Standing Query Inspection" from the query menu shows the output workflow of a running standing query as a diagram with tap points: the raw standing query matches, the results after any transformation step, and the results after any enrichment step.

Clicking a tap point streams the results flowing through that point of the workflow. Results can be fetched a batch at a time ("Get more"), followed continuously ("Go live"), or stopped. A tap retains a bounded buffer of recent results, so it is safe to leave open against a busy standing query.

Viewing and Editing Node Properties¶

Right-clicking a node opens a context menu of actions and quick queries. Clicking "View properties" displays the properties of this node as well as the node's ID and labels.

Users can add, edit, or delete the properties and labels of the node by clicking the "Edit" button. Property values can be entered as text, a number, a boolean, or a JSON string, selectable using the selector to the left of each input box. If there is ever doubt about how the properties will be edited, clicking "Cypher query" will show the exact Cypher query used to edit the properties. No changes will be written to the graph until you click "Apply changes" and click "OK" in the confirmation popup.

Interacting With Data¶

A quick query is a pre-programmed query that is made available for execution by right-clicking a relevant starting node. Any number of quick queries can be pre-programmed into the system, and each quick query can define on which kind of node it becomes available. The node on which the quick query is executed is bound to the variable n — for example, MATCH (n)--(m) RETURN DISTINCT m expands one hop from the clicked node. Quine automatically prepends MATCH (n) WHERE id(n) = <clicked-node-id> to the querySuffix you provide, so your query will use n as its starting point.

Quick queries that are configured with an edgeLabel will produce a "synthetic edge" in the Exploration UI. A synthetic edge is rendered as a purple dotted edge in the Exploration UI. A synthetic edge does not directly exist in the underlying data; it exists only in the canvas. A synthetic edge connects the starting node from a quick query with all the results returned from that quick query. Synthetic edges enable displaying a complex result (e.g. the result of a complex graph traversal) as a simple single edge.

Nodes rendered on the canvas represent the state of the node at the moment it was retrieved by Quine. To update the rendered node on the canvas with new properties, the node simply needs to be returned again. This is done with another query, or by right-clicking a node and choosing the built-in Quick Query to "Refresh" a node. If multiple nodes are selected (e.g. by pressing Ctrl-A, or holding shift to draw a box or multi-select), clicking the "Refresh" quick query for one will refresh all selected nodes.

When queries are executed and new results are added to the canvas, nodes are animated by simulating the physics of a force-directed graph. This animation helps to lay out nodes in a two-dimensional arrangement for quick interpretation and further interaction. Depending on the data, the short animation may not be enough to conveniently separate the rendered nodes. In that case, clicking the play button will allow the physics animation to continue indefinitely until the animation is paused again. Nodes are automatically "pinned" to the canvas and removed from the physics simulation when they are dragged. Pinned nodes remain pinned when dragged again. Nodes that have been removed from the physics simulation will have a subtle drop shadow behind their node and label. To unpin a node and allow it to animate freely again, hold Shift and click and hold on the node(s).

Interactive exploration of the data is usually an iterative process. Investigating one node often leads to the next, which leads to the next, and so on. As such, interactive exploration benefits from the ability to jump back and forth between what has been rendered at each step, as well as saving and sharing of progress. The toolbar includes buttons to undo and redo each step of the exploration. Each time results are rendered to the canvas, a new entry is added to the timeline managed by the Exploration UI.

At any point during exploration, clicking the checkpoint button will allow the user to create a named checkpoint in the exploration. Right-clicking the checkpoint button will show a list of all named checkpoints and where they fall in the timeline compared to the present state of the canvas.

Clicking the download button will download a JSON representation of the exploration history so far. The history.json file can be loaded back into the Exploration UI, using the upload option in the download button's right-click menu, on any machine running Quine, whether it is a part of the original system or not.

The Exploration UI is an interface into the underlying graph data managed by Quine. The underlying graph data is fully versioned, making it possible to run queries at past moments to see what the results would have been at previous points in time. Unlike the timeline used to undo and redo exploration history, historical queries are a feature of the underlying graph interpreter, and not the Exploration UI. The Exploration UI does provide an interface to querying past historical moments, however. A user can set the Exploration UI to query past moments by clicking the History button and following the prompt to choose a single historical moment to begin a new exploration session. Choosing a new historical moment to query with the history button will clear anything rendered on the canvas and in the Exploration UI timeline.

Querying for a matched node is especially useful if there is a Cypher query registered as one of the outputs of the Standing Query and if that second query modifies the data—for instance, adding an edge connected to the node.

Reference: Key Combinations¶

Enter: when in the query bar, run the query; equivalent to clicking the "Query" button.
Shift-Enter: when in the query bar, insert a newline and switch to multi-line editing.
Cmd-Enter (Ctrl-Enter on Windows and Linux): run the query, in single-line or multi-line mode.
Ctrl-Shift-Enter: run the query as a text query with tabular results.
Up/Down arrows: when in the single-line query bar, step through query history.
Ctrl-A: select all nodes on the canvas.
Backspace: remove the selected node(s) from the canvas.
Shift-click and drag: draw a box to select multiple nodes.
Shift-click a node: add a node to the selected nodes.
Right click a node: bring up the menu of actions and quick queries available from the clicked node.
Drag a node: pin it to the canvas so it does not animate with future queries.
Shift-click and hold a pinned node: unpin it so it animates freely again.
Double click a node: execute the node's default quick query (the first in the node's quick query list).
Shift-click thatDot logo: download an SVG image of the canvas.

Quine Enterprise

For multi‑tenant role based access control, see Quine Enterprise. Compare editions.