Skip to content

Version 1.7 of the documentation is no longer actively maintained. The site that you are currently viewing is an archived snapshot. For up-to-date documentation, see the latest version.

HugeGraph Python Client Quick Start

hugegraph-python-client is the Python SDK for HugeGraph. It manages schemas, reads and writes graph data, and executes Gremlin queries. HugeGraph-LLM and HugeGraph-ML also use this client.

Requirements

  • Python 3.9 or later
  • An accessible HugeGraph Server
  • uv (recommended) or pip

Installation

The package is currently published on PyPI as hugegraph-python:

1uv pip install hugegraph-python
2# Alternatively: pip install hugegraph-python

To use the latest repository code, sync the workspace from the root of the HugeGraph-AI repository:

1git clone https://github.com/apache/hugegraph-ai.git
2cd hugegraph-ai
3uv sync
4source .venv/bin/activate

Connect and Write Data

 1from pyhugegraph.client import PyHugeClient
 2
 3client = PyHugeClient(
 4    "127.0.0.1:8080",
 5    graph="hugegraph",
 6    user="admin",
 7    pwd="admin",
 8    graphspace="DEFAULT",
 9)
10
11schema = client.schema()
12schema.propertyKey("name").asText().ifNotExist().create()
13schema.propertyKey("birthDate").asText().ifNotExist().create()
14schema.vertexLabel("Person").properties("name", "birthDate") \
15      .usePrimaryKeyId().primaryKeys("name").ifNotExist().create()
16schema.vertexLabel("Movie").properties("name") \
17      .usePrimaryKeyId().primaryKeys("name").ifNotExist().create()
18schema.edgeLabel("ActedIn").sourceLabel("Person").targetLabel("Movie") \
19      .ifNotExist().create()
20
21graph = client.graph()
22person = graph.addVertex(
23    "Person", {"name": "Al Pacino", "birthDate": "1940-04-25"}
24)
25movie = graph.addVertex("Movie", {"name": "The Godfather"})
26edge = graph.addEdge("ActedIn", person.id, movie.id, {})
27
28print(graph.getVertexById(person.id))
29print(graph.getEdgeById(edge.id))
30graph.close()

If GraphSpace is disabled in HugeGraph, omit graphspace. When it is enabled, pass the actual space name; the default space is usually DEFAULT.

Common Operations

Query the Schema

1schema = client.schema()
2print(schema.getPropertyKeys())
3print(schema.getVertexLabels())
4print(schema.getEdgeLabels())
5print(schema.getIndexLabels())

Update and Delete Graph Data

The graph API accepts dictionaries containing object properties:

1graph = client.graph()
2graph.appendVertex(person.id, {"birthDate": "1940-04-25"})
3graph.removeEdgeById(edge.id)
4graph.removeVertexById(person.id)
5graph.close()

Execute Gremlin

1gremlin = client.gremlin()
2result = gremlin.exec("g.V().limit(5)")
3print(result)

API parameters may change with the HugeGraph REST API version. If an interface is incompatible, first check the REST API documentation for the current server version and the client test cases.

Development Checks

Run formatting and static checks from the root of the HugeGraph-AI repository:

1./style/code_format_and_analysis.sh

The source code and tests are under hugegraph-python-client/src/pyhugegraph/ and hugegraph-python-client/src/tests/.

Last modified 2026-09-04 · docs: sync 1.7 documentation (4211f768b)