Gremlin Rest

前提条件

• 已开通 Lindorm 图引擎，并将客户端 IP 加入白名单。

• 如需使用向量检索能力，需同时开通 Lindorm 向量引擎。

• 已完成目标子图的 Schema 初始化，如未完成可参考Schema 定义。

提交 Gremlin 请求

• 请求格式

  • 方式一：通过请求体的 gremlin 字段直接传递语句字符串。语句内部出现的双引号需要使用反斜杠转义。

    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)"
      }'

  • 方式二：使用参数绑定（bindings），将变量从语句中分离，避免转义双引号。

    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}
      }'

• 参数说明

  参数	是否必填	说明
  SERVER_HOST	是	Lindorm 图引擎的连接地址。可在控制台 数据库连接 页面查询，例如 localhost。
  GREMLIN_PORT	是	Gremlin 服务的访问端口。可在控制台 数据库连接 页面查询，例如 16032。
  DB_NAME	否	子图名称。默认值为 default，URL 中可省略；即 /gremlin 等价于 /gremlin/default。
  SUB_USER	是	访问 Lindorm 图引擎的用户名。
  SUB_PASSWORD	是	用户名对应的访问密码。

添加顶点

使用 g.addV() 创建顶点。以下分别给出 person（包含向量属性）与 software 两种顶点的示例。

• 语法格式：

  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 顶点（含向量属性）：

    g.addV('person')
      .property(id, 'marko')
      .property('name', 'marko')
      .property('age', 29)
      .property('city', 'Beijing')
      // embedding 为向量属性，长度需与 Schema 中定义的向量维度一致
      .property('embedding', [0.539821, -0.174532, 0.882461, 0.124091, -0.658313, 0.471802])

  • software 顶点：

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

• 参数说明：

  语法	说明
  g.addV('label')	创建指定标签的顶点，label 需为 Schema 中已定义的顶点标签。
  .property(id, 'value')	设置顶点的主键 ID。此处 id 是 Gremlin 内置标识符（不加引号），value 为字符串类型的主键值。
  .property('key', 'value')	设置普通属性。字符串值需用单引号或双引号包裹，数值类型直接书写即可，向量类型使用数组字面量（如 [0.1, 0.2, 0.3]）。

• 完整示例：

  // 添加 person 顶点
  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')
  
  // 添加 software 顶点
  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)

添加边

使用 g.addE() 在两个顶点之间创建有向边。

• 语法格式：

  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 图引擎支持以下两种顶点定位方式。

  • 方式一：通过 V('id').hasLabel('label') 定位顶点。

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

  • 方式二：通过 has('label', '~id', 'id') 定位顶点。其中 ~id 是 Gremlin 表示主键 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('label', '~id', 'id')	定位源顶点。~id 表示按主键 ID 过滤。
  .addE('label')	基于源顶点创建指定标签的边，label 需为 Schema 中已定义的边标签。
  .to(__.V(...))	指定边的目标顶点，使用匿名遍历 __ 嵌套定位。
  .property('key', 'value')	设置边属性。字符串值需用引号包裹，d 后缀表示 double 类型（如 0.5d）。

• 完整示例：

  // 方式一：通过 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)
  
  // 方式二：通过 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)

查询数据

以下示例演示两类典型查询：基于路径的图遍历查询，以及基于向量属性的相似度检索。两类查询均通过 POST 请求提交，差异仅在 Gremlin 语句本身。

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()"
  }'