接入应用

通过 HTTP API、Bolt 驱动或 Gremlin WebSocket 客户端运行只读查询。

本页目录

为应用准备身份

  1. 发布目标模型并记下 ID。下方代码使用样例中的 graph。
  2. 在权限管理中创建专用服务账号,例如 analytics,用 openssl rand -hex 32 生成令牌,再分配该模型的查询权限。参见用户与权限。
  3. 在客户端进程中从密钥存储读取 GRAPHLAKE_TOKEN,并将 GRAPHLAKE_ORIGIN 设为服务的 HTTPS 源地址。本机样例使用 http://127.0.0.1:7347。

通过 HTTP 查询指定版本

保存下方 Python 3 脚本,在已配置环境变量的客户端运行。它先读取模型的 active_revision,再带上唯一请求 ID、该版本和查询语句。parameters_json 是包含 Cypher 参数的 JSON 字符串。

Python
import base64
import json
import os
import uuid
from urllib.parse import quote
from urllib.request import Request, urlopen

origin = os.environ["GRAPHLAKE_ORIGIN"].rstrip("/")
model_id = os.environ.get("GRAPHLAKE_MODEL", "graph")
credentials = "svc/analytics:" + os.environ["GRAPHLAKE_TOKEN"]
basic = base64.b64encode(credentials.encode()).decode()

def call(path, body=None):
    headers = {"Authorization": "Basic " + basic}
    data = None
    if body is not None:
        headers.update({"Content-Type": "application/json", "Origin": origin})
        data = json.dumps(body).encode()
    with urlopen(Request(origin + "/api/v1" + path, data, headers), timeout=15) as response:
        return json.load(response)

models = call("/models")
model = next(model for model in models if model["id"] == model_id)
result = call("/models/" + quote(model_id, safe="") + "/query", {
    "request_id": str(uuid.uuid4()),
    "model_revision": model["active_revision"],
    "language": "cypher",
    "query": "MATCH (a:Account) WHERE a.id = $id RETURN a.name AS account",
    "parameters_json": json.dumps({"id": 1}),
    "timeout_ms": 10000,
})
print(result["rows"])

预期结果 样例返回 [['Alice']]。HTTP 预览以字符串或 null 表示单元格,响应还包含模型版本、来源信息和截断状态。

需要完整结果时,同时授予查询和导出权限。把 capture_result 设为 true,确认 snapshot_complete 后,在快照有效期内访问 GET /api/v1/models/{id}/results/{snapshot}。

通过 Bolt 驱动读取

用 --driver-model graph --bolt-port 7687 启用监听,并按客户端配置设置 TLS。生产连接使用 bolt+s:// 直连 URI,通过驱动的数据库参数选择已发布模型。

Python · neo4j
import os
from neo4j import GraphDatabase

auth = ("svc/analytics", os.environ["GRAPHLAKE_TOKEN"])
with GraphDatabase.driver("bolt+s://graphlake.example:7687", auth=auth) as driver:
    with driver.session(database="graph") as session:
        records = session.run("MATCH (a:Account) RETURN a.name AS name ORDER BY name")
        print([record["name"] for record in records])

发行版驱动验证使用 neo4j==5.28.2。已支持的来源可以使用自动提交。显式只读事务支持 PostgreSQL 和 Parquet。客户端版本按发行版协议参考选择。

通过 Gremlin WebSocket 读取

用 --driver-model graph 启用 Gremlin 并选定默认模型。HTTPS 代理须转发 /gremlin 上的 WebSocket 升级请求。遍历源名称可指定获准的模型。

Python · gremlinpython
import os
from gremlin_python.driver.driver_remote_connection import DriverRemoteConnection
from gremlin_python.driver.serializer import GraphSONSerializersV3d0
from gremlin_python.process.anonymous_traversal import traversal

conn = DriverRemoteConnection(
    "wss://graphlake.example/gremlin",
    "graph",
    username="svc/analytics",
    password=os.environ["GRAPHLAKE_TOKEN"],
    message_serializer=GraphSONSerializersV3d0(),
)
try:
    g = traversal().with_remote(conn)
    print(g.V().hasLabel("Account").values("name").order().to_list())
finally:
    conn.close()

本例使用 gremlinpython==3.7.4,打印 Alice、Bob 和 Carol。使用支持的只读遍历,以及 GraphSON 3 或 GraphBinary 1.0 编码器。

处理版本与权限错误

如果模型在发现后已重新发布,先读取当前的生效版本,确认映射符合预期后再用新的请求 ID 执行只读查询。收到 401 时检查账号和令牌。收到 403 时检查模型权限和租户范围。长查询失败时,先确定服务是否就绪、来源是否可读,再重试。

AI 客户端使用 MCP。服务或来源异常参见故障排查。