Khắc phục sự cố & Tối ưu

Các lỗi thường gặp & Cách xử lý

Nguyên nhân: Tệp được thêm/sửa/xóa mà chưa cập nhật danh mục.
Xử lý: Chạy br.lake.doctor("data", auto_heal=True), các khóa modified_files / unindexed_files / missing_files trong báo cáo chỉ đích danh thứ gì đã lệch.

Nguyên nhân: Extension chưa đăng ký và sniff magic-byte thất bại.
Cách 1: Kiểm tra br.formats.list_formats() để xem extension được hỗ trợ (csv, tsv, psv, txt, json, jsonl, ndjson, parquet, pq, feather, arrow, ipc, avro, xlsx, orc, msgpack).
Cách 2: Đăng ký handler tùy chỉnh: br.formats.register_delimited(ext="xyz", delimiter="|").

Nguyên nhân: preview_sample / bộ lọc mở phải tệp có batch đầu tiên bằng 0 dòng.
Xử lý: Xóa hoặc tạo lại tệp rỗng; chạy br.lake.doctor để tìm nó.

Nguyên nhân: Quy tắc trỏ tới cột không tồn tại, kiểu dữ liệu không hỗ trợ (ngày tháng, decimal…), hoặc giá trị không parse được theo kiểu cột, các quy tắc này bị bỏ qua im lặng theo Cú pháp quy tắc.
Xử lý: Kiểm tra tên cột qua br.read.slice_rows(path, 0, 1).schema.

Nguyên nhân: DataFusion kỳ vọng object phân tách bằng xuống dòng; mảng [...] tầng ngoài sẽ đi đường fallback MemTable.
Xử lý: Ưu tiên NDJSON cho workload SQL lớn.

Nguyên nhân: Ô chuỗi bắt đầu bằng =, +, @, hoặc - không phải số.
Hành vi: CSV Guard khử nhiễm tự động bằng cách thêm tiền tố ' khi ghi CSV; giá trị âm dạng số như -5.0 đi qua nguyên vẹn (xem src/engine/csv_guard.rs).

Cắt tỉa phân vùng: giữ bố cục kiểu Hive (year=.../month=.../) và truyền partition_filter= cùng đích là thư mục để bỏ cả nhánh trước khi đọc dữ liệu. Với filter_files_parallel, đích là tệp đơn hoặc glob không được cắt tỉa theo đường dẫn phân vùng.
Trần RAM: nâng/hạ ngân sách bằng BASALTIC_RED_MAX_RAM_GB (mặc định 2).
Độ rộng song song: giới hạn worker bằng num_threads= trên filter_files_parallel để chừa lõi cho việc khác.
Ưu tiên Parquet: pushdown ListingTable thuần túy (predicate + projection) chỉ áp dụng cho đích Parquet/phân cách/JSON/IPC trong SQL.