Cayley图数据库API接口详解与使用指南

概述

Cayley是一个开源的图数据库，提供了丰富的API接口用于数据操作和查询。本文将深入解析Cayley的API设计，帮助开发者快速掌握其核心功能和使用方法。

API基础信息

Cayley API遵循OpenAPI 3.0规范，当前版本为2.1.0，采用Apache 2.0开源协议。默认服务地址为http://localhost:64210，开发者可根据需要修改主机和端口配置。

数据操作API

1. 数据格式支持查询

通过/api/v2/formats接口可以查询系统支持的数据格式：

GET /api/v2/formats

响应包含每种格式的详细信息：

• id: 格式唯一标识符
• read: 是否支持读取
• write: 是否支持写入
• nodes: 是否支持节点描述
• ext: 常用文件扩展名
• mime: 对应的MIME类型
• binary: 是否为二进制编码

2. 四元组(Quad)操作

Cayley的核心数据模型是四元组(主体-谓词-对象-标签)，提供完整的CRUD操作：

读取四元组

GET /api/v2/read

支持多种格式参数：

• format: 指定返回格式(nquads/jsonld/json等)
• sub/pred/obj/label: 过滤条件
• iri: IRI格式(short/full)

写入四元组

POST /api/v2/write

支持多种内容类型：

• application/n-quads
• application/ld+json
• application/json
• application/x-protobuf

删除四元组

POST /api/v2/delete

3. 节点操作

删除节点及关联数据

POST /api/v2/node/delete

此操作会删除指定节点及其所有关联的四元组。

4. 命名空间规则管理

GET /api/v2/namespace-rules  # 获取所有命名空间规则
POST /api/v2/namespace-rules # 注册新命名空间规则

命名空间规则用于简化IRI表示，包含prefix和namespace两个属性。

查询API

Cayley支持多种查询语言，包括Gizmo、GraphQL、MQL和S-expression。

查询接口

GET /api/v2/query?lang={语言}&qu={查询文本}
POST /api/v2/query

支持的查询语言

1. Gizmo: Cayley原生查询语言，示例：

   g.V().getLimit(10)
   

2. GraphQL: 流行的图查询语言，示例：

   {
     nodes(first: 10){
       id
     }
   }
   

3. MQL: 早期支持的查询语言

4. S-expression: Lisp风格的查询语法

Gephi集成

Cayley提供专门的Gephi图可视化集成接口：

GET /gephi/gs

支持两种模式：

• raw: 原始四元组流
• nodes: 节点流

可通过参数限制返回数量或添加过滤条件。

数据结构定义

1. 四元组表示形式

1. N-Quads: 标准RDF格式

   <alice> <follows> <bob> .
   

2. JSON-LD: 结构化JSON表示

   {
     "@context": "http://schema.org/",
     "@type": "Person",
     "name": "Jane Doe"
   }
   

3. JSON Quads: 数组形式的四元组

   [
     {
       "subject": "alice",
       "predicate": "follows",
       "object": "bob"
     }
   ]
   

4. PQuads: Cayley专用的Protobuf二进制格式

2. 错误响应

统一错误格式：

{
  "error": "错误描述信息"
}

最佳实践

1. 批量操作：写入大量数据时，建议使用流式JSON或二进制格式提高效率
2. 查询优化：复杂查询优先使用Gizmo语言，简单查询可使用GraphQL
3. 可视化：与Gephi集成时，大数据集建议使用节点模式并设置limit参数
4. IRI处理：合理使用命名空间规则简化IRI表示

总结

Cayley的API设计简洁而强大，既支持标准图数据库操作，又提供了多种查询语言和格式的灵活性。通过本文的详细解析，开发者可以快速掌握Cayley API的核心功能，在实际项目中高效地进行图数据管理和查询操作。