Python客户端

此文档主要是TuGraph Python SDK的使用说明。

1. 概述

Python的TuGraph Client有两种，一种是RESTful的Client，使用HTTP方法向server发送请求，另一种是RPC的Client，使用RPC方法调用server远程服务，两者各有优劣。 RESTful client的使用方式简单，在项目的src/client/python/TuGraphClient目录下可以找到Client的源码文件，直接安装到用户环境中即可使用，但是支持的功能较少，性能也不高。RPC Client既支持单机的server，也支持高可用集群和负载均衡，接口较多，功能强大。但是使用方式较为复杂，需要用户自己编译TuGraph项目得到liblgraph_client_python.so，或者使用runtime镜像时直接在/usr/local/lib64目录下找到该依赖库，将其引入python项目即可正常使用。接下来将详细介绍这两种Client的使用方式。

2. RESTful Client

2.1.安装Client

TuGraph的Python RESTful client使用setuptools工具进行打包和分发，用户可以将client直接安装到本地环境中，在使用时即可直接引入。

cd src/client/python/TuGraphClient
python3 setup.py build
python3 setup.py install

注：使用setuptools工具安装python client时会安装httpx等依赖，需要在通外网的环境下执行。

2.2.调用Cypher

from TuGraphClient import TuGraphClient, AsyncTuGraphClient

client = TuGraphClient("127.0.0.1:7071" , "admin", "73@TuGraph")
cypher = "match (n) return properties(n) limit 1"
res = client.call_cypher(cypher)
print(res)

aclient = AsyncTuGraphClient("127.0.0.1:7071" , "admin", "73@TuGraph")
cypher = "match (n) return properties(n) limit 1"
res = await aclient.call_cypher(cypher)
print(res)

2.3.调用存储过程

from TuGraphClient import TuGraphClient, AsyncTuGraphClient

client = TuGraphClient("127.0.0.1:7071" , "admin", "73@TuGraph")
plugin_type = "cpp"
plugin_name = "khop"
plugin_input = "{\"root\": 10, \"hop\": 3}"
res = client.call_plugin(plugin_type, plguin_name, plugin_input)
print(res)

aclient = AsyncTuGraphClient("127.0.0.1:7071" , "admin", "73@TuGraph")
res = await aclient.call_plugin(plugin_type, plguin_name, plugin_input)
print(res)

3.RPC Client

Python的TuGraph Rpc Client是使用pybind11包装的CPP Client SDK，下表列出了Python和CPP Client SDK的对应关系。

Python Client SDK	CPP Client SDK
client(self: liblgraph_client_python.client, url: str, user: str, password: str)	RpcClient(const std::string& url, const std::string& user, const std::string& password)
client(self: liblgraph_client_python.client, urls: list, user: str, password: str)	RpcClient(std::vectorstd::string& urls, std::string user, std::string password)
callCypher(self: liblgraph_client_python.client, cypher: str, graph: str, json_format: bool, timeout: float, url: str) -> (bool, str)	bool CallCypher(std::string& result, const std::string& cypher, const std::string& graph, bool json_format, double timeout, const std::string& url)
callCypherToLeader(self: liblgraph_client_python.client, cypher: str, graph: str, json_format: bool, timeout: float) -> (bool, str)	bool CallCypherToLeader(std::string& result, const std::string& cypher, const std::string& graph, bool json_format, double timeout)
callGql(self: liblgraph_client_python.client, gql: str, graph: str, json_format: bool, timeout: float, url: str) -> (bool, str)	bool CallGql(std::string& result, const std::string& gql, const std::string& graph, bool json_format, double timeout, const std::string& url)
callGqlToLeader(self: liblgraph_client_python.client, gql: str, graph: str, json_format: bool, timeout: float) -> (bool, str)	bool CallGqlToLeader(std::string& result, const std::string& gql, const std::string& graph = “default”, bool json_format = true, double timeout = 0)
callProcedure(self: liblgraph_client_python.client, procedure_type: str, procedure_name: str, param: str, procedure_time_out: float, in_process: bool, graph: str, json_format: bool, url: str) -> (bool, str)	bool CallProcedure(std::string& result, const std::string& procedure_type, const std::string& procedure_name, const std::string& param, double procedure_time_out, bool in_process, const std::string& graph, bool json_format, const std::string& url)
callProcedureToLeader(self: liblgraph_client_python.client, procedure_type: str, procedure_name: str, param: str, procedure_time_out: float, in_process: bool, graph: str, json_format: bool) -> (bool, str)	CallProcedureToLeader(std::string& result, const std::string& procedure_type, const std::string& procedure_name, const std::string& param, double procedure_time_out, bool in_process, const std::string& graph, bool json_format)
loadProcedure(self: liblgraph_client_python.client, source_file: str, procedure_type: str, procedure_name: str, code_type: str, procedure_description: str, read_only: bool, version: str, graph: str) -> (bool, str)	bool LoadProcedure(std::string& result, const std::string& source_file, const std::string& procedure_type, const std::string& procedure_name, const std::string& code_type, const std::string& procedure_description, bool read_only, const std::string& version, const std::string& graph)
listProcedures(self: liblgraph_client_python.client, procedure_type: str, version: str, graph: str, url: str) -> (bool, str)	bool ListProcedures(std::string& result, const std::string& procedure_type, const std::string& version, const std::string& graph, const std::string& url)
deleteProcedure(self: liblgraph_client_python.client, procedure_type: str, procedure_name: str, graph: str) -> (bool, str)	bool DeleteProcedure(std::string& result, const std::string& procedure_type, const std::string& procedure_name, const std::string& graph)
importSchemaFromContent(self: liblgraph_client_python.client, schema: str, graph: str, json_format: bool, timeout: float) -> (bool, str)	bool ImportSchemaFromContent(std::string& result, const std::string& schema, const std::string& graph, bool json_format, double timeout)
importDataFromContent(self: liblgraph_client_python.client, desc: str, data: str, delimiter: str, continue_on_error: bool, thread_nums: int, graph: str, json_format: bool, timeout: float) -> (bool, str)	ImportDataFromContent(std::string& result, const std::string& desc, const std::string& data, const std::string& delimiter, bool continue_on_error, int thread_nums, const std::string& graph, bool json_format, double timeout)
importSchemaFromFile(self: liblgraph_client_python.client, schema_file: str, graph: str, json_format: bool, timeout: float) -> (bool, str)	ImportSchemaFromFile(std::string& result, const std::string& schema_file, const std::string& graph, bool json_format, double timeout)
importDataFromFile(self: liblgraph_client_python.client, conf_file: str, delimiter: str, continue_on_error: bool, thread_nums: int, skip_packages: int, graph: str, json_format: bool, timeout: float) -> (bool, str)	ImportDataFromFile(std::string& result, const std::string& conf_file, const std::string& delimiter, bool continue_on_error, int thread_nums, int skip_packages, const std::string& graph, bool json_format, double timeout)

