Gremlin REST

Prerequisites

• Lindorm Graph Engine is enabled and the client IP address is added to the whitelist.

• To use the vector search capability, Lindorm Vector Engine must also be enabled.

• The schema of the target subgraph has been initialized. If not, see Schema definition.

Submit a Gremlin request

• Request format

  • Method 1: Pass the statement string directly through the gremlin field in the request body. Double quotes inside the statement must be escaped with a backslash.

    curl -X POST "http://${SERVER_HOST}:${GREMLIN_PORT}/gremlin/${DB_NAME}" \
      -H "Content-Type: application/json" \
      -u ${SUB_USER}:${SUB_PASSWORD} \
      -d '{
        "gremlin": "g.V().hasLabel(\"vec_person\").limit(1)"
      }'

  • Method 2: Use parameter bindings to separate variables from the statement and avoid escaping double quotes.

    curl -X POST "http://${SERVER_HOST}:${GREMLIN_PORT}/gremlin/${DB_NAME}" \
      -H "Content-Type: application/json" \
      -u ${SUB_USER}:${SUB_PASSWORD} \
      -d '{
        "gremlin": "g.V().hasLabel(G__label).limit(G__count)",
        "bindings": {"G__label": "person", "G__count": 1}
      }'

• Parameters

  Parameter	Required	Description
  SERVER_HOST	Yes	The connection address of Lindorm Graph Engine, which can be found on the Database Connection page of the console. Example: localhost.
  GREMLIN_PORT	Yes	The access port of the Gremlin service, which can be found on the Database Connection page of the console. Example: 16032.
  DB_NAME	No	The subgraph name. Defaults to default and can be omitted in the URL. /gremlin is equivalent to /gremlin/default.
  SUB_USER	Yes	The username for accessing Lindorm Graph Engine.
  SUB_PASSWORD	Yes	The password corresponding to the username.

Add vertices

Use g.addV() to create vertices. The following examples show two vertex types: person (with a vector property) and software.

• Syntax:

  curl -X POST "http://${SERVER_HOST}:${GREMLIN_PORT}/gremlin/${DB_NAME}" \
    -H "Content-Type: application/json" \
    -u ${SUB_USER}:${SUB_PASSWORD} \
    -d '{
      "gremlin": "g.addV(\"person\").property(id,\"marko\").property(\"name\",\"marko\").property(\"age\",29).property(\"city\",\"Beijing\")"
    }'

  • person vertex (with vector property):

    g.addV('person')
      .property(id, 'marko')
      .property('name', 'marko')
      .property('age', 29)
      .property('city', 'Beijing')
      // embedding is a vector property; its length must match the vector dimension defined in the schema
      .property('embedding', [0.539821, -0.174532, 0.882461, 0.124091, -0.658313, 0.471802])

  • software vertex:

    g.addV('software')
      .property(id, 'lop')
      .property('name', 'lop')
      .property('lang', 'java')
      .property('price', 328)

• Parameters:

  Syntax	Description
  g.addV('label')	Creates a vertex with the specified label. label must be a vertex label that is already defined in the schema.
  .property(id, 'value')	Sets the primary key ID of the vertex. Here, id is a built-in Gremlin identifier (without quotes), and value is the primary key value of string type.
  .property('key', 'value')	Sets a regular property. String values must be enclosed in single or double quotes, numeric values can be written directly, and vector values use array literals (such as [0.1, 0.2, 0.3]).

• Example:

  // Add person vertices
  g.addV('person').property(id,'marko').property('name','marko').property('age',29).property('city','Beijing')
  g.addV('person').property(id,'vadas').property('name','vadas').property('age',27).property('city','Hongkong')
  g.addV('person').property(id,'josh').property('name','josh').property('age',32).property('city','Beijing')
  g.addV('person').property(id,'peter').property('name','peter').property('age',35).property('city','Shanghai')
  
  // Add software vertices
  g.addV('software').property(id,'lop').property('name','lop').property('lang','java').property('price',328)
  g.addV('software').property(id,'ripple').property('name','ripple').property('lang','java').property('price',199)

Add edges

Use g.addE() to create a directed edge between two vertices.

• Syntax:

  curl -X POST "http://localhost:16032/gremlin/default" \
    -H "Content-Type: application/json" \
    -u "admin:admin" \
    -d '{
      "gremlin": "g.V(\"marko\").hasLabel(\"person\").addE(\"knows\").to(__.V(\"vadas\").hasLabel(\"person\")).property(\"date\",\"20160110\").property(\"weight\",0.5d)"
    }'

  Lindorm Graph Engine supports the following two ways to locate vertices.

  • Method 1: Locate a vertex by V('id').hasLabel('label').

    g.V('marko').hasLabel('person')
      .addE('knows')
      .to(__.V('vadas').hasLabel('person'))
      .property('date', '20160110')
      .property('weight', 0.5d)

  • Method 2: Locate a vertex by has('label', '~id', 'id'). Here, ~id is the built-in property key that Gremlin uses to represent the primary key ID.

    g.V().has('person', '~id', 'josh')
      .addE('created')
      .to(__.V().has('software', '~id', 'lop'))
      .property('date', '20091111')
      .property('weight', 0.4d)

• Parameters:

  Syntax	Description
  g.V().has('label', '~id', 'id')	Locates the source vertex. ~id indicates filtering by primary key ID.
  .addE('label')	Creates an edge with the specified label from the source vertex. label must be an edge label that is already defined in the schema.
  .to(__.V(...))	Specifies the target vertex of the edge, using the anonymous traversal __ for nested location.
  .property('key', 'value')	Sets edge properties. String values must be enclosed in quotes. The d suffix indicates the double type (such as 0.5d).

• Example :

  // Method 1: Locate a vertex by V('id').hasLabel('label')
  g.V('marko').hasLabel('person').addE('knows').to(__.V('vadas').hasLabel('person')).property('date','20160110').property('weight',0.5d)
  g.V('marko').hasLabel('person').addE('knows').to(__.V('josh').hasLabel('person')).property('date','20130220').property('weight',1.0d)
  g.V('marko').hasLabel('person').addE('created').to(__.V('lop').hasLabel('software')).property('date','20171210').property('weight',0.4d)
  
  // Method 2: Locate a vertex by has('label','~id','id')
  g.V().has('person','~id','josh').addE('created').to(__.V().has('software','~id','lop')).property('date','20091111').property('weight',0.4d)
  g.V().has('person','~id','josh').addE('created').to(__.V().has('software','~id','ripple')).property('date','20171210').property('weight',1.0d)
  g.V().has('person','~id','peter').addE('created').to(__.V().has('software','~id','lop')).property('date','20170324').property('weight',0.2d)

Query data

The following examples demonstrate two typical query types: path-based graph traversal and vector similarity search. Both are submitted as POST requests; only the Gremlin statement differs.

curl -X POST "http://localhost:16032/gremlin/default" \
  -H "Content-Type: application/json" \
  -u "admin:admin" \
  -d '{
    "gremlin": "g.V(\"marko\").hasLabel(\"person\").out().in().limit(100).out().path()"
  }'