Using Graph Studio Oracle Autonomous Database
Using Graph Studio Oracle Autonomous Database
F36880-10
December 2021
Oracle Cloud Using Graph Studio in Oracle Autonomous Database,
F36880-10
Contributors: Chuck Murray, Korbi Schmid, Jayant Sharma, Steve Serra, Melliyal Annamalai, Gabriela
Montiel, Carol Palmer, Siva Ravada
This software and related documentation are provided under a license agreement containing restrictions on
use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your
license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license,
transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse
engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is
prohibited.
The information contained herein is subject to change without notice and is not warranted to be error-free. If
you find any errors, please report them to us in writing.
If this is software or related documentation that is delivered to the U.S. Government or anyone licensing it on
behalf of the U.S. Government, then the following notice is applicable:
U.S. GOVERNMENT END USERS: Oracle programs (including any operating system, integrated software,
any programs embedded, installed or activated on delivered hardware, and modifications of such programs)
and Oracle computer documentation or other Oracle data delivered to or accessed by U.S. Government end
users are "commercial computer software" or "commercial computer software documentation" pursuant to the
applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, the use,
reproduction, duplication, release, display, disclosure, modification, preparation of derivative works, and/or
adaptation of i) Oracle programs (including any operating system, integrated software, any programs
embedded, installed or activated on delivered hardware, and modifications of such programs), ii) Oracle
computer documentation and/or iii) other Oracle data, is subject to the rights and limitations specified in the
license contained in the applicable contract. The terms governing the U.S. Government’s use of Oracle cloud
services are defined by the applicable contract for such services. No other rights are granted to the U.S.
Government.
This software or hardware is developed for general use in a variety of information management applications.
It is not developed or intended for use in any inherently dangerous applications, including applications that
may create a risk of personal injury. If you use this software or hardware in dangerous applications, then you
shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure its
safe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this
software or hardware in dangerous applications.
Oracle, Java, and MySQL are registered trademarks of Oracle and/or its affiliates. Other names may be
trademarks of their respective owners.
Intel and Intel Inside are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are
used under license and are trademarks or registered trademarks of SPARC International, Inc. AMD, Epyc,
and the AMD logo are trademarks or registered trademarks of Advanced Micro Devices. UNIX is a registered
trademark of The Open Group.
This software or hardware and documentation may provide access to or information about content, products,
and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly
disclaim all warranties of any kind with respect to third-party content, products, and services unless otherwise
set forth in an applicable agreement between you and Oracle. Oracle Corporation and its affiliates will not be
responsible for any loss, costs, or damages incurred due to your access to or use of third-party content,
products, or services, except as set forth in an applicable agreement between you and Oracle.
Contents
Preface
Audience vi
Documentation Accessibility vi
Related Documents vi
Conventions vi
iii
6 Work with Notebooks in Graph Studio
About Notebooks 6-1
Create a Notebook 6-1
Available Notebook Interpreters 6-2
Markdown 6-3
Java (PGX) Interpreter 6-3
Python (PGX) Interpreter 6-5
PGQL (PGX) Interpreter 6-6
Reference Graphs in Notebook Paragraphs 6-7
Store a PgxFrame in Database 6-9
Visualize Output of Paragraphs 6-10
Apply Machine Learning on a Graph 6-10
Dynamic Forms 6-15
Paragraph Dependencies 6-17
Paragraph Comments 6-17
Keyboard Shortcuts for Notebooks 6-17
Find a Notebook 6-18
Move a Notebook 6-18
Example Notebooks 6-19
iv
Cancel a Job 9-3
Retry a Job 9-3
Delete a Job 9-4
Retention of Finished Jobs 9-4
What to do When a Job Fails 9-5
v
Preface
Preface
This document describes how to use and manage Graph Studio in Autonomous
Database and provides references to related documentation.
Audience
This document is intended for Oracle Cloud users who want to use and manage Graph
Studio to load and query property graph data.
Documentation Accessibility
For information about Oracle's commitment to accessibility, visit the Oracle
Accessibility Program website at http://www.oracle.com/pls/topic/lookup?
ctx=acc&id=docacc.
Related Documents
• Getting Started With Oracle Cloud
• Oracle Database Graph Developer's Guide for Property Graph
Conventions
The following text conventions are used in this document:
Convention Meaning
boldface Boldface type indicates graphical user interface elements associated with an
action, or terms defined in text or the glossary.
italic Italic type indicates book titles, emphasis, or placeholder variables for which you
supply particular values.
monospace Monospace type indicates commands within a paragraph, URLs, code in
examples, text that appears on the screen, or text that you enter.
vi
1
Get Started Using Graphs
Graph Studio, a component of Oracle Autonomous Database, simplifies the task of
developing applications that use graph analysis. The following features, in particular, support
the development of high-performing, high-security applications:
• Automatic database administration. Routine database administration tasks such as
patching and taking backups are performed automatically, so you can concentrate on
developing your application.
• Automatic performance tuning. You spend less time defining and tuning your database.
• Predefined, workload-specific database services.
• Graph data stored in an Autonomous Database is fully accessible using Structured Query
Language (SQL) and PGQL (Property Graph Query Language), for analytics and
interfacing with relational tools.
• Interactive graph visualization. You can visualize the graph query results to find
connections, patterns and dependencies within graph data.
Topics
• About Graph Data Support in Autonomous Database
• Typical Workflow for Using Graph Studio
1-1
Chapter 1
Typical Workflow for Using Graph Studio
1-2
2
Introduction to Graph Data in Autonomous
Database
Oracle Autonomous Database contains features that enable it to function as a scalable
property graph database.
This chapter outlines key graph data modeling and analysis concepts and the interactive
Graph Studio for working with graphs in an Autonomous Database.
Topics
• Overview of Graph Data in Autonomous Database
• Key Terms and Concepts for Working with Graphs
• Graph Studio: Interactive, Self-Service User Interface
• Use Accessibility Mode
• Tutorials and Other Resources
Property Graph
A property graph consists of vertices that are linked together by edges. Both vertices and
edges can have a set of properties attached to them. Common properties are id and label.
The label property often identifies what the vertex or edge represent. For example, a vertex
representing a bank account may have the label Account, while an edge representing a
transfer of funds between accounts may have the label Transfer.
A property graph is the main data structure used with Graph Studio.
Graph Modeler
Oracle Autonomous Database provides a tool called the Graph Modeler, which makes it easy
to create a property graph data structure from existing relational data.
2-1
Chapter 2
Key Terms and Concepts for Working with Graphs
Graph Model
A graph model is a mapping from relational data to graph data. The mapping is
persisted (stored) when you create a graph so that you can reuse it to create a new
snapshot of the graph without creating the same model again. The modeling and
creation process is automated in Graph Studio.
Graph Studio
Graph Studio is a user interface available with Oracle Autonomous Database that
provides access to all available graph features, such as querying (with PGQL) and
analytics.
Graph Algorithm
A graph algorithm is a pre-packaged set of instructions to traverse or analyze a graph.
For example, you can find a shortest path or important vertices in your graph.
PageRank is a well known graph algorithm, which ranks the importance of vertices.
Graph Studio notebooks expose over 60 such algorithms as built-in functions.
Notebooks
Notebooks are interactive browser-based applications that enable data engineers,
analysts, and scientists to be more productive by developing, organizing, executing,
and sharing code, and by visualizing results without using the command line or
needing to install anything. Notebooks enable you to execute code, to work
interactively with long workflows, and to collaborate on projects.
In addition to code execution, notebooks support a large set of built-in visualization
capabilities.
Job
A job is a potentially long-running asynchronous operation in Graph Studio. An
example of a job is loading a graph into memory or creating a graph from tables.
2-2
Chapter 2
Graph Studio: Interactive, Self-Service User Interface
Overview
The Overview menu link directs you to the main or landing page. It consists of two sections:
The right section is a welcome panel with links to:
• A tour of the interface. Click the "Take a Tour" link for a guided of the user interface
elements.
• Getting started guides on graph models and graphs, notebooks, and supported APIs.
• A Learn More section with links to documentation, blogs, and tutorials.
The middle section shows either of the following:
2-3
Chapter 2
Graph Studio: Interactive, Self-Service User Interface
• a collapsible panel showing the steps in a typical workflow with a link to Models
page for a first-time user as shown in the preceding figure.
• cards listing existing models, graph, notebooks, and jobs for a returning user with
existing content as shown in the following screen .
Models
The Models menu link directs you to the Models page. This page consists of a top
main pane that lists all existing graph models and a details pane at the bottom to
display the model details.
If there are no models, the page will be displayed as shown in the following figure. The
Start Modeling link initiates a graph modeling creation workflow.
If there are existing models, then the page lists all the available models as rows in a
table. The page also contains a Create button to get started on a new model and
graph as shown in the following figure:
2-4
Chapter 2
Graph Studio: Interactive, Self-Service User Interface
Clicking on an existing model, displays the details for the selected model in the details pane
of the Models page. You can choose to rename or delete that model. Additionally, you can
also share the model with other users.
Graphs
The Graphs menu link directs you to the Graphs page which lists all existing graphs. Clicking
on a listed graph, displays the graph details. You can optionally load the graph into memory,
share the graph with other users, rename or delete the graph.
You can perform one of the following supported options on this page:
• Create a new graph.
• Query an existing graph using PGQL.
2-5
Chapter 2
Graph Studio: Interactive, Self-Service User Interface
Query Playground
Clicking Query on the Graphs page will navigate you to the Query Playground page. It
is a notepad for entering and executing simple PGQL queries to validate a newly
created graph. It is not meant for testing complex queries or for use in a production
environment.
Queries submitted in the playground are executed directly against the graph stored in
Autonomous Database. This means they do not require Graph Studio to be attached
to an environment or initially have the graph loaded into memory.
Notebooks
The Notebooks menu link takes you to the Notebooks page that lists existing
notebooks.
Templates
The Templates menu link directs you to the Templates page. This page consists of a
left pane that lists all the existing templates. They are custom built templates with
predefined graph visualization and notebook settings. Clicking on an existing template
displays the custom data settings on the right pane. These template formats are
applied to a notebook.
2-6
Chapter 2
Use Accessibility Mode
Jobs
The Jobs menu link directs you to the Jobs page that lists previous and current jobs.
2-7
Chapter 2
Tutorials and Other Resources
2-8
Chapter 2
Tutorials and Other Resources
• Continue reading the documentation starting with the major topics such as Work with
Jobs in Graph Studio, Work with Notebooks in Graph Studio, and Visualize and Interact
with Graph Data in Graph Studio.
Then try one or more of the tutorials.
or
• Try one or more of the tutorials and use this documentation as needed for explanations
and reference.
Note:
With both approaches, you are encouraged to first read the following topics for
understanding:
• Key Terms and Concepts for Working with Graphs
• Graph Studio: Interactive, Self-Service User Interface
2-9
3
Create a Graph User
Working with Graphs in Graph Studio, requires users with granted roles.
You can create Graph users with the correct set of roles and privileges using Oracle
Database Actions.
Before you begin, you must access Oracle Database Actions from the Oracle Cloud
Infrastructure Console as the ADMIN user. See Access Database Actions as ADMIN for more
information.
1. Click Administration from the Database Actions Menu and then click Database Users.
2. Click Create User on the Database Users page, in the All Users area.
3. Enter a user name , password and enter the password again to confirm the password.
4. Switch on the Graph Enable toggle button for the user.
The GRAPH_DEVELOPER role gets automatically assigned to the user.
5. Switch on the REST Enable toggle button to provide the new user access to Database
Actions in Autonomous Database.
Note:
You must REST enable the new graph user in order to perform any of the
following Database Actions:
• Execute SQL statements or queries in the SQL worksheet
• Load and access data from local files
.
3-1
4
Access Graph Studio Application
You can access Graph Studio Application from Autonomous Database.
You can connect to Graph Studio using Oracle Cloud Infrastructure Console.
Topics
• Access Graph Studio Using Oracle Cloud Infrastructure Console
4-1
Chapter 4
Access Graph Studio Using Oracle Cloud Infrastructure Console
4. Enter your graph enabled username and password and then click Sign In.
You are now connected to Oracle Autonomous Database using Graph Studio.
4-2
5
Model and Create a Graph in Graph Studio
There are several ways to create a graph using Graph Studio in the Autonomous Database.
• Create a graph from scratch.
• Create a graph from existing relational tables.
Topics:
• Create a Graph from Scratch
• Create a Graph from Existing Relational Tables
• Manage Graphs
Note:
• You can create a PG View graph only from the Modeler page. See Create a
Graph from Existing Relational Tables for more information.
• See Manage Graphs for more information on the types of graphs that are
supported in Graph Studio.
5-1
Chapter 5
Create a Graph from Existing Relational Tables
Note:
To support graphs created from PG Objects, your database will
consume additional storage space because Graph Studio maintains a
copy of the data from the source tables. Depending on the volume of
your data, this operation may be time consuming.
3. Select the tables that are required as input for the graph and move them to the
Selections section on the right, as shown:
The following table shows a few supported input types and the corresponding
default mapping when transformed into graph properties:
5-2
Chapter 5
Create a Graph from Existing Relational Tables
1
Data types for a Property Graph View share a one-to-one mapping with Oracle Database data types.
5-3
Chapter 5
Create a Graph from Existing Relational Tables
This redirects you to the Jobs page, where a graph creation job is initiated.
On successful completion of the job, the graph is created and loaded into memory.
5-4
Chapter 5
Manage Graphs
Manage Graphs
You can load a graph into memory, share, rename, delete or preview a graph.
To manage graphs:
1. Click Graphs on the left navigation menu and navigate to the Graphs page.
You can see a list of graphs for which you have access in the Autonomous Database as
shown in the following figure.
Action Description
Note:
This action is disabled for PG View graphs.
5-5
Chapter 5
Manage Graphs
Action Description
Note:
Optionally, you can load a PG View graph by name directly in the notebook.
See Reference Graphs in Notebook Paragraphs for an example.
5-6
6
Work with Notebooks in Graph Studio
After you create a graph, you can analyze it and visualize the results by using a notebook.
Topics
• About Notebooks
• Create a Notebook
• Available Notebook Interpreters
• Reference Graphs in Notebook Paragraphs
• Store a PgxFrame in Database
• Visualize Output of Paragraphs
• Apply Machine Learning on a Graph
• Dynamic Forms
• Paragraph Dependencies
• Paragraph Comments
• Keyboard Shortcuts for Notebooks
• Find a Notebook
• Move a Notebook
• Example Notebooks
About Notebooks
A notebook is an interactive, browser-based object that enables data engineers, data
analysts, and data scientists to be more productive by developing, organizing, executing, and
sharing code, and by visualizing results without using the command line or needing to install
anything. Notebooks enable you to execute code and to work interactively with long
workflows.
You can create any number of notebooks, each of which can be a collection of
documentation, snippets of code, and other visualizations. Every entered user input is held in
paragraphs, each of which is configured to be executable with a particular interpreter.
Interpreters, for example, can be markdown or PGX. Results can be displayed in a variety of
ways, such as tables, charts, and as an interactive graph.
Create a Notebook
You can create a notebook to query, analyze and visualize a graph.
The following are the steps to create a notebook:
1. Click Notebooks on the left navigation menu and navigate to the Notebooks page.
6-1
Chapter 6
Available Notebook Interpreters
Note:
Graph Studio allows you to configure memory for the interpreters. See
Manually Manage the Environment for more information.
6-2
Chapter 6
Available Notebook Interpreters
Topics
• Markdown
• Java (PGX)
• Python (PGX)
• PGQL (PGX)
Markdown
You can format text using Markdown in a notebook paragraph.
Markdown paragraphs start with %md and accept Markdown syntax as input. When executed,
the underlying Markdown interpreter converts the input into HTML output. You can use the
Markdown interpreter to explain your notebook in a formatted way and to add media
elements like images or even videos.
Tip:
You can hover over the bottom part of a notebook paragraph and click the Add
Markdown Paragraph icon to open a Markdown paragraph instantly in the
notebook.
%md
# My First Notebook
This is my first paragraph
Tip:
You can hover over the bottom part of a notebook paragraph and click the Add
Java-PGX Paragraph icon to open a Java (PGX) paragraph instantly in the
notebook.
6-3
Chapter 6
Available Notebook Interpreters
import java.io.*
import java.util.concurrent.TimeUnit
import org.apache.commons.io.*
import oracle.pgx.common.*
import oracle.pgx.common.mutations.*
import oracle.pgx.common.types.*
import oracle.pgx.api.*
import oracle.pgx.api.admin.*
import oracle.pgx.config.*
import oracle.pgx.api.filter.*
import oracle.pgx.api.PgxGraph.SortOrder
import oracle.pgx.api.PgxGraph.Degree
import oracle.pgx.api.PgxGraph.Mode
import oracle.pgx.api.PgxGraph.SelfEdges
import oracle.pgx.api.PgxGraph.MultiEdges
import oracle.pgx.api.PgxGraph.TrivialVertices
%java-pgx
var g = session.getGraph("MY_FIRST_GRAPH") // reference in-memory
graphs by name
session.createAnalyst().pagerank(g) // run algorithms
You can also define new helper classes/functions inside paragraphs. For example:
%java-pgx
import java.lang.Math // import
6-4
Chapter 6
Available Notebook Interpreters
Internally, the Java (PGX) interpreter operates on the same PGX session as the Python
(PGX) interpreter. So, any analysis results computed in Python (PGX) paragraphs are
available for querying in subsequent Java (PGX) paragraphs.
The following example show the PageRank values computed on a graph in a Python (PGX)
paragraph. The pagerank property on the graph is then queried in the subsequent Java(PGX)
paragraph.
%python-pgx
g = session.get_graph("MY_FIRST_GRAPH")
analyst.pagerank(g,tol=0.001,damping=0.85,max_iter=100,norm=False,rank='pager
ank')
%java-pgx
session.getGraph("MY_FIRST_GRAPH").queryPgql("SELECT x.pagerank FROM MATCH
(x)").print(out,10,0)
See Known Issues for Graph Studio to learn about any known problems when executing a
Java (PGX) paragraph.
Tip:
You can hover over the bottom part of a notebook paragraph and click the Add
Python-PGX Paragraph icon to open a Python (PGX) paragraph instantly in the
notebook.
The following variables are built-in for easier PGX interaction when using a Python
paragraph:
• session: the PgxSession object bound to your user. You can access all graphs currently
loaded into memory via the session object. Note that sessions time out after a while of
not being used. A new session will be created when you log back in to the notebook;
thus, the underlying session ID is not always the same.
• instance: the ServerInstance pointing to the PGX server.
• visual_query: a helper object to convert PGQL queries into visualizable output.
• analyst: a helper object providing access to all built-in graph analytics such as
PageRank and Betweenness Centrality.
The following import is available by default on all Python (PGX) paragraphs:
import pypgx
6-5
Chapter 6
Available Notebook Interpreters
%python-pgx
# Reference in-memory graphs by name
graph = session.get_graph("FIRST_GRAPH")
# Executing an algorithm to determine the number of triangles in a
graph
analyst.count_triangles(graph, True)
You can also define new helper classes/functions inside Python paragraphs. For
example:
%python-pgx
import math
# Define helper classes/functions
class Functions:
def haversine (lat1, lon1, lat2, lon2):
delta_lon = (lon2 - lon1) * math.pi/180
delta_lat = (lat2 - lat1) * math.pi/180
a = math.pow(math.sin(delta_lat/2),2) + math.cos(lat1 * math.pi/
180) * math.cos(lat2 * math.pi / 180) * math.pow(math.sin(delta_lon /
2), 2)
c = 2 * math.asin(math.sqrt(a))
r = 6371 # Radius of the Earth in kilometers. Use 3956 for
miles
return c * r
Functions.haversine(30.26, 97.74, 48.13, 11.58)
Internally, the Python (PGX) interpreter operates on the same PGX session as the
Java (PGX) interpreter. So, any analysis results computed in Java (PGX) paragraphs
are available for querying in subsequent Python (PGX) paragraphs.
The following example show the PageRank values computed on a graph in a Java
(PGX) paragraph. The pagerank property on the graph is then queried in the
subsequent Python (PGX) paragraph.
%java-pgx
var g = session.getGraph("MY_FIRST_GRAPH")
session.createAnalyst().pagerank(g)
%python-pgx
session.execute_pgql("SELECT x.pagerank FROM MATCH (x) ON
MY_FIRST_GRAPH").print()
6-6
Chapter 6
Reference Graphs in Notebook Paragraphs
Tip:
You can hover over the bottom part of a notebook paragraph and click the Add
PGQL-PGX Paragraph icon to open a PGQL (PGX) paragraph instantly in the
notebook.
%pgql-pgx
SELECT v, e FROM MATCH (v)-[e]->() ON MY_FIRST_GRAPH
Internally, the PGQL interpreter operates on the same PGX session as the Java (PGX)
interpreter or the Python (PGX) interpreter. So, any analysis results computed in Java (PGX)
paragraphs or Python (PGX) paragraphs are available for querying in the subsequent PGQL
(PGX) paragraphs.
For example, the vertex ranking computed for each vertex using the Vertex Betweenness
Centrality algorithm in the Java(PGX) paragraph is used for querying in the following PGQL
(PGX) paragraph:
%java-pgx
var g = session.getGraph("MY_FIRST_GRAPH")
session.createAnalyst().approximateVertexBetweennessCentrality(g, 3)
%pgql-pgx
SELECT city, e
FROM MATCH (city) -[e] -> () ON MY_FIRST_GRAPH
ORDER BY city.approx_betweenness
• %java-pgx
• %python-pgx
• %pgql-pgx
%java-pgx
var graph = session.readGraphByName("BANK_GRAPH", GraphSource.PG_VIEW)
6-7
Chapter 6
Reference Graphs in Notebook Paragraphs
%python-pgx
graph = session.read_graph_by_name("BANK_GRAPH", "pg_view")
%pgql-pgx
SELECT v,e FROM BANK_GRAPH MATCH (v)-[e]->() LIMIT 10
Note:
If you try loading a PG Objects graph using the preceding code, you may
encounter an error message that TABLE OR VIEW DOES NOT EXIST.
Optionally, you can navigate to the Graphs page and verify the In Memory column for
the graph. This column must show the value in memory to indicate that the graph is
successfully loaded into memory.
For a PG Objects graph, you must first load the graph into memory from the Graphs
page. See Manage Graphs for more information on using the Load Graph Into
Memory action on a graph.
You can then reference the graph in a notebook as shown in the following example:
• %java-pgx
• %python-pgx
• %pgql-pgx
%java-pgx
var graph = session.getGraph("MY_GRAPH")
%python-pgx
graph = session.get_graph("MY_GRAPH")
%pgql-pgx
SELECT v,e FROM MY_GRAPH MATCH (v)-[e]->() LIMIT 10
Note:
You can also reference a PG View graph using this method if the PG View
graph is loaded into memory earlier.
6-8
Chapter 6
Store a PgxFrame in Database
The outputs of the graph machine learning algorithms are PgxFrame(s) and this data structure
can be stored in the database. The columns and rows of the PgxFrame correspond to the
columns and rows of the database table.
The following example converts a PGQL result set to a PgxFrame, which is then stored as a
table to the database.
• %java-pgx
• %python-pgx
%java-pgx
var g = session.readGraphByName("BANK_GRAPH", GraphSource.PG_VIEW)
var query = "SELECT s.acct_id FROM MATCH (s) LIMIT 10"
var rs = g.queryPgql(query)
if (rs != null) {
rs.toFrame().write().db()
.tablename("accounts") // name of the DB table
.overwrite(true)
.store();
}
%python-pgx
g = session.read_graph_by_name("BANK_GRAPH", "pg_view")
query = "SELECT s.acct_id FROM MATCH (s)"
rs = g.execute_pgql(query)
if (rs != None):
rs.to_frame().write().db().table_name("accounts").overwrite(True).store()
On executing the notebook paragraph, the PgxFrame data gets inserted in the appropriate
database table. You can verify this by viewing and querying the database table using
Database Actions. See SQL Page in Database Actions for more information on running SQL
statements in Database Actions.
Also, note the following:
• The generated table name and column names are case-sensitive. The preceding code
example creates a database table having a lowercase name "accounts" with a column
named "acct_id".
If however, the query is:
and table name is specified as tablename("ACCOUNTS"), then the database table will
have a uppercase name "ACCOUNTS" with a column named "ACCT_ID".
6-9
Chapter 6
Visualize Output of Paragraphs
• If a database table with the same name is already existing, then you can use the
overwrite mode by setting overwrite(true) as seen in the preceding example.
The previous table gets truncated and the data is then inserted. By default, the
value is set to false.
• If you are using an Always Free Autonomous Database instance (that is, one with
only 1 OCPU and 20GB of storage), then you must also specify that only one
connection must be used when writing the PgxFrame to the table in a Java (PGX)
notebook paragraph. For example, you must invoke write() as shown:
rs.toFrame().write().db().connections(1).tablename("accounts").overw
rite(true).store();
• %java-pgx
• %python-pgx
%java-pgx
out.println(visualQuery.queryPgql("select v,e,m FROM MATCH (v)-[e]->(m) ON SH
LIMIT 50"))
%python-pgx
print(visual_query.query_pgql("select v, e from match (v)-[e]->() on
FIRST_GRAPH"))
6-10
Chapter 6
Apply Machine Learning on a Graph
• Supervised GraphWise
• Unsupervised GraphWise
• Pg2vec
See Using the Machine Learning Library (PgxML) for Graphs in Oracle Database Graph
Developer's Guide for Property Graph for more information on the usage of the main
functionalities of these algorithms.
Running machine learning algorithms is supported in a notebook paragraph using the
following interpreters:
• Java (PGX): See oracle.pgx.api.mllib package in Java API Reference for more
information.
• Python (PGX): See the PyPGX MLlib package in Python API Reference for more
information.
For example, the following steps describe the usage of the DeepWalk model on a graph in a
notebook paragraph.
1. Load the required graph into memory and reference the graph in the notebook.
See Reference Graphs in Notebook Paragraphs for more information.
2. Build a DeepWalk model using customized hyper-parameters.
• %java-pgx
• %python-pgx
%java-pgx
import oracle.pgx.api.mllib.DeepWalkModel
var model = session.createAnalyst().deepWalkModelBuilder().
setMinWordFrequency(1).
setBatchSize(512).
setNumEpochs(1).
setLayerSize(100).
setLearningRate(0.05).
setMinLearningRate(0.0001).
setWindowSize(3).
setWalksPerVertex(6).
setWalkLength(4).
setSampleRate(0.00001).
setNegativeSample(2).
setValidationFraction(0.01).
build()
%python-pgx
model = analyst.deepwalk_builder(min_word_frequency= 1,
batch_size= 512,
num_epochs= 1,
layer_size= 100,
learning_rate= 0.05,
min_learning_rate= 0.0001,
window_size= 3,
walks_per_vertex= 6,
walk_length= 4,
6-11
Chapter 6
Apply Machine Learning on a Graph
sample_rate= 0.00001,
negative_sample= 2,
validation_fraction= 0.01)
• %java-pgx
• %python-pgx
%java-pgx
model.fit(g)
%python-pgx
model.fit(g)
You can now perform one or more of the following functionalities on the DeepWalk
model:
4. Compute the loss value on the data.
• %java-pgx
• %python-pgx
%java-pgx
var loss = model.getLoss()
%python-pgx
loss = model.loss
• %java-pgx
• %python-pgx
%java-pgx
import oracle.pgx.api.frames.*
List<java.lang.Object> vertices = Arrays.asList("3244407212344026742",
"371586706748522153")
6-12
Chapter 6
Apply Machine Learning on a Graph
%python-pgx
vertices = ["3244407212344026742", "371586706748522153"]
batch_similars = model.compute_similars(vertices, 2)
batch_similars.print()
+----------------------------------------------------------------+
| srcVertex | dstVertex | similarity |
+----------------------------------------------------------------+
| 3244407212344026742 | 3244407212344026742 | 1.0 |
| 3244407212344026742 | 3510061098087750671 | 0.2863036096096039 |
| 371586706748522153 | 371586706748522153 | 1.0 |
| 371586706748522153 | 2128822953047004384 | 0.3220503330230713 |
+----------------------------------------------------------------+
• %java-pgx
• %python-pgx
%java-pgx
var vertexVectors = model.getTrainedVertexVectors().flattenAll()
vertexVectors.write().db().name("deepwalkframe").tablename("vertexVectors").overwri
te(true).store()
%python-pgx
vertex_vectors = model.trained_vectors.flatten_all()
vertex_vectors.write().db().table_name("vertex_vectors").overwrite(True).store()
If you are using an Always Free Autonomous Database instance (that is, one with only 1
OCPU and 20GB of storage), then you must also specify that only one connection must
be used when writing the PgxFrame to the table in a Java (PGX) notebook paragraph. For
example, you must invoke write() as shown:
vertexVectors.write().db().name("deepwalkframe").tablename("vertexVectors"
).overwrite(true).connections(1).store()
The columns in the database table for the flattened vectors will appear as:
+----------------------------------------------------
+---------------------+
6-13
Chapter 6
Apply Machine Learning on a Graph
| vertexid | embedding_0 |
embedding_1 |
+----------------------------------------------------
+---------------------+
• %java-pgx
• %python-pgx
%java-pgx
model.export().db().modelstore("bank_model").modelname("model").description("
DeepWalk Model for Bank data").store()
%python-pgx
model.export().db(model_store="bank_model",
model_name="model", model_description="DeepWalk Model for
Bank data", overwrite=True)
• %java-pgx
• %python-pgx
%java-pgx
var model =
session.createAnalyst().loadDeepWalkModel().db().modelstore("bank_model").mod
elname("model").load()
%python-pgx
model = analyst.get_deepwalk_model_loader().db(model_store="bank_model",
model_name="model")
• %java-pgx
• %python-pgx
6-14
Chapter 6
Dynamic Forms
%java-pgx
model.destroy()
%python-pgx
model.destroy()
Dynamic Forms
Graph Studio supports the dynamic creation of input fields for a paragraph command. These
input fields are called dynamic forms.
On execution, the placeholders in the command will be replaced with the custom user input in
the respective input fields.
Because each programming language has its own protected characters and keywords, the
placeholder-syntax can start with a different escape-character: for example, ${my-form-info}
or @{my-form-info}
%md
My name is ${textbox(Title of textbox)=Data Studio}
%md
Country: ${country=US,US(United States)|UK|JP}
– The name, label, and default values can be specified similarly to a textbox.
– The selection options are separated by the | character.
– The label of an option can be specified in parentheses following the option For
example: US(United States)
• Slider: Allows the user to choose within a specified range. For example:
%md
My age is: ${slider(18.0,30.0,5.0):My Age=25.0}
– The default value can be specified similarly to a textbox. In this example, the
specified default value is 25.0
6-15
Chapter 6
Dynamic Forms
– After the keyword slider, the values in brackets specify the min, max, and
step-size values. In this example, min = 18.0, max = 30.0, and step-size = 5.0.
– The label of can be specified in brackets following the name. For example: $
{slider:name(My Label)}
• Checkbox: Allows the user to choose one or more specified values. For example:
%md
${checkbox( or ):country(Country)=US|JP, US(United States)|UK|JP}
%md
${date(EEEE):myName(my-label)=1994-06-15T09:00:00}
%md
${time(hh:mm:ss):myName(my-label)=1994-06-15T09:00:00}
6-16
Chapter 6
Paragraph Dependencies
• DateTime-Picker: Allows the user to choose one or more specified values. For example:
%md
${dateTime(YYYY-M-dd hh:mm:ss):myName(my-label)=1995-06-15T09:00:00}
Paragraph Dependencies
You can add dependencies between paragraphs.
The dependents of a paragraph are automatically executed after the original paragraph itself
or any graph manipulation on the original paragraph is executed.
To start dependency mode, click the Dependencies button in the paragraph settings bar.
Dependency Mode
In dependency mode, you can select dependent paragraphs that will be executed after the
current paragraph has finished running.
You can save or cancel your changes by clicking Save or Cancel.
Viewing Dependents
To view dependencies of a paragraph when not in dependency mode, select the paragraph.
The dependents will be displayed with a light blue border and a number indicating that
paragraph's position in the execution order.
Paragraph Comments
You can add and view comments on paragraphs, and you can delete your own comments.
The dependents of a paragraph are automatically executed after the original paragraph itself
or any graph manipulation on the original paragraph is executed.
To perform any action involving comments, click the Comments button in the paragraph
toolbar to start the comments view. This view shows all paragraph comments.
To add a comment, enter it in the New Comment text area.
To delete one of your own comments, select the comment and click the trash bin icon.
6-17
Chapter 6
Find a Notebook
You can open an overview of all keyboard shortcuts and perform a search for shortcuts
by using the context menu in the top-right corner. If the page you are currently on does
not have any keyboard shortcuts, this menu item will not appear. You can also search
for shortcuts by pressing Ctrl+Shift+F.
See Keyboard Shortcuts for Graph Studio in the Accessibility Guide for Oracle Cloud
Services for more information on keyboard shortcuts for notebooks in Graph Studio.
Find a Notebook
You can search for a notebook on the Notebooks page.
On the Notebooks page, you can use the search bar to search for a notebook by title,
description, or tags. Additionally you can use keyboard shortcuts when working with
notebooks.
1. Click Notebooks on the left navigation menu and navigate to the Notebooks page.
2. Enter the name of the notebook to find in the search bar.
This opens the desired notebook.
Move a Notebook
You can move a notebook to another directory in Graph Studio.
Notebooks can be moved from:
• the notebooks main workspace in to a directory or conversely
• one directory to another
The following are the steps to move a notebook:
1. Navigate to the Notebooks page.
2. Click to open the notebook you want to move.
3. Click the Modify Notebook icon on the notebook toolbar at the top of the
page.
The window to modify the notebook details opens.
4. Enter a Name with the new directory path as required. This path determines the
destination directory where you want to move the notebook.
Note:
Notebooks can be organized into a directory hierarchy. To create a new
directory or to add or to move a notebook to a directory, simply give the
notebook a name with slashes to indicate the directory structure.
6-18
Chapter 6
Example Notebooks
6. Click Save.
The notebook is moved to the destination directory.
Example Notebooks
Graph Studio includes a set of examples.
You can find these examples in the Notebooks section.
• Getting Started: PGQL Basics
• Use Cases: Meetup Recommendation
• Use Cases: Sales Analysis
Each of these notebooks contains a set of Markdown paragraphs that explain each step of
the example.
Each example notebook is ready to execute but read-only by default, so that they remain
unchanged for other users of Graph Studio. To remove the read-only state, first create a
private copy of the notebook by clicking Clone at the top of the example notebook.
After the private copy has been created, click Unlock to remove its read-only state.
After the private copy is unlocked, you can run each paragraph one-by-one by clicking Run.
6-19
7
Work with Templates in Graph Studio
A template allows you to persist graph visualization and notebook settings.
You can apply these custom built templates to your notebook.
Topics
• Create a Template
• Use a Template in a Notebook
Create a Template
You can create custom templates that you can use in your notebook to quicky format your
graph visualization.
The following are the steps to create a template:
1. Click Templates on the left navigation menu and navigate to the Templates page.
2. Click Create Template.
The Create Template window opens.
3. Enter the Name of the template.
4. Click Create.
This creates a new template and the new template name gets listed on the left pane.
Graph Studio displays the default settings for the template on the right pane. The right
pane is again divided into two sections. The left section lists the menu options for the
various components that can be configured in a template and the right section displays
the corresponding parameter settings for the selected menu item as shown:
5. Select the component to be formatted from the menu and configure the required settings.
6. Click Update at the bottom-right of the page.
7-1
Chapter 7
Use a Template in a Notebook
Note:
Templates are imported and exported using the JSON file format only.
The custom settings in the selected template gets applied to the notebook.
7-2
8
Visualize and Interact with Graph Data in
Graph Studio
You can visualize graph data in the form of a graph visualization.
Topics
• About Graph Visualization and Manipulation
• Manipulate a Graph Visualization
• Annotate a Graph
• Visualize a Dynamic Graph
• Settings for Graph Visualization
Note:
Some graph visualization and manipulation features are not enabled in Preview
mode.
8-1
Chapter 8
Manipulate a Graph Visualization
2. Hover over any one of the icons to view a tooltip describing its purpose.
The following actions are available from the graph manipulation toolbar or tooltip:
• Drop removes selected vertices from the view.
• Expand fetches n-hop neighbors of selected vertices or neighbors that fulfill
certain criteria if Smart Expand is used.
• Group groups selected vertices into a super vertex.
You can customize the appearance of super vertices by using the graph
visualization property Grouped Vertex in the Highlights tab of graph
visualization settings modal.
• Ungroup ungroups a group (that is, ungroups a super vertex).
• Focus shifts the focus of the view; it drops everything and fetches n-hop
neighbors of the selected vertex.
• Undo undoes (reverses the effect of) the last action.
• Redo repeats the last action.
• Reset resets the visualization to its default state.
3. Select the desired action.
The graph is altered accordingly.
You can also manipulate a graph visualization using the following features:
• Smart Explorer: Lets you specify conditions for properties for navigation and
destination vertices and edges that must be fulfilled when expanding or
grouping vertices.
See Expand Vertices Using Smart Expand for details on expanding vertices.
See Group Vertices Using Smart Group for details on grouping vertices.
• Visible Graph Mode: Allows you to store your graph data in a variable which
can be used in further graph queries.
See Enable Visible Graph Mode for more information.
8-2
Chapter 8
Manipulate a Graph Visualization
4. Optionally, change the default name of the variable in the Global Variable Name field.
5. Click the icon to copy the visible graph mode variable name to the clipboard.
6. Click X on the top-right to close the Settings dialog.
The graph data gets stored in the variable. You can now query the vertices and edges of
the graph using the variable as shown:
• Vertices: <visible_graph_mode_variable_name>.get("V")
• Edges: <visible_graph_mode_variable_name>.get("E")
7. Use the variable in your further queries.
The following example creates a prepared statement for a query. The visible graph mode
variable is used in the setArray method to set the bind variable to an array of values.
%java-pgx
var prepared_stmnt = graph.preparePgql("SELECT * FROM MATCH (v) WHERE
v.acct_id IN ?");
prepared_stmnt.setArray(1, visible_graph.get("E"));
var r = prepared_stmnt.executeQuery();
out.println(prepared_stmnt.executeQuery());
8-3
Chapter 8
Manipulate a Graph Visualization
Note:
8-4
Chapter 8
Manipulate a Graph Visualization
7. Optionally, join your conditions by clicking Match All or Match Any as required.
Note:
The join options are displayed only when you have multiple conditions.
Note:
Destination conditions are conditions that you apply to the last vertex or edge in
the path. It does not apply to the vertices selected for expand.
The options for adding a destination condition and joining multiple conditions is same as
described in the preceding steps for navigation conditions.
9. Click Create to add one or more conditions for Smart Expand.
10. Click X on the top-right to close the Settings dialog.
13. Select a specific vertex or multiple vertices on the graph and click the Expand action on
the graph manipulation toolbar.
Tip:
Alternatively, you can apply Smart Expand from the tool tip. You can display the
tool tip by using a right-click on the selected vertex.
Smart Expand fetches a shortest path to the vertex or vertices that are within the
specified maximum path length, fulfilling the navigation and destination conditions for the
selected vertex or vertices as shown in the preceding figure.
8-5
Chapter 8
Manipulate a Graph Visualization
Note:
If you do not configure the maximum hop count, navigation or destination
conditions for Smart Expand, then the graph expands on the default
infinite hop count value.
Tip:
You can use this Group Name in Highlights to customize the
appearance of grouped vertices.
Note:
You must switch off the Automatic toggle in case of manual Smart
Group.
8-6
Chapter 8
Manipulate a Graph Visualization
Note:
If Smart Group has any edge conditions, then the created groups are further
split into separate parts where all vertices are reachable just through edges
fulfilling specified edge conditions. This can be seen in the figure shown in
Step-11.b
8-7
Chapter 8
Manipulate a Graph Visualization
Note:
The join options are displayed only when you have multiple conditions.
c. Click specific vertices on the graph and click the Group action on the graph
manipulation toolbar.
Vertices fulfilling the configured conditions are grouped together.
Note:
8-8
Chapter 8
Annotate a Graph
Annotate a Graph
Graph Annotation mode allows you to add vertices and edges on a graph visualization. You
can also add or edit the graph's properties for visualization.
To annotate a graph:
1. Set to graph Annotation Mode on the Graph Visualization panel.
2. Annotate the graph visualization by performing one of the following actions:
• Add a new vertex by clicking anywhere in the graph visualization canvas.
• Create a new edge by dragging the mouse from the source vertex to the target
vertex.
• Move a vertex by dragging the mouse while holding the Shift key or with initial long
click on it.
• Add properties to new vertices and edges or edit the properties of existing ones.
All your edits are added to the graph manipulation action stack, so you can undo, redo, or
clear them using appropriate graph manipulation actions. The addedByUser and
editedByUser properties are added automatically to vertices and edges that you create
or edit, so that you can use them in Graph Highlights operations.
Note:
All graph annotations persist only on the graph visualization and not on the
actual graph itself. You can remove the graph annotations by resetting the
graph visualization to its default state.
8-9
Chapter 8
Visualize a Dynamic Graph
Note:
You can configure the network evolution to be based on vertices or
edges or both.
Depending on your selection, you must select one or more of the following
properties:
• Vertex Start Property: Select the name of the property to use for the vertex
filtering.
The time frame for the graph will be after the Vertex Start Property.
• Vertex End Property: Optionally, select the name of the property to use for
the vertex filtering.
The time frame for the graph will be before the Vertex End Property.
• Edge Start Property: Select the name of the property to use for the edge
filtering.
The time frame for the graph will be after the Edge Start Property.
• Edge End Property: Optionally, select the name of the property to use for the
edge filtering.
The time frame for the graph will be before the Edge End Property.
5. Select the data type value from the Data Type of the Property drop-down list.
Note:
Graph Studio supports only Integer and Date type property values.
8-10
Chapter 8
Settings for Graph Visualization
You can view the graph animation by clicking the Play Network Evolution button. The
animation shows the changes in the graph network over time.
Additionally, you can activate and deactivate network evolution, by clicking Activate
Network Evolution in the graph manipulation toolbar:
Note:
To use this approach, you must first configure the network evolution properties
in the graph visualization settings, as explained in the earlier steps.
8-11
Chapter 8
Settings for Graph Visualization
The Settings modal contains the following tabs that group the options according to
their scope:
• General Settings
• Visualization Settings
• Highlights Settings
The specific settings available on each tab can vary depending on the type of
visualization. This page focuses on settings for a graph visualization.
General Settings
General settings affect the entire visualization, including search-related options.
General settings can include the following options:
Option Description
Height Height of the visualization. Setting the value to 0 will take the
default height.
Number of Hops Number of hops for graph manipulation.
Truncate Labels If enabled, labels will be truncated at a specific length (see option
Maximum Visible Label Length).
8-12
Chapter 8
Settings for Graph Visualization
Option Description
Maximum Visible Label Maximum character length of a truncated label.
Length
Show Label on Hover When enabled, full labels will appear as a tooltip when hovering
over a vertex.
Display Graph Legend When enabled, the graph legend will be displayed.
Enable Live Search Enables the search, adds the search input to the visualization,
and allows to further customize the search.
Live search adds a live "fuzzy" search score to each item, so you
can create a highlight that shows the results of the search in the
graph immediately. (In the Highlights section, specify an
Interpolate value of LiveSearch.)
Enable Search In For live search, you can select whether you want to search the
properties of vertices, edges, or both.
Properties To Search For live search, based on the preceding setting, you will be
allowed to set one or more properties to search in. When 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. The same applies for vertices.
Advanced Settings If you want to fine tune the search even more, you can enable the
advanced settings for the search. Each of the advanced options is
documented with context help, visible upon enabling.
Visualization Settings
Visualization settings affect the visual aspects of the display. Visualization settings can
include the following options:
General
Option Description
Dimension Switches between 2D (default) and 3D views.
Theme Toggles the visualization between light and dark theme (useful for
presentations).
Edge Style Allows you to visualize edges as curved or straight lines. By default,
duplicated edges will be rendered as curved lines (even in straight
mode).
Edge Marker Determines if the outgoing edges have an arrow to show the flow
direction.
Similar Edges Collects similar edges when this button is checked. Toggled edges give
no overview of specific edges but a generalized tooltip.
Page Size Determines how many entries from the result set should be visualized.
Animate Changes Toggles animation on or off.
Layouts
Graph Studio supports many different graph layouts. Each layout has its own algorithm,
which computes the positions of the nodes and affects the visual structure of the graph.
The following graph layout options are supported:
8-13
Chapter 8
Settings for Graph Visualization
Option Description
Random Layout Puts nodes in random positions within the viewport.
Grid Layout Puts vertices in a well-spaced grid. It supports the following
configurable properties:
• Rows: Sets the number of rows in the grid.
• Columns: Sets the number of columns in the grid.
• Avoid Overlap: Prevents overlapping of vertices (may cause
some of the vertices to be placed outside the viewport if there
is not enough space within the viewport).
Circle Layout Positions vertices in a circle. It supports the following configurable
properties:
• SaveRadius: Sets the radius of the circle.
• Radius: Prevents overlapping of vertices (may cause the
some of the vertices to be placed outside the viewport if there
is not enough space within the viewport).
Concentric Layout Positions vertices in concentric circles. It supports the following
configurable properties
• Minimum Node Spacing: Sets the minimum spacing in
between vertices (used for radius adjustment).
• Avoid Overlap: Prevents overlapping of vertices (may cause
the some of the vertices to be placed outside the viewport if
there is not enough space within the viewport).
Force Layout Attempts to create an aesthetically-pleasing graph based on the
structure of the graph, with the goal of positioning the vertices in
the viewport so that all the edges are of approximately equal
length and there are as few crossing edges as possible. It has the
following configurable properties:
• Edge Distance: Sets every edge to the specified length (can
affect the padding between vertices).
• Force Strength: Influences the underlying forces (such as to
remain within the viewport or to push vertices away from
each other).
• Velocity Decay: Determines the speed at which the
simulation ends.
• Vertex Padding: Determines the proximity of different
vertices when rendered.
Geographical Layout Enables you to overlay the graph on a map, given latitude and
longitude coordinates. The latitude and longitude positions can be
selected from the vertex properties.
8-14
Chapter 8
Settings for Graph Visualization
Option Description
Hierarchical Layout Organizes the graph using a DAG (Directed Acyclic Graph)
system. It is especially suitable for DAGs and trees. It supports the
following configurable properties:
• Ranking Algorithm: Specifies the type of algorithm used to
rank the vertices. Possible values are Network Simplex, Tight
Tree and Longest Path.
• Network Simplex: Assigns ranks to each vertex in the input
graph and iteratively improves the ranking to reduce the
length of the edges.
• Tight Tree: Constructs a spanning tree with tight edges by
adjusting the ranks of the input vertex. The length of a tight
edge matches its minlen attribute.
• Longest Path: Pushes vertices to the lowest layer possible,
leaving the bottom ranks wide and leaving edges longer than
necessary.
• Direction: Specifies the direction of the graph. Possible
values are Top Bottom, Bottom Top, Left Right, and Right Left
• Alignment of Rank Nodes: Determines the alignment of the
ranked vertices. Possible values are Up Left, Up Right, Down
Left and Down Right
• Vertex Separation: Sets the horizontal separation between
the vertices.
• Edge Separation: Sets the horizontal separation between
the edges.
• Rank Separation: Sets the separation between two ranks
(levels) in the graph.
Radial Layout Displays the dependency chain of a graph by using an outwards
expanding tree structure. It can be especially useful if the graph
data has a hierarchical structure and contains many children for
each parent vertex. It has the following configurable properties:
• Starting Point (left, top, right, bottom): Defines the starting
point of the radial layout and thus allows you to change the
orientation.
• Arc Degree slider (0° - 360°): Specifies the arc degree of the
circle used for the radial layout. Higher arc degree values can
help to detangle the network; lower values make it more
compact.
• Packing slider (0 - 5): Reduces the separation gap between
neighboring vertices if they share the same parent vertex. If
set to 0, no packing will be applied.
• Intelligent Separation: Reduces the separation gap
proportionally to the depth level of each vertex.
Option Description
Node Label The selected property will be displayed on the node.
Node Label Orientation Determines where the selected property will be displayed. Options are:
bottom, center, top, right, left.
Edge Label The selected property will be displayed on the edge.
8-15
Chapter 8
Settings for Graph Visualization
Highlights Settings
Highlights let you customize the appearance of nodes and edges based on search
criteria. You can create new highlights or edit existing ones. As you create or edit a
highlight, an automatic preview is displayed.
Search criteria can include:
• Element type to search for (node or edge).
• Search conditions.
• Condition operator (match all or any).
Each search condition includes:
• The property of that element (such as its ID value).
• The operator to be applied (such as smaller, greater, equal, or regex).
• The value that must be fulfilled for the operator and property.
You can highlight all elements that fulfill the criteria. However, you can instead use the
list of elements that fulfill the criteria as a base, and then highlight just the incoming or
outgoing edges. If the search was applied to edges, you can also highlight the nodes
from the start or end of the edge.
A highlight value can either be a constant or an interpolation based on some property
value. Interpolation settings include:
• The property of the element
• The min or max value (If not specified, the min or max property value from all
matched elements will be used, and the highlight will be applied proportionally
between the selected min and max values of the specified property.)
The following options apply to highlights:
Option Description
Size Sets the size of the node/edge to the specific
value. If interpolation is selected, the slider will
have two ends and the size of the node/edge
is interpolated based on the result of the
search criteria.
Color Sets the color of the node/edge. If interpolation
is selected, the combobox will let you add
multiple colors. All nodes/edges are
interpolated between these colors based on
the result of the search criteria.
Icon Sets an icon for the node (not applicable to
edges). If interpolation is selected, multiple
icons can be selected.
Label Sets the label for the node (not applicable to
edges).
Image Sets an image for the node based on an href
property (not applicable to edges).
8-16
Chapter 8
Settings for Graph Visualization
Option Description
Animations Lets you set certain animation CSS classes for
nodes and edges (such as flashing, dotted-
line, animated dotted-line, pulsating) and the
duration of an animation cycle.
Legend Adds text in the graph legend for elements
where this highlight applies.
When you create a highlight, you can choose
to include the highlight in the legend displayed
next to the graph by providing a title. Updates
to the highlight will be reflected in the legend.
8-17
9
Work with Jobs in Graph Studio
A job in Graph Studio is a potentially long-running asychronous operation composed of a set
of tasks.
Topics
• About Jobs
• Inspect a Job
• Review a Job Log
• Cancel a Job
• Retry a Job
• Delete a Job
• Retention of Finished Jobs
• What to do When a Job Fails
About Jobs
A job is identified by an id, a name, a status, and a set of tasks. Additionally, a job includes
information about the operation's input, progress logs, progress output, and result (if
succeeded).
Types of jobs in Graph Studio include:
• Creating a graph from an existing model.
• Reading an existing graph into memory to perform analytics.
• Starting, stopping and restarting the environment.
A job starts when an operation (for example: create graph, load into memory) is executed.
During a job execution, the job status is set to RUNNING and the progress logs and outputs are
updated to keep track of the executed tasks and processed entities. At the end of the job
execution, the job's status depends on the success or failure of its tasks:
• A failed job has a FAILED or TIMEOUT status and produces no result.
• A successful job has a SUCCEEDED status and produces a result.
A job can be canceled at any time during the job execution. When a job is canceled, its job
status is set to CANCELED and no result is produced.
Inspect a Job
You can inspect (that is, preview) a job.
The Jobs page provides features to review the current status, progress logs and outputs of
the existing jobs in Graph Studio.
9-1
Chapter 9
Review a Job Log
In addition, you can inspect the progress output, which includes the list of
processed, queued, and failed entities or tasks. For a running job, the status of the
job includes the progress percentage.
The Jobs page refreshes automatically without the need to manually refresh the
page via the browser. In addition, older, successful jobs get deleted automatically
from the list. Failed jobs stay for further inspection until explicitly deleted.
9-2
Chapter 9
Cancel a Job
Cancel a Job
You can cancel a running job.
This action cannot be undone. After the job is canceled, all changes done to the entities
affected by the job execution will be rolled back.
To cancel a job during its execution:
1. Select a job in progress on the Jobs page.
The job details are displayed in the job details section.
2. Click Cancel Job in the job details section.
The job is cancelled.
Retry a Job
You can retry the execution of a failed or canceled job.
When a job execution is retried, the job operation will be executed using the stored input. For
a graph creation operation, the service will request the data source credentials of the input
model if you are not already connected, because no credentials are stored within the service.
To retry a job:
1. Select a job to retry on the Jobs page.
2. Click Retry Job in the details section of the selected job. The Retry Job icon is shown
highlighted in the following figure:
9-3
Chapter 9
Delete a Job
Delete a Job
You can delete a job that has successfully finished, has failed, or has been canceled.
To delete a job:
1. Select a job for deleting on the Jobs page.
2. Click Delete Job in the details section of the selected job. The Delete Job icon is
shown highlighted in the following figure:
Deleting a job removes the information about the job execution including the input,
progress log, and output. However, the job result and any changes made by the
job are not affected by this operation. For example, if you delete a graph creation
job that finished successfully, the graph that was created will remain in the system.
9-4
Chapter 9
What to do When a Job Fails
9-5
10
Manage the Environment
Graph Studio must be attached to an internal compute environment in order to perform all
graph analysis tasks.
Topics
• About the Environment
• Inspect the Environment
• Manually Manage the Environment
Note:
The data deletion during the detachment process is only limited to in-memory
copies of graph data and transient analysis results like in-memory algorithms or
query results. Models, graphs, notebooks (including input and generated output of
paragraphs) remain persisted in your Autonomous Database and are available even
in detached state.
Graph Studio automatically reonnects to the environment when you reload the graph into
memory and rerun your notebook from the top.
The environment also supports configuration of memory for the graph server and the
notebook interpreters.
10-1
Chapter 10
Inspect the Environment
10-2
Chapter 10
Inspect the Environment
State Description
Attached Graph Studio is currently attached to an environment.
Attaching Graph Studio is currently in the process of attaching to an
environment.
Detached Graph Studio is currently not attached to any environment
Detaching Graph Studio is currently in the process of detaching from an
environment
If the environment status is Attached, then you can also view the total amount of
memory allocated to the environment. See the note in Manually Manage the
Environment for more details on the total allocated memory.
• Graph server memory configuration.
10-3
Chapter 10
Manually Manage the Environment
10-4
Chapter 10
Manually Manage the Environment
10-5
Chapter 10
Manually Manage the Environment
Note:
At this time, Graph Studio does not allow
allocation of more than 109 GB of memory
for graph analysis per tenancy.
In case you get a "Not enough memory
available" error message, although you
selected less than 109 GB, the cause
could be other Autonomous Databases in
your tenancy currently being attached to
the environment.
If you require more memory, please
contact Oracle Cloud Support.
Note:
The total amount of memory allocated to
the environment is the sum of the memory
given to the graph server and all the
interpreters. However, the final amount of
memory allocated may exceed that
number slightly to account for internal
services running on the environment.
Restart the environment You can detach and attach again in a single operation by
clicking the Restart button. In this case, Graph Studio will
attach to an environment with the same amount of
memory as the current configuration for the graph server
and the interpreters.
3. Monitor the progress of any of the manual operations on the Jobs page.
10-6
Chapter 10
Manually Manage the Environment
10-7
A
Autonomous Database Graph PGX API
Limitations
The following features and APIs of the graph server available in our on-premises offering
(Oracle Graph Server and Client) are not available in the managed cloud service when being
invoked from within %pgx-java paragraphs.
Using any of these APIs will result either in errors being returned upon invocation or in not
achieving the desired behavior.
Reference information about these on-premises APIs is included in the Oracle Graph Java
API Reference for Property Graph in the Oracle Database documentation library. For Oracle
Database Release 21c, see Javadoc for more information on the APIs.
Read graphs
APIs to read a graph directly from files or any other input sources are not available. For
example:
• PgxSession#readGraphWithProperties and similar methods
• PgxSession#readGraphFiles and similar methods
Instead, import the data you want to analyze as a graph into the Autonomous Database using
any of the available data import capabilities such as DBMS_CLOUD, SQL Developer Web, or
Oracle Data Integrator. After the data is in the Autonomous Database, use Graph Studio to
convert the data into a graph (Graph Modeler) or import it as a graph. Only graphs managed
and loaded into memory by Graph Studio can be accessed using PGX APIs.
Publish graphs
APIs to publish graphs or any of their properties are not available. For example:
• PgxGraph#publish() and similar methods
• Property#publish() and similar methods
Instead, graphs must be shared with other users through corresponding GRANT statements
in the Autonomous Database. You can also conveniently share graphs with other users using
the Share capability available in Graph Studio.
A-1
Appendix A
Export graphs
APIs to write in-memory graphs to the local file system are not available:
• PgxGraph#store() and similar methods
Custom algorithms
APIs to compile algorithms from source using the PGX Algorithm API are not
available:
• PgxSession#createProgram() and similar methods
Other APIs
Any APIs from outside the oracle.pgx.* package are not available. This includes (but
might not be limited to) all the APIs of the following packages:
• oracle.pg.common
• oracle.pg.rdbms
• oracle.pg.rdbms.pgql
• oracle.pg.hbase
• oracle.pg.nosql
• oracle.pg.text
A-2
B
Submit a Service Request
You can raise a service request with My Oracle Support, if you need help to resolve issues
when working with Graph Studio in Oracle Autonomous Database.
My Oracle Support is a customer portal that offers product services through various support
tools and contains a repository of useful information, where you can find solution to your
issue. You can raise a service request using this application through one of the following two
interfaces:
1. My Oracle Support
2. Cloud Support
You must meet the following prerequisites to create a service request:
• You must have a Support Identifier which verifies your eligibility for Support services.
• You must have an account at My Oracle Support
1. Access My Oracle Support at https://support.oracle.com.
You can choose to create a service request either from My Oracle Support interface or
from Cloud Support interface by using the switch toggle button on the top-right of the
window.
2. Perform the following steps to create a service request from My Oracle Support
interface:
a. Click Create Technical SR on the Service Requests tab.
b. Enter the Problem Summary.
c. Enter the Problem Description.
Note:
It is important to provide your Region, Tenancy OCID and Database
Name along with your problem details. See Obtain Tenancy Details on how
to obtain the tenancy details for your instance.
B-1
Appendix B
B-2
C
Known Issues for Graph Studio
You can learn about the issues you may encounter when using Graph Studio and how to
work around them.
Syntax error not thrown for a missing closing parenthesis ")" in a Java paragraph in
Notebook
Syntax error must be thrown when executing a %java-pgx paragraph containing an
incomplete Java statement due to a missing closing parenthesis. However, the Java
interpreter in notebook, returns a Successful execution: No result returned message,
which is incorrect. For example:
%java-pgx
out.println("This line is problematic";
<small><i>Successful execution: No result returned.</i></small>
This is because internally the paragraphs are interpreted through JShell which considers the
incomplete command statement to be of multiple lines. Until a command termination using
the closing parenthesis is executed, any other execution of %java-pgx in the subsequent
paragraphs inside the notebook are considered as continuation of the incomplete statement
and therefore will produce incorrect results. For example, executing the following paragraph
after running the preceding code does not retrieve the graph configurations as expected:
%java-pgx
PgxGraph g = session.getGraph("BANK_GRAPH")
<small><i>Successful execution: No result returned.</i></small>
Workaround
To work around this problem, you can use one of the following options:
• Restore the notebook environment to the normal state by performing the following steps:
1. Execute a closing parenthesis statement in a new %java-pgx paragraph to mark the
termination of the incomplete statement as shown:
%java-pgx
)
Error:
')' expected
out.println("This line is problematic";
^
C-1
Appendix C
2. Fix the incorrect statement to include the closing parenthesis and re-execute
the statement.
%java-pgx
out.println("This line is problematic");
This line is problematic
• Restart the environment. See Manually Manage the Environment for more
information to restart the environment.
After implementing one of the workaround options, any execution of %java-pgx
paragraphs in the notebook will produce the desired results. For example:
%java-pgx
PgxGraph g = session.getGraph("BANK_GRAPH")
PgxGraph[name=BANK_GRAPH,N=1000,E=5001,created=1628583419041]
C-2