|
| 1 | +# Graph Planner Interface by JNI and RESTful API |
| 2 | + |
| 3 | +`GraphPlanner` is the primary entry point for GOpt’s query optimization and physical plan generation. Originally, it was tightly integrated into the Frontend service, where it optimized Cypher queries received via the Bolt protocol and generated execution plans for various backend engines. |
| 4 | + |
| 5 | +To enhance its flexibility and ease of integration, `GraphPlanner` is now available as a standalone module, free from any dependencies on other Frontend modules. It supports both JNI and RESTful API interfaces, enabling lightweight and straightforward integration into diverse systems. Whether you are working on a native application or web-based services, `GraphPlanner` can seamlessly integrate into your architecture, providing efficient query optimization and physical plan generation across a wide range of use cases. |
| 6 | + |
| 7 | + |
| 8 | +## JNI API |
| 9 | + |
| 10 | +### Interface Overview |
| 11 | + |
| 12 | +We provide a c++ wrapper implementation `GraphPlannerWrapper` for the JNI interface. Here is a brief explanation of the logical interface provided by the `c++` class. |
| 13 | + |
| 14 | +Constructor: |
| 15 | + |
| 16 | +```cpp |
| 17 | +/** |
| 18 | + * @brief Constructs a new GraphPlannerWrapper object |
| 19 | + * @param java_path Java class path |
| 20 | + * @param jna_path JNA library path |
| 21 | + * @param graph_schema_yaml Path to the graph schema file in YAML format (optional) |
| 22 | + * @param graph_statistic_json Path to the graph statistics file in JSON format (optional) |
| 23 | + */ |
| 24 | +GraphPlannerWrapper(const std::string &java_path, |
| 25 | + const std::string &jna_path, |
| 26 | + const std::string &graph_schema_yaml = "", |
| 27 | + const std::string &graph_statistic_json = ""); |
| 28 | +``` |
| 29 | +
|
| 30 | +Method: |
| 31 | +
|
| 32 | +```cpp |
| 33 | +/** |
| 34 | + * @brief Compile a cypher query to a physical plan by JNI invocation. |
| 35 | + * @param compiler_config_path The path of compiler config file. |
| 36 | + * @param cypher_query_string The cypher query string. |
| 37 | + * @param graph_schema_yaml Content of the graph schema in YAML format |
| 38 | + * @param graph_statistic_json Content of the graph statistics in JSON format |
| 39 | + * @return The physical plan in bytes and result schema in yaml. |
| 40 | + */ |
| 41 | +Plan GraphPlannerWrapper::CompilePlan(const std::string &compiler_config_path, |
| 42 | + const std::string &cypher_query_string, |
| 43 | + const std::string &graph_schema_yaml, |
| 44 | + const std::string &graph_statistic_json) |
| 45 | +``` |
| 46 | + |
| 47 | +### Getting Started |
| 48 | +Follow the steps below to get started with the Graph Planner interface for c++ invocation. |
| 49 | + |
| 50 | +#### Step 1: Build the Project |
| 51 | + |
| 52 | +Navigate to the project directory and build the package using Maven: |
| 53 | +```bash |
| 54 | +cd interactive_engine |
| 55 | +mvn clean package -DskipTests -Pgraph-planner-jni |
| 56 | +``` |
| 57 | + |
| 58 | +#### Step 2: Locate and Extract the Package |
| 59 | + |
| 60 | +After the build completes, a tarball named `graph-planner-jni.tar.gz` will be available in the `assembly/target` directory. Extract the contents of the tarball: |
| 61 | + |
| 62 | +```bash |
| 63 | +cd assembly/target |
| 64 | +tar xvzf graph-planner-jni.tar.gz |
| 65 | +cd graph-planner-jni |
| 66 | +``` |
| 67 | + |
| 68 | +#### Step 3: Run the Example Binary |
| 69 | + |
| 70 | +To demonstrate the usage of the JNI interface, an example binary `test_graph_planner` is provided. Use the following command to execute it: |
| 71 | + |
| 72 | +```bash |
| 73 | +# bin/test_graph_planner <java class path> <jna lib path> <graph schema path> <graph statistics path> <query> <config path> |
| 74 | +bin/test_graph_planner libs native ./conf/graph.yaml ./conf/modern_statistics.json "MATCH (n) RETURN n, COUNT(n);" ./conf/gs_interactive_hiactor.yaml |
| 75 | +``` |
| 76 | + |
| 77 | +The output consists of the physical plan (in byte format) and the result schema (in YAML format). The physical plan adheres to the specifications defined in the [protobuf](). |
| 78 | + |
| 79 | +Below is an example of a result schema: |
| 80 | + |
| 81 | +```yaml |
| 82 | +schema: |
| 83 | + name: default |
| 84 | + description: default desc |
| 85 | + mode: READ |
| 86 | + extension: .so |
| 87 | + library: libdefault.so |
| 88 | + params: [] |
| 89 | +returns: |
| 90 | + - name: n |
| 91 | + type: {primitive_type: DT_UNKNOWN} |
| 92 | + - name: $f1 |
| 93 | + type: {primitive_type: DT_SIGNED_INT64} |
| 94 | +type: UNKNOWN |
| 95 | +query: MATCH (n) RETURN n, COUNT(n); |
| 96 | +``` |
| 97 | +
|
| 98 | +The `returns` field defines the structure of the data returned by backend engines. Each nested entry in the returns field includes three components: |
| 99 | +- the column name, which specifies the name of the result column; |
| 100 | +- the entry’s ordinal position, which determines the column ID; |
| 101 | +- the type, which enforces the data type constraint for the column. |
| 102 | + |
| 103 | +## Restful API |
| 104 | + |
| 105 | +We provide an alternative method to expose the interface as a RESTful API. Follow the steps below to access the interface via REST. |
| 106 | + |
| 107 | +### Getting Started |
| 108 | + |
| 109 | +#### Step 1: Build the Project |
| 110 | + |
| 111 | +To build the project, run the following command: |
| 112 | +```bash |
| 113 | +cd interactive_engine |
| 114 | +# Use '-Dskip.native=true' to skip compiling C++ native code |
| 115 | +mvn clean package -DskipTests -Pgraph-planner-jni -Dskip.native=true |
| 116 | +``` |
| 117 | + |
| 118 | +#### Step 2: Locate and Extract the Package |
| 119 | + |
| 120 | +Once the build completes, a tarball named graph-planner-jni.tar.gz will be available in the assembly/target directory. Extract the contents as follows: |
| 121 | + |
| 122 | +```bash |
| 123 | +cd assembly/target |
| 124 | +tar xvzf graph-planner-jni.tar.gz |
| 125 | +cd graph-planner-jni |
| 126 | +``` |
| 127 | + |
| 128 | +#### Step 3: Start the Graph Planner RESTful Service |
| 129 | + |
| 130 | +To start the service, run the following command: |
| 131 | + |
| 132 | +```bash |
| 133 | +java -cp ".:./libs/*" com.alibaba.graphscope.sdk.restful.GraphPlannerService --spring.config.location=./conf/application.yaml |
| 134 | +``` |
| 135 | + |
| 136 | +#### Step 4: Access the RESTful API by `Curl` |
| 137 | + |
| 138 | +To send a request to the RESTful API, use the following `curl` command: |
| 139 | + |
| 140 | +```bash |
| 141 | +curl -X POST http://localhost:8080/api/compilePlan \ |
| 142 | + -H "Content-Type: application/json" \ |
| 143 | + -d "{ |
| 144 | + \"configPath\": \"$configPath\", |
| 145 | + \"query\": \"$query\", |
| 146 | + \"schemaYaml\": \"$schemaYaml\", |
| 147 | + \"statsJson\": \"$statsJson\" |
| 148 | + }" |
| 149 | +``` |
| 150 | + |
| 151 | +Replace `$configPath`, `$query`, `$schemaYaml`, and `$statsJson` with the appropriate values. |
| 152 | + |
| 153 | +The response will be in JSON format, similar to: |
| 154 | + |
| 155 | +```json |
| 156 | +{ |
| 157 | + "graphPlan": { |
| 158 | + "physicalBytes": "", |
| 159 | + "resultSchemaYaml": "" |
| 160 | + } |
| 161 | +} |
| 162 | +``` |
| 163 | + |
| 164 | +The response contains two fields: |
| 165 | +1. physicalBytes: A Base64-encoded string representing the physical plan bytes. |
| 166 | +2. resultSchemaYaml: A string representing the YAML schema. |
| 167 | + |
| 168 | +You can decode these values into the required structures. |
| 169 | + |
| 170 | +#### Step 4: Access the RESTful API by `Java` Sdk |
| 171 | + |
| 172 | +Alternatively, if you are a java-side user, we provide a java sdk example to guide you how to access the restful API and decode the response : |
| 173 | + |
| 174 | +```java |
| 175 | +public static void main(String[] args) throws Exception { |
| 176 | + if (args.length < 4) { |
| 177 | + System.out.println("Usage: <configPath> <query> <schemaPath> <statsPath>"); |
| 178 | + System.exit(1); |
| 179 | + } |
| 180 | + // set request body in json format |
| 181 | + String jsonPayLoad = createParameters(args[0], args[1], args[2], args[3]).toString(); |
| 182 | + HttpClient client = HttpClient.newBuilder().build(); |
| 183 | + // create http request, set header and body content |
| 184 | + HttpRequest request = |
| 185 | + HttpRequest.newBuilder() |
| 186 | + .uri(URI.create("http://localhost:8080/api/compilePlan")) |
| 187 | + .setHeader("Content-Type", "application/json") |
| 188 | + .POST( |
| 189 | + HttpRequest.BodyPublishers.ofString( |
| 190 | + jsonPayLoad, StandardCharsets.UTF_8)) |
| 191 | + .build(); |
| 192 | + // send request and get response |
| 193 | + HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString()); |
| 194 | + String body = response.body(); |
| 195 | + // parse response body as json |
| 196 | + JsonNode planNode = (new ObjectMapper()).readTree(body).get("graphPlan"); |
| 197 | + // print result |
| 198 | + System.out.println(getPhysicalPlan(planNode)); |
| 199 | + System.out.println(getResultSchemaYaml(planNode)); |
| 200 | +} |
| 201 | +
|
| 202 | +private static JsonNode createParameters( |
| 203 | + String configPath, String query, String schemaPath, String statsPath) throws Exception { |
| 204 | + Map<String, String> params = |
| 205 | + ImmutableMap.of( |
| 206 | + "configPath", |
| 207 | + configPath, |
| 208 | + "query", |
| 209 | + query, |
| 210 | + "schemaYaml", |
| 211 | + FileUtils.readFileToString(new File(schemaPath), StandardCharsets.UTF_8), |
| 212 | + "statsJson", |
| 213 | + FileUtils.readFileToString(new File(statsPath), StandardCharsets.UTF_8)); |
| 214 | + return (new ObjectMapper()).valueToTree(params); |
| 215 | +} |
| 216 | +
|
| 217 | +// get base64 string from json, convert it to physical bytes , then parse it to PhysicalPlan |
| 218 | +private static GraphAlgebraPhysical.PhysicalPlan getPhysicalPlan(JsonNode planNode) |
| 219 | + throws Exception { |
| 220 | + String base64Str = planNode.get("physicalBytes").asText(); |
| 221 | + byte[] bytes = java.util.Base64.getDecoder().decode(base64Str); |
| 222 | + return GraphAlgebraPhysical.PhysicalPlan.parseFrom(bytes); |
| 223 | +} |
| 224 | +
|
| 225 | +// get result schema yaml from json |
| 226 | +private static String getResultSchemaYaml(JsonNode planNode) { |
| 227 | + return planNode.get("resultSchemaYaml").asText(); |
| 228 | +} |
| 229 | +``` |
| 230 | + |
| 231 | +Run the java sdk example with the following command: |
| 232 | +```bash |
| 233 | +java -cp ".:./libs/*" com.alibaba.graphscope.sdk.examples.TestGraphPlanner ./conf/gs_interactive_hiactor.yaml "Match (n) Return n;" ./conf/graph.yaml ./conf/modern_statistics.json |
| 234 | +``` |
0 commit comments