1. Graph Developer's Guide for Property Graph
  2. PGQL Property Graphs
  3. Getting Started with the Client Tools
  4. Interactive Graph Shell CLIs

12.1 Interactive Graph Shell CLIs

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

The interactive graph shells dynamically interpret command-line inputs from the user, execute them by invoking the underlying functionality, and can print results or process them further. The graph shells provide a lightweight and interactive way of exercising graph functionality without creating a Java or Python application.

The graph shells are especially helpful if you 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

The graph shell for the Java API (OPG4J) 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 for the Python API (OPG4Py) uses IPython in case it is installed.

The following sections explain in detail on how to start the graph shell CLIs:

See Also:

Parent topic: Getting Started with the Client Tools

12.1.1 Starting the OPG4J Shell

Launching the OPG4J Shell

The Java shell executables are found in /opt/oracle/graph/bin after the graph server (PGX) installation, and in <CLIENT_INSTALL_DIR>/bin after the Java client installation.

The OPG4J shell uses JShell, which means the shell needs to run on Java 11 or later. See Installing the Java Client From the Graph Server and Client Downloads for more details on the prerequisites. You can then launch the OPG4J shell by entering the following in your terminal: 

cd /opt/oracle/graph
./bin/opg4j

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

For an introduction type: /help intro
Oracle Graph Server Shell 24.2.0
Variables instance, session, and analyst ready to use.
opg4j>

By default, the OPG4J 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.

Command-line Options

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

./bin/opg4j --help

To start the opg4j shell without connecting to the graph server (PGX), use the --no_connect option as shown: 

./bin/opg4j --no_connect

Starting the OPG4J Shell on Remote Mode

The OPG4J shell can connect to a graph server (PGX) instance that is running on another JVM (possibly on a different machine). In order to launch the OPG4J shell in remote mode, you must specify the --base_url parameter as shown:
./bin/opg4j --base_url https://<host>:7007 --username <graphuser>
where :
  • <host>: is the server host
  • <graphuser>: is the database user

    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 Graph Server (PGX) for details.

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

Oracle Graph Server Shell 24.2.0
Variables instance, session, and analyst ready to use.
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

Batch Execution of Scripts

The OPG4J 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 OPG4J 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 also provide parameters to the script executed by the graph server (PGX). For example:

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

The script /path/to/script.jsh can then access the arguments through the arguments.scriptArgs variable. The arguments are provided as an array of strings (String[]). For example: 

Arrays.stream(arguments.scriptArgs).forEach((a) -> 
    System.out.println(a));

The preceding example prints the output as shown:

script-arg-1
script-arg-2

Staying in Interactive Mode

By default, the OPG4J 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: Interactive Graph Shell CLIs

12.1.2 Starting the OPG4Py Shell

Launching the OPG4Py Shell

The OPG4Py shell executables are found in /opt/oracle/graph/bin after the graph server (PGX) installation, and in <CLIENT_INSTALL_DIR>/bin after the Python client installation.

Before launching the OPG4Py shell, verify that your system meets these prerequisites. You can then launch the OPG4Py shell by entering the following in your terminal: 

cd /opt/oracle/graph
./bin/opg4py

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

Oracle Graph Server Shell 24.2.0
>>>

If IPython is installed the following prompt will appear:

In [1]:

By default, the OPG4Py 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.

Command-line Options

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

./bin/opg4py --help

To start the PyPGX shell without connecting to the graph server (PGX), use the --no_connect option as shown: 

./bin/opg4py --no_connect

Starting the OPG4Py Shell on Remote Mode

The OPG4Py shell can connect to a graph server (PGX) instance that is running on another JVM (possibly on a different machine). In order to launch the OPG4Py shell in remote mode, you must specify the --base_url parameter as shown:
./bin/opg4py --base_url https://<host>:7007 --username <graphuser>
where :
  • <host>: is the server host
  • <graphuser>: is the database user

    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 Graph Server (PGX) for details.

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

Oracle Graph Server Shell 24.2.0
>>>

Parent topic: Interactive Graph Shell CLIs