Sự kiện chuẩn và bộ cột
Mục lục
Trang này viết cho vnstock_pipeline v6.0.0rc1, 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à v3.1.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 nguồn gửi dữ liệu trong phiên theo định dạng, tên trường và đơn vị riêng. Pipeline giải mã tất cả về sự kiện chuẩn phiên bản 3: cùng một loại sự kiện có cùng tên cột, cùng đơn vị, cùng kiểu dữ liệu, dù đến từ nguồn nào. Vì vậy bạn ghép, so sánh hay chuyển đổi dữ liệu nhiều nguồn mà không phải viết mã riêng cho từng nguồn.
14 loại sự kiện
| Loại | Ý nghĩa | Cột lõi (luôn có giá trị) | Nguồn có |
|---|---|---|---|
trade | Một lần khớp lệnh | symbol, board, time_ns, price, volume | dnse, tcbs, ssi, binance |
quote | Các bước giá mua, bán | symbol, board, time_ns, bids, asks | dnse, tcbs, ssi, binance |
book_delta | Thay đổi sổ lệnh | symbol, time_ns, bids, asks, first_update_id, last_update_id | binance |
index_tick | Giá trị chỉ số | index, time_ns, value | dnse, tcbs, ssi |
index_estimate | Chỉ số dự kiến ở phiên định kỳ | index, time_ns, value | dnse, ssi |
foreign_flow | Khối ngoại mua, bán cộng dồn | symbol, time_ns, buy_volume, sell_volume | dnse, tcbs, ssi |
bar | Nến | symbol, interval, time_ns, open, high, low, close, volume, final, origin | dnse, ssi, binance; nến pipeline dựng cho mọi nguồn |
stats | Thống kê chạy theo cửa sổ | symbol, window, time_ns | tcbs, ssi, binance |
price_limits | Tham chiếu, trần, sàn, trạng thái giao dịch | symbol, time_ns, reference | dnse, tcbs, ssi, binance |
auction | Giá khớp dự kiến | symbol, time_ns, price | dnse, ssi |
put_through_offer | Chào mua, bán thoả thuận | symbol, side, time_ns, price, volume | tcbs |
flow | Mua, bán chủ động theo khung | symbol, interval, time_ns | tcbs |
status | Chuyển phiên, trạng thái của mã | market, time_ns, state | dnse, ssi |
index_contribution | Mức đóng góp của một mã vào chỉ số | index, symbol, time_ns, influence | dnse |
Loại nào cũng có thêm ba cột lõi: type (tên loại), source (nguồn) và seq (số thứ tự thông điệp trong phiên).
Bảng kênh ra loại sự kiện của từng nguồn có ở Dữ liệu trong phiên.
Ba tầng cột
| Tầng | Ví dụ ở trade | Quy tắc |
|---|---|---|
| Lõi | price, volume, time_ns | Luôn có giá trị, cùng nghĩa với mọi nguồn |
| Chung | side, cum_volume, cum_value, session, day_high, day_low, feed, trade_id, replay, recv_ns | Cùng nghĩa, cùng đơn vị chuẩn với mọi nguồn. Để trống (null) khi nguồn không gửi |
| Chi tiết | dnse_isin, ssi_ref_price, tcbs_color, binance_buyer_is_maker | Trường riêng của một nguồn, giữ nguyên đơn vị và nghĩa gốc. Tên cột là <nguồn>_<khoá> |
Tầng chi tiết giữ những thứ chỉ một nguồn có, như mã ISIN, mã trạng thái gốc, cờ cho biết bên mua là bên chờ khớp (maker), giờ nhận gói tin phía nguồn, để bạn không mất thông tin khi chuẩn hoá. Một bộ dữ liệu có đủ cột chi tiết của mọi nguồn; dòng của nguồn khác để trống. Vì vậy mỗi bộ dữ liệu chỉ có một bộ cột cho mọi nguồn, và mọi tệp của nó có cùng cấu trúc Arrow.
Số cột chi tiết ở bản này:
| Loại | dnse | tcbs | ssi | binance |
|---|---|---|---|---|
trade | 4 | 15 | 14 | 4 |
quote | 3 | 3 | ||
index_tick | 8 | 1 | 8 | |
foreign_flow | 8 | 3 | ||
bar | 2 | 1 | 7 | |
stats | 7 | 12 | ||
price_limits | 11 | 1 | ||
status | 4 | 3 | ||
flow | 1 |
Ý nghĩa và trường gốc của từng cột chi tiết tra bằng canonical.detail_spec:
from vnstock_pipeline import canonical
canonical.detail_spec("<nguồn>", "trade", "<kênh gốc>")[:3]
# mỗi dòng: [cột chi tiết, trường gốc của nguồn, kiểu, đơn vị]Đơn vị và giờ
| Trường | Đơn vị chuẩn |
|---|---|
| Giá cổ phiếu, chứng quyền | Nghìn đồng |
| Giá trị chỉ số, giá phái sinh | Điểm |
| Khối lượng | Cổ phiếu; phái sinh: hợp đồng |
Giá trị (cum_value, value) | Đồng. Nến hợp đồng tương lai VN30, VN100: 100.000 đồng mỗi điểm; phái sinh khác: để trống |
binance | Giá và giá trị theo tài sản định giá (ví dụ USDT), khối lượng theo tài sản gốc |
time_ns | Giờ của sự kiện, nano giây kể từ 1970-01-01 UTC. Nguồn chỉ có giờ nhận thì bằng recv_ns |
recv_ns | Giờ máy bạn nhận thông điệp |
Pipeline quy đổi theo đơn vị gốc của từng nguồn để ra đơn vị chuẩn. Ví dụ, khối lượng lô chẵn của dnse tính theo lô
10 cổ phiếu, còn giá cổ phiếu của tcbs, ssi tính bằng đồng. Cột chi tiết thì giữ đơn vị gốc, đơn vị ghi trong
detail_spec.
Giá trị dùng chung
| Cột | Giá trị |
|---|---|
board | main (lô chẵn), odd_lot (lô lẻ), put_through (thoả thuận), other |
side | buy, sell (bên chủ động); null khi nguồn không gửi |
trading_status | normal, halted, suspended, delisted, special, other; mã gốc của nguồn ở cột chi tiết |
bar.interval | tick, 1s, 1m, 3m, 5m, 15m, 30m, 1H, 2H, 4H, 6H, 8H, 12H, 1D, 3D, 1W, 1M |
bar.origin | source (nến nguồn phát), trades (nến pipeline dựng từ khớp lệnh) |
bar.final | true khi nến đã đóng |
stats.window | session, 5m, 1h, 4h, 1d, 24h |
trade.feed | Kênh gốc của lệnh, ví dụ tick, tick_extra, match, history_1m, match_history, trade, agg_trade |
trade.replay | true khi nguồn gửi lại lệnh cũ: lúc vừa đăng ký, lệnh cũ hơn 60 giây lúc nhận, hoặc thông điệp khớp lặp lại mà tổng cộng dồn không tăng |
Chọn cột lưu
Mặc định thư mục lưu trữ giữ đủ ba tầng. Muốn gọn hơn, chọn bộ cột trong pipeline.toml hoặc trong mã:
| Bộ cột | Giữ |
|---|---|
FieldSet.default() | Lõi, chung và mọi cột chi tiết |
FieldSet.common() | Lõi và chung, giống nhau cho mọi nguồn |
FieldSet.core_only() | Chỉ lõi |
FieldSet.filled_by("<nguồn 1>", "<nguồn 2>", detail=True) | Chỉ những cột mà các nguồn đã chọn có điền, nên không có cột luôn trống |
from vnstock_pipeline import Session, Store, canonical
fields = canonical.FieldSet.filled_by("<nguồn>").with_("trade", "<cột chi tiết>").without("quote", "board_code")
Session(Store(), "<nguồn>", ["<kênh>"], ["<mã>"], fields=fields).run(seconds=300)
fields.columns("trade") # thứ tự cột của bảng: lõi, chung đã bật, chi tiết đã bậtTrong pipeline.toml, liệt kê cột chung và cột chi tiết muốn giữ cho từng loại. Loại không ghi thì chỉ giữ cột lõi:
[stream.fields]
trade = ["side", "cum_volume", "session", "feed", "replay", "dnse_isin"]
quote = ["total_bid_volume", "total_ask_volume"]
bar = ["value", "volume_basis"]Tên cột sai hoặc loại sự kiện không có thì pipeline báo lỗi ngay khi mở phiên, không bỏ qua lặng lẽ.
Hợp đồng dữ liệu
Định nghĩa đầy đủ của 14 loại sự kiện nằm trong thư viện, ở dạng JSON Schema:
from vnstock_pipeline import canonical
canonical.EVENT_VERSION # 3
canonical.types() # 14 loại
canonical.core_fields("trade") # cột lõi
canonical.optional_fields("trade") # cột chung
canonical.detail_columns("trade") # cột chi tiết của mọi nguồn
canonical.dtypes("trade", ["time_ns", "price", "replay"]) # kiểu cột cố định: Int64, float64, boolean
canonical.validate(event) # kiểm một sự kiện theo hợp đồngMỗi tệp stream ghi event_version vào metadata, còn _catalog/contract.json ghi phiên bản của cả thư mục. Tệp ghi bằng
phiên bản cũ vẫn đọc được; cột không có ở phiên bản cũ là null khi gộp.