Go で JSONL を扱う:bufio、json.Decoder、並行処理
Go で JSONL(JSON Lines)ファイルを扱うための総合ガイドです。標準ライブラリの bufio、encoding/json と goroutine を使い、JSONL データの読み書き、ストリーミング、並行処理の方法を解説します。
JSONL の処理に Go が適している理由
Go は JSONL ファイルの処理に適した言語です。特に、パフォーマンスや並行処理が重要な場面で力を発揮します。効率的な行単位の I/O には bufio、パースとシリアライズには encoding/json、並列処理には goroutine と、必要な機能がすべて標準で揃っており、サードパーティのライブラリに依存する必要はありません。Go はコンパイル言語のため、同じ処理を行う Python や Node.js のスクリプトと比べて、JSONL パイプラインを大幅に高速化できます。高性能なハードウェアでなくても、毎秒数百万行を処理できることがよくあります。
JSONL(JSON Lines)は1行に1つの JSON オブジェクトを格納する形式で、Go のストリーミング I/O モデルと相性がよいのが特徴です。ファイル全体をメモリに読み込まずに、スキャナーやデコーダーでレコードを1件ずつ読み取って処理できます。Go の軽量な goroutine とチャネルを組み合わせれば、利用可能な CPU コアをすべて使い切る並行処理パイプラインを構築できます。このガイドでは、bufio.Scanner による JSONL の読み取り、json.Decoder によるストリーミング、効率的な書き込み、レコードの並行処理、エラーに適切に対処する方法を解説します。
bufio.Scanner で JSONL ファイルを読み取る
Go で JSONL を読み取る最もシンプルな方法は、bufio.Scanner を使うことです。ファイルを1行ずつ読み取り、各行を json.Unmarshal でパースします。バッファサイズやエラー処理を細かく制御できる方法です。
ファイルを開いてスキャナーを作成し、ループで1行ずつ読み取ります。各行は json.Unmarshal で map または struct にパースします。この方法では、メモリ使用量をファイル全体のサイズではなく、単一レコードのサイズに応じた量に抑えられます。
package main
import (
"bufio"
"encoding/json"
"fmt"
"log"
"os"
)
func main() {
file, err := os.Open("data.jsonl")
if err != nil {
log.Fatal(err)
}
defer file.Close()
var records []map[string]any
scanner := bufio.NewScanner(file)
// Increase buffer for lines longer than 64KB
scanner.Buffer(make([]byte, 0, 1024*1024), 1024*1024)
for scanner.Scan() {
var record map[string]any
if err := json.Unmarshal(scanner.Bytes(), &record); err != nil {
log.Printf("skipping invalid JSON: %v", err)
continue
}
records = append(records, record)
}
if err := scanner.Err(); err != nil {
log.Fatal(err)
}
fmt.Printf("Loaded %d records\n", len(records))
}本番用のコードでは、汎用的な map ではなく、型を定義した Go の構造体に JSONL レコードをパースしましょう。コンパイル時の型安全性を確保でき、パフォーマンスとコードの読みやすさも向上します。構造体に json タグを付けて、フィールドの対応関係を指定します。
package main
import (
"bufio"
"encoding/json"
"fmt"
"log"
"os"
)
type User struct {
ID int `json:"id"`
Name string `json:"name"`
Email string `json:"email"`
Age int `json:"age,omitempty"`
}
func readUsers(path string) ([]User, error) {
file, err := os.Open(path)
if err != nil {
return nil, fmt.Errorf("open file: %w", err)
}
defer file.Close()
var users []User
scanner := bufio.NewScanner(file)
lineNum := 0
for scanner.Scan() {
lineNum++
var u User
if err := json.Unmarshal(scanner.Bytes(), &u); err != nil {
return nil, fmt.Errorf("line %d: %w", lineNum, err)
}
users = append(users, u)
}
if err := scanner.Err(); err != nil {
return nil, fmt.Errorf("scanner error: %w", err)
}
return users, nil
}
func main() {
users, err := readUsers("users.jsonl")
if err != nil {
log.Fatal(err)
}
for _, u := range users {
fmt.Printf("%s (%s)\n", u.Name, u.Email)
}
}json.Decoder でストリーミング処理する
json.Decoder は、データをいったん行に分割することなく io.Reader から直接読み取るため、高速なストリーミング処理に適しています。バッファリングも内部で行われます。大容量の JSONL ファイルやネットワークストリームを扱い、メモリアロケーションを最小限に抑えたい場合におすすめです。
json.NewDecoder は任意の io.Reader をラップし、JSON 値を順にデコードします。Decode を呼び出すたびに JSON オブジェクトを1つ読み取り、ストリームの終端に達すると io.EOF を返します。各行を別のバッファにコピーせずに済むため、bufio.Scanner + json.Unmarshal よりも効率的です。
package main
import (
"encoding/json"
"errors"
"fmt"
"io"
"log"
"os"
)
type LogEntry struct {
Timestamp string `json:"timestamp"`
Level string `json:"level"`
Message string `json:"message"`
Service string `json:"service"`
}
func processJSONLStream(path string) error {
file, err := os.Open(path)
if err != nil {
return fmt.Errorf("open: %w", err)
}
defer file.Close()
decoder := json.NewDecoder(file)
var count int
for {
var entry LogEntry
err := decoder.Decode(&entry)
if errors.Is(err, io.EOF) {
break
}
if err != nil {
return fmt.Errorf("decode record %d: %w", count+1, err)
}
count++
// Process each record as it's decoded
if entry.Level == "ERROR" {
fmt.Printf("[%s] %s: %s\n",
entry.Timestamp, entry.Service, entry.Message)
}
}
fmt.Printf("Processed %d log entries\n", count)
return nil
}
func main() {
if err := processJSONLStream("logs.jsonl"); err != nil {
log.Fatal(err)
}
}Go で JSONL ファイルに書き込む
Go で JSONL を書き込む手順はシンプルです。各レコードを json.Marshal でシリアライズし、改行バイトを追加してファイルに書き込みます。パフォーマンスを最大限に引き出すには、ファイルへの書き込みを bufio.Writer でバッファリングし、システムコールの回数を減らします。
json.Marshal で各レコードを JSON のバイト列にシリアライズし、末尾に改行を付けて書き込みます。シンプルな方法で、小規模から中規模のファイルに適しています。
package main
import (
"encoding/json"
"fmt"
"log"
"os"
)
type Product struct {
ID int `json:"id"`
Name string `json:"name"`
Price float64 `json:"price"`
}
func main() {
products := []Product{
{ID: 1, Name: "Laptop", Price: 999.99},
{ID: 2, Name: "Mouse", Price: 29.99},
{ID: 3, Name: "Keyboard", Price: 79.99},
}
file, err := os.Create("products.jsonl")
if err != nil {
log.Fatal(err)
}
defer file.Close()
for _, p := range products {
data, err := json.Marshal(p)
if err != nil {
log.Printf("skip marshal error: %v", err)
continue
}
data = append(data, '\n')
if _, err := file.Write(data); err != nil {
log.Fatal(err)
}
}
fmt.Printf("Wrote %d records to products.jsonl\n", len(products))
}高いスループットが必要な場合は、json.NewEncoder と bufio.Writer を組み合わせます。エンコーダーは Encode を呼び出すたびに自動で改行を追加します。バッファ付きライターは小さな書き込みをバッファに蓄え、まとめてシステムコールで書き出します。ファイルを閉じる前に、必ず Flush を呼び出してください。
package main
import (
"bufio"
"encoding/json"
"fmt"
"log"
"os"
)
type Event struct {
Type string `json:"type"`
Timestamp int64 `json:"timestamp"`
Payload map[string]any `json:"payload"`
}
func writeEvents(path string, events []Event) error {
file, err := os.Create(path)
if err != nil {
return fmt.Errorf("create file: %w", err)
}
defer file.Close()
writer := bufio.NewWriter(file)
encoder := json.NewEncoder(writer)
// Disable HTML escaping for cleaner output
encoder.SetEscapeHTML(false)
for i, event := range events {
if err := encoder.Encode(event); err != nil {
return fmt.Errorf("encode event %d: %w", i, err)
}
}
// Flush buffered data to file
if err := writer.Flush(); err != nil {
return fmt.Errorf("flush: %w", err)
}
fmt.Printf("Wrote %d events to %s\n", len(events), path)
return nil
}
func main() {
events := []Event{
{Type: "click", Timestamp: 1700000001, Payload: map[string]any{"x": 120, "y": 450}},
{Type: "view", Timestamp: 1700000002, Payload: map[string]any{"page": "/home"}},
}
if err := writeEvents("events.jsonl", events); err != nil {
log.Fatal(err)
}
}goroutine で JSONL を並行処理する
Go の goroutine とチャネルを使えば、JSONL を並行処理するパイプラインを簡単に構築できます。ファンアウトパターンでは、ファイルから読み取ったレコードを複数のワーカー goroutine に振り分け、チャネルを通じて結果を集めます。大容量の JSONL ファイルに対して、CPU バウンドな変換処理を行う場合に最適です。
package main
import (
"bufio"
"encoding/json"
"fmt"
"log"
"os"
"runtime"
"sync"
)
type Record struct {
ID int `json:"id"`
Data map[string]any `json:"data"`
}
type Result struct {
ID int `json:"id"`
Processed bool `json:"processed"`
Score int `json:"score"`
}
func process(r Record) Result {
// Simulate CPU-bound work
score := len(r.Data) * r.ID
return Result{ID: r.ID, Processed: true, Score: score}
}
func main() {
file, err := os.Open("records.jsonl")
if err != nil {
log.Fatal(err)
}
defer file.Close()
numWorkers := runtime.NumCPU()
jobs := make(chan Record, numWorkers*2)
results := make(chan Result, numWorkers*2)
// Start workers
var wg sync.WaitGroup
for i := 0; i < numWorkers; i++ {
wg.Add(1)
go func() {
defer wg.Done()
for record := range jobs {
results <- process(record)
}
}()
}
// Close results channel when all workers finish
go func() {
wg.Wait()
close(results)
}()
// Read file and send records to workers
go func() {
scanner := bufio.NewScanner(file)
for scanner.Scan() {
var r Record
if err := json.Unmarshal(scanner.Bytes(), &r); err != nil {
log.Printf("skip invalid line: %v", err)
continue
}
jobs <- r
}
close(jobs)
}()
// Collect and write results
outFile, err := os.Create("results.jsonl")
if err != nil {
log.Fatal(err)
}
defer outFile.Close()
writer := bufio.NewWriter(outFile)
encoder := json.NewEncoder(writer)
var count int
for result := range results {
if err := encoder.Encode(result); err != nil {
log.Printf("encode error: %v", err)
}
count++
}
writer.Flush()
fmt.Printf("Processed %d records with %d workers\n", count, numWorkers)
}このファンアウトパターンでは、CPU コア数と同じ数の goroutine に JSONL レコードを振り分けます。バッファ付きチャネルを使うことで、送受信時に goroutine がブロックされるのを防ぎます。sync.WaitGroup により、すべてのワーカーが処理を終えてから results チャネルが閉じられることを保証します。API 呼び出しなどの I/O バウンドな処理では、numWorkers を CPU 数より多く設定できます。ただし、並行処理では出力順序が保証されない点に注意してください。
エラー処理のベストプラクティス
Go で JSONL を安定して処理するには、エラーへの丁寧な対処が欠かせません。実際の JSONL ファイルには、形式が不正な行や文字エンコーディングの問題、想定より大きなレコードが含まれることがあります。ここで紹介するパターンでは、行ごとのエラーの記録、エラー時にスキップするかどうかの設定、処理結果の集計を行います。
package main
import (
"bufio"
"encoding/json"
"fmt"
"log"
"os"
)
type ParseError struct {
Line int
Err error
Raw string
}
func (e *ParseError) Error() string {
return fmt.Sprintf("line %d: %v", e.Line, e.Err)
}
type JSONLReader struct {
scanner *bufio.Scanner
lineNum int
Errors []ParseError
Skipped int
Success int
}
func NewJSONLReader(file *os.File) *JSONLReader {
scanner := bufio.NewScanner(file)
scanner.Buffer(make([]byte, 0, 1024*1024), 10*1024*1024)
return &JSONLReader{scanner: scanner}
}
func (r *JSONLReader) ReadAll(target any) error {
slice, ok := target.(*[]map[string]any)
if !ok {
return fmt.Errorf("target must be *[]map[string]any")
}
for r.scanner.Scan() {
r.lineNum++
line := r.scanner.Bytes()
// Skip empty lines
if len(line) == 0 {
continue
}
var record map[string]any
if err := json.Unmarshal(line, &record); err != nil {
r.Errors = append(r.Errors, ParseError{
Line: r.lineNum,
Err: err,
Raw: string(line),
})
r.Skipped++
continue
}
*slice = append(*slice, record)
r.Success++
}
return r.scanner.Err()
}
func (r *JSONLReader) Summary() string {
return fmt.Sprintf(
"Lines: %d | Success: %d | Skipped: %d | Errors: %d",
r.lineNum, r.Success, r.Skipped, len(r.Errors),
)
}
func main() {
file, err := os.Open("data.jsonl")
if err != nil {
log.Fatal(err)
}
defer file.Close()
reader := NewJSONLReader(file)
var records []map[string]any
if err := reader.ReadAll(&records); err != nil {
log.Fatal(err)
}
fmt.Println(reader.Summary())
for _, e := range reader.Errors {
log.Printf("Parse error at %s", e.Error())
}
}この JSONLReader 構造体は行番号を記録し、パースエラーを元の行データとともに収集して、成功と失敗の件数を集計します。スキャナーのバッファを 10MB に設定しているため、通常より大きな行でもパニックを起こさずに処理できます。本番で使う場合は、context.Context によるキャンセル対応、エラー件数が上限に達したときに処理を中断する仕組み、slog による構造化ログなどの追加を検討するとよいでしょう。
JSONL の処理に使う Go のパッケージ
Go の標準ライブラリには、JSONL の処理に必要な機能がすべて揃っています。ここでは、基本となる3つの方法と、それぞれが適している場面を紹介します。
bufio.Scanner
柔軟性重視ファイルを行単位で読み取るための標準的なリーダーです。json.Unmarshal と組み合わせ、読み取った行を明示的にパースします。バッファサイズを調整したい場合、元の行データをスキップしたり確認したりしたい場合、エラーの報告に行番号が必要な場合に適しています。設定したバッファサイズまでの行を処理できます。
json.Decoder
推奨io.Reader から直接読み取るストリーミング JSON デコーダーです。データのコピーを避けられるため、Scanner + Unmarshal よりも効率的で、大容量ファイルやネットワークストリームに適しています。改行で明示的に分割しなくても、連続する JSON 値を自動で処理します。
json.Encoder
書き込み用io.Writer に書き込むストリーミング JSON エンコーダーです。Encode を呼び出すたびに自動で改行が追加されるため、JSONL の出力に最適です。高い書き込みスループットを得るには、bufio.Writer と組み合わせます。SetEscapeHTML と SetIndent による設定にも対応しています。
無料の JSONL ツールを試す
コードを書かずに済ませたい場合は、無料のオンラインツールをご利用ください。ブラウザ上で直接 JSONL ファイルの表示、検証、変換ができます。
ギガバイト規模の JSONL データを処理する方法を紹介します。ストリーミングでの読み込み、メモリ管理、ファイル分割、圧縮、オンラインツールを取り上げます。
整形、スキーマの一貫性、エラーハンドリング、パフォーマンスの最適化、ファイル整理に関する JSONL のベストプラクティスを解説します。実践的な例を通じて、よくある落とし穴を避ける方法を学べます。
JSONL ファイルを 1 行ずつ検証します。構文エラーや文字エンコーディング、形式の問題をすぐに検出できます。
Node.jsとPythonでJSONLデータをストリーミングする方法を学びます。SSE、WebSocket、リアルタイムログ処理をカバー。
Rust で JSONL ファイルを扱うための完全ガイドです。serde_json、BufReader、rayon による並列処理、tokio による非同期 I/O、堅牢なエラーハンドリングのパターンを解説します。