Gremlin-Console

Gremlin-Console is an interactive client developed by TinkerPop. Users can use this client to perform various operations on Graph. There are two main usage modes:

  • Stand-alone offline mode
  • Client/Server mode

1 Stand-alone offline mode

Since the lib directory already contains the HugeCore jar package, and HugeGraph has been registered in the Console as a plug-in, the users can write a groovy script directly to call the code of HugeGraph-Core, and then hand it over to the parsing engine in Gremlin-Console for execution. As a result, the users can operate the graph without starting the Server.

This mode is convenient for users to get started quickly, but it is not suitable for scenarios where a large amount of data is inserted and queried. Here is an example:

There is a sample script in the script directory example.groovy:

  1. import org.apache.hugegraph.HugeFactory
  2. import org.apache.hugegraph.backend.id.IdGenerator
  3. import org.apache.hugegraph.dist.RegisterUtil
  4. import org.apache.hugegraph.type.define.NodeRole
  5. import org.apache.tinkerpop.gremlin.structure.T
  7. RegisterUtil.registerRocksDB()
  9. conf = "conf/graphs/hugegraph.properties"
  10. graph = HugeFactory.open(conf)
  11. graph.serverStarted(IdGenerator.of("server-tinkerpop"), NodeRole.MASTER)
  12. schema = graph.schema()
  14. schema.propertyKey("name").asText().ifNotExist().create()
  15. schema.propertyKey("age").asInt().ifNotExist().create()
  16. schema.propertyKey("city").asText().ifNotExist().create()
  17. schema.propertyKey("weight").asDouble().ifNotExist().create()
  18. schema.propertyKey("lang").asText().ifNotExist().create()
  19. schema.propertyKey("date").asText().ifNotExist().create()
  20. schema.propertyKey("price").asInt().ifNotExist().create()
  22. schema.vertexLabel("person").properties("name", "age", "city").primaryKeys("name").ifNotExist().create()
  23. schema.vertexLabel("software").properties("name", "lang", "price").primaryKeys("name").ifNotExist().create()
  24. schema.indexLabel("personByCity").onV("person").by("city").secondary().ifNotExist().create()
  25. schema.indexLabel("personByAgeAndCity").onV("person").by("age", "city").secondary().ifNotExist().create()
  26. schema.indexLabel("softwareByPrice").onV("software").by("price").range().ifNotExist().create()
  27. schema.edgeLabel("knows").sourceLabel("person").targetLabel("person").properties("date", "weight").ifNotExist().create()
  28. schema.edgeLabel("created").sourceLabel("person").targetLabel("software").properties("date", "weight").ifNotExist().create()
  29. schema.indexLabel("createdByDate").onE("created").by("date").secondary().ifNotExist().create()
  30. schema.indexLabel("createdByWeight").onE("created").by("weight").range().ifNotExist().create()
  31. schema.indexLabel("knowsByWeight").onE("knows").by("weight").range().ifNotExist().create()
  33. marko = graph.addVertex(T.label, "person", "name", "marko", "age", 29, "city", "Beijing")
  34. vadas = graph.addVertex(T.label, "person", "name", "vadas", "age", 27, "city", "Hongkong")
  35. lop = graph.addVertex(T.label, "software", "name", "lop", "lang", "java", "price", 328)
  36. josh = graph.addVertex(T.label, "person", "name", "josh", "age", 32, "city", "Beijing")
  37. ripple = graph.addVertex(T.label, "software", "name", "ripple", "lang", "java", "price", 199)
  38. peter = graph.addVertex(T.label, "person", "name", "peter", "age", 35, "city", "Shanghai")
  40. marko.addEdge("knows", vadas, "date", "20160110", "weight", 0.5)
  41. marko.addEdge("knows", josh, "date", "20130220", "weight", 1.0)
  42. marko.addEdge("created", lop, "date", "20171210", "weight", 0.4)
  43. josh.addEdge("created", lop, "date", "20091111", "weight", 0.4)
  44. josh.addEdge("created", ripple, "date", "20171210", "weight", 1.0)
  45. peter.addEdge("created", lop, "date", "20170324", "weight", 0.2)
  47. graph.tx().commit()
  49. g = graph.traversal()
  51. System.out.println(">>>> query all vertices: size=" + g.V().toList().size())
  52. System.out.println(">>>> query all edges: size=" + g.E().toList().size())

In fact, this groovy script is almost Java code, the only difference is that the variable definition can be written without the type declaration, and the semicolon at the end of each line can be removed.

g.V() is to get all the vertices, g.E() is to get all the edges, toList() is to store the result in a List, refer to TinkerPop Terminal Steps。

Enter the gremlin-console below and pass in the script to execute it:

  1. > ./bin/gremlin-console.sh -- -i scripts/example.groovy
  3.          \,,,/
  4.          (o o)
  5. -----oOOo-(3)-oOOo-----
  6. plugin activated: HugeGraph
  7. plugin activated: tinkerpop.server
  8. plugin activated: tinkerpop.utilities
  9. plugin activated: tinkerpop.tinkergraph
  10. main dict load finished, time elapsed 644 ms
  11. model load finished, time elapsed 35 ms.
  12. >>>> query all vertices: size=6
  13. >>>> query all edges: size=6
  14. gremlin>

