Cấu hình và lưu trữ

Một trong những ưu điểm nổi bật của vnstock_pipeline là khả năng quản lý thư mục dữ liệu cục bộ một cách có tổ chức, khoa học và nhất quán. Toàn bộ thiết lập về đường dẫn lưu trữ, định dạng tệp và cấu trúc cây thư mục đều được kiểm soát tập trung qua một tệp cấu hình duy nhất.

Trang này hướng dẫn bạn cách thiết lập tệp pipeline.toml và sử dụng lớp DataManager để đọc, ghi dữ liệu trong mã nguồn Python.

Tệp cấu hình pipeline.toml

Thư viện tìm kiếm tệp pipeline.toml theo thứ tự ưu tiên:

1. Thư mục làm việc hiện tại của bạn (./pipeline.toml).
2. Thư mục cấu hình cá nhân của Vnstock (~/.vnstock/config/pipeline.toml).

Khởi tạo cấu hình mặc định

Nếu bạn bắt đầu dự án mới, hãy chạy lệnh sau trong terminal để tạo tệp cấu hình mẫu:

vnstock_pipeline storage init-config

Để xem cấu hình lưu trữ hiện tại đang được kích hoạt:

vnstock_pipeline storage config

Nội dung mẫu tệp pipeline.toml

[storage]
# Đường dẫn thư mục gốc chứa dữ liệu (tương đối hoặc tuyệt đối)
base_path = "./data"

# Định dạng tệp: "parquet" (khuyên dùng) hoặc "csv"
format = "parquet"

# Cấu trúc cây thư mục: "flat" (đơn giản) hoặc "nested" (phân tầng sâu)
layout = "flat"

# Thuật toán nén cho tệp Parquet: "snappy", "zstd", "gzip"
compression = "snappy"

# Duy trì danh mục metadata
enable_catalog = true
enable_history = true

[universe]
# Cấu hình danh sách mã theo dõi mặc định
default_group = "VN30"

Hai định dạng lưu trữ: Parquet và CSV

Thư viện hỗ trợ hai định dạng tệp tuỳ theo nhu cầu sử dụng của bạn:

Chuyển đổi định dạng cơ sở dữ liệu

Bạn có thể chuyển đổi định dạng của toàn bộ cơ sở dữ liệu hiện có trên máy bất kỳ lúc nào:

# Chuyển đổi toàn bộ dữ liệu sang Parquet
vnstock_pipeline storage set-format parquet -y

# Hoặc chuyển đổi sang CSV
vnstock_pipeline storage set-format csv -y

Tuỳ chọn -y giúp hệ thống chuyển đổi trực tiếp toàn bộ các tệp dữ liệu cũ sang định dạng mới mà không cần bạn phải xác nhận từng bước.

Hai cấu trúc cây thư mục: Flat và Nested

Thư viện cung cấp hai mô hình tổ chức thư mục trên đĩa:

• Mô hình flat (Mặc định): Mỗi loại dữ liệu là một thư mục, toàn bộ tệp của các mã cổ phiếu nằm trực tiếp bên trong:

  Text

  data/
  ├── ohlcv/
  │   ├── ACB.parquet
  │   ├── FPT.parquet
  │   └── VNM.parquet
  └── trades/
      └── 2026-03-01/
          └── ACB.parquet

  Ưu điểm: Cấu trúc đơn giản, trực quan, dễ tìm kiếm tệp trong trình duyệt tệp của hệ điều hành.

• Mô hình nested (Phân tầng chuyên sâu): Dữ liệu được phân chia theo từng tầng miền (domain/layer/interval/instrument/ticker.parquet):

  Text

  data/
  └── market/
      └── processed/
          └── 1D/
              └── equity/
                  └── ACB.parquet

  Ưu điểm: Phù hợp cho các hệ thống lưu trữ lớn, nhiều khung thời gian (1 phút, 5 phút, 1 ngày) và đa dạng loại tài sản (cổ phiếu, chỉ số, phái sinh).