Python RPC Client的使用方式较为复杂，用户可以在本地环境中编译TuGraph得到liblgraph_client_python.so，也可以使用官方提供的runtime镜像，在镜像中的/usr/local/lib64目录下可以直接找到该依赖库，引入用户项目即可使用。

import liblgraph_client_python

3.1.实例化client对象

3.1.1.实例化单节点client对象

当以单节点模式启动server时，client按照如下格式进行实例化

client = liblgraph_client_python.client("127.0.0.1:19099", "admin", "73@TuGraph")

client(self: liblgraph_client_python.client, url: str, user: str, password: str)

3.1.2.实例化HA集群直连连接client对象

当服务器上部署的HA集群可以使用ha_conf中配置的网址直接连接时，client按照如下格式进行实例化。

client = liblgraph_client_python.client("127.0.0.1:19099", "admin", "73@TuGraph")

client(self: liblgraph_client_python.client, url: str, user: str, password: str)

用户只需要传入HA集群中的任意一个节点的url即可，client会根据server端返回的查询信息自动维护连接池，在HA集群横向扩容时也不需要手动重启client。

3.1.3.实例化HA集群间接连接client对象

当服务器上部署的HA集群不能使用ha_conf中配置的网址直接连接而必须使用间接网址（如阿里云公网网址）连接时， client按照如下格式进行实例化

client = liblgraph_client_python.client(["189.33.97.23:9091","189.33.97.24:9091", "189.33.97.25:9091"], "admin", "73@TuGraph")

client(self: liblgraph_client_python.client, urls: list, user: str, password: str)

因为用户连接的网址和server启动时配置的信息不同，不能通过向集群发请求的方式自动更新client连接池，所以需要在启动 client时手动传入所有集群中节点的网址，并在集群节点变更时手动重启client。

3.2.调用cypher

ret, res = client.callCypher("CALL db.edgeLabels()", "default", 10)

callCypher(self: liblgraph_client_python.client, cypher: str, graph: str, json_format: bool, timeout: float, url: str) -> (bool, str)

本接口支持在单机模式和HA模式下使用。其中，在HA模式下的client中，通过指定url参数可以定向向某个server发送读请求。

3.3.向leader发送cypher请求

ret, res = client.callCypherToLeader("CALL db.edgeLabels()", "default", 10)

callCypherToLeader(self: liblgraph_client_python.client, cypher: str, graph: str, json_format: bool, timeout: float) -> (bool, str)

本接口只支持在HA模式下使用，在HA模式下的client中，为防止向未同步数据的follower发送请求，用户可以直接向leader发送请求，leader由集群选出。

3.4.调用GQL

ret, res = client.callGql("CALL db.edgeLabels()", "default", 10)

