Vnstock Logo

Quy tắc chuẩn hoá dữ liệu, bộ cột và hồ sơ tương thích

Mở rộng

Mục lục

Nguồn của bạn

Chọn nguồn bạn có khoá, mã trên trang sẽ điền theo. Chưa chọn thì mã giữ chỗ trống <nguồn>. Nguồn xếp theo bảng chữ cái, không phải khuyến nghị.

Mỗi hàm trong vnstock thế hệ 6 đều có một lược đồ chuẩn dùng chung giữa các nguồn dữ liệu. Khi gọi hàm, bạn có thể dùng tham số columns để chọn lấy bộ cột chuẩn, bộ cột giao nhau giữa mọi nguồn, hoặc lấy thêm các trường riêng của nguồn đang dùng; đồng thời dùng tham số compat để chọn giữ quy ước tên cột và đơn vị như thế hệ 5 (mặc định) hay chuyển sang chuẩn đồng nhất mới của thế hệ 6.

Tuỳ chọn số lượng cột trả về bằng tham số columns

Giá trị columns=Bảng kết quả bạn nhận đượcKhi nào nên sử dụng
"standard" (mặc định)Toàn bộ các cột chuẩn của hàm theo đúng thứ tự cố định giữa mọi nguồn (những cột mà nguồn đang chọn không gửi sẽ được để trống NA)Khi bạn muốn đổi nguồn dữ liệu linh hoạt mà không phải sửa lại các bước xử lý cột phía sau
"common"Chỉ giữ lại những cột chuẩn mà tất cả các nguồn hỗ trợ hàm đó đều có số liệuKhi bạn ghép nối dữ liệu từ nhiều nguồn khác nhau và muốn hạn chế tối đa các cột trống
"all"Toàn bộ các cột chuẩn đứng trước, nối tiếp là các trường riêng của nguồn đã được khai báo cho hàm đó (mang tiền tố src_<tên_tường_minh>)Khi bạn cần khai thác thêm những trường thông tin đặc thù chỉ có ở nguồn đang dùng
Python
from vnstock import Market

q = Market("<nguồn>").equity("FPT")
q.quote().shape                       # (1, 34) — đầy đủ 34 cột theo lược đồ chuẩn
q.quote(columns="common").shape       # (1, 12) — 12 cột mà mọi nguồn hỗ trợ quote() đều có

Số lượng cột có thể được cập nhật khi lược đồ mở rộng. Để xem nhanh danh sách cột của bất kỳ hàm nào ngay trên máy, bạn chạy lệnh vnstock doc Market.equity.quote.

Lưu ý rằng columns="all" không đổ thô toàn bộ phản hồi gốc của nguồn vào bảng, mà chỉ bổ sung những trường riêng có giá trị sử dụng thực tế và đặt lại tên cột tường minh dễ đọc. Hiện tại, các trường mở rộng src_* đã được khai báo cho nguồn ssi gồm:

Hàm áp dụngCột mở rộng được thêmÝ nghĩa dữ liệu
trade_history() (cổ phiếu)src_price_change_unadjustedMức thay đổi giá gốc do nguồn gửi (chưa điều chỉnh theo sự kiện quyền)
src_foreign_roomRoom ngoại còn lại tại phiên đó
src_foreign_room_totalTổng room ngoại tối đa của mã
events.calendar()src_price_adjustment_ratioHệ số điều chỉnh giá kỹ thuật của sự kiện quyền (không phải tỷ lệ chia thưởng)
equity.list()src_indicative_navThông tin NAV tham chiếu mở rộng (chỉ một số mã chứng chỉ quỹ có dữ liệu)
src_indicative_indexThông tin chỉ số tham chiếu mở rộng (chỉ một số mã có dữ liệu)
Python
df = Market("ssi").equity("FPT").trade_history(start="2026-10-01", columns="all")
df.attrs["extra_columns"]             # tra cứu kiểu dữ liệu và tên trường gốc của từng cột src_*

