TuGraph Java SDK

This document primarily provides usage instructions for the TuGraph Java SDK. It is crucial to note that the TuGraph Java SDK will no longer receive updates or maintenance in the future. Users are strongly advised to utilize bolt instead.

1.Compile java client code

cd deps/tugraph-db-client-java
sh local_build.sh

2.Demo

2.1.Instantiate the client object

Adding maven dependencies

<dependency>
    <groupId>com.antgroup.tugraph</groupId>
    <artifactId>tugraph-db-java-rpc-client</artifactId>
    <version>1.4.1</version>
</dependency>

Introduce dependencies

import com.antgroup.tugraph.TuGraphDbRpcClient;

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

TuGraphDbRpcClient client = new TuGraphDbRpcClient("127.0.0.1:19099", "admin", "73@TuGraph");

public TuGraphDbRpcClient(String url, String user, String pass)
@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

TuGraphDbRpcClient client = new TuGraphDbRpcClient("127.0.0.1:19099", "admin", "73@TuGraph");

public TuGraphDbRpcClient(String url, String user, String pass)
@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.

List<String> urls = new ArrayList<>();
urls.add("189.33.97.23:9091");
urls.add("189.33.97.24:9091");
urls.add("189.33.97.25:9091");
TuGraphDbRpcClient client = new TuGraphDbRpcClient(urls, "admin", "73@TuGraph");