callGql(self: liblgraph_client_python.client, gql: str, graph: str, json_format: bool, timeout: float, url: str) -> (bool, str)

本接口支持在单机模式和HA模式下使用。其中，在HA模式下的client中，通过指定url参数可以定向向某个server发送读请求。

3.5.向leader发送GQL请求

ret, res = client.callGqlToLeader("CALL db.edgeLabels()", "default", 10)

callGqlToLeader(self: liblgraph_client_python.client, gql: str, graph: str, json_format: bool, timeout: float) -> (bool, str)

本接口只支持在HA模式下使用，在HA模式下的client中，为防止向未同步数据的follower发送请求，用户可以直接向leader发送请求，leader由集群选出。

3.6.调用存储过程

ret, res = client.callProcedure("CPP", "test_plugin1", "bcefg", 1000, False, "default")

callProcedure(self: liblgraph_client_python.client, procedure_type: str, procedure_name: str, param: str, procedure_time_out: float, in_process: bool, graph: str, json_format: bool, url: str) -> (bool, str)

本接口支持在单机模式和HA模式下使用，默认以字符串格式直接返回存储过程的执行结果，指定jsonFormat为true可以返回json格式的执行结果。其中，在HA模式下的client中，通过指定url参数可以定向向某个server发送读请求。

3.7.向leader调用存储过程

ret, res = client.callProcedureToLeader("CPP", "khop", kHopParamGen(), 1000, false, "default")

callProcedureToLeader(self: liblgraph_client_python.client, procedure_type: str, procedure_name: str, param: str, procedure_time_out: float, in_process: bool, graph: str, json_format: bool) -> (bool, str)

本接口支持在HA模式下使用，默认以字符串格式直接返回存储过程的执行结果，指定jsonFormat为true可以返回json格式的执行结果。

3.8.加载存储过程

ret, res = client.loadProcedure("./test/procedure/khop.so", "CPP", "khop", "SO", "test loadprocedure", true, "v1", "default");

loadProcedure(self: liblgraph_client_python.client, source_file: str, procedure_type: str, procedure_name: str, code_type: str, procedure_description: str, read_only: bool, version: str, graph: str) -> (bool, str)

本接口支持在单机模式和HA模式下使用。其中，由于加载存储过程是写请求，HA模式下的client只能向leader发送加载存储过程请求。

3.9.列举存储过程

ret, res = client.listProcedures("CPP", "any", "default")

listProcedures(self: liblgraph_client_python.client, procedure_type: str, version: str, graph: str, url: str) -> (bool, str)

本接口支持在单机模式和HA模式下使用。其中，在HA模式下的client中，通过指定url参数可以定向向某个server发送读请求。

3.10.删除存储过程

ret, res = client.deleteProcedure("CPP", "sortstr", "default")

deleteProcedure(self: liblgraph_client_python.client, procedure_type: str, procedure_name: str, graph: str) -> (bool, str)

本接口支持在单机模式和HA模式下使用。其中，由于删除存储过程是写请求，HA模式下的client只能向leader发送删除存储过程请求。

3.11.从字节流中导入schema

ret, res = client.importSchemaFromContent(schema, "default", 1000)

importSchemaFromContent(self: liblgraph_client_python.client, schema: str, graph: str, json_format: bool, timeout: float) -> (bool, str)

本接口支持在单机模式和HA模式下使用。其中，由于导入schema是写请求，HA模式下的client只能向leader发送导入schema请求。

3.12.从字节流中导入点边数据

ret, res = client.importDataFromContent(personDesc, person, ",", true, 16, "default", 1000)

importDataFromContent(self: liblgraph_client_python.client, desc: str, data: str, delimiter: str, continue_on_error: bool, thread_nums: int, graph: str, json_format: bool, timeout: float) -> (bool, str)

本接口支持在单机模式和HA模式下使用。其中，由于导入点边数据是写请求，HA模式下的client只能向leader发送导入点边数据请求。

3.13.从文件中导入schema

ret, res = client.importSchemaFromFile("./test/data/yago.conf", "default", 1000)

importSchemaFromFile(self: liblgraph_client_python.client, schema_file: str, graph: str, json_format: bool, timeout: float) -> (bool, str)

本接口支持在单机模式和HA模式下使用。其中，由于导入schema是写请求，HA模式下的client只能向leader发送导入schema请求。

3.14.从文件中导入点边数据

ret, res = client.importDataFromFile("./test/data/yago.conf", ",", true, 16, 0, "default", 1000000000)

importDataFromFile(self: liblgraph_client_python.client, conf_file: str, delimiter: str, continue_on_error: bool, thread_nums: int, skip_packages: int, graph: str, json_format: bool, timeout: float) -> (bool, str)

本接口支持在单机模式和HA模式下使用。其中，由于导入点边数据是写请求，HA模式下的client只能向leader发送导入点边数据请求。