TSV を Parquet に変換

科学分野や分析の出力の多くは、選択の結果というより慣習としてタブ区切りです。発現行列、バリアントコールの要約、注釈テーブル、機器のログ、検索や広告プラットフォームの書き出しなど。タブが選ばれたのは説明用の列がカンマやセミコロンだらけだったからで、30 年間トランスポート形式として使われてきました。

これは繰り返し計算対象にするには不向きな形式です。読み込むたびにすべてのバイトが解析され、ツールごとに列の型がそれぞれ少しずつ違う形で導出され、百回フィルターされるテーブルは、その解析コストを百回払うことになります。一度だけ型付きの列形式に変換しておけば、その手間を先送りせず前もって片付けられます。それがこの変換をする理由のすべてです。

Parquet の列は、すべての値に対して 1 つの型を持ちます。ここでの書き出しは列全体を読んでから判断し、規則はあえて容赦のないものになっています。空でないすべての値が真偽値なら BOOLEAN、32 ビットの範囲に収まる整数ならすべて INT32、すべて数値なら DOUBLE、そして 1 つでもそのどれにも当てはまらない値があれば、列全体が文字列になります。

分析用のテーブルには、そのどれにも当てはまらない値があふれています。NA は R の慣習で、R が触れたほぼすべてのテーブルに現れます。単なる . は VCF や GTF の欠損値の慣習です。-、n/a、NULL、#N/A、-- は、どのプログラムがファイルを書いたかによって現れます。そのどれか 1 つでもどこかの行にあれば、千万件の数値の列は千万件の文字列の列になり、それが数値だと分かっている列が文字列として届く理由です。

誘惑にかられる代替案は、最初の行、あるいは最初の千行から列の型を決め、それに合わないものは null として書くというやり方です。多くのツールはまさにそれを行い、警告なく読み込める有効なファイルを作りますが、その記号が現れたすべての行を静かに削除しています。

それに誰も気づかないまま、件数が合わないと分かるのはたいてい後になってからで、その頃にはファイルはすでに 3 つと結合されています。文字列の列はうるさいものです。スキーマを見た瞬間に目立ち、1 つの式でキャストでき、そのキャストはどの値が変換できなかったかを正確に教えてくれます。推測を拒むことでキャストの手間を払い、その代わり見つけるのがとても難しい種類の誤りを防ぎます。この取引は意図的なもので、この変換の中でいちばん影響の大きい判断です。

コマンド 1 行で済みます。cut -f7 table.tsv | sort -u | head -50 で 7 列目の異なる値を表示すれば、その中に記号は明らかに見えるはずです。幅の広いテーブルの全列でやるならループが必要ですが、実際にフィルターをかける 3 列だけなら、たいていそれで十分です。

修正はソース側で行うべきで、変換器の中ではありません。記号を本当に空のフィールドに置き換えてください。null は型推定から除外されるので、本物の欠損を持つ数値の列は null を含む数値の列として通り、これはクエリエンジンが期待する形であり、平均や範囲フィルターが扱える形です。1 つの列に対する awk のフィールド単位の置換は数秒の作業で、結果ファイルのスキーマを変えます。

幅の広いテーブルは、列指向のレイアウトがいちばん報われる場面です。遺伝子ごとに行、サンプルごとに列を持つ発現行列や、測定項目ごとに列を持つ特徴量テーブルは、1 行また 1 行ではなく 1 列また 1 列として保存されるので、4 列を指定するクエリは 4 列分のバイトだけを読み、残りには一切触れません。

タブ区切りファイルに対する同じクエリは、17 番目のフィールドを見つけるにはタブを 17 個数えるしかないため、すべての行のすべてのバイトを読む必要があります。この違いはテーブルが大きくなっても小さくなりません。むしろ広がります。フッターは幅の狭いテーブルより広いテーブルでいっそう重要になります。データを一切読まずに 2,000 の列名と型を一覧できることは、検査できるスキーマと、head -1 | tr で分解しなければならないヘッダー行との違いです。

