{"id":23647105,"url":"https://github.com/wey-gu/jupyter_nebulagraph","last_synced_at":"2025-10-29T17:31:14.742Z","repository":{"id":62571620,"uuid":"345321678","full_name":"wey-gu/jupyter_nebulagraph","owner":"wey-gu","description":"NebulaGraph Queries and visualization in Jupyter notebook.(previously known as ipython-ngql)","archived":false,"fork":false,"pushed_at":"2024-08-16T09:51:20.000Z","size":2305,"stargazers_count":34,"open_issues_count":5,"forks_count":5,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-02-07T18:56:36.319Z","etag":null,"topics":["graph-database","hacktoberfest","ipython","jupyter","nebula-graph","nebulagraph","python"],"latest_commit_sha":null,"homepage":"https://jupyter-nebulagraph.readthedocs.io/en/stable/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wey-gu.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-03-07T10:53:16.000Z","updated_at":"2024-12-30T22:25:51.000Z","dependencies_parsed_at":"2024-01-15T05:48:39.200Z","dependency_job_id":"9ba1dd74-b81d-4626-bfae-2d3122f636e8","html_url":"https://github.com/wey-gu/jupyter_nebulagraph","commit_stats":{"total_commits":110,"total_committers":3,"mean_commits":"36.666666666666664","dds":"0.045454545454545414","last_synced_commit":"f17465b0e0dc63879c3c484d6094ed4c6cbd4542"},"previous_names":["wey-gu/jupyter_nebulagraph","wey-gu/ipython-ngql"],"tags_count":34,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wey-gu%2Fjupyter_nebulagraph","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wey-gu%2Fjupyter_nebulagraph/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wey-gu%2Fjupyter_nebulagraph/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wey-gu%2Fjupyter_nebulagraph/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wey-gu","download_url":"https://codeload.github.com/wey-gu/jupyter_nebulagraph/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238861164,"owners_count":19542909,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["graph-database","hacktoberfest","ipython","jupyter","nebula-graph","nebulagraph","python"],"created_at":"2024-12-28T13:49:22.602Z","updated_at":"2025-10-29T17:31:14.120Z","avatar_url":"https://github.com/wey-gu.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"![](https://github.com/wey-gu/jupyter_nebulagraph/assets/1651790/61fccff2-c9be-43a0-a26f-6f5a00b1c198)\n\n\n[![for NebulaGraph](https://img.shields.io/badge/Toolchain-NebulaGraph-blue)](https://github.com/vesoft-inc/nebula) [![Jupyter](https://img.shields.io/badge/Jupyter-Supported-brightgreen)](https://github.com/jupyterlab/jupyterlab) [![Docker Image](https://img.shields.io/docker/v/weygu/nebulagraph-jupyter?label=Image\u0026logo=docker)](https://hub.docker.com/r/weygu/nebulagraph-jupyter) [![Docker Extension](https://img.shields.io/badge/Docker-Extension-blue?logo=docker)](https://hub.docker.com/extensions/weygu/nebulagraph-dd-ext) [![GitHub release (latest by date)](https://img.shields.io/github/v/release/wey-gu/jupyter_nebulagraph?label=Version)](https://github.com/wey-gu/jupyter_nebulagraph/releases)\n[![pypi-version](https://img.shields.io/pypi/v/jupyter_nebulagraph)](https://pypi.org/project/jupyter_nebulagraph/)\n[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/wey-gu/jupyter_nebulagraph/blob/main/docs/get_started.ipynb)\n[![Documentation](https://img.shields.io/badge/docs-Read%20The%20Docs-blue)](https://jupyter-nebulagraph.readthedocs.io/)\n\n\nhttps://github.com/wey-gu/jupyter_nebulagraph/assets/1651790/10135264-77b5-4d3c-b68f-c5810257feeb\n\n`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.\n\n![](https://github.com/wey-gu/jupyter_nebulagraph/assets/1651790/b3d9ca07-2eb1-45ae-949b-543f58a57760)\n\n## Getting Started\n\n```bash\npip install jupyter_nebulagraph\n```\n\nLoad the extension in Jupyter Notebook or iPython:\n\n```python\n%load_ext ngql\n%ngql --address 127.0.0.1 --port 9669 --user root --password nebula\n```\n\nMake queries:\n\n```python\n%ngql USE basketballplayer;\n%ngql MATCH p=(v:player)--\u003e(v2:player) WHERE id(v) == \"player100\" RETURN p;\n```\n\nDraw the graph:\n\n```python\n%ng_draw\n```\n\nDiscover the features of `jupyter_nebulagraph` by experimenting with it on [Google Colab](https://colab.research.google.com/github/wey-gu/jupyter_nebulagraph/blob/main/docs/get_started.ipynb). You can also access a similar Jupyter Notebook in the documentation [here](https://jupyter-nebulagraph.readthedocs.io/en/stable/get_started_docs/).\n\nFor a detailed guide, refer to the [official documentation](https://jupyter-nebulagraph.readthedocs.io/en/stable).\n\n| Feature | Cheat Sheet | Example | Command Documentation |\n| ------- | ----------- | --------- | ---------------------- |\n| Connect | `%ngql --address 127.0.0.1 --port 9669 --user user --password password` | [Connect](https://jupyter-nebulagraph.readthedocs.io/en/stable/get_started_docs/#connect-to-nebulagraph) | [`%ngql`](https://jupyter-nebulagraph.readthedocs.io/en/stable/magic_words/ngql/#connect-to-nebulagraph) |\n| Load Data from CSV | `%ng_load --source actor.csv --tag player --vid 0 --props 1:name,2:age --space basketballplayer` | [Load Data](https://jupyter-nebulagraph.readthedocs.io/en/stable/get_started_docs/#load-data-from-csv) | [`%ng_load`](https://jupyter-nebulagraph.readthedocs.io/en/stable/magic_words/ng_load/) |\n| Query Execution | `%ngql MATCH p=(v:player{name:\"Tim Duncan\"})--\u003e(v2:player) RETURN p;`| [Query Execution](https://jupyter-nebulagraph.readthedocs.io/en/stable/get_started_docs/#query) | [`%ngql` or `%%ngql`(multi-line)](https://jupyter-nebulagraph.readthedocs.io/en/stable/magic_words/ngql/#make-queries) |\n| Result Visualization | `%ng_draw` | [Draw Graph](https://jupyter-nebulagraph.readthedocs.io/en/stable/magic_words/ng_draw/) | [`%ng_draw`](https://jupyter-nebulagraph.readthedocs.io/en/stable/magic_words/ng_draw/) |\n| Draw Schema | `%ng_draw_schema` | [Draw Schema](https://jupyter-nebulagraph.readthedocs.io/en/stable/magic_words/ng_draw_schema/) | [`%ng_draw_schema`](https://jupyter-nebulagraph.readthedocs.io/en/stable/magic_words/ng_draw_schema/) |\n| Tweak Query Result | `df = _` to get last query result as `pd.dataframe` or [`ResultSet`](https://github.com/vesoft-inc/nebula-python/blob/master/nebula3/data/ResultSet.py) | [Tweak Result](https://jupyter-nebulagraph.readthedocs.io/en/stable/get_started_docs/#result-handling) | [Configure `ngql_result_style`](https://jupyter-nebulagraph.readthedocs.io/en/stable/configurations/#configure-ngql_result_style) |\n\n\n\u003cdetails\u003e\n\u003csummary\u003eClick to see more!\u003c/summary\u003e\n\n### Installation\n\n`jupyter_nebulagraph` could be installed either via pip or from this git repo itself.\n\n\u003e Install via pip\n\n```bash\npip install jupyter_nebulagraph\n```\n\n\u003e Install inside the repo\n\n```bash\ngit clone git@github.com:wey-gu/jupyter_nebulagraph.git\ncd jupyter_nebulagraph\npython setup.py install\n```\n\n### Load it in Jupyter Notebook or iPython\n\n```python\n%load_ext ngql\n```\n\n### Connect to NebulaGraph\n\nArguments as below are needed to connect a NebulaGraph DB instance:\n\n| Argument               | Description                              |\n| ---------------------- | ---------------------------------------- |\n| `--address` or `-addr` | IP address of the NebulaGraph Instance   |\n| `--port` or `-P`       | Port number of the NebulaGraph Instance  |\n| `--user` or `-u`       | User name                                |\n| `--password` or `-p`   | Password                                 |\n\nBelow is an exmple on connecting to `127.0.0.1:9669` with username: \"user\" and password: \"password\".\n\n```python\n%ngql --address 127.0.0.1 --port 9669 --user user --password password\n```\n\n### Make Queries\n\nNow two kind of iPtython Magics are supported:\n\nOption 1: The one line stype with `%ngql`:\n\n```python\n%ngql USE basketballplayer;\n%ngql MATCH (v:player{name:\"Tim Duncan\"})--\u003e(v2:player) RETURN v2.player.name AS Name;\n```\n\nOption 2: The multiple lines stype with `%%ngql `\n\n```python\n%%ngql\nSHOW TAGS;\nSHOW HOSTS;\n```\n\n### Query String with Variables\n\n`jupyter_nebulagraph` supports taking variables from the local namespace, with the help of [Jinja2](https://jinja.palletsprojects.com/) template framework, it's supported to have queries like the below example.\n\nThe actual query string should be `GO FROM \"Sue\" OVER owns_pokemon ...`, and `\"{{ trainer }}\"` was renderred as `\"Sue\"` by consuming the local variable `trainer`:\n\n```python\nIn [8]: vid = \"player100\"\n\nIn [9]: %%ngql\n   ...: MATCH (v)\u003c-[e:follow]- (v2)-[e2:serve]-\u003e(v3)\n   ...:   WHERE id(v) == \"{{ vid }}\"\n   ...: RETURN v2.player.name AS FriendOf, v3.team.name AS Team LIMIT 3;\nOut[9]:   RETURN v2.player.name AS FriendOf, v3.team.name AS Team LIMIT 3;\nFriendOf\tTeam\n0\tLaMarcus Aldridge\tTrail Blazers\n1\tLaMarcus Aldridge\tSpurs\n2\tMarco Belinelli\tWarriors\n```\n\n### Draw query results\n\n**Draw Last Query**\n\nJust call `%ng_draw` after queries with graph data.\n\n```python\n# one query\n%ngql GET SUBGRAPH 2 STEPS FROM \"player101\" YIELD VERTICES AS nodes, EDGES AS relationships;\n%ng_draw\n\n# another query\n%ngql match p=(:player)-[]-\u003e() return p LIMIT 5\n%ng_draw\n```\n\n![](https://github.com/wey-gu/jupyter_nebulagraph/assets/1651790/b3d9ca07-2eb1-45ae-949b-543f58a57760)\n\n**Draw a Query**\n\nOr `%ng_draw \u003cone_line_query\u003e`, `%%ng_draw \u003cmultiline_query\u003e` instead of drawing the result of the last query.\n\n\u003cimg width=\"1142\" alt=\"ng_draw_demo_1\" src=\"https://github.com/wey-gu/jupyter_nebulagraph/assets/1651790/a6e3b2d4-0320-4287-bd2f-537cff77c1de\"\u003e\n\nOne line query:\n\n```python\n%ng_draw GET SUBGRAPH 2 STEPS FROM \"player101\" YIELD VERTICES AS nodes, EDGES AS relationships;\n```\n\nMultiple lines query:\n\n```python\n%%ng_draw\nMATCH path_0=(n)--() WHERE id(n) == \"p_0\"\nOPTIONAL MATCH path_1=(n)--()--()\nRETURN path_0, path_1\n```\n### Draw Graph Schema\n\n```python\n%ng_draw_schema\n```\n\n![](https://github.com/wey-gu/jupyter_nebulagraph/assets/1651790/81fd71b5-61e7-4c65-93be-c2f4e507611b)\n\n### Load Data from CSV\n\nIt's supported to load data from a CSV file into NebulaGraph with the help of `ng_load_csv` magic.\n\nFor 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`:\n\n```csv\n\"player999\",\"Tom Hanks\",30\n\"player1000\",\"Tom Cruise\",40\n\"player1001\",\"Jimmy X\",33\n```\n\nJust run the below line:\n\n```python\n%ng_load --source actor.csv --tag player --vid 0 --props 1:name,2:age --space basketballplayer\n```\n\nSome other examples:\n\n```python\n# load CSV from a URL\n%ng_load --source https://github.com/wey-gu/jupyter_nebulagraph/raw/main/examples/actor.csv --tag player --vid 0 --props 1:name,2:age --space demo_basketballplayer\n# with rank column\n%ng_load --source follow_with_rank.csv --edge follow --src 0 --dst 1 --props 2:degree --rank 3 --space basketballplayer\n# without rank column\n%ng_load --source follow.csv --edge follow --src 0 --dst 1 --props 2:degree --space basketballplayer\n```\n\n### Tweak Query Result\n\nBy default, the query result is a Pandas Dataframe, and we could access that by read from variable `_`.\n\n```python\nIn [1]: %ngql MATCH (v:player{name:\"Tim Duncan\"})--\u003e(v2:player) RETURN v2.player.name AS Name;\n\nIn [2]: df = _\n```\n\nIt's also configurable to have the result in raw ResultSet, to enable handy NebulaGraph Python App Development.\n\nSee more via [Docs: Result Handling](https://jupyter-nebulagraph.readthedocs.io/en/stable/get_started_docs/#result-handling)\n\n### CheatSheet\n\nIf 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!\n\n```python\n%ngql help\n```\n\n\u003c/details\u003e\n\n## Acknowledgments ♥️\n\n- Inspiration for this project comes from [ipython-sql](https://github.com/catherinedevlin/ipython-sql), courtesy of [Catherine Devlin](https://catherinedevlin.blogspot.com/).\n- Graph visualization features are enabled by [pyvis](https://github.com/WestHealth/pyvis), a project by [WestHealth](https://github.com/WestHealth).\n- Generous sponsorship and support provided by [Vesoft Inc.](https://www.vesoft.com/) and the [NebulaGraph community](https://github.com/vesoft-inc/nebula).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwey-gu%2Fjupyter_nebulagraph","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwey-gu%2Fjupyter_nebulagraph","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwey-gu%2Fjupyter_nebulagraph/lists"}