Vnstock Logo

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

Cập nhật lần cuối:

Thảo luận

Mục lục

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 các biến cấu hình đường dẫn 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 tệp và tự động cách ly dữ liệu lỗi.

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

Toàn bộ thông số cơ sở dữ liệu được quản lý tự động thông qua một tệp cấu hình 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 để phù hợp với các nhu cầu khác nhau:

  • Cấu trúc Phẳng - Flat (Mặc định): Dành cho người dùng cá nhân, lược bỏ các cấp thư mục trung gian để dễ dàng truy cập trực tiếp các tệp dữ liệu (.parquet hay .csv).

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

  • Cấu trúc Phân Cấp - 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 đoạn mã Python phức tạp.

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

Shell
# 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 tính/máy chủ và đảm bảo dữ liệu đầu vào chạy mô hình là chính xác:

Shell
# Xoá tự động các tệp 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à tệp 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 (Schema Guard)

Khi nguồn cấp dữ liệu có những thay đổi bất ngờ về cấu trúc bảng (thêm cột rác, thiếu cột quan trọng, hoặc đổi tên cột), 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 dữ liệu mới tải về với cấu trúc chuẩn ban đầu.
  2. Cách ly dữ liệu lỗi: Đẩy các tệp gây phá vỡ cấu trúc vào thư mục cách ly (.tmp/.quarantine/) thay vì ghi đè làm hỏng cơ sở dữ liệu gốc của bạn. Đồng thời tạo ra tệp .diff.json giải thích chi tiết nguyên nhân lỗi.
  3. Các tệp bị cách ly sẽ tự động bị xóa sau 14 ngày.

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

Shell
# Xem danh sách các tệp 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 sự thay đổi cấu trúc này và cập nhật nó thành cấu trúc chuẩn mới
python -m vnstock_pipeline.cli quarantine adopt ohlcv ACB

Di chuyển dữ liệu cũ (Migration)

Nếu bạn có một thư mục dữ liệu tự thu thập từ bản vnstock_pipeline cũ và muốn tái cấu trúc, hãy tham khảo Hướng dẫn nâng cấp phiên bản. Hệ thống cung cấp công cụ tự động dọn dẹp và đưa dữ liệu cũ vào kho lưu trữ mới bằng công cụ dòng lệnh migrate-legacy mà không cần tải lại từ đầu.

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ý siêu tốc: Tối ưu tốc độ đọc/ghi dữ liệu lớn qua thư viện pyarrow.
  3. Ghi nối tiếp an toàn: Ghi đè hoặc chèn dòng dữ liệu mới liên tục mà không làm hỏng cấu trúc tệp, hỗ trợ truy vấn lọc cột nhanh chóng và chính xác.

Thảo luận

Đang tải bình luận...