Các cột src_* giữ nguyên giá trị gốc như nguồn gửi về (không tự đổi đơn vị, không đổi mã từ vựng, có thể ở dạng chuỗi số). Do đó, bạn không nên phụ thuộc vào các cột src_* khi viết đoạn mã cần chạy chung cho nhiều nguồn.

Mỗi bảng kết quả đều ghi nhận chế độ cột đã dùng trong df.attrs:

Khoá trong df.attrsNội dung ghi nhận
columns_modeChế độ cột đã chọn: "standard", "common" hoặc "all"
extra_columnsDanh sách chi tiết các cột src_*, kiểu dữ liệu và tên trường gốc của nguồn (khi dùng columns="all")
source_columnsDanh sách những cột chuẩn mà nguồn hiện tại thực sự có dữ liệu điền vào

Chọn hồ sơ quy ước tên cột và đơn vị (compat="v5" hoặc "v6")

Thư viện hỗ trợ song song hai hồ sơ đầu ra để vừa bảo vệ mã nguồn cũ, vừa cung cấp chuẩn dữ liệu nhất quán cho các dự án mới:

Tiêu chí so sánhHồ sơ v5 (mặc định)Hồ sơ v6 (chuẩn đồng nhất mới)
Tên và thứ tự cộtGiữ nguyên như thế hệ 5 (open_price, bid_vol_1, buy_vol); các cột mới bổ sung xếp ở cuối bảngMỗi đại lượng chỉ có một tên duy nhất trên mọi bảng (open, bid_volume_1, foreign_buy_volume)
Đơn vị giá ở bảng giá, sổ lệnh, thoả thuận, khớp theo bước giá, trade_history(), session_stats()Tính bằng đồng (giống thế hệ 5)Quy đổi đồng nhất về nghìn đồng (cùng đơn vị với bảng nến ohlcv)
Biểu diễn tỷ lệ phần trămGiữ dạng tỷ lệ thập phân ở những cột thế hệ 5 vốn dùng tỷ lệ (percent_price_change, rate)Quy về điểm phần trăm trên mọi bảng (ví dụ: 1.5 nghĩa là 1,5%)
Chiều mua/bán ở khớp lệnh (trades)Một cột match_type gồm Buy, Sell, ATO, ATC, UnknownTách rõ thành hai cột: side (buy, sell, unknown) và session
Kiểu số nguyênint64 (chuyển sang Int64 khi cột có ô trống)Luôn dùng Int64 (hỗ trợ giá trị NA tự nhiên của pandas)
Thứ tự dòng của foreign_flow(), proprietary_flow(), trade_history()Xếp phiên mới nhất lên đầu (giống thế hệ 5)Sắp xếp tăng dần theo thời gian (cùng chiều với bảng nến)
Mốc giờ của các bảng theo ngày ở trên00:00+07:00 (giống thế hệ 5)07:00+07:00 (trùng khớp với mốc giờ của nến ngày để ghép bảng trực tiếp)

Bạn có thể chuyển sang hồ sơ v6 cho toàn bộ phiên làm việc hoặc cho từng lời gọi hàm riêng lẻ:

Python
import vnstock
vnstock.compat.use("v6")                                  # áp dụng chuẩn v6 cho mọi lời gọi trong tiến trình
Market("<nguồn>").equity("FPT").quote(compat="v6")       # hoặc chỉ áp dụng cho riêng lời gọi này
# Cách khác: đặt biến môi trường VNSTOCK_COMPAT=v6 trước khi chạy Python

Nhờ mặc định ở hồ sơ v5, các kịch bản viết cho thế hệ 5 có thể chạy ngay mà không cần sửa tên cột hay hệ số đơn vị. Khi bắt đầu viết dự án mới hoặc xây dựng mô hình định lượng ghép nối nhiều bảng, bạn nên bật hồ sơ v6 để tận hưởng sự đồng nhất hoàn toàn về tên cột, đơn vị và trục thời gian.

Quy ước chuẩn về kiểu dữ liệu, đơn vị giá và múi giờ

