Interactive Shell

Lightweight, Interactive Graph Analysis via the PGX Shell

The PGX shell is an interactive command-line application for interacting with the PGX runtime on local or remote computers. The PGX shell dynamically interprets command-line inputs from the user, executes them by invoking the underlying PGX functionality and can print results or process them further. The PGX shell provides a light-weight and interactive way of exercising PGX functionality without creating a Java application.

The PGX shell is especially helpful in the following use cases:

• The user is interested in quickly running a one-off graph analysis on a specific data set, rather than creating a large application.
• The user is exploring the data set; trying different graph analyses on the data set interactively.
• Learning how to use PGX and developing a sense of what the built-in algorithms are good at.
• Developing and testing custom graph analytics algorithms.

The same PGX shell executable can be used in both local mode and remote mode.

Highlights of the Features

The PGX shell is implemented on top of the Java Shell tool (jshell). As such, the PGX shell inherits all features provided by JShell such as tab-completion, history, reverse search, semicolon inference, script files, internal variables, etc. The PGX shell provides the following features on top of JShell:

• Automatic PGX initialization: The PGX shell automatically connects to a PGX instance (either remote or embedded depending on the --base_url command-line option) and creates a PGX session. If --base_url is not provided, a new local PGX instance and session are created.

Starting the PGX Shell

Prerequisites

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

PGX Shell Executable

After installing PGX the PGX shell (pgx-jshell) can be found at $PGX_HOME/bin. The shell may be launched by entering the following in your terminal:

cd $PGX_HOME
./bin/pgx-jshell

Check the Prompt

Once the PGX shell has started, the following command line prompt will appear:

pgx>

Command-line Options

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

./bin/pgx-jshell --help

Embedded Vs. Remote Mode

The PGX shell can be started in local (embedded) mode or remote mode. By default the PGX shell starts in local mode, which means a local PGX instance is created. The local PGX instance will try to load a PGX configuration file from $PGX_HOME/conf/pgx.conf. You can change the location of the configuration file by passing the --pgx_conf command-line option followed by the path to the configuration file:

# start local PGX instance with custom config
./bin/pgx-jshell --pgx_conf path/to/my/pgx.conf

The PGX shell can also be started in remote mode. In that case the shell connects to a PGX instance that runs in a separate JVM (possibly on a different machine). To launch the shell in remote mode, specify the base URL of the server with the --base_url option:

./bin/pgx-jshell --base_url https://myserver.com:7007/pgx

Please refer to the client configuration guide for more remote-specific configuration options.

Batch-Execution of PGX Scripts

The PGX shell can execute a script by passing the path(s) to the script(s) to the pgx command:

./bin/pgx-jshell /path/to/script.jsh

Predefined Functions

The PGX shell provides two 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 has the effect that all logs of INFO and higher (i.e. WARN, ERROR, FATAL) are printed to the console.

Script Arguments

You can provide parameters to the script:

./bin/pgx-jshell /path/to/script.jsh script-arg-1 script-arg-2

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

Stay in Interactive Mode

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

./bin/pgx-jshell -b https://myserver.com:7007/pgx -u scott -p tiger /path/to/script.jsh --keep_running