1_started.md

NebulaGraph Python Client Getting Started

Installation

from pypi

pip install nebula5_python==5.2.0

from source

git clone -b dev https://github.com/vesoft-inc/nebula-python.git
cd nebula-python
pip install -e .

Get Started

1. We could easily connect and get a query result.

import asyncio
from nebulagraph_python.client import AsyncNebulaClient

async def main() -> None:
    # Create async client
    # Note: AsyncNebulaClient requires manual initialization
    client = AsyncNebulaClient(
        addresses="127.0.0.1:9669",
        user_name="root",
        password="nebula",
        connect_timeout_ms=3000,
        request_timeout_ms=30000
    )

    # Initialize the connection
    await client._init_client()

    result = await client.execute("RETURN 1 AS a, 2 AS b")
    result.print()

asyncio.run(main())

2. Then we could inspect the result ourselves.

# Print the result in table style
result.print()

╔═══╤═══╗
║   │   ║
║ a │ b ║
║   │   ║
╟───┼───╢
║   │   ║
║ 1 │ 2 ║
║   │   ║
╚═══╧═══╝

Summary
├── Rows: 1
└── Latency: 1450μs

# Get one row
row = result.one()

# Get one value
cell = row["a"].cast_primitive()

# Print its value
print(cell, type(cell))

1 <class 'int'>

3. We could actually get primitive values from the result set.

print(result.as_primitive_by_column())
print(list(result.as_primitive_by_row()))

{'a': [1], 'b': [2]}
[{'a': 1, 'b': 2}]

4. If needed we could also get a pandas dataframe from the result.

We need to install pandas first.

pip install pandas

Then we could get a pandas dataframe like this:

result = await client.execute(query)

df = result.as_pandas_df()

   a  b
0  1  2

Synchronous Client

Prefer a blocking API? A synchronous client is also available and mirrors the async API:

from nebulagraph_python import NebulaClient

with NebulaClient(
    hosts=["127.0.0.1:9669"],
    user_name="root",
    password="NebulaGraph01",
) as client:
    result = client.execute("RETURN 1 AS a, 2 AS b")
    result.print()

Manual Initialization and Closing

If you prefer manual lifecycle control, you can explicitly open and close clients.

• Sync version:

from nebulagraph_python import NebulaClient

client = NebulaClient(
    hosts=["127.0.0.1:9669"],
    user_name="root",
    password="NebulaGraph01",
)
try:
    result = client.execute("RETURN 1 AS a, 2 AS b")
    result.print()
finally:
    client.close()

• Async version:

import asyncio
from nebulagraph_python.client import NebulaAsyncClient

async def main() -> None:
    client = await NebulaAsyncClient.connect(
        hosts=["127.0.0.1:9669"],
        user_name="root",
        password="NebulaGraph01",
    )
    try:
        result = await client.execute("RETURN 1 AS a, 2 AS b")
        result.print()
    finally:
        await client.close()

asyncio.run(main())

Console Tools

Run ngcli --help to get the help message. An example to connect to NebulaGraph is as follows:

ngcli -h 127.0.0.1:9669 -u root -p NebulaGraph01