🚀 Raphtory GraphQL Schema Explorer 中文文档

该 Python 模块搭建了一个 FastMCP 服务器，借助一组 HTTP 资源，将 Raphtory 图表的 GraphQL 模式信息公开出来。它让大语言模型（LLM）能够探索并理解图表的结构，涵盖节点属性和关系类型等方面。

🚀 快速开始

本模块可助力大语言模型探索 Raphtory 图表的结构，通过 HTTP 资源公开图表的 GraphQL 模式信息。使用前需确保运行中的 Raphtory GraphQL 服务器已启动。

✨ 主要特性

1. 图表模式查询

• 可查询特定图表名称的模式。
• 能获取节点属性的详细信息。
• 可获取唯一的关系类型及其元数据。
• 支持可选包含属性变体。

2. 资源

schema://database

返回数据库的完整 GraphQL 模式，具体包含：

• 所有可用类型。
• 每个类型的字段。
• 字段描述。
• 参数及其默认值。

schema://graph_exists/{graph_name}

通过检查节点的存在，验证特定图表是否存在于数据库中。

schema://{graph_name}/{include_variants}

返回特定图表的详细模式信息：

• 节点属性：
  • 属性键。
  • 属性类型（例如："Str"）。
  • 可选属性变体。
• 关系：
  • 唯一关系类型（例如："edge_type_1"、"edge_type_2"、"edge_type_3"）。

3. 实现细节

该模块采用了以下技术和方法：

• 依赖运行中的 Raphtory GraphQL 服务器（需提前启动）。
• 运用 httpx 进行异步 HTTP 请求，支持 HTTP/2。
• 借助 FastMCP 管理资源。
• 采用全局异步客户端实现持久连接。
• 利用上下文管理确保资源正确清理。

💻 使用示例

基础用法

查询图表模式：

{
  graph(path: "your_graph_name") {
    schema {
      nodes {
        properties {
          key
          propertyType
        }
      }
    }
    edges {
      list {
        properties {
          keys
          values {
            value
          }
        }
      }
    }
  }
}

响应格式

模式响应包含如下值：

{
  "data": {
    "graph": {
      "schema": {
        "nodes": [{
          "properties": [
            {"key": "name", "propertyType": "Str"},
            {"key": "type", "propertyType": "Str"}
            // ... 其他属性
          ]
        }]
      },
      "relationships": [
        "edge_type_1",
        "edge_type_2",
        "edge_type_3"
      ]
    }
  }
}

🔧 技术细节

该模块使用运行中的 Raphtory GraphQL 服务器，借助 httpx 进行异步 HTTP 请求，支持 HTTP/2 协议。通过 FastMCP 管理资源，采用全局异步客户端实现持久连接，并利用上下文管理确保资源正确清理。这些技术的运用使得模块在性能和资源管理方面表现出色，能够高效地公开 Raphtory 图表的 GraphQL 模式信息。

📦 安装指南

依赖项

• FastMCP
• httpx
• Python 3.x
• 运行中的 Raphtory GraphQL 端点（默认：http://localhost:1736/）

配置

该模块使用默认配置：

• HTTP/2 启用
• 10 秒超时
• Content-Type: application/json

还可以通过环境变量添加其他配置，例如身份验证。

📚 详细文档

错误处理

该模块包含以下错误处理机制：

• 处理不存在的图表情况。
• 处理无效查询问题。
• 处理连接问题。
• 处理响应格式错误。