Nhóm dữ liệuKiểu dữ liệu pandas chuẩn
Chuỗi văn bản, mã chứng khoánstring
Giá trị logic (Đúng / Sai)boolean
Số nguyên (khối lượng, số lệnh)int64 (ở hồ sơ v5 khi không có ô trống); Int64 (ở hồ sơ v6 hoặc khi có ô trống)
Số thực (giá, giá trị, tỷ lệ)float64
Thời gian (ngày, giờ)Luôn gắn múi giờ: Asia/Ho_Chi_Minh (+07:00) cho thị trường Việt Nam, UTC cho tài sản quốc tế

Chi tiết các quy ước chuẩn hoá:

  • Đơn vị giá nến và khớp lệnh của cổ phiếu, chứng quyền, chứng chỉ quỹ ETF: luôn tính bằng nghìn đồng ở cả hai hồ sơ v5 và v6.
  • Chỉ số thị trường và hợp đồng tương lai chỉ số: tính bằng điểm.
  • Khối lượng giao dịch: tính bằng cổ phiếu trên mọi nguồn và mọi bảng giao dịch; riêng hợp đồng tương lai tính theo hợp đồng (nếu nguồn gửi theo đơn vị lô, thư viện tự động quy đổi khi đọc).
  • Tiền mã hoá, ngoại hối, hàng hoá quốc tế: tính theo đồng tiền định giá của cặp tài sản.
  • Làm tròn số: các cột giá được làm tròn theo tham số floating (mặc định 2 chữ số thập phân); các cột khối lượng, giá trị giao dịch và tỷ lệ phần trăm giữ nguyên độ chính xác gốc.
  • Mốc giờ của nến ngày, tuần, tháng: mang mốc 00:00 UTC của ngày đầu kỳ, tức 07:00+07:00 theo giờ Việt Nam.
  • Mốc ngày của nến tuần và nến tháng: nến tuần luôn gắn vào ngày thứ Hai của tuần đó, nến tháng luôn gắn vào ngày 01 của tháng theo lịch dương ở mọi nguồn Việt Nam (kể cả khi ngày thứ Hai hoặc ngày 01 rơi vào ngày nghỉ lễ). Nhờ vậy, khi bạn ghép nối dữ liệu nến tuần/tháng giữa nhiều nguồn theo cột time, các kỳ luôn khớp nhau.

Nếu nguồn gửi về một mức giá nằm ngoài dải hợp lý của đơn vị tiền tệ (chẳng hạn lỗi nhân chia 1.000 lần từ phía nguồn), hàm sẽ dừng lại và báo lỗi VNSTOCK_PAYLOAD_PRICE_UNIT thay vì tự ý đoán và nhân chia lại. Những mã phân loại mới từ nguồn chưa có trong từ điển chuẩn sẽ được giữ nguyên giá trị gốc và ghi chú vào df.attrs["unmapped_codes"].

Lưu ý quan trọng khi ghép bảng và đưa vào mô hình định lượng

Khi sử dụng hồ sơ compat="v6", mọi bảng dữ liệu theo ngày đều dùng chung mốc giờ 07:00+07:00 và sắp xếp tăng dần theo thời gian, nên bạn có thể ghép nối (merge) trực tiếp trên cột time:

Python
from vnstock import Market

q = Market("<nguồn>").equity("FPT")
bars = q.ohlcv(start="2026-10-01", compat="v6")
flows = q.foreign_flow(start="2026-10-01", compat="v6")
panel = bars.merge(flows, on="time")

Ngược lại, nếu bạn giữ hồ sơ mặc định v5, cột thời gian của foreign_flow(), proprietary_flow(), trade_history() mang mốc 00:00+07:00 và xếp dòng mới nhất lên đầu. Trước khi ghép bảng hoặc gọi các hàm trượt theo chuỗi thời gian như .shift(), .pct_change(), .rolling(), bạn cần quy về ngày và sắp xếp lại thứ tự tăng dần:

Python
flows = flows.assign(day=flows["time"].dt.date).sort_values("day")