The -- here will be parsed by getopts as the last option, allowing the subsequent options to be passed to Gremlin-Console for processing. -i represents Execute the specified script and leave the console open on completion. For more options, you can refer to the source code of Gremlin-Console.

As you can see, 6 vertices and 6 edges are inserted and queried. After entering the console, you can continue to enter groovy statements to operate on the graph:

  1. gremlin> g.V()
  2. ==>v[2:lop]
  3. ==>v[1:josh]
  4. ==>v[1:marko]
  5. ==>v[1:peter]
  6. ==>v[1:vadas]
  7. ==>v[2:ripple]
  8. gremlin> g.E()
  9. ==>e[S1:josh>2>>S2:lop][1:josh-created->2:lop]
  10. ==>e[S1:josh>2>>S2:ripple][1:josh-created->2:ripple]
  11. ==>e[S1:marko>1>>S1:josh][1:marko-knows->1:josh]
  12. ==>e[S1:marko>1>>S1:vadas][1:marko-knows->1:vadas]
  13. ==>e[S1:marko>2>>S2:lop][1:marko-created->2:lop]
  14. ==>e[S1:peter>2>>S2:lop][1:peter-created->2:lop]
  15. gremlin>

For more Gremlin statements, please refer to Tinkerpop Official Website

2 Client/Server mode

Because Gremlin-Console can only connect to HugeGraph-Server through WebSocket, HugeGraph-Server provides HTTP connections by default, so modify the configuration of gremlin-server first.

NOTE: After changing the connection method to WebSocket, HugeGraph-Client, HugeGraph-Loader, HugeGraph-Hubble and other supporting tools cannot be used.

  1. # vim conf/gremlin-server.yaml
  2. # ......
  3. # If you want to start gremlin-server for gremlin-console (web-socket),
  4. # please change `HttpChannelizer` to `WebSocketChannelizer` or comment this line.
  5. channelizer: org.apache.tinkerpop.gremlin.server.channel.HttpChannelizer
  6. # ......

Modify channelizer: org.apache.tinkerpop.gremlin.server.channel.HttpChannelizer to channelizer: org.apache.tinkerpop.gremlin.server.channel.WebSocketChannelizer or comment directly, and then follow the steps to start the Server.

Then enter gremlin-console:

  1. > ./bin/gremlin-console.sh
  3.          \,,,/
  4.          (o o)
  5. -----oOOo-(3)-oOOo-----
  6. plugin activated: HugeGraph
  7. plugin activated: tinkerpop.server
  8. plugin activated: tinkerpop.utilities
  9. plugin activated: tinkerpop.tinkergraph

To connect to the server, you need to specify the connection parameters in the configuration file, and there is a default remote.yaml file in the conf directory

  1. # cat conf/remote.yaml
  2. hosts: [localhost]
  3. port: 8182
  4. serializer: {
  5.   className: org.apache.tinkerpop.gremlin.driver.ser.GraphSONMessageSerializerV1d0,
  6.   config: {
  7.     serializeResultToString: false,
  8.     ioRegistries: [org.apache.hugegraph.io.HugeGraphIoRegistry]
  9.   }
  10. }
  1. gremlin> :remote connect tinkerpop.server conf/remote.yaml
  2. ==>Configured localhost/127.0.0.1:8182

After a successful connection, if the sample graph example.groovy is imported during the startup of HugeGraphServer, you can directly perform queries in the console.

  1. gremlin> :> hugegraph.traversal().V()
  2. ==>[id:2:lop,label:software,type:vertex,properties:[name:lop,lang:java,price:328]]
  3. ==>[id:1:josh,label:person,type:vertex,properties:[name:josh,age:32,city:Beijing]]
  4. ==>[id:1:marko,label:person,type:vertex,properties:[name:marko,age:29,city:Beijing]]
  5. ==>[id:1:peter,label:person,type:vertex,properties:[name:peter,age:35,city:Shanghai]]
  6. ==>[id:1:vadas,label:person,type:vertex,properties:[name:vadas,age:27,city:Hongkong]]
  7. ==>[id:2:ripple,label:software,type:vertex,properties:[name:ripple,lang:java,price:199]]

NOTE: In Client/Server mode, all operations related to the Server should be prefixed with :> . If not added, it indicates local console operations.

You can also put multiple statements in a single string variable and send them to the Server at once:

  1. gremlin> script = """
  2. ......1> graph = hugegraph;
  3. ......2> g = graph.traversal();
  4. ......3> g.V().toList().size();
  5. ......4> """
  6. ==>
  7. graph = hugegraph;
  8. g = graph.traversal();
  9. g.V().toList().size();
  11. gremlin> :> @script
  12. ==>6
  13. gremlin>

For more information on the use of gremlin-console, please refer to Tinkerpop Official Website

Last modified June 12, 2023: doc: update Log4j2 configuration and gremlin-console guide (#268) (46ee92e3)