Bạn có thể chuyển đổi cấu trúc cây thư mục bất kỳ lúc nào bằng lệnh:

vnstock_pipeline storage set-layout flat
# hoặc
vnstock_pipeline storage set-layout nested

Xem trực quan cây thư mục dữ liệu

Thư viện tích hợp sẵn công cụ hiển thị cây thư mục mà không cần cài đặt thêm phần mềm bên ngoài:

vnstock_pipeline storage tree -L 3

Lệnh này sẽ in ra sơ đồ cây thư mục dữ liệu hiện tại tới độ sâu 3 tầng một cách trực quan trên terminal.

Sử dụng DataManager trong Python

Lớp DataManager là giao diện lập trình trung tâm giúp bạn thao tác với các tệp dữ liệu đã lưu một cách tiện lợi.

Khởi tạo DataManager

from vnstock_pipeline.core.storage import DataManager

# Khởi tạo mặc định theo đường dẫn trong pipeline.toml
manager = DataManager()

# Hoặc chỉ định một thư mục dữ liệu tuỳ ý
# manager = DataManager(base_path="/duong-dan/kho-du-lieu")

Đọc dữ liệu giá lịch sử (OHLCV)

Hàm load_ohlcv() cung cấp phương thức nhanh nhất để lấy bảng nến giá lịch sử của một mã:

# Lấy toàn bộ lịch sử giá của mã VNM
df = manager.load_ohlcv("VNM")

# Lấy dữ liệu trong một khoảng thời gian cụ thể và chỉ lấy một số cột cần thiết
df = manager.load_ohlcv(
    ticker="VNM",
    start_date="2025-01-01",
    end_date="2026-03-01",
    columns=["time", "open", "high", "low", "close", "volume"]
)
print(df.head())

Đọc dữ liệu khớp lệnh từng bước giá (Trades)

# Đọc dữ liệu khớp lệnh trong phiên ngày 01/03/2026 của mã FPT
df_trades = manager.load_trades(ticker="FPT", date="2026-03-01")
print(df_trades.tail())

Đọc dữ liệu tổng quát với bộ lọc SQL

Với các tệp định dạng Parquet, hàm load_data() cho phép bạn áp dụng bộ lọc trực tiếp ở tầng đĩa, giúp tiết kiệm bộ nhớ RAM tối đa:

# Đọc các phiên giao dịch có giá đóng cửa trên 50.000 đồng
df_filtered = manager.load_data(
    ticker="ACB",
    data_type="ohlcv",
    filters=[("close", ">", 50)]
)

Các toán tử so sánh được hỗ trợ gồm: ==, !=, >, >=, <, <=.

Ghi dữ liệu vào kho lưu trữ

Khi bạn có một bảng DataFrame cần lưu trữ theo cấu trúc chuẩn của hệ thống:

import pandas as pd

# Giả sử bạn có DataFrame mới cần lưu
# df_new = ...

# Ghi dữ liệu: Thư mục cha và định dạng tệp được xử lý đồng bộ
file_saved = manager.save_data(
    data=df_new,
    ticker="FPT",
    data_type="ohlcv"
)
print(f"Đã lưu thành công tại: {file_saved}")

Liệt kê và xoá dữ liệu

# Liệt kê danh sách các mã đang có dữ liệu OHLCV trên máy
available = manager.list_available_data(data_type="ohlcv")
print("Danh sách mã hiện có:", available.get("ohlcv", []))

# Xoá dữ liệu của một mã cụ thể khi cần dọn dẹp
# manager.delete_data(data_type="ohlcv", ticker="ACB")

Bước tiếp theo

Khi kho lưu trữ đã sẵn sàng, hãy tiếp tục tìm hiểu cách sử dụng các câu lệnh tải dữ liệu theo lô cho danh sách mã theo dõi tại trang Tải dữ liệu theo lô.