6 Graph Visualization Application

The Graph Visualization application enables interactive exploration and visualization of property graphs. It can also visualize graphs stored in the database.

• About the Graph Visualization Application
  The Graph Visualization application is a single-page web application that works with the in-memory graph server (PGX).
• How does the Graph Visualization Application Work
  The Graph Visualization application exposes its own web interface and REST endpoint and can execute PGQL queries against the in-memory graph server (PGX) or the Oracle Database (PGQL on RDBMS).
• Deploying Graph Visualization Application
  This section describes the various methods to deploy the Graph Visualization Application.
• Using GraphViz
  The principal points of entry for the GraphViz application are the query editor and the graph lists.

6.1 About the Graph Visualization Application

The Graph Visualization application is a single-page web application that works with the in-memory graph server (PGX).

The in-memory graph analytics server can be deployed in embedded mode or in Apache Tomcat or Oracle Weblogic Server. Graph Visualization application takes PGQL queries as an input and renders the result visually. A rich set of client-side exploration and visualization features can reveal new insights into your graph data.

Graph Visualization application works with the in-memory analytics server. It can visualize graphs that are have been loaded into the in-memory analytics server, either preloaded when the in-memory analytics server is started, or loaded at run-time by a client application and made available through the graph.publish() API.

6.2 How does the Graph Visualization Application Work

The Graph Visualization application exposes its own web interface and REST endpoint and can execute PGQL queries against the in-memory graph server (PGX) or the Oracle Database (PGQL on RDBMS).

By default, it uses PGX and therefore requires a running PGX server to function. Alternatively, you can configure Graph Visualization application to directly talk to the database via PGQL on RDBMS. Graph Visualization application does not have any UI to create graphs, it can only visualize graphs which are already loaded into PGX or Oracle Database. There are two ways you can use the Graph Visualization application:

• Standalone mode

  If you install the Graph Server rpm file, the Graph Visualization application starts up by default when you start the PGX server and is reachable at https://localhost:7007/ui.

• Custom web container mode

  You can download the Graph Webapps package which contains a web application archive (WAR) file. You can deploy this file into your Oracle Weblogic 12.2 (or later) or Apache Tomcat (9.x or later) web containers.

6.3 Deploying Graph Visualization Application

This section describes the various methods to deploy the Graph Visualization Application.

• How to Deploy the Graph Visualization Application
  You can use the instructions in this section to deploy the Graph Visualization application.
• Deploying Graph Visualization Application in Oracle WebLogic Server
  The following instructions are for deploying Graph Visualization application in Oracle WebLogic Server 12.2.1.3. You might need to make slight modifications, as appropriate, for different versions of the Weblogic Server.

6.3.1 How to Deploy the Graph Visualization Application

You can use the instructions in this section to deploy the Graph Visualization application.

To change the PGQL execution mode, modify the WEB-INF/web.xml file inside of the Graph Visualization application WAR file named graphviz-<version>-pgviz<graphviz-version>.war.

If you have installed the RPM file, the WAR file is located inside the /opt/oracle/graph/graphviz directory.

If you have downloaded the Oracle Graph Webapps package, the WAR file is located in the root directory of that webapps package.

• To extract the WAR file and directly modify the file contents, run the following command:

  unzip graphviz-*.war -d /tmp/pgviz/

• Edit the web.xml descriptor using any file editor of your choice:

  nano /tmp/pgviz/WEB-INF/web.xml

To configure Graph Visualization application to communicate with a PGX deployment (PGQL on PGX)

1. Locate the graphviz.driver.class context parameter. If applicable, set the value to oracle.pgx.graphviz.driver.PgxDriver (this is the default value):

   <context-param>
       <param-name>graphviz.driver.class</param-name>
       <param-value>oracle.pgx.graphviz.driver.PgxDriver</param-value>
   </context-param>

2. Locate the pgx.base_url context parameter. Modify the value to match your secure PGX deployment endpoint. Use the correct FQDN or IP address, along with the correct port. For example,

   <context-param>
       <param-name>pgx.base_url</param-name>
       <param-value>https://myhost:7007</param-value>
   </context-param>

   Note:

   This step does not have any effect if you use Graph Visualization in standalone mode (RPM installation). The PGX base URL is set automatically to point to the local PGX server.

When Graph Visualization application is using PGQL on PGX the application will use your Oracle Database as identity manager by default. This means that you log into the application using existing Oracle Database credentials (username and password), and the actions which you are allowed to do on the graph server are determined by the roles that have been granted to you in the Oracle Database.

To configure Graph Visualization application to communicate with Oracle Database (PGQL on RDBMS)

1. Locate the graphviz.driver.class context parameter. If applicable, set the value to oracle.pg.rdbms.PgqlDriver:

   <context-param>
       <param-name>graphviz.driver.class</param-name>
       <param-value>oracle.pg.rdbms.PgqlDriver</param-value>
   </context-param>

