TuGraph C++ SDK
This document is the usage instruction of TuGraph C++ SDK
1.Instructions
C++ Client can use RPC to connect to lgraph_server to import data, execute stored procedures, call Cypher and other operations.
2.Demo
2.1.Instantiate the client object
Introduce dependencies and instantiate
2.1.1. Instantiate a single node client object
When starting the server in single-node mode, the client is instantiated in the following format
RpcClient client("127.0.0.1:19099", "admin", "73@TuGraph");
RpcClient(const std::string& url, const std::string& user, const std::string& password);
@param url: tugraph host looks like ip:port
@param user: login user name
@param password: login password
2.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
RpcClient client("127.0.0.1:19099", "admin", "73@TuGraph");
RpcClient(const std::string& url, const std::string& user, const std::string& password);
@param url: tugraph host looks like ip:port
@param user: login user name
@param password: login password
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.
2.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.
std::vector<std::string> urls = {"189.33.97.23:9091", "189.33.97.24:9091", "189.33.97.25:9091"};
TuGraphDbRpcClient client = new TuGraphDbRpcClient(urls, "admin", "73@TuGraph");
RpcClient(std::vector<std::string>& urls, std::string user, std::string password)
@param urls: tugraph host list
@param user: login user name
@param password: login password
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.
2.2.Call cypher
std::string str;
bool ret = client.CallCypher(str,
"CALL db.createVertexLabel('actor', 'name', 'name', string, false, 'age', int8, true)");
bool CallCypher(std::string& result, const std::string& cypher,
const std::string& graph = "default", bool json_format = true,
double timeout = 0, const std::string& url = "");
@param [out] result The result.
@param [in] cypher inquire statement.
@param [in] graph (Optional) the graph to query.
@param [in] json_format (Optional) Returns the format， true is json，Otherwise, binary
format.
@param [in] timeout (Optional) Maximum execution time, overruns will be interrupted.
@param [in] url (Optional) Node address of calling cypher.
@returns True if it succeeds, false if it fails.
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.
2.3. Send cypher request to leader
std::string str;
bool ret = client.CallCypherToLeader(str,
"CALL db.createVertexLabel('actor', 'name', 'name', string, false, 'age', int8, true)");
bool CallCypherToLeader(std::string& result, const std::string& cypher,
const std::string& graph = "default", bool json_format = true,
double timeout = 0);
@param [out] result The result.
@param [in] cypher inquire statement.
@param [in] graph (Optional) the graph to query.
@param [in] json_format (Optional) Returns the format, true is json, otherwise, binary
format.
@param [in] timeout (Optional) Maximum execution time, overruns will be interrupted.
@returns True if it succeeds, false if it fails.
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.
2.4. Call GQL
std::string str;
bool ret = client.CallGql(str,
"CALL db.createVertexLabel('actor', 'name', 'name', string, false, 'age', int8, true)");
bool CallGql(std::string& result, const std::string& gql,
const std::string& graph = "default", bool json_format = true,
double timeout = 0, const std::string& url = "");
@param [out] result The result.
@param [in] gql inquire statement.
@param [in] graph (Optional) the graph to query.
@param [in] json_format (Optional) Returns the format, true is json, otherwise, binary
format.
@param [in] timeout (Optional) Maximum execution time, overruns will be interrupted.
@param [in] url (Optional) Node address of calling gql.
@returns True if it succeeds, false if it fails.
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.
2.5. Send GQL request to leader
std::string str;
bool ret = client.CallGqlToLeader(str,
"CALL db.createVertexLabel('actor', 'name', 'name', string, false, 'age', int8, true)");
bool CallGqlToLeader(std::string& result, const std::string& gql,
const std::string& graph = "default", bool json_format = true,
double timeout = 0);
@param [out] result The result.
@param [in] gql inquire statement.
@param [in] graph (Optional) the graph to query.
@param [in] json_format (Optional) Returns the format, true is json, otherwise, binary
format.
@param [in] timeout (Optional) Maximum execution time, overruns will be interrupted.
@returns True if it succeeds, false if it fails.
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.
2.6. Calling stored procedures
std::string str;
bool ret = client.CallProcedure(str, "CPP", "test_plugin1", "bcefg");
bool CallProcedure(std::string& result, const std::string& procedure_type,
const std::string& procedure_name, const std::string& param,
double procedure_time_out = 0.0, bool in_process = false,
const std::string& graph = "default", bool json_format = true,
const std::string& url = "");
@param [out] result The result.
@param [in] procedure_type the procedure type, currently supported CPP and PY.
@param [in] procedure_name procedure name.
@param [in] param the execution parameters.
@param [in] procedure_time_out (Optional) Maximum execution time, overruns will be
interrupted.
@param [in] in_process (Optional) support in future.
@param [in] graph (Optional) the graph to query.
@param [in] json_format (Optional) Returns the format, true is json, Otherwise,
binary format.
@param [in] url (Optional) Node address of calling procedure.
@returns True if it succeeds, false if it fails.
This interface supports use in stand-alone mode and HA mode. By default, the execution result of the stored procedure is directly returned in json format. Specifying jsonFormat as false can return the execution result in string format. Among them, in the client in HA mode, a read request can be directed to a server by specifying the url parameter.
2.7. Call the stored procedure to the leader
std::string str;
bool ret = client.CallProcedureToLeader(str, "CPP", "test_plugin1", "bcefg");
bool CallProcedureToLeader(std::string& result, const std::string& procedure_type,
const std::string& procedure_name, const std::string& param,
double procedure_time_out = 0.0, bool in_process = false,
const std::string& graph = "default", bool json_format = true);
@param [out] result The result.
@param [in] procedure_type the procedure type, currently supported CPP and PY.
@param [in] procedure_name procedure name.
@param [in] param the execution parameters.
@param [in] procedure_time_out (Optional) Maximum execution time, overruns will be
interrupted.
@param [in] in_process (Optional) support in future.
@param [in] graph (Optional) the graph to query.
@param [in] json_format (Optional) Returns the format, true is json, Otherwise,
binary format.
@returns True if it succeeds, false if it fails.
This interface supports use in HA mode. By default, the execution result of the stored procedure is directly returned in json format. Specifying jsonFormat as false can return the execution result in string format.
2.8. Load stored procedure
std::string str;
bool ret = client.LoadProcedure(str, code_sleep, "PY", "python_plugin1", "PY", "this is a test plugin", true)
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 = "v1",
const std::string& graph = "default");
@param [out] result The result.
@param [in] source_file the source_file contain procedure code.
@param [in] procedure_type the procedure type, currently supported CPP and PY.
@param [in] procedure_name procedure name.
@param [in] code_type code type, currently supported PY, SO, CPP, ZIP.
@param [in] procedure_description procedure description.
@param [in] read_only procedure is read only or not.
@param [in] version (Optional) the version of procedure.
@param [in] graph (Optional) the graph to query.
@returns True if it succeeds, false if it fails.
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.
2.9. List stored procedures
std::string str;
bool ret = client.ListProcedures(str);
bool ListProcedures(std::string& result, const std::string& procedure_type,
const std::string& version = "any",
const std::string& graph = "default", const std::string& url = "");
@param [out] result The result.
@param [in] procedure_type (Optional) the procedure type, "" for all procedures,
CPP and PY for special type.
@param [in] version (Optional) the version of procedure.
@param [in] graph (Optional) the graph to query.
@param [in] url Node address of calling procedure.
@returns True if it succeeds, false if it fails.
This interface supports use in stand-alone mode and HA mode. Among them, in the client in HA mode, the request can be directed to a server by specifying the url parameter.
2.10. Delete stored procedures
std::string str;
bool ret = client.DeleteProcedure(str, "CPP", "test_plugin1");
bool DeleteProcedure(std::string& result, const std::string& procedure_type,
const std::string& procedure_name, const std::string& graph = "default");
@param [out] result The result.
@param [in] procedure_type the procedure type, currently supported CPP and PY.
@param [in] procedure_name procedure name.
@param [in] graph (Optional) the graph to query.
@returns True if it succeeds, false if it fails.
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.
2.11. Import schema from byte stream
std::string str;
bool ret = client.ImportSchemaFromContent(str, sImportContent["schema"]);
bool ImportSchemaFromContent(std::string& result, const std::string& schema,
const std::string& graph = "default", bool json_format = true,
double timeout = 0);
@param [out] result The result.
@param [in] schema the schema to be imported.
@param [in] graph (Optional) the graph to query.
@param [in] json_format (Optional) Returns the format, true is json, otherwise, binary
format.
@param [in] timeout (Optional) Maximum execution time, overruns will be interrupted.
@returns True if it succeeds, false if it fails.
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.
2.12. Import edge data from byte stream
std::string str;
ret = client.ImportDataFromContent(str, sImportContent["person_desc"], sImportContent["person"],",");
bool ImportDataFromContent(std::string& result, const std::string& desc,
const std::string& data, const std::string& delimiter,
bool continue_on_error = false, int thread_nums = 8,
const std::string& graph = "default", bool json_format = true,
double timeout = 0);
@param [out] result The result.
@param [in] desc data format description.
@param [in] data the data to be imported.
@param [in] delimiter data separator.
@param [in] continue_on_error (Optional) whether to continue when importing data fails.
@param [in] thread_nums (Optional) maximum number of threads.
@param [in] graph (Optional) the graph to query.
@param [in] json_format (Optional) Returns the format, true is json, Otherwise,
binary format.
@param [in] timeout (Optional) Maximum execution time, overruns will be
interrupted.
@returns True if it succeeds, false if it fails.
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.
2.13. Import schema from file
std::string conf_file("./yago.conf");
std::string str;
ret = client.ImportSchemaFromFile(str, conf_file);
bool ImportSchemaFromFile(std::string& result, const std::string& schema_file,
const std::string& graph = "default", bool json_format = true,
double timeout = 0);
@param [out] result The result.
@param [in] schema_file the schema_file contain schema.
@param [in] graph (Optional) the graph to query.
@param [in] json_format (Optional) Returns the format, true is json, otherwise, binary
format.
@param [in] timeout (Optional) Maximum execution time, overruns will be interrupted.
@returns True if it succeeds, false if it fails.
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.
2.14. Import point and edge data from file
std::string conf_file("./yago.conf");
std::string str;
ret = client.ImportDataFromFile(str, conf_file, ",");
bool ImportDataFromFile(std::string& result, const std::string& conf_file,
const std::string& delimiter, bool continue_on_error = false,
int thread_nums = 8, int skip_packages = 0,
const std::string& graph = "default", bool json_format = true,
double timeout = 0);
@param [out] result The result.
@param [in] conf_file data file contains format description and data.
@param [in] delimiter data separator.
@param [in] continue_on_error (Optional) whether to continue when importing data fails.
@param [in] thread_nums (Optional) maximum number of threads.
@param [in] skip_packages (Optional) skip packages number.
@param [in] graph (Optional) the graph to query.
@param [in] json_format (Optional) Returns the format, true is json, Otherwise,
binary format.
@param [in] timeout (Optional) Maximum execution time, overruns will be
interrupted.
@returns True if it succeeds, false if it fails.
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.