ROAPI

ROAPI 可以自动为静态数据集创建只读 API，无需编写任何代码。它建立在 Apache Arrow 和 Datafusion 之上。其核心设计可以归纳为以下几点：

• 查询前端将 SQL、FlightSQL、GraphQL 和 REST API 查询转换为 Datafusion 计划。
• 使用 Datafusion 执行查询计划。
• 数据层可从各种来源和格式加载数据集，并自动推断模式。
• 响应编码层将中间 Arrow 记录批次序列化为客户端请求的各种格式。

以下是高级架构图：

<img alt="roapi-设计图" src="https://yellow-cdn.veclightyear.com/835a84d5/c85a3bae-90c4-451e-926b-0dc58dc7b8ac.png">

安装

安装预构建的二进制文件

# 如果使用 homebrew
brew install roapi
# 或者如果prefer pip
pip install roapi

查看 Github 发布页面 获取各平台的预构建二进制文件。预构建的 Docker 镜像也可在 ghcr.io/roapi/roapi 获取。

从源代码安装

cargo install --locked --git https://github.com/roapi/roapi --branch main --bins roapi

使用

快速开始

为 test_data/uk_cities_with_headers.csv 和 test_data/spacex_launches.json 创建 API：

roapi \
    --table "uk_cities=test_data/uk_cities_with_headers.csv" \
    --table "test_data/spacex_launches.json"

对于 Windows，必须填写完整的方案（file:// 或 filesystem://），并使用双引号（"）而不是单引号（'）来避免 Windows 命令行限制：

roapi \
    --table "uk_cities=file://d:/path/to/uk_cities_with_headers.csv" \
    --table "file://d:/path/to/test_data/spacex_launches.json"

或使用 Docker：

docker run -t --rm -p 8080:8080 ghcr.io/roapi/roapi:latest --addr-http 0.0.0.0:8080 \
    --table "uk_cities=test_data/uk_cities_with_headers.csv" \
    --table "test_data/spacex_launches.json"

对于 MySQL 和 SQLite，使用如下参数：

--table "table_name=mysql://username:password@localhost:3306/database"
--table "table_name=sqlite://path/to/database"

想要动态注册数据？在命令中添加 -d 参数。目前 --table 参数不能省略。

roapi \
    --table "uk_cities=test_data/uk_cities_with_headers.csv" \
    -d

然后向 /api/table 发送配置以注册数据。

curl -X POST http://172.24.16.1:8080/api/table \
     -H 'Content-Type: application/json' \
     -d '[
       {
         "tableName": "uk_cities2",
         "uri": "./test_data/uk_cities_with_headers.csv"
       },
       {
         "tableName": "table_name",
         "uri": "sqlite://path/to/database"
       }
     ]'

使用 SQL、GraphQL 或 REST 查询表：

curl -X POST -d "SELECT city, lat, lng FROM uk_cities LIMIT 2" localhost:8080/api/sql
curl -X POST -d "query { uk_cities(limit: 2) {city, lat, lng} }" localhost:8080/api/graphql
curl "localhost:8080/api/tables/uk_cities?columns=city,lat,lng&limit=2"

获取所有表的推断模式：

curl 'localhost:8080/api/schema'

配置文件

你也可以使用 YAML 或 Toml 配置文件配置多个表源，这支持更高级的特定格式表选项：

addr:
  http: 0.0.0.0:8084
  postgres: 0.0.0.0:5433
tables:
  - name: "blogs"
    uri: "test_data/blogs.parquet"

  - name: "ubuntu_ami"
    uri: "test_data/ubuntu-ami.json"
    option:
      format: "json"
      pointer: "/aaData"
      array_encoded: true
    schema:
      columns:
        - name: "zone"
          data_type: "Utf8"
        - name: "name"
          data_type: "Utf8"
        - name: "version"
          data_type: "Utf8"
        - name: "arch"
          data_type: "Utf8"
        - name: "instance_type"
          data_type: "Utf8"
        - name: "release"
          data_type: "Utf8"
        - name: "ami_id"
          data_type: "Utf8"
        - name: "aki_id"
          data_type: "Utf8"

  - name: "spacex_launches"
    uri: "https://api.spacexdata.com/v4/launches"
    option:
      format: "json"

  - name: "github_jobs"
    uri: "https://web.archive.org/web/20210507025928if_/https://jobs.github.com/positions.json"

使用配置文件运行服务表：

roapi -c ./roapi.yml # 或 .toml

查看配置文档了解更多选项，包括使用 Google 电子表格作为表源。

响应序列化

默认情况下，ROAPI 以 JSON 格式编码响应，但你可以通过指定 ACCEPT 头请求不同的编码：

