HugeGraph Python 客户端快速入门
hugegraph-python-client
是 HugeGraph 图数据库的 Python 客户端/SDK。
它用于定义图结构、对图数据执行 CRUD 操作、管理 Schema 以及执行 Gremlin 查询。hugegraph-llm
和 hugegraph-ml
模块都依赖于这个基础库。
安装
安装已发布的包(稳定版)
要安装 hugegraph-python-client
,您可以使用 uv/pip 或从源码构建:
# uv 是可选的,您可以直接使用 pip uv pip install hugegraph-python # 注意:可能不是最新版本,建议从源码安装 # WIP:我们很快会将 'hugegraph-python-client' 作为包名
从源码安装(最新代码)
要从源码安装,请克隆仓库并安装所需的依赖项:
git clone https://github.com/apache/incubator-hugegraph-ai.git cd incubator-hugegraph-ai/hugegraph-python-client # 普通安装 uv pip install . # (可选) 安装开发版本 uv pip install -e .
使用示例
定义图结构
您可以使用 hugegraph-python-client
来定义图结构。以下是如何定义图的示例:
from pyhugegraph.client import PyHugeClient # 初始化客户端 # 对于 HugeGraph API 版本 ≥ v3:(或启用 graphspace 功能) # - 如果启用了 graphspace,则 'graphspace' 参数变得相关(默认名称为 'DEFAULT') # - 否则,graphspace 参数是可选的,可以忽略。 client = PyHugeClient("127.0.0.1", "8080", user="admin", pwd="admin", graph="hugegraph", graphspace="DEFAULT") """" 注意: 可以参考您 HugeGraph 版本的官方 REST-API 文档以获取准确的详细信息。 如果某些 API 与预期不符,请提交 issue 或联系我们。 """ schema = client.schema() schema.propertyKey("name").asText().ifNotExist().create() schema.propertyKey("birthDate").asText().ifNotExist().create() schema.vertexLabel("Person").properties("name", "birthDate").usePrimaryKeyId().primaryKeys("name").ifNotExist().create() schema.vertexLabel("Movie").properties("name").usePrimaryKeyId().primaryKeys("name").ifNotExist().create() schema.edgeLabel("ActedIn").sourceLabel("Person").targetLabel("Movie").ifNotExist().create() print(schema.getVertexLabels()) print(schema.getEdgeLabels()) print(schema.getRelations()) # 初始化图 g = client.graph() v_al_pacino = g.addVertex("Person", {"name": "Al Pacino", "birthDate": "1940-04-25"}) v_robert = g.addVertex("Person", {"name": "Robert De Niro", "birthDate": "1943-08-17"}) v_godfather = g.addVertex("Movie", {"name": "The Godfather"}) v_godfather2 = g.addVertex("Movie", {"name": "The Godfather Part II"}) v_godfather3 = g.addVertex("Movie", {"name": "The Godfather Coda The Death of Michael Corleone"}) g.addEdge("ActedIn", v_al_pacino.id, v_godfather.id, {}) g.addEdge("ActedIn", v_al_pacino.id, v_godfather2.id, {}) g.addEdge("ActedIn", v_al_pacino.id, v_godfather3.id, {}) g.addEdge("ActedIn", v_robert.id, v_godfather2.id, {}) res = g.getVertexById(v_al_pacino.id).label print(res) g.close()
Schema 管理
hugegraph-python-client
提供了全面的 Schema 管理功能。
定义属性键 (Property Key)
# 定义属性键 client.schema().propertyKey('name').dataType('STRING').cardinality('SINGLE').create()
定义顶点标签 (Vertex Label)
# 定义顶点标签 client.schema().vertexLabel('person').properties('name', 'age').primaryKeys('name').create()
定义边标签 (Edge Label)
# 定义边标签 client.schema().edgeLabel('knows').sourceLabel('person').targetLabel('person').properties('since').create()
定义索引标签 (Index Label)
# 定义索引标签 client.schema().indexLabel('personByName').onV('person').by('name').secondary().create()
CRUD 操作
客户端允许您对图数据执行 CRUD 操作。以下是如何创建、读取、更新和删除顶点和边的示例:
创建顶点和边
# 创建顶点 v1 = client.graph().addVertex('person').property('name', 'John').property('age', 29).create() v2 = client.graph().addVertex('person').property('name', 'Jane').property('age', 25).create() # 创建边 client.graph().addEdge(v1, 'knows', v2).property('since', '2020').create()
读取顶点和边
# 通过 ID 获取顶点 vertex = client.graph().getVertexById(v1.id) print(vertex) # 通过 ID 获取边 edge = client.graph().getEdgeById(edge.id) # 假设 edge 对象已定义并有 id 属性 print(edge)
更新顶点和边
# 更新顶点 client.graph().updateVertex(v1.id).property('age', 30).update() # 更新边 client.graph().updateEdge(edge.id).property('since', '2021').update() # 假设 edge 对象已定义并有 id 属性
删除顶点和边
# 删除顶点 client.graph().deleteVertex(v1.id) # 删除边 client.graph().deleteEdge(edge.id) # 假设 edge 对象已定义并有 id 属性
执行 Gremlin 查询
客户端还支持执行 Gremlin 查询:
# 执行 Gremlin 查询 g = client.gremlin() res = g.exec("g.V().limit(5)") print(res)
其他信息正在建设中 🚧 (欢迎为此添加更多文档,用户可以参考 java-client-doc 获取类似用法)
API 文档参考
贡献
- 欢迎为
hugegraph-python-client
做出贡献。请参阅 贡献指南 获取更多信息。 - 代码格式:请在提交 PR 前运行
./style/code_format_and_analysis.sh
来格式化您的代码。
感谢所有已经为 hugegraph-python-client
做出贡献的人!
Last modified June 13, 2025: BREAKING CHANGE: refactor doc structure & add new content for client/AI (#407) (48ff6f26)