Lưu trữ dữ liệu tối ưu

Giới thiệu

Kể từ phiên bản v2.3.1, hệ thống lưu trữ của vnstock_pipeline đã được tái thiết kế hoàn toàn với cơ chế lưu trữ tập trung. Bạn không còn phải truyền thủ công biến BASE_DATA_DIR hay lo lắng về việc dữ liệu bị phân mảnh ở nhiều nơi. Hệ thống tự động quản lý vị trí, cấu trúc thư mục, định dạng file và cách ly dữ liệu lỗi.

Kiến trúc lưu trữ tập trung (pipeline.toml)

Tất cả thông số CSDL được quản lý tự động thông qua một file duy nhất:

• Mac/Linux: ~/.vnstock/config/pipeline.toml
• Windows: %USERPROFILE%\.vnstock\config\pipeline.toml

Cấu trúc thư mục linh hoạt

Hệ thống hiện tại hỗ trợ hai chế độ tổ chức thư mục linh hoạt:

• Chế độ Flat (mặc định): Dành cho người dùng cá nhân, lược bỏ các cấp thư mục thừa để dễ dàng truy cập trực tiếp các file .parquet hay .csv.

  Text

  ├── stock_db/
  │   ├── ohlcv/                          
  │   │   ├── ACB.parquet
  │   ├── trades/                         
  │   │   ├── ACB.parquet
  │   ├── session_stats/                  
  │   │   ├── foreign_flow/
  │   │   │   └── ACB.parquet

• Chế độ Nested: Dành cho các hệ thống kho dữ liệu lớn, tổ chức chặt chẽ theo từng lớp siêu dữ liệu.

  Text

  ├── stock_db/
  │   ├── processed/                      # Lớp dữ liệu
  │   │   ├── market/                     # Tên miền
  │   │   │   ├── ohlcv/                  # Danh mục
  │   │   │   │   ├── 1D/                 # Khung thời gian
  │   │   │   │   │   ├── equity/         # Loại tài sản
  │   │   │   │   │   │   └── ACB.parquet

Quản trị lưu trữ bằng giao diện dòng lệnh (CLI)

Giao diện dòng lệnh giúp bạn dễ dàng tùy biến dữ liệu mà không cần viết các kịch bản Python phức tạp.

1. Thay đổi cấu hình cơ bản

# Xem thông số cấu hình kho dữ liệu hiện tại
python -m vnstock_pipeline.cli storage config

# Đổi kiến trúc thư mục lưu trữ (từ flat sang nested và ngược lại)
python -m vnstock_pipeline.cli storage set-layout nested

# Thay đổi định dạng lưu trữ mặc định (CSV hoặc Parquet)
# Chú ý: Lệnh này sẽ tự động hỏi bạn có muốn chuyển đổi toàn bộ dữ liệu cũ sang chuẩn mới không.
python -m vnstock_pipeline.cli storage set-format parquet -y

2. Dọn dẹp và kiểm soát chất lượng dữ liệu

Để tiết kiệm dung lượng ổ cứng cho máy chủ VPS và đảm bảo dữ liệu chạy mô hình là chính xác:

# Xoá tự động các file dữ liệu cũ hơn 90 ngày để giải phóng bộ nhớ
python -m vnstock_pipeline.cli storage cleanup --days 90

# Phân tích chất lượng dữ liệu: phát hiện đứt gãy thời gian và file lỗi/quá hạn
python -m vnstock_pipeline.cli storage audit --category ohlcv --stale-days 5

# Quét và xây dựng lại hệ thống mục lục dữ liệu
python -m vnstock_pipeline.cli storage build-catalog

Tính năng bảo vệ cấu trúc dữ liệu

Khi API nguồn có những sự cố thay đổi cấu trúc bảng, thêm cột rác hoặc thiếu cột quan trọng, hệ thống tự động:

1. Phát hiện sai lệch cấu trúc: Tự động so sánh cấu trúc với cấu trúc chuẩn ban đầu.
2. Cách ly dữ liệu lỗi: Đẩy các file gây phá vỡ cấu trúc vào thư mục .tmp/.quarantine/ thay vì ghi đè làm hỏng cơ sở dữ liệu gốc của bạn. Cung cấp file .diff.json giải thích nguyên nhân lỗi.
3. Các file cách ly tự động bị dọn dẹp sau 14 ngày.

Kiểm tra dữ liệu cách ly:

# Xem danh sách các file dữ liệu bị cách ly do lệch cấu trúc
python -m vnstock_pipeline.cli quarantine list

# Chấp nhận thay đổi cấu trúc này và cập nhật cấu trúc chuẩn
python -m vnstock_pipeline.cli quarantine adopt ohlcv ACB

Di chuyển dữ liệu cũ

Nếu bạn có một thư mục dữ liệu tự thu thập từ bản vnstock_pipeline cũ, bạn không cần phải xóa đi chạy lại từ đầu. Hệ thống cung cấp công cụ tự động dọn dẹp và đưa nó vào kho lưu trữ mới.

# Lệnh tự động nhận diện định dạng, phân loại nhóm dữ liệu và sắp xếp vào kho chuẩn mới
python -m vnstock_pipeline.cli storage migrate-legacy --source ./old_data_folder

Lợi ích của việc sử dụng Parquet so với CSV:

1. Tiết kiệm dung lượng: Dữ liệu được nén hiệu quả, giảm tới 75% dung lượng.
2. Tốc độ xử lý: Tối ưu tốc độ đọc/ghi siêu tốc qua thư viện pyarrow.
3. Ghi thêm dữ liệu thông minh: Ghi đè hoặc chèn dòng dữ liệu liên tục không làm phá vỡ file, hỗ trợ truy vấn lọc cột nhanh chóng.