curl -X POST \
    -H 'ACCEPT: application/vnd.apache.arrow.stream' \
    -d "SELECT launch_library_id FROM spacex_launches WHERE launch_library_id IS NOT NULL" \
    localhost:8080/api/sql

REST API 查询接口

你可以通过向 /api/tables/{table_name} 发送 GET 请求来通过 REST API 查询表。查询操作符作为查询参数指定。

REST 查询前端目前支持以下查询操作符：

• columns
• sort
• limit
• filter

要按升序对 col1 排序，按降序对 col2 排序，设置查询参数为：sort=col1,-col2。

要查找 col1 等于字符串 'foo' 的所有行，设置查询参数为：filter[col1]='foo'。你也可以使用过滤器进行基本比较，例如谓词 0 <= col2 < 5 可以表示为 filter[col2]gte=0&filter[col2]lt=5。

GraphQL 查询接口

要使用 GraphQL 查询表，通过 POST 请求将查询发送到 /api/graphql 端点。

GraphQL 查询前端支持与 REST 查询前端 相同的操作符集。以下是如何在查询中应用各种操作符：

{
  table_name(
    filter: { col1: false, col2: { gteq: 4, lt: 1000 } }
    sort: [{ field: "col2", order: "desc" }, { field: "col3" }]
    limit: 100
  ) {
    col1
    col2
    col3
  }
}

SQL查询接口

要使用标准SQL的子集查询表格，请通过POST请求将查询发送到/api/sql端点。这是唯一支持表连接的查询接口。

键值查找

你可以从表中选择两列作为键和值，通过在配置中添加以下行来创建快速键值存储API：

kvstores:
  - name: "launch_name"
    uri: "test_data/spacex_launches.json"
    key: id
    value: name

键值查找可以通过简单的HTTP GET请求完成：

curl -v localhost:8080/api/kv/launch_name/600f9a8d8f798e2a4d5f979e
Starlink-21 (v1.0)%

通过Postgres有线协议查询

ROAPI可以将自己呈现为Postgres服务器，使用户能够使用Postgres客户端发出SQL查询。

$ psql -h 127.0.0.1
psql (12.10 (Ubuntu 12.10-0ubuntu0.20.04.1), server 13)
警告：psql主版本12，服务器主版本13。
      某些psql功能可能无法工作。
输入"help"获取帮助。

houqp=> select count(*) from uk_cities;
 COUNT(UInt8(1))
-----------------
              37
(1 行)

特性

查询层：

• REST API GET
• GraphQL
• SQL
• 表之间的连接
• 通过索引访问数组元素
• 通过键访问嵌套结构字段
• 列索引
• 协议
  • Postgres
  • FlightSQL
• 键值查找

响应序列化：

• JSON application/json
• Arrow application/vnd.apache.arrow.stream
• Parquet application/vnd.apache.parquet
• msgpack

数据层：

• 文件系统
• HTTP/HTTPS
• S3
• GCS
• Azure存储
• Google电子表格
• MySQL
• SQLite
• Postgres
• Airtable
• 数据格式
  • CSV
  • JSON
  • NDJSON
  • parquet
  • xls, xlsx, xlsb, ods: https://github.com/tafia/calamine
  • DeltaLake

其他：

• 自动生成REST层的OpenAPI文档
• 基于表结构的查询输入类型转换
• 流式Arrow编码响应
• 认证层

开发

ROAPI的核心，包括查询前端和数据层，位于独立的columnq包中。它接收查询并输出Arrow记录批次。数据源也将作为Arrow记录批次加载并存储在内存中。

roapi包用多协议查询层包装了columnq。它根据客户端请求将columnq生成的Arrow记录批次序列化为不同格式。

调试

要在控制台记录所有FlightSQL请求，请设置RUST_LOG=tower_http=trace。

构建Docker镜像

docker build --rm -t ghcr.io/roapi/roapi:latest .

VS Code DevContainer

要求

• Vscode
• 确保在VS Code上安装了此扩展ms-vscode-remote.remote-containers

---

完成后，你会在左侧看到提示，要求在开发容器中重新打开项目，或者打开命令面板并搜索"使用远程容器打开"：

1. 安装依赖

apt-get update  && apt-get install --no-install-recommends -y cmake

2. 使用你选择的数据库客户端从本地连接到数据库，使用以下凭据

用户名：user
密码：user
数据库：test

完成后创建表，以便在-t参数中映射，或考虑使用.devcontainer/db-migration.sql中的示例来填充一些带数据的表

3. 使用mysql数据库作为功能运行cargo命令

cargo run --bin roapi --features database -- -a localhost:8080 -t posts=mysql://user:user@db:3306/test 

否则，如果你正在寻找其他功能，你必须从roapi/Cargo.toml中选择适当的功能