Source: https://dev-docs.yueshu.com.cn/v5.3.2/app-development/python-sdk/
Documentation version: v5.3.2

# 使用 Python SDK 构建查询服务

使用 Python SDK 和 FastAPI 创建电影演员查询服务。访问`GET /movies/3/actors`，可获取电影 Shadows in Paradise 及其参演演员的 JSON 数据。

## 前提条件

- 已按[准备悦数图数据库开发版](https://dev-docs.yueshu.com.cn/v5.3.2/app-development/#prepare-database)启动悦数图数据库开发版，并加载`movie`示例数据集。
- 已安装 Python 3.10 或更高版本，了解函数、字典和异常处理。
- 已准备悦数图数据库开发版用户名和密码，应用所在电脑能够访问悦数图数据库开发版的查询端口。

以下终端命令适用于 macOS 和 Linux，均在运行应用的电脑上执行。该电脑可以是部署 Docker 的开发机，也可以是能够访问悦数图数据库开发版的另一台电脑。

## 1. 创建项目并安装依赖

````
mkdir movie-sdk-app
cd movie-sdk-app
python3 -m venv .venv
source .venv/bin/activate
python -m pip install nebula5_python==5.3.0 fastapi==0.142.1 uvicorn==0.54.0

````

Python SDK 5.3.0 负责连接悦数图数据库开发版，FastAPI 提供应用 HTTP 接口，Uvicorn 运行应用。

## 2. 配置悦数图数据库开发版连接

按应用所在位置选择悦数图数据库开发版地址：

 | 应用所在位置 | 悦数图数据库开发版地址
 | 与 Docker 在同一台开发机 | `127.0.0.1:9669`
 | 在另一台电脑 | `<开发机IP>:9669`

将`<开发机IP>`替换为运行 Docker 的机器 IP。如果修改过`9669:9669`端口映射，使用冒号左侧的开发机端口。

在创建项目时使用的终端中设置环境变量。下方以应用与 Docker 在同一台开发机为例：

````
export NEBULA_ADDRESS='127.0.0.1:9669'
export NEBULA_USER='root'
export NEBULA_PASSWORD="$(python -c 'import getpass; print(getpass.getpass("Database password: "))')"

````

出现`Database password:`提示后，输入悦数图数据库开发版当前的实际密码。Compose 文件中用`$$`表示的字符，在这里输入单个`$`。后续启动命令继续在此终端执行。

## 3. 保存应用代码

下载 [movie_sdk.py](https://dev-docs.yueshu.com.cn/v5.3.2/app-development/files/movie_sdk.py)，保存到`movie-sdk-app`目录中。

示例固定查询`/default_schema/movie`。如果数据位于其他 Schema，修改文件中两条查询的图路径。

查看完整代码

````
"""Run with: python -m uvicorn movie_sdk:app --host 127.0.0.1 --port 8100."""

import logging
import os
from typing import Annotated

from fastapi import FastAPI, HTTPException, Path
from nebulagraph_python.client import NebulaClient

app = FastAPI(title="Movie cast service (Python SDK)")
logger = logging.getLogger(__name__)
address = os.environ.get("NEBULA_ADDRESS", "127.0.0.1:9669")
username = os.environ.get("NEBULA_USER", "root")
password = os.environ["NEBULA_PASSWORD"]


@app.get("/movies/{movie_id}/actors")
def get_actors(movie_id: Annotated[int, Path(ge=1, le=9223372036854775807)]):
    # FastAPI validates the ID as an integer before this function runs.
    # The graph path is fixed; neither query accepts arbitrary query text.
    movie_query = (
        "USE /default_schema/movie MATCH (m@Movie) "
        f"WHERE m.id = {movie_id} RETURN m.name AS movie"
    )
    actors_query = (
        "USE /default_schema/movie MATCH (a@Actor)-[:Act]->(m@Movie) "
        f"WHERE m.id = {movie_id} "
        "RETURN a.id AS actor_id, a.name AS actor ORDER BY actor_id"
    )

    client = None
    try:
        # A request owns its client and closes it before returning.
        client = NebulaClient(
            addresses=address,
            user_name=username,
            password=password,
            connect_timeout_ms=3000,
            request_timeout_ms=10000,
        )
        movies = list(client.execute(movie_query).as_primitive_by_row())
        actors = (
            list(client.execute(actors_query).as_primitive_by_row())
            if movies
            else []
        )
    except Exception as exc:
        logger.warning("Database request failed (%s)", type(exc).__name__)
        raise HTTPException(status_code=502, detail="Database request failed") from exc
    finally:
        if client is not None:
            client.close()

    if not movies:
        raise HTTPException(status_code=404, detail="Movie not found")

    return {"movie_id": movie_id, "movie": movies[0]["movie"], "actors": actors}

````

## 4. 启动应用

在项目目录中、虚拟环境已激活的终端中执行：

````
python -m uvicorn movie_sdk:app --host 127.0.0.1 --port 8100

````

如果`8100`端口已被占用，先停止占用它的应用，或改用`--port 8101`，并同步修改后续访问地址。

看到以下提示，表示应用已启动：

````
Application startup complete.
Uvicorn running on http://127.0.0.1:8100 (Press CTRL+C to quit)

````

保持此终端运行，另开浏览器或终端调用接口。应用监听本机的`8100`端口；按 Ctrl+C 停止应用。

## 5. 调用查询接口

在运行应用的同一台电脑上，选择以下任一方式查询编号为`3`的电影。如果通过 SSH 在远端运行应用，先建立下方的[端口转发](https://dev-docs.yueshu.com.cn/v5.3.2/app-development/python-sdk/#ssh-access)。

浏览器curl

1. 打开`http://127.0.0.1:8100/docs`，这是应用自动生成的接口页面。
2. 展开`GET /movies/{movie_id}/actors`，单击 Try it out。
3. 在`movie_id`中输入`3`，单击 Execute，查看响应。

在应用所在电脑另开一个终端，执行：

````
curl -sS http://127.0.0.1:8100/movies/3/actors | python3 -m json.tool --no-ensure-ascii

````

两种方式应返回相同的 JSON：

````
{
  "movie_id": 3,
  "movie": "Shadows in Paradise",
  "actors": [
    {"actor_id": 4826, "actor": "Matti Pellonpää"},
    {"actor_id": 4828, "actor": "Sakari Kuosmanen"},
    {"actor_id": 5999, "actor": "Kati Outinen"}
  ]
}

````

通过 SSH 访问远端应用

在浏览器所在电脑的本地终端建立转发，将`<SSH用户名>`和`<远端地址>`替换为登录应用所在电脑时使用的值：

````
ssh -N -L 8100:127.0.0.1:8100 <SSH用户名>@<远端地址>

````

如 SSH 使用非默认端口，添加`-p <SSH端口>`。认证成功后，转发终端会持续等待，通常没有输出。

保持远端应用终端和本地转发终端运行，在本地浏览器打开`http://127.0.0.1:8100/docs`。本地`8100`端口的请求会转发到远端应用的`8100`端口。

如果本地端口已被占用，将`-L`后的值改为`8101:127.0.0.1:8100`，访问地址同步改为`http://127.0.0.1:8101/docs`。

应用端口是`8100`，悦数图数据库开发版查询端口是`9669`。

## 代码说明

### 查询与响应字段

应用先查询电影名称，再查询参演演员。先检查电影是否存在，可以区分“没有这部电影”和“电影存在但没有演员”：前者返回`404`，后者返回空的`actors`数组。

演员查询如下：

````
USE /default_schema/movie MATCH (a@Actor)-[:Act]->(m@Movie)
WHERE m.id = 3
RETURN a.id AS actor_id, a.name AS actor ORDER BY actor_id

````

`(a@Actor)-[:Act]->(m@Movie)`匹配演员参演电影的关系，箭头从演员指向电影。`WHERE`筛选电影编号，`ORDER BY`按演员编号排序。应用将示例中的`3`替换为校验后的整数`movie_id`。数据模型见[示例数据集：movie](https://dev-docs.yueshu.com.cn/v5.3.2/get-started/dataset/)。

 | 查询结果 | 应用响应字段
 | 电影查询中的`m.name AS movie` | `movie`
 | 演员查询中的`a.id AS actor_id` | `actors`中每项的`actor_id`
 | 演员查询中的`a.name AS actor` | `actors`中每项的`actor`

### 连接悦数图数据库开发版并读取结果

下面是示例中的悦数图数据库开发版调用片段。`as_primitive_by_row()`按行返回 Python 字典，`list()`收集结果行，供 FastAPI 返回 JSON。无论查询成功还是失败，`finally`都会关闭客户端。

````
client = NebulaClient(addresses=address, user_name=username, password=password)
try:
    movies = list(client.execute(movie_query).as_primitive_by_row())
    actors = list(client.execute(actors_query).as_primitive_by_row()) if movies else []
finally:
    client.close()

````

每条查询都用`USE /default_schema/movie`指定图，无需先设置会话工作图。Python 多行字符串可直接传给`execute()`，无需添加`ngql`的`'''`输入标记。

## 响应状态与排查

 | HTTP 状态 | 含义 | 处理方法
 | `200` | 查询成功 | 查看`movie`和`actors`；没有演员时数组为空
 | `404` | 没有这个电影编号 | 使用数据中已有的编号，例如`3`
 | `422` | 电影编号格式或范围不符合要求 | 使用正整数，且不超过`9223372036854775807`
 | `502` | 悦数图数据库开发版连接或查询失败 | 核对悦数图数据库开发版地址和密码，并按[连接并完成首次查询](https://dev-docs.yueshu.com.cn/v5.3.2/get-started/first-query/#select-graph)确认数据可访问

需要验证参数校验时，执行：

````
curl -i http://127.0.0.1:8100/movies/abc/actors

````

应返回 HTTP`422`，请求不会发送到悦数图数据库开发版执行查询。应用只接收电影编号，查询结构和图路径由代码固定。

### 应用无法访问

浏览器显示`ERR_CONNECTION_REFUSED`或`curl`无法连接时，检查：

- 应用终端是否仍在运行。
- 请求是否发往应用所在电脑；`127.0.0.1`始终指运行浏览器或命令的电脑。
- 通过 SSH 访问时，本地转发终端是否仍在运行。

在浏览器所在电脑的终端执行以下命令；如果修改了本地端口，使用修改后的值：

````
curl -I http://127.0.0.1:8100/docs

````

应返回`HTTP/1.1 200 OK`，表示应用的接口页面可以访问。随后再调用电影查询接口，检查悦数图数据库开发版查询结果。

详细错误类型记录在运行应用的终端中。

## 扩展练习：查询导演

复制`get_actors()`函数及其`@app.get`装饰器，将新函数命名为`get_directors()`，路由改为`/movies/{movie_id}/directors`。保留电影存在性检查，将演员查询替换为：

````
USE /default_schema/movie MATCH (d@Director)-[:Direct]->(m@Movie)
WHERE m.id = 3
RETURN d.id AS director_id, d.name AS director ORDER BY director_id

````

将演员查询和结果变量改为相应的导演变量。返回 JSON 使用`directors`数组，其中每项使用`director_id`和`director`。

重启应用后调用新接口，核对电影及其导演。电影存在但没有导演关系时，`directors`为空数组；电影不存在时返回`404`。可先在悦数图管理控制台中执行上述查询，再与应用结果比较。

## 继续开发

按 Ctrl+C 停止应用后，悦数图数据库开发版继续运行，图数据保留。更换终端后再次启动时，需重新激活虚拟环境并设置环境变量。

示例每次请求创建一个 SDK 客户端，并在请求结束时关闭。接入自己的服务时，可按并发量和访问权限要求设计连接复用与调用方认证。

- [Python SDK 指南](https://dev-docs.yueshu.com.cn/v5.3.2/clients/python-client/)：查看连接和结果集的用法。
- [FastAPI 文档](https://fastapi.tiangolo.com/tutorial/first-steps/)：学习路由和应用配置。
- [使用 REST API 构建查询服务](https://dev-docs.yueshu.com.cn/v5.3.2/app-development/rest-api/)：通过 HTTP 实现相同接口。