TuGraph Python SDK

This document is the usage instruction of TuGraph Python SDK

1.Overview

There are two kinds of Python’s TuGraph Client. One is the RESTful Client, which uses the HTTP method to send requests to the server. The other is the RPC Client, which uses the RPC method to call the server remote service. Both have their own advantages and disadvantages. The RESTful client is simple to use. You can find the source code file of the Client in the src/client/python/TuGraphClient directory of the project. You can install it directly into the user environment and use it. However, it supports fewer functions and its performance is not high. RPC Client supports both stand-alone servers and high-availability clusters and load balancing. It has many interfaces and powerful functions. However, the usage is more complicated. Users need to compile the TuGraph project themselves to obtain liblgraph_client_python.so, or directly find the dependent library in the /usr/local/lib64 directory when using the runtime image, and introduce it into the python project for normal use. Next, the usage of these two Clients will be introduced in detail.

2.RESTful Client

2.1. Install Client

TuGraph’s Python RESTful client uses the setuptools tool for packaging and distribution. Users can install the client directly into the local environment and introduce it directly when using it.

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

Note: When using the setuptools tool to install the python client, dependencies such as httpx will be installed and need to be executed in an environment with external network access.

2.2.Call 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)

2.3.Call stored procedure

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)

3.RPC Client

Python’s TuGraph Rpc Client is a CPP Client SDK packaged using pybind11. The following table lists the correspondence between Python and 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)

The use of Python RPC Client is more complicated. Users can compile TuGraph in the local environment to get liblgraph_client_python.so, or they can use the official runtime image. The dependent library can be found directly in the /usr/local/lib64 directory in the image. It can be used after introducing the user project.

import liblgraph_client_python

3.1.Instantiate the client object

3.1.1.Instantiate a single node client object

When starting the server in single-node mode, the client is instantiated in the following format

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.Instantiate the HA cluster to directly connect to the client object

When the HA cluster deployed on the server can be directly connected using the URL configured in ha_conf, the client is instantiated according to the following format

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)

The user only needs to pass in the url of any node in the HA cluster, and the client will automatically maintain the connection pool based on the query information returned by the server, and there is no need to manually restart the client when the HA cluster expands horizontally.

3.1.3.Instantiate the HA cluster to indirectly connect to the client object

When the HA cluster deployed on the server cannot use the URL configured in ha_conf to connect directly but must use an indirect URL (such as the Alibaba Cloud public network URL), the client is instantiated according to the following format.

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)

Because the URL that the user connects to is different from the information configured when the server starts, the client connection pool cannot be automatically updated by sending a request to the cluster, so it is necessary to manually pass in the URLs of all nodes in the cluster when starting the client, and when the cluster node changes Manually restart the client.

3.2.Call 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)

This interface supports use in stand-alone mode and HA mode. Among them, in the client in HA mode, a read request can be directed to a server by specifying the url parameter.

3.3.Send cypher request to leader

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)

This interface only supports use in HA mode. In the client in HA mode, in order to prevent requests from being sent to followers with unsynchronized data, Users can directly send requests to the leader, and the leader is elected by the cluster.

3.4.Call 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)

This interface supports use in stand-alone mode and HA mode. Among them, in the client in HA mode, a read request can be directed to a server by specifying the url parameter.

3.5.Send GQL request to leader

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)

This interface only supports use in HA mode. In the client in HA mode, in order to prevent requests from being sent to followers with unsynchronized data, Users can directly send requests to the leader, and the leader is elected by the cluster.

3.6.Calling stored procedures

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)

This interface supports use in stand-alone mode and HA mode. By default, the execution result of the stored procedure is directly returned in string format. Specifying jsonFormat as true can return the execution result in json format. Among them, in the client in HA mode, a read request can be directed to a server by specifying the url parameter.

3.7.Call the stored procedure to the 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)

This interface supports use in HA mode. By default, the execution result of the stored procedure is directly returned in string format. Specifying jsonFormat as true can return the execution result in json format.

3.8.Load stored procedure

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)

This interface supports use in stand-alone mode and HA mode. Among them, since loading a stored procedure is a write request, the client in HA mode can only send a request to load a stored procedure to the leader.

3.9.List stored procedures

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

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

This interface supports use in stand-alone mode and HA mode. Among them, in the client in HA mode, a read request can be directed to a server by specifying the url parameter.

3.10.Delete stored procedures

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

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

This interface supports use in stand-alone mode and HA mode. Among them, since deleting a stored procedure is a write request, the client in HA mode can only send a delete request to the leader.

3.11.Import schema from byte stream

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

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

This interface supports use in stand-alone mode and HA mode. Among them, since importing schema is a write request, the client in HA mode can only send an import schema request to the leader.

3.12.Import edge data from byte stream

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)

This interface supports use in stand-alone mode and HA mode. Among them, since importing point and edge data is a write request, the client in HA mode can only send a request to import point and edge data to the leader.

3.13.Import schema from file

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)

This interface supports use in stand-alone mode and HA mode. Among them, since importing schema is a write request, the client in HA mode can only send an import schema request to the leader.

3.14.Import point and edge data from file

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)

This interface supports use in stand-alone mode and HA mode. Among them, since importing point and edge data is a write request, the client in HA mode can only send a request to import point and edge data to the leader.