著者: Jerry Fan

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 にパースします。この方法では、メモリ使用量をファイル全体のサイズではなく、単一レコードのサイズに応じた量に抑えられます。

bufio.Scanner による基本的な読み取り
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 よりも効率的です。

json.Decoder によるストリーミング処理
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 のバイト列にシリアライズし、末尾に改行を付けて書き込みます。シンプルな方法で、小規模から中規模のファイルに適しています。

json.Marshal による基本的な書き込み
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 を呼び出してください。

json.Encoder とバッファリングによる書き込み
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 バウンドな変換処理を行う場合に最適です。

goroutine で JSONL を並行処理する
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 ファイルを扱う

最大 1GB の JSONL ファイルを、ブラウザ上で直接表示、検証、変換できます。アップロードは不要で、プライバシーは 100% 保たれます。

よくある質問

参考資料