NebulaGraph Python Client (nebula3-python)

The nebula3 package is the primary Python client for interacting with NebulaGraph. It provides the core functionality for connecting to GraphD, executing queries, and managing graph data. The package is organized into several key modules:

• nebula3.gclient: Subpackage containing graph client implementations.
• nebula3.Config: Module for managing configuration settings.
• nebula3.Exception: Module containing custom exception classes for error handling.
• nebula3.logger: Module for logging client activities.

The nebula3.gclient.net package provides the core networking and session management capabilities for interacting with NebulaGraph. It is organized into several submodules that handle different levels of the connection lifecycle, from raw network connections to managed session pools.

Key submodules include:

• AuthResult: Handles authentication outcomes.
• Connection: Manages low-level network connections.
• ConnectionPool: Manages a pool of Connection objects.
• Session: Represents a single logical session for executing queries.
• SessionPool: Manages a pool of Session objects for efficient query execution in multi-threaded or high-concurrency environments.

A SessionPool manages a collection of sessions to improve efficiency and reduce overhead.

Key Assumptions & Constraints:

1. A space must exist in the database before initializing the session pool.
2. Each session pool is associated with a single user and a single space. To query different spaces or use different users, you must use multiple session pools.
3. Queries executed via sessionPool.execute() run within the space configured for that pool.
4. Warning: Avoid executing commands that alter passwords or remove users through the session pool.

When the NebulaGraph core repository (vesoft-inc/nebula) updates its Thrift interface definitions, you may need to regenerate the Python RPC interface files to maintain compatibility.

To do this, you must use the thrift1 binary (built on Fedora30) and the .thrift files located in the src/interface directory of the NebulaGraph repository. This process generates the necessary Python code for common.thrift, graph.thrift, meta.thrift, and storage.thrift.

# 1. Download the thrift binary
wget https://oss-cdn.nebula-graph.com.cn/fbthrift_bin/thrift1

# 2. Generate the Python interface files
./thrift1 --strict --allow-neg-enum-vals --gen "py" -o . common.thrift
./thrift1 --strict --allow-neg-enum-vals --gen "py" -o . graph.thrift
./thrift1 --strict --allow-neg-enum-vals --gen "py" -o . meta.thrift
./thrift1 --strict --allow-neg-enum-vals --gen "py" -o . storage.thrift

You can install the NebulaGraph Python client using pip. Use nebula3-python for version 3.x of the database and nebula2-python for version 2.x.

# for v3.x
pip install nebula3-python==$version

# for v2.x
pip install nebula2-python==$version

To install from source, clone the repository and use pip install . for Python versions $\ge$ 3.7.0. For Python versions $\ge$ 3.6.2 but $<$ 3.7.0, use python3 setup.py install.

# Clone and enter directory
git clone https://github.com/vesoft-inc/nebula-python.git
cd nebula-python

# For python version >= 3.7.0
pip install .

# For python version >= 3.6.2, < 3.7.0
python3 setup.py install

To connect to a NebulaGraph service, use the ConnectionPool class. You must initialize it with a list of server addresses (tuples of (host, port)) and a Config object.

It is recommended to use connection_pool.session_context(USER, PASSWORD) within a with statement to ensure that the session is automatically released after use.

import time
from nebula3.gclient.net import ConnectionPool
from nebula3.Config import Config

SERVER = "127.0.0.1"
PORT = 9669
USER = "root"
PASSWORD = "nebula"

connection_pool = ConnectionPool()
# Initialize with a list of (host, port) tuples
connection_pool.init([(SERVER, PORT)], Config())

# Use session_context for automatic session management
with connection_pool.session_context(USER, PASSWORD) as session:
    session.execute_py("SHOW SPACES;")

connection_pool.close()

Install the NebulaGraph Python client using pip. If you are working in a Jupyter environment, use the %pip magic command.

%pip install nebula3-python

You can parameterize queries using client.execute_py(query, params). The params argument is a dictionary where keys are parameter names (e.g., $p1) and values are the data to be injected. Note that not all query tokens can be parameterized.

params = {
    "p1": 3,
    "p2": True,
    "p3": "Bob",
    "ids": ["player100", "player101"],
}

# Example with scalar parameters
resp = client.execute_py(
    "RETURN abs($p1)+3 AS col1, (toBoolean($p2) and false) AS col2, toLower($p3)+1 AS col3",
    params,
)

# Example with list parameters
resp = client.execute_py(
    "MATCH (v) WHERE id(v) in $ids RETURN id(v) AS vertex_id",
    params,
)

To prepare graph data for front-end libraries like vis.js, d3.js, or Apache ECharts, use the ResultSet.dict_for_vis() method. This returns a dictionary containing structured nodes and edges lists, along with lookup dictionaries (nodes_dict, edges_dict) and counts.

result = session.execute(
    'GET SUBGRAPH WITH PROP 2 STEPS FROM "player101" YIELD VERTICES AS nodes, EDGES AS relationships;'
)

data_for_vis = result.dict_for_vis()