Gremlin API

8.1 Gremlin

8.1.1 Sending a gremlin statement (GET) to HugeGraphServer for synchronous execution

Params
  • gremlin: The gremlin statement to be sent to HugeGraphServer for execution
  • bindings: Used to bind parameters. Key is a string, and the value is the bound value (can only be a string or number). This functionality is similar to MySQL’s Prepared Statement and is used to speed up statement execution.
  • language: The language type of the sent statement. Default is gremlin-groovy.
  • aliases: Adds aliases for existing variables in the graph space.

Querying vertices

Method & Url
  1. GET http://127.0.0.1:8080/gremlin?gremlin=hugegraph.traversal().V('1:marko')
Response Status
  1. 200
Response Body
  1. {
  2.     "requestId": "c6ef47a8-b634-4b07-9d38-6b3b69a3a556",
  3.     "status": {
  4.         "message": "",
  5.         "code": 200,
  6.         "attributes": {}
  7.     },
  8.     "result": {
  9.         "data": [{
  10.             "id": "1:marko",
  11.             "label": "person",
  12.             "type": "vertex",
  13.             "properties": {
  14.                 "city": [{
  15.                     "id": "1:marko>city",
  16.                     "value": "Beijing"
  17.                 }],
  18.                 "name": [{
  19.                     "id": "1:marko>name",
  20.                     "value": "marko"
  21.                 }],
  22.                 "age": [{
  23.                     "id": "1:marko>age",
  24.                     "value": 29
  25.                 }]
  26.             }
  27.         }],
  28.         "meta": {}
  29.     }
  30. }

8.1.2 Sending a gremlin statement (POST) to HugeGraphServer for synchronous execution

Method & Url
  1. POST http://localhost:8080/gremlin

Querying vertices

Request Body
  1. {
  2.     "gremlin": "hugegraph.traversal().V('1:marko')",
  3.     "bindings": {},
  4.     "language": "gremlin-groovy",
  5.     "aliases": {}
  6. }
Response Status
  1. 200
Response Body
  1. {
  2.     "requestId": "c6ef47a8-b634-4b07-9d38-6b3b69a3a556",
  3.     "status": {
  4.         "message": "",
  5.         "code": 200,
  6.         "attributes": {}
  7.     },
  8.     "result": {
  9.         "data": [{
  10.             "id": "1:marko",
  11.             "label": "person",
  12.             "type": "vertex",
  13.             "properties": {
  14.                 "city": [{
  15.                     "id": "1:marko>city",
  16.                     "value": "Beijing"
  17.                 }],
  18.                 "name": [{
  19.                     "id": "1:marko>name",
  20.                     "value": "marko"
  21.                 }],
  22.                 "age": [{
  23.                     "id": "1:marko>age",
  24.                     "value": 29
  25.                 }]
  26.             }
  27.         }],
  28.         "meta": {}
  29.     }
  30. }

Note:

Here we directly use the graph object (hugegraph), first retrieve its traversal iterator (traversal()), and then retrieve the vertices. Instead of writing graph.traversal().V() or g.V(), you can use aliases to operate on the graph and traversal iterator. In this case, hugegraph is a native variable, and __g_hugegraph is an additional variable added by HugeGraphServer. Each graph will have a corresponding traversal iterator object in this format (__g_${graph}).

The structure of the response body is different from the RESTful API structure of other vertices or edges. Users may need to parse it manually.

Querying edges

Request Body
  1. {
  2.     "gremlin": "g.E('S1:marko>2>>S2:lop')",
  3.     "bindings": {},
  4.     "language": "gremlin-groovy",
  5.     "aliases": {
  6.         "graph": "hugegraph", 
  7.         "g": "__g_hugegraph"
  8.     }
  9. }
Response Status
  1. 200
Response Body
  1. {
  2.     "requestId": "3f117cd4-eedc-4e08-a106-ee01d7bb8249",
  3.     "status": {
  4.         "message": "",
  5.         "code": 200,
  6.         "attributes": {}
  7.     },
  8.     "result": {
  9.         "data": [{
  10.             "id": "S1:marko>2>>S2:lop",
  11.             "label": "created",
  12.             "type": "edge",
  13.             "inVLabel": "software",
  14.             "outVLabel": "person",
  15.             "inV": "2:lop",
  16.             "outV": "1:marko",
  17.             "properties": {
  18.                 "weight": 0.4,
  19.                 "date": "20171210"
  20.             }
  21.         }],
  22.         "meta": {}
  23.     }
  24. }

8.1.3 Sending a gremlin statement (POST) to HugeGraphServer for asynchronous execution

Method & Url
  1. POST http://localhost:8080/graphs/hugegraph/jobs/gremlin

Querying vertices

Request Body
  1. {
  2.     "gremlin": "g.V('1:marko')",
  3.     "bindings": {},
  4.     "language": "gremlin-groovy",
  5.     "aliases": {}
  6. }

Note:

Asynchronous execution of Gremlin statements does not currently support aliases. You can use graph to represent the graph you want to operate on, or directly use the name of the graph, such as hugegraph. Additionally, g represents the traversal, which is equivalent to graph.traversal() or hugegraph.traversal().

Response Status
  1. 201
Response Body
  1. {
  2.     "task_id": 1
  3. }

Note:

You can query the execution status of an asynchronous task by using GET http://localhost:8080/graphs/hugegraph/tasks/1 (where “1” is the task_id). For more information, refer to the Asynchronous Task RESTful API.

Querying edges

Request Body
  1. {
  2.     "gremlin": "g.E('S1:marko>2>>S2:lop')",
  3.     "bindings": {},
  4.     "language": "gremlin-groovy",
  5.     "aliases": {}
  6. }
Response Status
  1. 201
Response Body
  1. {
  2.     "task_id": 2
  3. }

Note:

You can query the execution status of an asynchronous task by using GET http://localhost:8080/graphs/hugegraph/tasks/2 (where “2” is the task_id). For more information, refer to the Asynchronous Task RESTful API.

Last modified May 21, 2023: Update gremlin.md (#249) (bda69477)