STINGER图数据库JSON-RPC API详解

概述

STINGER图数据库提供了一套基于JSON-RPC 2.0规范的API接口，允许客户端应用程序查询图数据和算法计算结果。本文将全面解析这套API的功能和使用方法，帮助开发者快速掌握STINGER的远程调用能力。

JSON-RPC基础

STINGER实现的JSON-RPC 2.0接口具有以下特点：

• 仅支持命名参数调用，不支持位置参数
• 当前版本不支持通知(Notifications)功能
• 当前版本不支持批量(Batch)请求
• 响应中包含"millis"字段，表示服务器端执行时间(毫秒)

核心API方法详解

1. 服务器信息查询

get_server_info方法用于获取STINGER服务器基本信息：

请求示例：
{
  "jsonrpc": "2.0",
  "method": "get_server_info",
  "id": 1
}

响应示例：
{
  "jsonrpc": "2.0",
  "result": {
    "pid": 12345 
  },
  "id": 1,
  "millis": 0.5
}

2. 图统计信息

get_graph_stats方法返回图的整体统计信息：

请求示例（带类型信息）：
{
  "jsonrpc": "2.0",
  "method": "get_graph_stats",
  "params": {
    "get_types": true
  },
  "id": 2
}

响应示例：
{
  "jsonrpc": "2.0",
  "result": {
    "vertices": 1000,
    "edges": 5000,
    "time": 1580000000,
    "edge_types": ["friendship", "collaboration"],
    "vertex_types": ["user", "product"]
  },
  "id": 2,
  "millis": 2.3
}

3. 算法管理

get_algorithms获取当前运行的算法列表：

响应示例：
{
  "jsonrpc": "2.0",
  "result": {
    "algorithms": ["pagerank", "community_detection"]
  },
  "id": 3,
  "millis": 1.2
}

get_data_description查询算法输出的数据字段：

请求示例：
{
  "jsonrpc": "2.0",
  "method": "get_data_description",
  "params": {
    "name": "pagerank"
  },
  "id": 4
}

响应示例：
{
  "jsonrpc": "2.0",
  "result": {
    "alg_data": ["score", "normalized_score"]
  },
  "id": 4,
  "millis": 1.8
}

数据查询方法

STINGER提供了多种数据查询方式，满足不同场景需求：

1. 全量数据获取

get_data_array获取算法输出的完整数据：

请求示例（带采样参数）：
{
  "jsonrpc": "2.0",
  "method": "get_data_array",
  "params": {
    "name": "pagerank",
    "data": "score",
    "samples": 100,
    "log": true
  },
  "id": 5
}

2. 范围查询

get_data_array_range和get_data_array_sorted_range支持分页和排序：

请求示例（排序分页）：
{
  "jsonrpc": "2.0",
  "method": "get_data_array_sorted_range",
  "params": {
    "name": "pagerank",
    "data": "score",
    "offset": 0,
    "count": 10,
    "order": "DESC"
  },
  "id": 6
}

3. 定点查询

get_data_array_set查询指定顶点的数据：

请求示例：
{
  "jsonrpc": "2.0",
  "method": "get_data_array_set",
  "params": {
    "name": "pagerank",
    "data": "score",
    "set": [1001, 1002, "user_1003"]
  },
  "id": 7
}

4. 聚合计算

get_data_array_reduction支持数据聚合：

请求示例：
{
  "jsonrpc": "2.0",
  "method": "get_data_array_reduction",
  "params": {
    "name": "pagerank",
    "data": "score",
    "op": "sum"
  },
  "id": 8
}

实时图分析功能

STINGER提供了多种实时图算法API：

1. 广度优先搜索(BFS)

breadth_first_search查找最短路径：

请求示例：
{
  "jsonrpc": "2.0",
  "method": "breadth_first_search",
  "params": {
    "source": "user_123",
    "target": "user_456",
    "get_types": true
  },
  "id": 9
}

2. Adamic-Adar指数

adamic_adar_index计算顶点相似度：

请求示例：
{
  "jsonrpc": "2.0",
  "method": "adamic_adar_index",
  "params": {
    "source": "user_123",
    "include_neighbors": true
  },
  "id": 10
}

会话管理

STINGER支持会话式操作：

register创建新会话：

请求示例：
{
  "jsonrpc": "2.0",
  "method": "register",
  "params": {
    "type": "algorithm_monitor"
  },
  "id": 11
}

request使用会话查询数据：

请求示例：
{
  "jsonrpc": "2.0",
  "method": "request",
  "params": {
    "session_id": 12345
  },
  "id": 12
}

最佳实践建议

1. 对于大型图数据，合理使用stride和samples参数控制返回数据量
2. 优先使用定点查询而非全量查询，减少网络传输
3. 长时间监控可使用会话机制，减少连接开销
4. 注意API响应中的millis字段，监控查询性能

通过这套JSON-RPC API，开发者可以方便地将STINGER图数据库的强大分析能力集成到各类应用中。