Các nguyên tắc bảo toàn tính đúng đắn của dữ liệu trong nghiên cứu định lượng:

  • Phân biệt giá đã điều chỉnh và khối lượng/giá trị gốc: trên nguồn ssi, dữ liệu nến (ohlcv) và các cột giá của trade_history() đã được điều chỉnh theo sự kiện quyền (chia cổ tức, thưởng cổ phiếu), trong khi volume và matched_volume vẫn là khối lượng khớp thực tế của ngày hôm đó. Thuộc tính df.attrs["column_basis"] ghi rõ trạng thái adjusted hay unadjusted cho từng cột. Các cột matched_value, deal_value phản ánh đúng số tiền giao dịch thực tế trong phiên. Ở hồ sơ v6, bạn có thể suy ra hệ số điều chỉnh giá của một phiên theo công thức: average_price / (matched_value / matched_volume / 1000).
  • Lưu ý khác biệt đơn vị giữa giá và giá trị: ở hồ sơ v6, các cột giá cổ phiếu tính bằng nghìn đồng, còn các cột tổng giá trị giao dịch và cổ tức tiền mặt (cash_per_share) tính bằng đồng. Do đó, giá trị giao dịch ước tính từ bảng nến bằng close * 1000 * volume.
  • Các chỉ số trong summary() không nằm trên cùng một kỳ thời gian: trên nguồn fhsc, các cột eps, roe, roa, nim là số liệu của năm tài chính gần nhất, trong khi pe và pb lại được tính theo thị giá hiện tại. Bạn không nên lấy pe * eps để suy ngược ra giá cổ phiếu, cũng không nên so sánh trực tiếp roe này với ROE trượt 4 quý gần nhất (TTM). Hãy kiểm tra df.attrs["column_basis"] để biết cơ sở kỳ của từng cột.
  • Sử dụng đúng số lượng cổ phiếu lưu hành khi tính toán trên mỗi cổ phiếu: khoản mục Vốn điều lệ trên báo cáo tài chính lịch sử chưa phản ánh các đợt chia tách cổ phiếu diễn ra sau ngày khóa sổ, trong khi giá lịch sử đã được điều chỉnh lùi. Khi tính chỉ số định giá hiện tại, hãy lấy outstanding_shares từ Reference("fhsc").company(mã).listing().
  • Bảng dữ liệu vĩ mô chứa nhiều chỉ tiêu và đơn vị khác nhau: mỗi dòng là một chỉ tiêu tại một kỳ công bố; hãy luôn lọc riêng từng mã indicator trước khi đưa vào chuỗi tính toán (Kinh tế vĩ mô).
  • Khác biệt nhỏ ở nến phút giữa các nguồn: giá cao nhất, thấp nhất và tổng khối lượng cả phiên thường khớp nhau, nhưng giá mở cửa (open) và đóng cửa (close) của từng thanh nến 1 phút có thể chênh lệch nhẹ giữa các nguồn do thứ tự ghi nhận các lệnh khớp trong cùng một giây. Hiện tượng này dễ thấy hơn ở hợp đồng tương lai phái sinh nơi tốc độ khớp lệnh dày.
  • Lưu ý thiên lệch sống sót (Survivorship Bias): danh sách mã từ Reference().equity.list() và thành phần rổ chỉ số hiện tại là ảnh chụp tại thời điểm truy vấn, không bao gồm những mã đã huỷ niêm yết hoặc lịch sử thêm/bớt cổ phiếu khỏi rổ chỉ số trong quá khứ.
  • Lưu ý độ trễ công bố báo cáo tài chính (Lookahead Bias): cột kỳ báo cáo (2025, 2025-Q3) là kỳ kế toán, không phải ngày doanh nghiệp công bố báo cáo ra công chúng. Khi kiểm thử chiến lược (backtest), bạn cần cộng thêm độ trễ công bố theo quy định.

