Custom Data
NautilusTrader รองรับ custom data ที่เขียนด้วย Rust โดยใช้ pipeline ด้าน runtime routing, persistence และ query เดียวกับข้อมูล built-in
เอกสารนี้อธิบายว่า custom data:
- ถูกลงทะเบียนตอน runtime อย่างไร
- ถูก serialize ไปและกลับจาก Arrow/Parquet อย่างไร
- ถูก route ผ่าน actor และ strategy อย่างไร
เป้าหมาย
สถาปัตยกรรมของ custom data ตอบโจทย์ข้อกำหนดต่อไปนี้:
- ให้ custom data ที่นิยามใน Rust ใช้ JSON และ Arrow handler แบบ native ของ Rust ได้
- รองรับ persistence ใน
ParquetDataCatalogโดยใช้การลงทะเบียน type แบบ dynamic แทน schema ที่ hardcode ไว้ - ทำให้ custom data route ผ่าน flow การ subscribe ปกติของ data engine, actor และ strategy ได้
ภาพรวมระดับสูง
| Mode | รูปแบบการเขียน | เส้นทางการลงทะเบียน | เส้นทาง encode/decode | Wrapper backend |
|---|---|---|---|---|
| Same-binary Rust | type ที่ใช้ #[custom_data] | ensure_custom_data_registered::<T>() | Native Rust | Native Rust payload |
custom data ใช้ wrapper CustomData ชั้นนอกตัวเดียวกันและโมเดล identity ของ DataType แบบเดียวกัน
Component หลัก
Registry module
crates/model/src/data/registry.rs เก็บ registry ระดับ process สำหรับ JSON และ Arrow
การลงทะเบียนใช้ operation แบบ atomic ของ DashMap::entry() เพื่อไม่ให้การเรียก register_* และ ensure_*
พร้อมกันเกิด race ขณะจอง entry
module นี้ initialize สถานะของ registry ผ่าน OnceLock และเก็บ:
- JSON deserializer โดยใช้
type_nameเป็น key - Arrow schema, encoder และ decoder โดยใช้
type_nameเป็น key
แทนที่จะ hardcode แต่ละ type ไว้ใน binary หลัก NautilusTrader จะ resolve handler ตอน runtime โดยใช้
type_name ที่เก็บไว้ใน DataType และ Parquet metadata
CustomData
wrapper CustomData ชั้นนอกเป็น container กลางที่ห่อ custom data ทุกชนิด
โดยรับ DataType เป็นอันดับแรก แล้วตามด้วย payload ภายใน
ประกอบด้วย:
DataType- custom payload ภายในที่ implement
CustomDataTrait(ห่อไว้ในArc<dyn CustomDataTrait>)
timestamp (ts_event, ts_init) ถูก delegate ไปยัง implementation ของ
CustomDataTrait ภายใน และเปิดให้เข้าถึงผ่าน wrapper
implementation ของ PartialEq ใน Rust จะเปรียบเทียบ DataType และ delegate การเปรียบเทียบ payload
ไปยังค่าภายใน
JSON envelope ของ CustomData
เมื่อ serialize เป็น JSON เช่นสำหรับ to_json_bytes / from_json_bytes, SQL cache หรือ Redis
CustomData จะใช้ envelope มาตรฐานรูปแบบเดียว การ deserialize จึงไม่ขึ้นกับชื่อฟิลด์ของ payload ของผู้ใช้:
type: ชื่อ custom type (จากCustomDataTrait::type_name)data_type: object ที่มีtype_name,metadataและidentifier(optional)payload: เฉพาะ payload ภายใน (ผลลัพธ์ของCustomDataTrait::to_jsonที่ parse เป็นค่าแล้ว) deserializer ที่ลงทะเบียนไว้จะส่งเฉพาะค่านี้ไปยังfrom_jsonดังนั้น struct ของผู้ใช้จึงใช้ชื่อฟิลด์ใดก็ได้ รวมถึงvalueโดยไม่ชนกับ metadata ของ wrapper
envelope นี้สร้างโดยการ serialize CustomData ใน Rust และถูกใช้โดย
registry module ตอน deserialize custom data จาก JSON
DataType
DataType ระบุตัวตนของ custom data สำหรับการ route และ persistence
ประกอบด้วย:
type_namemetadata(optional)identifier(optional) สำหรับ path ของ persistence และการค้นหาใน cache database ไม่มีผลต่อการ route, equality หรือ hashing
Equality, hashing และการ route topic คำนวณจาก type_name และ metadata เท่านั้น ค่า DataType
สองค่าที่มี type name และ metadata เดียวกันแต่ identifier ต่างกันจะถือว่าเท่ากันและ publish ไปยัง
topic เดียวกันบน message bus
identifier ใช้เลือก path ใน catalog ภายใต้ data/custom/<type_name>/<identifier...> และใช้ในการกรองของ
PostgreSQL และ Redis
persistence จะเก็บ DataType ทั้งหมดไว้กับค่า CustomData แต่ละค่าและกู้คืนเมื่อ query ส่วนการค้นหา
handler ใช้ type_name ดังนั้น type เชิงตรรกะเดียวกันจึงมี metadata หรือ identifier ต่างกันได้ และยัง
decode ผ่าน handler ที่ลงทะเบียนไว้ตัวเดียวกัน
สถาปัตยกรรมการลงทะเบียน
การลงทะเบียน Rust แบบ same-binary
สำหรับ Rust type ที่ compile อยู่ใน process:
#[custom_data]สร้าง implementation ของ trait และ JSON รวมถึง implementation ของ Arrow โดย defaultensure_custom_data_registered::<T>()ใส่ handler schema/encoder/decoder แบบ native ลงใน registry ระดับ process
เส้นทางนี้เป็น native Rust ทั้งหมดสำหรับ encode/decode
ลำดับความสำคัญของการลงทะเบียน
การลงทะเบียนแบบ idempotent ของ ensure_* จะไม่เขียนทับ handler ที่มีอยู่ สำหรับแต่ละ type name การลงทะเบียน
Arrow ครั้งแรกจะคง schema, encoder และ decoder ของตนไว้
Wrapper backend
Native same-binary Rust payload
สำหรับ Rust type ที่ compile อยู่ใน process payload ภายในคือ Rust type ตัวจริง
และสามารถ downcast ได้โดยตรงจาก Arc<dyn CustomDataTrait>
สถาปัตยกรรม persistence
ทำไมต้องลงทะเบียน Arrow แบบ dynamic
data type แบบ built-in ของ NautilusTrader มี schema และ encoder ที่ Rust binary รู้จักแบบ static แต่ custom data
ไม่เป็นเช่นนั้น persistence layer จึง resolve custom data แบบ dynamic โดยใช้ type_name ที่ลงทะเบียนไว้
Flow การเขียน catalog
ParquetDataCatalog คาดหวังให้การเขียน custom data เข้ามาเป็นค่า CustomData
เส้นทางการเขียน custom data:
- นำ
type_nameจาก payload ภายใน และmetadataกับidentifierจากDataTypeของค่าแรก - ตรวจสอบว่า Arrow schema ที่ลงทะเบียนไว้มี
ts_initและฟิลด์ts_eventหรือts_initใช้timestamp("ns", tz="UTC") - ค้นหา Arrow encoder ใน registry ระดับ process
- encode ค่าต่าง ๆ เป็น
RecordBatch - เพิ่มคอลัมน์
data_typeที่มีDataTypeที่ persist ไว้ - แนบ
type_nameและ metadata ไปกับ Arrow schema - เขียน batch ลง Parquet ภายใต้ path ของ custom data
layout ของ path คือ data/custom/<type_name>/<identifier...>
identifier จะถูก normalize ก่อนกลายเป็นส่วนหนึ่งของ path
Flow การอ่าน catalog
เมื่อ query:
- catalog อ่านไฟล์ Parquet ที่ตรงกัน
- ดึง
type_nameจาก schema metadata - ขอ decoder จาก registry ระดับ process
- decode
RecordBatchเป็นVec<Data> - สร้าง
CustomDataขึ้นใหม่ด้วยDataTypeเดิม
ทำให้การ resolve ตอน query custom data สมมาตรกับการลงทะเบียนตอนเขียน
ระหว่างการแปลง Feather เป็น Parquet (เช่นหลัง backtest) branch ของ custom data จะแปลง Arrow batch และเขียนผลลัพธ์ไปยัง path ของ custom data ที่ตรงกันโดยตรง:
- ส่ง data class เป็น
custom/{TypeName}โดยใช้ type name ที่ลงทะเบียนไว้ตามตัวอักษร session ของ Feather เก็บ custom data ไว้ใต้data/custom/{TypeName}ไม่ใช่ใต้ไดเรกทอรีแบบ snake_case - ตั้ง
promote_on_close=Falseเมื่อต้องการแปลงเอง ค่า default คือ promote ตอนปิด การแปลง session ที่ promote ไปแล้วจะเขียนช่วงts_initเดิมซ้ำภายใต้ชื่อไฟล์อื่น ซึ่ง catalog จะปฏิเสธเพราะช่วงเวลาไม่ disjoint กัน
การอ่านใช้เฉพาะ data/custom/{TypeName} เท่านั้น catalog ที่ยังใช้ layout เดิม data/custom_<snake_case>
ที่เขียนโดยฝั่ง Python (เช่น data/custom_binance_bar) ให้แปลงด้วย
nautilus catalog migrate-parquet
การสร้างข้อมูลขึ้นใหม่ตอน query
เมื่อโหลด custom data กลับจาก catalog Rust type แบบ same-binary จะ decode เป็นค่า Rust แบบ native โดยตรง
การ integrate กับ runtime
custom data มีส่วนร่วมใน runtime routing ของ NautilusTrader ด้วย
integration ที่เกี่ยวข้องได้แก่:
crates/data/src/engine/dispatch.rspublishCustomDataผ่าน message buscrates/common/src/msgbus/switchboard.rsสร้าง custom topic จากDataTypecrates/common/src/actor/*route custom data ไปยัง subscription ของ actorcrates/backtest/src/engine.rsถือว่าData::Customเป็น input ที่ data engine ส่งมอบ ไม่ใช่ข้อมูลที่ route ผ่าน exchange
custom type ที่ลงทะเบียนแล้วสามารถ persist, query, subscribe และใช้งานได้ ผ่าน runtime interface เดียวกับกลุ่มข้อมูล built-in
การ integrate กับ cache database
implementation ของ cache database แบบ PostgreSQL และ Redis รองรับ CustomData
- PostgreSQL เก็บ custom data ไว้ในตาราง
custom - record ที่เก็บประกอบด้วย
data_type,metadata,identifierและ JSON payload ทั้งหมด - การอ่านจะสร้าง
CustomDataขึ้นใหม่ด้วยCustomData::from_json_bytes(...) - Redis cache เก็บ custom data ภายใต้ key
custom:<ts_init_020>:<uuid>โดยมี JSON ของCustomDataทั้งหมดเป็นค่า add_custom_dataและload_custom_dataของ Redis กรองตามDataType(type_name, metadata, identifier) และ return ผลลัพธ์เรียงตามts_init
แปลจาก เอกสาร NautilusTrader © Nautech Systems Pty Ltd และผู้ร่วมพัฒนา เผยแพร่ภายใต้ LGPL-3.0 ฉบับแปลนี้ตัดเนื้อหาเฉพาะ Python ออกและเน้น Rust