datafusion-server crate

使用 Rust 实现的多种会话、多种数据源查询服务器。

• 使用 Tokio 生态系统异步架构
• Apache Arrow 与 Apache DataFusion
  • 支持使用 SQL 查询多个数据源
• 数据源连接器和后处理程序的 Python 插件功能
• 使用 Arrow Flight gRPC 功能在服务器之间实现水平扩展架构

请参阅 文档 以获取入门教程和完整的使用指南。此外，根据 OpenAPI 规范，还有 REST API 文档。有关最新信息，请参阅 变更日志。

系统概述

许可证

遵循 MIT 许可证

版权所有 © 2022 - 2024 SAL Ltd. - https://sal.co.jp

支持的操作系统

• Linux
• 基于 BSD 的 Unix，包括 macOS / Mac OSX
• 基于 SVR 的 Unix
• Windows，包括 WSL2 / Cygwin

以及其他 LLVM 支持的环境。

使用预构建的 Docker 镜像（目前仅提供 amd64 架构）

先决条件

• Docker CE / EE v20+

从 GitHub 容器注册库拉取容器镜像

$ docker pull ghcr.io/sal-openlab/datafusion-server/datafusion-server:latest

或构建不带 Python 插件版本。

$ docker pull ghcr.io/sal-openlab/datafusion-server/datafusion-server-without-plugin:latest

执行容器

$ docker run -d --rm \
    -p 4000:4000 \
    -v ./data:/var/datafusion-server/data \
    --name datafusion-server \
    ghcr.io/sal-openlab/datafusion-server/datafusion-server:latest

如果您仅在容器中使用示例数据，则省略 --v ./data:/var/xapi-server/data。

自己构建容器

先决条件

• Docker CE / EE v20+

构建两个容器，datafusion-server 和 datafusion-server-without-plugin

$ cd <repository-root-dir>
$ ./make-containers.sh

执行容器

$ docker run -d --rm \
    -p 4000:4000 \
    -v ./bin/data:/var/datafusion-server/data \
    --name datafusion-server \
    datafusion-server:0.19.1

如果你只在一个容器中使用示例数据，请省略以下命令：-v ./bin/data:/var/xapi-server/data。

从源代码构建以供项目使用

先决条件

• Rust 工具链 1.76+ (2021 版) 来自 https://rust-lang.net.cn
• 或 来自 https://hub.docker.com/_/rust 的 Rust 官方容器

如何运行

$ cargo init server-executor
$ cd server-executor

Cargo.toml 的示例

[package]
name = "server-executor"
version = "0.1.0"
edition = "2021"

[dependencies]
datafusion-server = "0.19.1"
clap = { version = "4.5", features = ["derive"] }

src/main.rs 的示例

use std::path::PathBuf;

use clap::Parser;
use datafusion_server::settings::Settings;

#[derive(Parser)]
#[clap(author, version, about = "Arrow and other large datasets web server", long_about = None)]
struct Args {
    #[clap(
        long,
        value_parser,
        short = 'f',
        value_name = "FILE",
        help = "Configuration file",
        default_value = "./config.toml"
    )]
    config: PathBuf,
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let args = Args::parse();
    let settings = Settings::new_with_file(&args.config)?;
    datafusion_server::execute(settings)?;
    Ok(())
}

有关详细信息，请进一步阅读 main.rs 和 Config.toml。

config.toml 的示例

# Configuration file of datafusion-server

[server]
port = 4000
flight_grpc_port = 50051
base_url = "/"
data_dir = "./data"
plugin_dir = "./plugins"

[session]
default_keep_alive = 3600 # in seconds
upload_limit_size = 20 # MB

[log]
# trace, debug, info, warn, error
level = "debug"

调试构建和运行

$ cargo run

datafusion-server 带有 Python 插件功能

需要 Python 解释器 v3.7+

如何运行

Cargo.toml 的示例

[dependencies]
datafusion-server = { version = "0.19.1", features = ["plugin"] }

调试构建和运行

$ cargo run

带有全面优化的发布构建

Cargo.toml 的示例

[profile.release]
opt-level = 'z'
strip = true
lto = "fat"
codegen-units = 1

[dependencies]
datafusion-server = { version = "0.19.1", features = ["plugin"] }

构建发布版

$ cargo build --release

清理工作空间

$ cargo clean

用法

使用 SQL 查询的多个数据源

• 可以使用多种数据源格式（Parquet、JSON、ndJSON、CSV、...）。
• 数据可以从本地文件系统和外部 REST 服务中检索。
  • 如果需要，可以执行 JSONPath 处理。
• 跨多个数据源执行查询。
  • SQL 查询引擎使用 Arrow DataFusion。
    • 更多信息请参阅 https://arrow.apache.ac.cn/datafusion/user-guide/sql/index.html。
• 以 Arrow、JSON 和 CSV 格式响应。

示例（本地文件）

$ curl -X "POST" "https://127.0.0.1:4000/dataframe/query" \
     -H 'Content-Type: application/json' \
     -d $'
{
  "dataSources": [
    {
      "format": "csv",
      "name": "sales",
      "location": "file:///superstore.csv",
      "options": {
        "inferSchemaRows": 100,
        "hasHeader": true
      }
    }
  ],
  "query": {
    "sql": "SELECT * FROM sales"
  },
  "response": {
    "format": "json"
  }
}'

示例（远程 REST API）

$ curl -X "POST" "https://127.0.0.1:4000/dataframe/query" \
     -H 'Content-Type: application/json' \
     -H 'Accept: text/csv' \
     -d $'
{
  "dataSources": [
    {
      "format": "json",
      "name": "population",
      "location": "https://datausa.io/api/data?drilldowns=State&measures=Population",
      "options": {
        "jsonPath": "$.data[*]"
      }
    }
  ],
  "query": {
    "sql": "SELECT * FROM population WHERE \"ID Year\">=2020"
  }
}'

示例（Python 数据源连接器插件）

$ curl -X "POST" "https://127.0.0.1:4000/dataframe/query" \
     -H 'Content-Type: application/json' \
     -H 'Accept: application/json' \
     -d $'
{
  "dataSources": [
    {
      "format": "arrow",
      "name": "example",
      "location": "excel://example-workbook.xlsx/Sheet1",
      "pluginOptions": {
        "skipRows": 2
      }
    }
  ],
  "query": {
    "sql": "SELECT * FROM example"
  }
}'