Bộ cột và chuẩn hoá
Mục lục
Trang này viết cho vnstock v6.0.0rc2, bản thử nghiệm. Tên hàm, tham số và cột dữ liệu có thể còn đổi trước ngày phát hành; khi cài, ghi rõ số phiên bản như ở trang Cài đặt. Bản đang phát hành chính thức là v5.0.1, xem tài liệu 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 có một lược đồ chuẩn dùng chung giữa các nguồn. Tham số columns cho phép chọn bộ cột đầy đủ
theo lược đồ, bộ cột giao nhau giữa các nguồn, hoặc thêm trường riêng từ nguồn đang dùng. Tham số compat chọn
cách đặt tên và đơn vị: như thế hệ 5 (mặc định) hoặc chuẩn đồng nhất v6.
Ba bộ cột: tham số columns
columns= | Bạn nhận được | Khi nào dùng |
|---|---|---|
"standard" (mặc định) | Toàn bộ cột chuẩn của hàm, theo cùng thứ tự giữa các nguồn. Cột nguồn không có được để trống | Muốn đổi nguồn mà không phải sửa bước xử lý phía sau |
"common" | Các cột chuẩn mà tất cả nguồn đang hỗ trợ hàm đều có thể điền | Ghép dữ liệu từ nhiều nguồn và muốn hạn chế cột trống |
"all" | Cột chuẩn đứng trước, tiếp theo là trường riêng của nguồn với tên dạng src_<tên> | Cần thêm thông tin chỉ nguồn đang dùng mới có |
from vnstock import Market
q = Market("<nguồn>").equity("FPT")
q.quote().shape # (1, 34) bộ chuẩn
q.quote(columns="common").shape # (1, 12) cột mọi nguồn đều có
q.quote(columns="all").shape # thêm các cột src_* mà riêng nguồn này gửiSố cột trong ví dụ đo ngày 03/11/2026 và có thể thay đổi khi lược đồ được cập nhật. Xem cột của một hàm ngay trên máy:
vnstock doc Market.equity.quote.
Cột src_* giữ giá trị đúng như nguồn gửi: không đổi đơn vị, không đổi mã. Tên và ý nghĩa của chúng
theo tài liệu của nguồn, có thể đổi khi nguồn đổi. Đừng dựa vào cột src_* khi viết mã cần chạy với
nhiều nguồn.
Kết quả ghi lại bộ cột đã dùng:
attrs | Nội dung |
|---|---|
columns_mode | standard, common hoặc all |
extra_columns | Với all: mỗi cột src_*, kiểu và trường gốc của nguồn |
source_columns | Cột chuẩn nào nguồn này điền |
Hai hồ sơ đầu ra: v5 và v6
v5 (mặc định) | v6 | |
|---|---|---|
| Tên, thứ tự cột | Như thế hệ 5 (open_price, bid_vol_1, buy_vol); cột mới đứng sau | Một tên một nghĩa trên mọi bảng (open, bid_volume_1, foreign_buy_volume) |
Giá bảng giá, sổ lệnh, thoả thuận, khớp theo bước giá, trade_history(), session_stats() | Đồng, như thế hệ 5 | Nghìn đồng, như nến |
| Phần trăm | Tỷ lệ ở cột thế hệ 5 vốn là tỷ lệ (percent_price_change, rate) | Điểm phần trăm (1.5 là 1,5%) |
| Chiều khớp lệnh | match_type: Buy, Sell, ATO, ATC, Unknown | side (buy, sell, unknown) và session |
| Số nguyên | int64 khi không có ô trống | Int64 |
import vnstock
vnstock.compat.use("v6") # mọi kết quả trong tiến trình
Market("<nguồn>").equity("FPT").quote(compat="v6") # hoặc một lời gọi
# hoặc biến môi trường VNSTOCK_COMPAT=v6 trước khi importMã viết cho thế hệ 5 chạy với hồ sơ v5 mà không phải đổi tên cột hay đơn vị. Hồ sơ v6 hợp khi bạn viết mã
mới và muốn mọi bảng cùng một cách gọi tên và một đơn vị.
Kiểu, đơn vị, thời gian
| Kiểu | pandas |
|---|---|
| Chuỗi | string |
| Đúng sai | boolean |
| Số nguyên | int64 (hồ sơ v5, Int64 khi có ô trống); Int64 (hồ sơ v6) |
| Số thực | float64 |
| Ngày, giờ | Có múi giờ: giờ Việt Nam cho thị trường Việt Nam, UTC cho tài sản quốc tế |
- Nến và khớp lệnh cổ phiếu, chứng quyền, chứng chỉ quỹ: nghìn đồng ở cả hai hồ sơ.
- Chỉ số, hợp đồng tương lai chỉ số: điểm.
- Tiền mã hoá, ngoại hối, hàng hoá: theo đồng định giá của cặp.
- Cột giá làm tròn theo
floating(mặc định 2 chữ số); khối lượng, giá trị, phần trăm không làm tròn. - Nến ngày, tuần, tháng mang mốc 00:00 UTC của phiên:
07:00+07:00với thị trường Việt Nam, như thế hệ 5. foreign_flow(),proprietary_flow(),trade_history()xếp phiên mới nhất trước, như thế hệ 5.
Nguồn gửi giá nằm ngoài dải hợp lý của đơn vị thì hàm báo lỗi VNSTOCK_PAYLOAD_PRICE_UNIT, không tự
nhân chia. Mã của nguồn chưa có trong bảng đổi được giữ nguyên và ghi vào attrs["unmapped_codes"].
Thông tin kèm theo kết quả
Mỗi bảng mang df.attrs để bạn biết dữ liệu từ đâu ra:
| Nhóm | Trường |
|---|---|
| Nguồn | source, source_rule, source_skipped, route, operation |
| Yêu cầu | symbol, interval, start, end, length, rows |
| Lần lấy | retrieved_at, request_count, latency_ms, envelope_count |
| Chất lượng | last_bar_partial (nến cuối thuộc phiên chưa kết thúc), truncated (nguồn còn dữ liệu sau trần số trang), rows_skipped, unmapped_codes |
| Điều khoản | terms_title, terms_summary, terms_url, disclaimer |
| Khác thế hệ 5 | profile (v5 hoặc v6), schema_changes (mã các thay đổi so với thế hệ 5) |
from vnstock import provenance
provenance.cite(df) # một dòng trích dẫn nguồn và thời điểm lấy
provenance.terms(df) # điều khoản của nguồnViệc truy cập và sử dụng dữ liệu bằng khoá của bạn chịu điều khoản của nguồn. Hãy đọc điều khoản trước khi lưu trữ, hiển thị hoặc chia sẻ dữ liệu và kết quả xử lý.