書き出し側は、列のすべての値が 32 ビットの範囲に収まる場合にのみ INT32 を出力します。それを超えると INT64 ではなく DOUBLE になり、Parquet が 64 ビット整数の型を持つことを知っている人ほど意外に感じます。

理由は届いた値についての正直さです。値は取り込みの途中で 53 ビットの整数精度を持つ JavaScript の数値を通るため、その範囲を超えるゲノムの座標やイベント ID は、書き出し側がそれを見る前にすでに丸められています。INT64 と宣言することは、もう持っていない正確さを約束することになります。1 だけずれた識別子は正しい識別子に見えてしまいます。ある列が量ではなく大きな識別子を保持しているなら、ソース側でテキストとして残してください。数字以外の接頭辞があれば十分で、文字列の列として無傷のまま届きます。

ファイルのフッターには、ヘッダー行が書いたとおりの列名、それぞれの型、行数が保存され、データそのものは千行から十万行の行グループとして書かれ、列ごとの統計値が添えられます。各列は個別に Snappy で圧縮され、値が繰り返す列は辞書として 1 回だけ保存され、小さな整数の参照で置き換えられます。

分析用テーブルにとって、サイズの多くはそこに行きます。染色体名、サンプル ID、鎖の向き、カテゴリー——それぞれが少数の異なる値を持ち、それが数百万行に繰り返され、ほとんど何もない大きさまで潰れます。連続的な測定値の列はそうならず、それが結果のファイルの大きさを支配します。どの列がどちらかを知っておくことが、得られるサイズの良い予測材料になります。

DuckDB はファイルをその場で読みます。パスを名指しする FROM 句だけで済み、インポートの手順もテーブル定義も要りません。DESCRIBE SELECT * FROM "table.parquet" は推測されたスキーマを表示し、最初に見るべき場所であり、テキストとして通った列を見つけるいちばん速い方法でもあります。

pandas は 1 回の呼び出しで読み込み、Spark はネイティブなテーブル形式として扱います。どの場合でも、意外な結果があったら盲目的にキャストするのではなく、原因の値をクエリで確かめるのが正しい対処です。キャストは合わないものを null にしてしまい、それはまさに書き出し側があなたに代わって決めることを拒んだ失敗そのものだからです。ファイルは 4 バイトの PAR1 で始まり終わり、それぞれのツールはフッターを読む前にそれで Parquet だと認識します。

どちらの半分もこのページで動きます。タブ区切りのパーサーは普通の JavaScript で、Parquet の書き出しは必要なときに読み込まれるライブラリです。アップロードはなく、未発表の結果セットや、まだ公開されていないデータ、配布権限のない測定値にとって意味のある点です。

テーブル全体は列へと転置される間メモリー上に保持されるため、数十メガバイトなら滞りなく変換でき、数百メガバイトあたりからブラウザータブが厳しくなります。数ギガバイトの行列は DuckDB に向いています。ディスクからタブ区切りファイルを読み、どちらも保持することなく 1 つの文で Parquet を書き出せます。大きな変換がなんとなく最後まで届かず失敗するより、そう伝えておくほうが役に立ちます。

人やスクリプトがテキストとして読む必要があるなら、そのままにしておいてください。Parquet はバイナリで、編集できず、レジストリはその対応状況をまだらだと記録しています。しかるべき道具を持たない共同研究者にはまったく開けず、「先に DuckDB を入れてください」はテーブルを見たかった人への良い返事ではありません。

ファイルが公開された成果物である場合も、そのままにしておいてください。タブ区切りのテーブルは学術誌やリポジトリ、公開データセットが受け付ける形式で、20 年後も依存物なしに読めます。何度もフィルターし、結合し、集計する作業用のコピーは Parquet に変換し、元のファイルは正本として残してください。