public TuGraphDbRpcClient(List<String> urls, String user, 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

    String res = client.callCypher("CALL db.edgeLabels()", "default", 10);
    log.info("db.edgeLabels() : " + res);

    @param cypher: inquire statement.
    @param graph: the graph to query.
    @param timeout: Maximum execution time, overruns will be interrupted
    @param url: (Optional) Node address of calling cypher
    @return: the result of cypher query execution
    public String callCypher(String cypher, String graph, double timeout, String url)

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. Note: JAVA does not support default parameters, therefore, default parameters in JAVA are implemented using overloaded functions.

2.3. Send cypher request to leader

     String res = client.callCypherToLeader("CALL db.edgeLabels()", "default", 10);
     log.info("db.edgeLabels() : " + res);

     @param cypher: inquire statement.
     @param graph: the graph to query.
     @param timeout: Maximum execution time, overruns will be interrupted
     @return: the result of cypher query execution
     public String callCypherToLeader(String cypher, String graph, double timeout)

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

     String res = client.callGql("CALL db.edgeLabels()", "default", 10);
     log.info("db.edgeLabels() : " + res);

     @param gql: inquire statement.
     @param graph: the graph to query.
     @param timeout: Maximum execution time, overruns will be interrupted
     @param url: (Optional) Node address of calling GQL
     @return: the result of GQL query execution
     public String callGql(String gql, String graph, double timeout, String url)

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. Note: JAVA does not support default parameters, therefore, default parameters in JAVA are implemented using overloaded functions.

2.5. Send GQL request to leader

     String res = client.callGqlToLeader("CALL db.edgeLabels()", "default", 10);
     log.info("db.edgeLabels() : " + res);

     @param gql: inquire statement.
     @param graph: the graph to query.
     @param timeout: Maximum execution time, overruns will be interrupted
     @return: the result of cypher query execution
     public String callGqlToLeader(String cypher, String graph, double timeout)

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

     String result = client.callProcedure("CPP", "khop", kHopParamGen(), 1000, false, "default");
     log.info("testCallProcedure : " + result);

     @param procedureType: the procedure type, currently supported CPP and PY
     @param procedureName: procedure name
     @param param: the execution parameters
     @param procedureTimeOut: Maximum execution time, overruns will be interrupted
     @param inProcess: Running query or not
     @param graph: the graph to query
     @param jsonFormat: (Optional) Return format of calling stored procedure
     @param url: (Optional) Node address of calling procedure
     @return: the result of procedure execution
     public String callProcedure(String procedureType, String procedureName, String param, double procedureTimeOut,
             boolean inProcess, String graph, String url)

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.

2.7. Call the stored procedure to the leader

     String result = client.callProcedureToLeader("CPP", "khop", kHopParamGen(), 1000, false, "default");
     log.info("testCallProcedureToLeader : " + result);

     @param procedureType: the procedure type, currently supported CPP and PY
     @param procedureName: procedure name
     @param param: the execution parameters
     @param procedureTimeOut: Maximum execution time, overruns will be interrupted
     @param inProcess: Running query or not
     @param graph: the graph to query
     @param jsonFormat: (Optional) Return format of calling stored procedure
     @return: the result of procedure execution
     public String callProcedureToLeader(String procedureType, String procedureName, String param, double procedureTimeOut,
             boolean inProcess, String graph)

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.

2.8. Load stored procedure

     boolean result = client.loadProcedure("./test/procedure/khop.so", "CPP", "khop", "SO", "test loadprocedure", true, "v1", "default");
     log.info("loadProcedure : " + result);

     @param sourceFile: the source_file contains procedure code
     @param procedureType: the procedure type, currently supported CPP and PY
     @param procedureName: procedure name
     @param codeType: code type, currently supported PY, SO, CPP, ZIP
     @param procedureDescription: procedure description
     @param readOnly: procedure is read only or not
     @param version: The version of procedure
     @param graph: the graph to query.
     @return: the result of procedure execution
     public boolean loadProcedure(String sourceFile, String procedureType, String procedureName, String codeType,
                               String procedureDescription, boolean readOnly, String version, String graph) throws Exception

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

     String result = client.listProcedures("CPP", "any", "default");
     log.info("listProcedures : " + result);

     @param procedureType: the procedure type, currently supported CPP and PY
     @param version: The version of procedure
     @param graph: the graph to query.
     @param url: (Optional) Node address of listing procedure
     @return: the list of procedures
     public String listProcedures(String procedureType, String version, String graph, String url) throws Exception

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.10. Delete stored procedures

     String result = client.deleteProcedure("CPP", "sortstr", "default");
     log.info("loadProcedure : " + result);

     @param procedureType: the procedure type, currently supported CPP and PY
     @param procedureName: procedure name
     @param graph: the graph to query.
     @return: the result of procedure execution
     public boolean deleteProcedure(String procedureType, String procedureName, String graph) throws Exception

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

     boolean ret = client.importSchemaFromContent(schema, "default", 1000);
     log.info("importSchemaFromContent : " + ret);

     @param schema: the schema to be imported
     @param graph: the graph to query.
     @param timeout: Maximum execution time, overruns will be interrupted
     @return: the result of import schema
     public boolean importSchemaFromContent(String schema, String graph, double timeout) throws UnsupportedEncodingException

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

     boolean ret = client.importDataFromContent(personDesc, person, ",", true, 16, "default", 1000);
     log.info("importDataFromContent : " + ret);

     @param desc: data format description
     @param data: the data to be imported
     @param delimiter: data separator
     @param continueOnError: whether to continue when importing data fails
     @param threadNums: maximum number of threads
     @param graph: the graph to query.
     @param timeout: Maximum execution time, overruns will be interrupted
     @return: the result of import data
     public boolean importDataFromContent(String desc, String data, String delimiter, boolean continueOnError,
             int threadNums, String graph, double timeout) throws UnsupportedEncodingException

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

     boolean ret = client.importSchemaFromFile("./test/data/yago.conf", "default", 1000);
     log.info("importSchemaFromFile : " + ret);

     @param schemaFile: the schema_file contains schema
     @param graph: the graph to query.
     @param timeout: Maximum execution time, overruns will be interrupted
     @return: the result of import schema
     public boolean importSchemaFromFile(String schemaFile, String graph, double timeout)
             throws UnsupportedEncodingException, IOException

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

     boolean ret = client.importDataFromFile("./test/data/yago.conf", ",", true, 16, 0, "default", 1000000000);
     log.info("importDataFromFile : " + ret);

     @param confFile: data file contains format description and data
     @param delimiter: data separator
     @param continueOnError: whether to continue when importing data fails
     @param threadNums: maximum number of threads
     @param skipPackages: skip packages number
     @param graph: the graph to query.
     @param timeout: Maximum execution time, overruns will be interrupted
     @return: the result of import data
     public boolean importDataFromFile(String confFile, String delimiter, boolean continueOnError, int threadNums,
             int skipPackages, String graph, double timeout) throws IOException, UnsupportedEncodingException

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.