// STRYKE-PARQUET — ENGINEERING REPORT

>_EXECUTIVE SUMMARY

stryke-parquet is one of the opt-in connector packages in the stryke ecosystem. Parquet file inspector for stryke — schema, footer stats, row-group breakdown, head/tail, recompression. Diagnostic counterpart to stryke-arrow.

Schema + footer / row-group introspection is a different workload from reading parquet into a typed DataFrame. Lightweight tool for ops + debugging.

~ARCHITECTURE

In-process cdylib design: the stryke side is a thin .stk wrapper that calls FFI symbols on the dlopen'd library. No subprocess, no pipe — calls return on the same thread that made them.

$WHY OPT-IN (NOT BUILTIN)

Schema + footer / row-group introspection is a different workload from reading parquet into a typed DataFrame. Lightweight tool for ops + debugging.

The trade-off is intentional. The core stryke binary stays under ~40 MB precisely because each connector ships separately. Daily-driver work (one-liners, awk replacement, data scripting) doesn't need MongoDB drivers, AWS SDKs, or Spark Connect bindings linked in.

&FFI ENVELOPE

JSON in / JSON out across the FFI boundary. Each Parquet::* wrapper serializes its args to a JSON dict and calls the matching parquet__* symbol resolved out of libstryke_parquet.{dylib,so}; the cdylib returns a JSON CString the wrapper parses. The exports span inspection (version, inspect, schema, dtypes, count, rowgroups, row_group_summary, stats, metadata, schema_diff), row read (head, tail, slice, sample, reverse, gather, random_sample, to_json, to_csv, to_ndjson, column), row predicates and reshaping (filter, where_count, filter_to, distinct, sort, top_k, value_counts, group_by), aggregates (sum, min, max, mean, n_unique, quantile, describe), conversion and write (from_csv, from_json, write, write_partitioned, compress, repartition, merge, hstack, select, drop, rename, with_row_index), and diagnostics (validate, column_chunk_stats, size_report, null_summary, encoding_summary, bloom_filter_summary, sorting_columns_summary, features); the authoritative list is [ffi].exports in stryke.toml. The returned CString is freed via the cdylib-exported stryke_free_cstring, wired automatically by rust_ffi::load_cdylib.

# request shape (built by the .stk wrapper)
{"verb": "<op>", "...": ...}

# response shape
{"result": ...}            # success — per-fn shape
{"error": "<msg>"}        # failure — wrapper die()s with the message

/SCOPE

See the README's "What this is (and what it isn't)" + "API reference" sections for the authoritative scope. The package is intentionally narrower than its underlying SDK / driver — the goal is "useful from a shell pipeline", not "complete API coverage".

%PUBLIC SURFACE

61 public Parquet::* functions backed by 57 parquet__* FFI exports (the remainder are pure-stryke composites — column_names, column_count, is_empty, median — built over other calls). Grouped by intent below; the full annotated reference with return shapes is the README "API reference", and the canonical export list is [ffi].exports in stryke.toml.

+DEPENDENCIES

The cdylib is built on the same parquet + arrow crate family as stryke-arrow; the JSON envelope uses serde_json with preserve_order so column order survives round-trips. Compression backends are compiled into the parquet crate's feature set.

Release profile: opt-level = 3, lto = "thin", codegen-units = 1, strip = true, panic = "abort".

#PROJECT METADATA