Skip to main content

Jupyter extension for NebulaGraph

Project description

for NebulaGraph Jupyter Docker Image Docker Extension GitHub release (latest by date) pypi-version Open In Colab Documentation

jupyter_nebulagraph, formerly ipython-ngql, is a Python package that simplifies the process of connecting to NebulaGraph from Jupyter Notebooks or iPython environments. It enhances the user experience by streamlining the creation, debugging, and sharing of Jupyter Notebooks. With jupyter_nebulagraph, users can effortlessly connect to NebulaGraph, load data, execute queries, visualize results, and fine-tune query outputs, thereby boosting collaborative efforts and productivity.

Getting Started

pip install jupyter_nebulagraph

Load the extension in Jupyter Notebook or iPython:

%load_ext ngql
%ngql --address --port 9669 --user root --password nebula

Make queries:

%ngql USE basketballplayer;
%ngql MATCH p=(v:player)-->(v2:player) WHERE id(v) == "player100" RETURN p;

Draw the graph:


Discover the features of jupyter_nebulagraph by experimenting with it on Google Colab. You can also access a similar Jupyter Notebook in the documentation here.

For a detailed guide, refer to the official documentation.

Feature Cheat Sheet Example Command Documentation
Connect %ngql --address --port 9669 --user user --password password Connect %ngql
Load Data from CSV %ng_load --source actor.csv --tag player --vid 0 --props 1:name,2:age --space basketballplayer Load Data %ng_load
Query Execution %ngql MATCH p=(v:player{name:"Tim Duncan"})-->(v2:player) RETURN p; Query Execution %ngql or %%ngql(multi-line)
Result Visualization %ng_draw Draw Graph %ng_draw
Draw Schema %ng_draw_schema Draw Schema %ng_draw_schema
Tweak Query Result df = _ to get last query result as pd.dataframe or ResultSet Tweak Result Configure ngql_result_style
Click to see more!


jupyter_nebulagraph could be installed either via pip or from this git repo itself.

Install via pip

pip install jupyter_nebulagraph

Install inside the repo

git clone
cd jupyter_nebulagraph
python install

Load it in Jupyter Notebook or iPython

%load_ext ngql

Connect to NebulaGraph

Arguments as below are needed to connect a NebulaGraph DB instance:

Argument Description
--address or -addr IP address of the NebulaGraph Instance
--port or -P Port number of the NebulaGraph Instance
--user or -u User name
--password or -p Password

Below is an exmple on connecting to with username: "user" and password: "password".

%ngql --address --port 9669 --user user --password password

Make Queries

Now two kind of iPtython Magics are supported:

Option 1: The one line stype with %ngql:

%ngql USE basketballplayer;
%ngql MATCH (v:player{name:"Tim Duncan"})-->(v2:player) RETURN AS Name;

Option 2: The multiple lines stype with %%ngql


Query String with Variables

jupyter_nebulagraph supports taking variables from the local namespace, with the help of Jinja2 template framework, it's supported to have queries like the below example.

The actual query string should be GO FROM "Sue" OVER owns_pokemon ..., and "{{ trainer }}" was renderred as "Sue" by consuming the local variable trainer:

In [8]: vid = "player100"

In [9]: %%ngql
   ...: MATCH (v)<-[e:follow]- (v2)-[e2:serve]->(v3)
   ...:   WHERE id(v) == "{{ vid }}"
   ...: RETURN AS FriendOf, AS Team LIMIT 3;
Out[9]:   RETURN AS FriendOf, AS Team LIMIT 3;
FriendOf	Team
0	LaMarcus Aldridge	Trail Blazers
1	LaMarcus Aldridge	Spurs
2	Marco Belinelli	Warriors

Draw query results

Draw Last Query

Just call %ng_draw after queries with graph data.

# one query
%ngql GET SUBGRAPH 2 STEPS FROM "player101" YIELD VERTICES AS nodes, EDGES AS relationships;

# another query
%ngql match p=(:player)-[]->() return p LIMIT 5

Draw a Query

Or %ng_draw <one_line_query>, %%ng_draw <multiline_query> instead of drawing the result of the last query.


One line query:

%ng_draw GET SUBGRAPH 2 STEPS FROM "player101" YIELD VERTICES AS nodes, EDGES AS relationships;

Multiple lines query:

MATCH path_0=(n)--() WHERE id(n) == "p_0"
OPTIONAL MATCH path_1=(n)--()--()
RETURN path_0, path_1

Draw Graph Schema


Load Data from CSV

It's supported to load data from a CSV file into NebulaGraph with the help of ng_load_csv magic.

For example, to load data from a CSV file actor.csv into a space basketballplayer with tag player and vid in column 0, and props in column 1 and 2:

"player999","Tom Hanks",30
"player1000","Tom Cruise",40
"player1001","Jimmy X",33

Just run the below line:

%ng_load --source actor.csv --tag player --vid 0 --props 1:name,2:age --space basketballplayer

Some other examples:

# load CSV from a URL
%ng_load --source --tag player --vid 0 --props 1:name,2:age --space demo_basketballplayer
# with rank column
%ng_load --source follow_with_rank.csv --edge follow --src 0 --dst 1 --props 2:degree --rank 3 --space basketballplayer
# without rank column
%ng_load --source follow.csv --edge follow --src 0 --dst 1 --props 2:degree --space basketballplayer

Tweak Query Result

By default, the query result is a Pandas Dataframe, and we could access that by read from variable _.

In [1]: %ngql MATCH (v:player{name:"Tim Duncan"})-->(v2:player) RETURN AS Name;

In [2]: df = _

It's also configurable to have the result in raw ResultSet, to enable handy NebulaGraph Python App Development.

See more via Docs: Result Handling


If you find yourself forgetting commands or not wanting to rely solely on the cheat sheet, remember this one thing: seek help through the help command!

%ngql help

Acknowledgments ♥️

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

jupyter_nebulagraph-0.13.4.tar.gz (17.4 kB view hashes)

Uploaded Source

Built Distribution

jupyter_nebulagraph-0.13.4-py3-none-any.whl (18.9 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page