为 Rust 编写 Parquet 代码

本项目提供生成 Rust 代码的工具，用于使用 Parquet 文件，该代码使用了 Arrow 的 Rust 实现。它包括一个代码生成crate（parquetry-gen）和生成代码所需的小型运行时库（parquetry）。

请注意，此软件不是“开源”的，但源代码可供个人、非营利组织和工人拥有企业使用和修改（有关详细信息，请参阅下面的许可证部分）。

目录

• 示例
• 依赖项
• 用法
• 测试
• 状态和范围
• 警告
• 许可证

示例

给定如下架构

message user {
    required int64 id (integer(64, false));
    required int64 ts (timestamp(millis, true));
    optional int32 status;

    optional group user_info {
        required byte_array screen_name (string);

        optional group user_name_info {
            required byte_array name (string);

            optional group user_profile_info {
                required int64 created_at (timestamp(millis, true));
                required byte_array location (string);
                required byte_array description (string);
                optional byte_array url (string);

                required int32 followers_count;
                required int32 friends_count;
                required int32 favourites_count;
                required int32 statuses_count;

                optional group withheld_in_countries (list) {
                    repeated group list {
                        required byte_array element (string);
                    }
                }
            }
        }
    }
}

代码生成器将生成以下 Rust 结构

#[derive(Clone, Debug, Eq, PartialEq, serde::Deserialize, serde::Serialize)]
pub struct User {
    pub id: u64,
    #[serde(with = "chrono::serde::ts_milliseconds")]
    pub ts: chrono::DateTime<chrono::Utc>,
    pub status: Option<i32>,
    pub user_info: Option<UserInfo>,
}

#[derive(Clone, Debug, Eq, PartialEq, serde::Deserialize, serde::Serialize)]
pub struct UserInfo {
    pub screen_name: String,
    pub user_name_info: Option<UserNameInfo>,
}

#[derive(Clone, Debug, Eq, PartialEq, serde::Deserialize, serde::Serialize)]
pub struct UserNameInfo {
    pub name: String,
    pub user_profile_info: Option<UserProfileInfo>,
}

#[derive(Clone, Debug, Eq, PartialEq, serde::Deserialize, serde::Serialize)]
pub struct UserProfileInfo {
    #[serde(with = "chrono::serde::ts_milliseconds")]
    pub created_at: chrono::DateTime<chrono::Utc>,
    pub location: String,
    pub description: String,
    pub url: Option<String>,
    pub followers_count: i32,
    pub friends_count: i32,
    pub favourites_count: i32,
    pub statuses_count: i32,
    pub withheld_in_countries: Option<Vec<String>>,
}

它还将为 User 生成一个 parquetry::Schema trait 实例，其中包括读取和写入 Parquet 文件值的代码。

依赖项

所有使用都要求使用 parquetry、parquet、chrono 和 lazy_static crate 作为运行时依赖项。

如果配置中启用了 serde_support 标志（默认情况下是启用的），您还需要对 serde 有依赖，并启用 derive 功能。

如果配置中启用了 tests 标志（默认情况也是如此），您需要将 bincode（最新版本的 2.0.0-rc.x 并启用 serde 功能）、tempdir 和 quickcheck 添加到您的 dev-dependencies。

用法

example 目录提供了一个相当简化的示例，生成的代码也存储在那里。在大多数情况下，您可能只需要像以下这样的 build.rs。

use std::{fs::File, io::Write};

fn main() -> Result<(), parquetry_gen::error::Error> {
    for schema in parquetry_gen::ParsedFileSchema::open_dir(
        "src/schemas/",
        Default::default(),
        Some(".parquet.txt"),
    )? {
        println!("cargo:rerun-if-changed={}", schema.absolute_path_str()?);
        let mut output = File::create(format!("src/{}.rs", schema.name))?;
        write!(output, "{}", schema.code()?)?;
    }

    Ok(())
}

默认情况下，生成的代码使用 prettyplease 格式化，并注释表明不应使用 Rustfmt 格式化，但如果您想自己使用 Rustfmt，可以在配置中将 format 设置为 false。

测试

默认配置将生成使用 QuickCheck 生成任意值并确认它们正确序列化和反序列化的测试代码。

当前的测试代码生成不支持某些类型。具体来说，不支持浮点数字符串、固定长度的字节数组和时间戳。如果您的模式包含这些类型中的任何一种，生成的测试代码将无法编译，您需要在配置中禁用 tests 标志（您也可以提出问题）。

生成的测试代码不会为浮点类型生成 NaN 值。如果您想确认您的系统正确处理这些值，您必须手动进行。

默认情况下，为您的类型生成的任意值可能非常大。如果您的测试速度太慢，您可以将 QUICKCHECK_GENERATOR_SIZE 环境变量设置为较小的值（例如 10 或 20）。