Lõi MatrixEngine

MatrixEngine (src/engine/mod.rs) là struct duy nhất đứng sau mọi lệnh của SDK. Nó mang bốn ngưỡng chất lượng dữ liệu dùng cho đường tắt lọc tĩnh và preview_sample:

pub struct MatrixEngine {
    pub min_passenger: i64,   // mặc định 1
    pub max_passenger: i64,   // mặc định 9
    pub min_fare: f64,        // mặc định 0.01
    pub max_speed_mph: f64,   // mặc định 100.0; dùng khi có timestamp taxi
}

Khởi tạo

import basaltic_red as br

# Singleton dùng chung cho mọi lệnh br.<group>.* (ngưỡng 1, 9, 0.01, 100.0)
br.read.slice_rows(...)

# Ngưỡng tùy chỉnh cho mục đích nâng cao
engine = br.MatrixEngine(
    min_passenger=0,
    max_passenger=20,
    min_fare=-5.0,
    max_speed_mph=200.0,
)

br.MatrixEngine(...) nhận tham số theo vị trí hoặc từ khóa. Các ngưỡng này dùng để thiết lập tiêu chuẩn lọc tĩnh (static validation). Instance dùng chung được tạo một lần mỗi tiến trình qua OnceLock, nên ngưỡng không bao giờ lệch nhau giữa các lệnh con.

Thao tác cắt lát (Slicing)

Cài đặt trong src/engine/slice.rs; phơi ra qua br.read.*:

Phương thức	Hành vi
`slice_rows(file_path, offset, limit)`	Parquet, ORC, Avro và MsgPack phân giải row group/stripe/block native khỏe từ `.br_map.bazan`; XLSX bắt đầu `XlsxRows` từ block dòng logic của worksheet đã lập chỉ mục (Calamine vẫn materialize worksheet); NDJSON/JSONL và JSON-array nhảy tới checkpoint đã lập chỉ mục; CSV/TSV/PSV/TXT nhảy tới block dòng đã lập chỉ mục; Arrow IPC/Feather nhảy tới RecordBatch đã lập chỉ mục. Các nhánh này sau đó áp dụng offset/limit cục bộ; định dạng khác vẫn stream và bỏ qua batch.
`slice_cols(file_path, selected_cols, offset, limit)`	Cùng cách phân giải vị trí. Parquet, Arrow IPC/Feather và ORC chuyển phép chiếu xuống reader. Delimited mapped parse cột được chọn nhưng vẫn đọc byte của từng record; định dạng theo dòng khác thường decode các dòng được chọn rồi mới project. Nếu không có locator phù hợp, handler có thể stream và bỏ qua dòng trước. Thứ tự cột đầu ra theo `selected_cols`.
`preview_sample(file_path, limit_rows)`	Mở batch đầu tiên và chạy bộ lọc ngưỡng tĩnh; trả về `(clean_table, trash_table)`.

Cả hai phương thức slice đều phân giải handler qua registry định dạng, nên hỗ trợ các định dạng đã đăng ký ngoài Parquet. Locator trong map tùy theo định dạng; handler fallback có thể stream và bỏ qua từ đầu. XLSX bắt đầu ở dòng logic đã lập chỉ mục sau khi Calamine materialize worksheet.

Phân loại lỗi

Toàn bộ lỗi engine đi qua một enum duy nhất, BazanError trong src/error.rs, được ánh xạ sang Python bởi một hàm duy nhất (src/pyapi/mod.rs):

Variant Rust	Exception Python	Nguyên nhân thường gặp
`UnsupportedFormat(_)`	`ValueError`	Extension chưa đăng ký và sniff thất bại
`DataFusion(_)`	`RuntimeError`	Lỗi parse/thực thi SQL
còn lại (`Message`, IO, Arrow)	`IOError`	Thiếu tệp, tệp rỗng, dữ liệu hỏng

Lỗi cú pháp quy tắc phát sinh trước khi thực thi được trả về dưới dạng ValueError ngay từ bộ phân tích quy tắc.

Lọc Tĩnh vs Động

Đường tắt tĩnh (src/filter.rs + engine/filter.rs): ba cờ bit cố định, khoảng passenger, mức giá tối thiểu và bất thường tốc độ/distance-fare. Passenger hỗ trợ cả dạng Int64 và Float64 có trong dữ liệu TLC. Khi có timestamp pickup/dropoff, tốc độ được tính từ khoảng cách và thời lượng; schema khác dùng fallback distance/fare cũ. Dùng cho process_batch / process_file / process_and_write_lake / preview_sample.
Nhân động (engine/dynamic_filter.rs): quy tắc người dùng tùy ý parsed từ chuỗi trên mọi kiểu cột được hỗ trợ. Xem Nhân SIMD Bitmask.