2. Set the context parameter graphviz.driver.rdbms.jdbc_url referencing the JDBC URL of your Oracle Database. For example:

   <context-param>
       <param-name>graphviz.driver.rdbms.jdbc_url</param-name>
       <param-value>jdbc:oracle:thin:@myhost:1521/myService</param-value>
   </context-param>

   Note:

   Replace above URL with the JDBC URL that you want to use for user authentication.

When Graph Visualization application is using PGQL on RDBMS, the application displays a custom login page and the user can use their Oracle Database credentials for user authentication, using the Oracle Database set mentioned in step 2. After logging in, you can see the graphs that you are granted to see on the Oracle Database.

Repackage the WAR file

cd /tmp/pgviz/
jar -cvf graphviz-<version>-pgviz<graphviz-version>.war *

For the standalone deployment mode, copy the updated WAR file back into /opt/oracle/graph/graphviz and then start the server as usual.

6.3.2 Deploying Graph Visualization Application in Oracle WebLogic Server

The following instructions are for deploying Graph Visualization application in Oracle WebLogic Server 12.2.1.3. You might need to make slight modifications, as appropriate, for different versions of the Weblogic Server.

1. Start WebLogic Server.

   # Start Server
   cd $MW_HOME/user_projects/domains/base_domain
   ./bin/startWebLogic.sh

