Running Custom Graph Algorithms

This section explains the API's ability to compile and run custom algorithms. The APIs for built-in algorithms can be found in our Analyst API section.

Compiling Custom Algorithms

As discussed in the Green-Marl language overview, PGX allows users to implement custom graph algorithms with the Green-Marl DSL. PGX then compiles the given graph algorithm, so that it may be executed.

The following are the PgxSession methods used to compile custom algorithms:

CompiledProgram compileProgram(String path)
CompiledProgram compileProgram(InputStream code)
CompiledProgram compileProgramCode(String code)

The Green-Marl code to compile can either be assigned directly (code) or via a file path or InputStream.

This method returns a CompiledProgram instance that contains methods to run the compiled algorithm as well as signature information.

Refer to the related javadoc for details.

Running Algorithms

The following generic methods in CompiledProgram are used to run compiled algorithms:

PgxFuture<AnalysisResult<T>> runAsync(Object... args)
PgxFuture<AnalysisResult<T>> runAsync(PoolType targetPool, Object... args)

Blocking equivalent:

AnalysisResult<T> run(Object... args)
AnalysisResult<T> run(PoolType targetPool, Object... args)

Fundamentally, the method invokes the compiled algorithm with the given arguments (args).

Note: The given args must match the signature of the graph algorithm. Otherwise, PGX throws a type mismatch exception to the client. For example, if the Green-Marl program you compiled has the signature

my_algorithm(G: graph, d: double; result: nodeProp<double>, avg: int): double

Then you must provide Java objects of type PgxGraph, double, VertexProperty<ID, Double> and Scalar<Integer>, in that order. Note: Primitive out arguments have to be of type Scalar. The returned AnalystResult should be parametrized with AnalysisResult<Double>.

The user has the option to choose a specific thread pool in PGX with targetPool. In 20.1.1, PGX provides several different thread pools for multiple clients to make progress concurrently. Refer to the related javadoc for details.

Each of the above methods returns an AnalysisResult, which contains not only the return value of the algorithm, but also other information such as exception status and execution time.