Đặc điểm riêng cần biết khi làm việc với nguồn ssi:

  • Ở hàm trade_history(), hai cột reference_price và price_change đã được điều chỉnh cùng gốc với close. Nếu cần mức thay đổi giá gốc chưa điều chỉnh, bạn truyền columns="all" và đọc cột src_price_change_unadjusted.
  • Đối với chỉ số thị trường (index), thư viện tính lại reference_price, price_change và phần trăm thay đổi từ giá đóng cửa phiên liền trước (do trường thay đổi gốc của nguồn có một số giai đoạn lịch sử không nhất quán). Riêng dòng đầu tiên của khoảng truy vấn không có phiên liền trước nên giữ nguyên số của nguồn (hoặc để trống nếu giá trị vượt ngoài biên độ hợp lý của một phiên).
  • Ở hàm foreign_flow() của chỉ số, các cột giá trị mua và bán được để trống (NA) vì nguồn luôn trả về số 0; bạn nên sử dụng các cột khối lượng và giá trị mua bán ròng (net).
  • Ở hàm foreign_flow() của cổ phiếu, những phiên khối ngoại không phát sinh giao dịch vẫn được giữ lại dòng ngày hôm đó với các cột khối ngoại để trống (NA).
  • Nguồn ssi chưa trả dòng dữ liệu của phiên đang diễn ra cho một số hàm lịch sử. Khi gọi Market("ssi").index(mã).quote() không truyền khoảng ngày, hàm sẽ trả về phiên gần nhất đã đóng và đánh dấu df.attrs["stale"] = True.
  • Ở hàm ohlcv(), cột volume của cổ phiếu chỉ bao gồm khối lượng khớp lệnh trên sàn, trong khi volume của chỉ số thị trường bao gồm cả khối lượng giao dịch thoả thuận.
  • Số lượng mã tăng, giảm, đứng giá của chỉ số hiện chỉ có số liệu trên VNINDEX; các chỉ số khác sẽ để trống (NA) thay vì điền số 0 gây nhầm lẫn.

Tra cứu nguồn gốc dữ liệu và điều khoản qua df.attrs

Mỗi bảng DataFrame trả về từ vnstock đều mang theo từ điển siêu dữ liệu df.attrs giúp bạn kiểm tra xuất xứ và chất lượng dữ liệu:

Nhóm thông tinCác trường trong df.attrs
Định danh nguồn & tuyếnsource, source_rule, source_skipped, route, operation
Tham số truy vấnsymbol, interval, start, end, length, rows
Thống kê truy vấn mạngretrieved_at (thời điểm lấy), request_count (số lần gọi), latency_ms (độ trễ), envelope_count
Cờ kiểm soát chất lượnglast_bar_partial (nến cuối thuộc phiên chưa đóng), truncated (chạm trần phân trang), empty_result (nguồn trả về 0 dòng), resampled_from (khung nến gốc dùng để gộp), rows_skipped, unmapped_codes
Điều khoản của nguồnterms_title, terms_summary, terms_url, disclaimer
Cơ sở tính toán cộtcolumn_basis (ghi rõ từng cột là số liệu năm tài chính, theo thị giá hiện tại, đã điều chỉnh hay chưa điều chỉnh)
Hợp đồng tương laicontract_since (ngày bắt đầu hợp đồng hiện tại trong chuỗi liên tục), requested_symbol (mã bạn truyền vào trước khi ánh xạ sang mã của nguồn)
Xử lý lọc tại máyfiltered_locally (danh sách các bước lọc, cắt khoảng thời gian hoặc giới hạn dòng được thư viện thực hiện trên máy khi nguồn không hỗ trợ lọc trực tiếp)
Tương thích thế hệ 5profile ("v5" hoặc "v6"), schema_changes (danh sách mã thay đổi cấu trúc bảng so với thế hệ 5)

Bạn cũng có thể dùng mô-đun provenance để in nhanh dòng trích dẫn nguồn hoặc đọc điều khoản sử dụng của nguồn dữ liệu:

Python
from vnstock import provenance
provenance.cite(df)       # tạo chuỗi trích dẫn nguồn và thời điểm truy xuất
provenance.terms(df)      # xem tóm tắt điều khoản sử dụng dữ liệu của nguồn

Việc truy xuất và sử dụng dữ liệu bằng khoá Open API của bạn tuân theo điều khoản của từng nguồn. Hãy kiểm tra kỹ điều khoản của nguồn trước khi lưu trữ, hiển thị hoặc chia sẻ kết quả.