1. Graph Developer's Guide for Property Graph
  2. Getting Started with Oracle Property Graphs
  3. Property Graph Support Overview
  4. Interactive Graph Shell

1.7 Interactive Graph Shell

Both the Oracle Graph server and client packages contain an interactive command-line application for interacting with all the Java APIs of the product, locally or on remote computers.

This interactive graph shell dynamically interprets command-line inputs from the user, executes them by invoking the underlying functionality, and can print results or process them further. The graph shell provides a lightweight and interactive way of exercising graph functionality without creating a Java application.

The graph shell is especially helpful if want to do any of the following:

  • Quickly run a "one-off" graph analysis on a specific data set, rather than creating a large application
  • Run getting started examples and create demos on a sample data set
  • Explore the data set, trying different graph analyses on the data set interactively
  • Learn how to use the product and develop a sense of what the built-in algorithms are good for
  • Develop and test custom graph analytics algorithms

This graph shell is implemented on top of the Java Shell tool (JShell). As such, it inherits all features provided by JShell such as tab-completion, history, reverse search, semicolon inference, script files, and internal variables.

The graph shell connects to a graph server (PGX) specified by the --base_url parameter. When the --base_url parameter is not specified, the graph shell creates a local PGX instance, to run graph functions in the same JVM as the shell as described in Developing Applications Using Graph Server Functionality as a Library.

Starting the Graph Shell

The Graph Shell uses JShell, which means the shell needs to run on Java 11 or later.

After installation, the shell executables are found in /opt/oracle/graph/bin after server installation, and <CLIENT_INSTALL_DIR>/bin after the client installation.

To launch the graph shell and connect to a graph server (PGX) enter the following in your terminal:

./bin/opg4j --base_url https://<host>:7007 --username <graphuser>
where :
  • <host>: is the server host
  • <graphuser>: is the database user

    Note:

    You will be prompted for the database password.

Note:

The graph server (PGX), listens on port 7007 by default. If needed, you can configure the graph server to listen on a different port by changing the port value in the server configuration file (server.conf). See Configuring the In-Memory Graph Server (PGX) for details.

When the shell has started, the following command line prompt appears:

opg4j>

If you have multiple versions of Java installed, you can easily switch between installations by setting the JAVA_HOME variable before starting the shell. For example:

export JAVA_HOME=/usr/lib/jvm/java-11-oracle

Command-line Options

To view the list of available command-line options, add --help to the opg4j command: 

./bin/opg4j --help

Batch Execution of Scripts

The graph shell can execute a script by passing the path(s) to the script(s) to the opg4j command. For example: 

./bin/opg4j /path/to/script.jsh

Predefined Functions

The graph shell provides the following utility functions:

  • println(String): A shorthand for System.out.println(String).
  • loglevel(String loggerName, String levelName): A convenient function to set the loglevel.

The loglevel function allows you to set the log level for a logger. For example, loglevel("ROOT", "INFO") sets the level of the root logger to INFO. This causes all logs of INFO and higher (WARN, ERROR, FATAL) to be printed to the console.

Script Arguments

You can provide parameters to the script. For example:

./bin/opg4j /path/to/script.jsh script-arg-1 script-arg-2

In this example, the script /path/to/script.jsh can access the arguments via the scriptArgs system property. For example: 

println(System.getProperty("scriptArgs"))// Prints: script-arg-1 script-arg-2

Staying in Interactive Mode

By default, the graph shell exits after it finishes execution. To stay in interactive mode after the script finishes successfully, pass the --keep_running flag to the shell. For example: 

./bin/opg4j -b https://myserver.com:7007/ /path/to/script.jsh --keep_running

Parent topic: Property Graph Support Overview