2. Enable tunneling.

   In order to be able to deploy the Graph Visualization application WAR file over HTTP, you must enable tunneling first. Go to the WebLogic admin console (by default on http://localhost:7001/console). Select Environment (left panel) > Servers (left panel). Click the server that will run graph visualization (main panel). Select (top tab bar), check Enable Tunneling, and click Save.

3. Deploy the WAR File

   To deploy the repackaged WAR file to WebLogic Server, use the following command, replacing the <<...>> markers with values matching your installation:

   cd $MW_HOME/user_projects/domains/base_domain
   source bin/setDomainEnv.sh
   java weblogic.Deployer -adminurl <<admin-console-url>> -username <<admin-user>> -password <<admin-password>> -deploy -upload <<path/to>>/graphviz-<<version>>-pgviz<<graphviz-version>>.war

   To undeploy, you can use the following command:

   java weblogic.Deployer -adminurl <<admin-console-url>> -username <<admin-user>> -password <<admin-password>> -name <<path/to>>/graphviz-<<version>>-pgviz<<graphviz-version>>.war -undeploy

   To test the deployment, navigate using your browser to: https://<<fqdn-ip>>:<<port>>/ui.

   The browser prompts for your credentials (user name and password). After you log in, the Graph Visualization user interface (UI) appears and the graphs from PGX is retrieved.

6.4 Using GraphViz

The principal points of entry for the GraphViz application are the query editor and the graph lists.

When you start GraphViz, the graph list will be populated with the graphs loaded in PGX. To run queries against a graph, select that graph. The query lets you write PGQL queries that can be visualized. (PGQL is the SQL-like query language supported by GraphViz.)

Once the query is ready and the desired graph is selected, click the Run icon to execute the query. The following figure shows a query visualization identifying all edges that are directed edges from any vertex in the graph to any other vertex.

Figure 6-1 Query Visualization

Description of "Figure 6-1 Query Visualization"

When a query is successful, the graph visualization is displayed, including nodes and their connections. You can right-click a node or connection to display tooltip information, and you can drag the nodes around.

• GraphViz Modes
  The buttons on the right let you switch between two modes: Graph Manipulation and Zoom/Move.
• GraphViz Settings
  You can click the Settings gear icon to display the GraphViz settings window.
• Using Live Search
  Live Search lets you to search the displayed graph and add live fuzzy search score to each item, so you can create a Highlight which visually shows the results of the search in the graph immediately.
• Using URL Parameters to Control GraphViz
  You can provide GraphViz input data through URL parameters instead of using the form fields of the user interface.

6.4.1 GraphViz Modes

The buttons on the right let you switch between two modes: Graph Manipulation and Zoom/Move.

• Graph Manipulation mode lets you execute actions that modify the visualization. These actions include:
  • Drop removes selected vertices from visualization. Can also be executed from the tooltip.
  • Group selects multiple vertices and collapses them into a single one.
  • Ungroup selects a group of collapsed vertices and ungroups them.
  • Expand retrieves a configurable number of neighbors (hops) of selected vertices. Can also be executed from the tooltip.
  • Focus, like Expand, retrieves a configurable number of neighbors, but also drops all other vertices. Can also be executed from the tooltip.
  • Undo undoes the last action.
  • Redo redoes the last action.
  • Reset resets the visualization to the original state after the query.
• Zoom/Move mode lets you zoom in and out, as well as to move to another part of the visualization. The Pan to Center button resets the zoom and returns the view to the original one.

An additional mode, called Sticky mode, lets you cancel the action of dragging the nodes around.

6.4.2 GraphViz Settings

You can click the Settings gear icon to display the GraphViz settings window.

The settings window lets you modify some parameters for the visualization, and it has tabs for General, Visualization, and Highlights. The following figure shows this window, with the Visualization tab selected.

Figure 6-2 GraphViz Settings Window

Description of "Figure 6-2 GraphViz Settings Window"

The General tab includes the following:

• Number of hops: The configurable number of hops for the expand and focus actions.
• Truncate label: Truncates the label if it exceeds the maximum length.
• Max. visible label length: Maximum length before truncating.
• Show Label On Hover: Controls whether the label is shown on hover.
• Display the graph legend: Controls whether the legend is displayed.

The Visualization tab includes the following:

• Theme: Select a light or dark mode.
• Edge Style: Select straight or curved edges.
• Edge Marker: Select arrows or no edge marker. This only applies to directed edges.
• Similar Edges: Select keep or collect.
• Page Size: Specify how many vertices and edges are displayed per page.
• Layouts: Select between different layouts (random, grid, circle, concentric, ...).
• Vertex Label: Select which property to use as the vertex label.
• Vertex Label Orientation: Select the relative position of the vertex label.
• Edge Label: Select which property to use as the edge label.

The Highlights tab includes customization options that let you modify the appearance of edges and vertices. Highlighting can be applied based on conditions (filters) on single or multiple elements. The following figure shows a condition (country = United States) and visual highlight options for vertices.

Figure 6-3 Highlights Options for Vertices

Description of "Figure 6-3 Highlights Options for Vertices"

A filter for highlights can contain multiple conditions on any property of the element. The following conditions are supported.

• = (equal to)
• < (less than)
• <= (less than or equal to)
• > (greater than)
• >= (greater than or equal to)
• != (not equal to)
• ~ (filter is a regular expression)
• * (any: like a wildcard, can match to anything)

The visual highlight customization options include:

• Edges:
  • Width
  • Color
  • Label
  • Style
  • Animations
• Vertices:
  • Size
  • Color
  • Icon
  • Label
  • Image
  • Animations

You can export and import highlight options by clicking the Save and Import buttons in the main window. Save lets you persist the highlight options, and Load lets you apply previously saved highlight options.

When you click Save, a file is saved containing a JSON object with the highlights configuration. Later, you can load that file to restore the highlights of the saved session.

6.4.3 Using Live Search

Live Search lets you to search the displayed graph and add live fuzzy search score to each item, so you can create a Highlight which visually shows the results of the search in the graph immediately.

If you run a query, and a graph is displayed, you can add the live search, which is on the settings dialog. On the bottom of the General tab, you will see these options.

• Enable Live Search: Enables the Live Search feature, adds the search input to the visualization, and lets you further customize the search.
• Enable Search In: You can select whether you want to search the properties of Vertices, Edges, or both.
• Properties To Search: Based on what you selected for Enable Search In, you can set one or more properties to search in. For example, if you disable the search for edges but you had a property from edges selected, it will be stored and added back when you enable search for the edges again. (This also works for vertices.)
• Advanced Settings: You can fine-tune the search even more. Each of the advanced options is documented with context help, visible upon enabling.
  • Location: Determines approximately where in the text the pattern is expected to be found.
  • Distance: Determines how close the match must be to the fuzzy location (specified by location). An exact letter match which is distance characters away from the fuzzy location would score as a complete mismatch. A distance of 0 requires the match be at the exact location specified, a distance of 1000 would require a perfect match to be within 800 characters of the location to be found using a threshold of 0.8.
  • Maximum Pattern Length: The maximum length of the pattern. The longer the pattern (that is, the search query), the more intensive the search operation will be. Whenever the pattern exceeds this value, an error will be thrown.
  • Min Char Match: The minimum length of the pattern. Whenever the pattern length is below this value, an error will be thrown.

When the search is enabled, the input will be displayed in the top left part of the Graph Visualization component. If you start typing, the search will add a score to every vertex or edge, based on the settings and the search match.

To be able to see the results visually, you have to add a Highlight with interpolation set to a Live Search score and other settings based on the desired visual change.

6.4.4 Using URL Parameters to Control GraphViz

You can provide GraphViz input data through URL parameters instead of using the form fields of the user interface.

If you supply the parameters in the URL, the GraphViz application automatically executes the specified query and hides the input form fields from the screen, so only the resulting visualization output is visible. This feature is useful if you want to embed the resulting graph visualization into an existing application, such as through an iframe.

The following table specifies the available URL parameters:

Table 6-1 Available URL Parameters

Parameter Name	Value (must be URL encoded)	Type	Optional?
graph	Graph name	string	No
parallelism	Degree of parallelism desired	number	Yes (defaults to server-side default parallelism)
query	PQL query	string	No

The following URL shows an example of visualizing the PGQL query SELECT v, e MATCH (v) -[e]-> () LIMIT 10 on graph myGraph with parallelism 4:

https://myhost:7007/ui/?query=SELECT%20v%2C%20e%20MATCH%20%28v%29%20-%5Be%5D-%3E%20%28%29%20LIMIT%2010&graph=myGraph&parallelism=4