nautilus_serialization/arrow/display/
order_filled.rs

1// -------------------------------------------------------------------------------------------------
2//  Copyright (C) 2015-2026 Nautech Systems Pty Ltd. All rights reserved.
3//  https://nautechsystems.io
4//
5//  Licensed under the GNU Lesser General Public License Version 3.0 (the "License");
6//  You may not use this file except in compliance with the License.
7//  You may obtain a copy of the License at https://www.gnu.org/licenses/lgpl-3.0.en.html
8//
9//  Unless required by applicable law or agreed to in writing, software
10//  distributed under the License is distributed on an "AS IS" BASIS,
11//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12//  See the License for the specific language governing permissions and
13//  limitations under the License.
14// -------------------------------------------------------------------------------------------------
15
16//! Display-mode Arrow encoder for [`OrderFilled`].
17
18use std::sync::Arc;
19
20use arrow::{
21    array::{BooleanBuilder, Float64Builder, StringBuilder, TimestampNanosecondBuilder},
22    datatypes::Schema,
23    error::ArrowError,
24    record_batch::RecordBatch,
25};
26use nautilus_model::events::OrderFilled;
27
28use super::{
29    bool_field, float64_field, price_to_f64, quantity_to_f64, timestamp_field, unix_nanos_to_i64,
30    utf8_field,
31};
32
33/// Returns the display-mode Arrow schema for [`OrderFilled`].
34#[must_use]
35pub fn order_filled_schema() -> Schema {
36    Schema::new(vec![
37        utf8_field("trader_id", false),
38        utf8_field("strategy_id", false),
39        utf8_field("instrument_id", false),
40        utf8_field("client_order_id", false),
41        utf8_field("venue_order_id", false),
42        utf8_field("account_id", false),
43        utf8_field("trade_id", false),
44        utf8_field("order_side", false),
45        utf8_field("order_type", false),
46        float64_field("last_qty", false),
47        float64_field("last_px", false),
48        utf8_field("currency", false),
49        utf8_field("liquidity_side", false),
50        utf8_field("event_id", false),
51        timestamp_field("ts_event", false),
52        timestamp_field("ts_init", false),
53        bool_field("reconciliation", false),
54        utf8_field("position_id", true),
55        utf8_field("commission", true),
56    ])
57}
58
59/// Encodes order fills as a display-friendly Arrow [`RecordBatch`].
60///
61/// Emits `Float64` columns for `last_qty` and `last_px`, `Timestamp(Nanosecond)`
62/// columns for event and init times, and `Utf8` columns for identifiers and enums.
63/// Commission renders as its `Display` representation (e.g. `"100.50 USD"`).
64/// Mixed-instrument batches are supported.
65///
66/// Returns an empty [`RecordBatch`] with the correct schema when `data` is empty.
67///
68/// # Errors
69///
70/// Returns an [`ArrowError`] if the Arrow `RecordBatch` cannot be constructed.
71pub fn encode_order_fills(data: &[OrderFilled]) -> Result<RecordBatch, ArrowError> {
72    let mut trader_id = StringBuilder::new();
73    let mut strategy_id = StringBuilder::new();
74    let mut instrument_id = StringBuilder::new();
75    let mut client_order_id = StringBuilder::new();
76    let mut venue_order_id = StringBuilder::new();
77    let mut account_id = StringBuilder::new();
78    let mut trade_id = StringBuilder::new();
79    let mut order_side = StringBuilder::new();
80    let mut order_type = StringBuilder::new();
81    let mut last_qty = Float64Builder::with_capacity(data.len());
82    let mut last_px = Float64Builder::with_capacity(data.len());
83    let mut currency = StringBuilder::new();
84    let mut liquidity_side = StringBuilder::new();
85    let mut event_id = StringBuilder::new();
86    let mut ts_event = TimestampNanosecondBuilder::with_capacity(data.len());
87    let mut ts_init = TimestampNanosecondBuilder::with_capacity(data.len());
88    let mut reconciliation = BooleanBuilder::with_capacity(data.len());
89    let mut position_id = StringBuilder::new();
90    let mut commission = StringBuilder::new();
91
92    for fill in data {
93        trader_id.append_value(fill.trader_id);
94        strategy_id.append_value(fill.strategy_id);
95        instrument_id.append_value(fill.instrument_id.to_string());
96        client_order_id.append_value(fill.client_order_id);
97        venue_order_id.append_value(fill.venue_order_id);
98        account_id.append_value(fill.account_id);
99        trade_id.append_value(fill.trade_id.to_string());
100        order_side.append_value(format!("{}", fill.order_side));
101        order_type.append_value(format!("{}", fill.order_type));
102        last_qty.append_value(quantity_to_f64(&fill.last_qty));
103        last_px.append_value(price_to_f64(&fill.last_px));
104        currency.append_value(fill.currency.to_string());
105        liquidity_side.append_value(format!("{}", fill.liquidity_side));
106        event_id.append_value(fill.event_id.to_string());
107        ts_event.append_value(unix_nanos_to_i64(fill.ts_event.as_u64()));
108        ts_init.append_value(unix_nanos_to_i64(fill.ts_init.as_u64()));
109        reconciliation.append_value(fill.reconciliation);
110        position_id.append_option(fill.position_id.map(|v| v.to_string()));
111        commission.append_option(fill.commission.map(|v| format!("{v}")));
112    }
113
114    RecordBatch::try_new(
115        Arc::new(order_filled_schema()),
116        vec![
117            Arc::new(trader_id.finish()),
118            Arc::new(strategy_id.finish()),
119            Arc::new(instrument_id.finish()),
120            Arc::new(client_order_id.finish()),
121            Arc::new(venue_order_id.finish()),
122            Arc::new(account_id.finish()),
123            Arc::new(trade_id.finish()),
124            Arc::new(order_side.finish()),
125            Arc::new(order_type.finish()),
126            Arc::new(last_qty.finish()),
127            Arc::new(last_px.finish()),
128            Arc::new(currency.finish()),
129            Arc::new(liquidity_side.finish()),
130            Arc::new(event_id.finish()),
131            Arc::new(ts_event.finish()),
132            Arc::new(ts_init.finish()),
133            Arc::new(reconciliation.finish()),
134            Arc::new(position_id.finish()),
135            Arc::new(commission.finish()),
136        ],
137    )
138}
139
140#[cfg(test)]
141mod tests {
142    use arrow::{
143        array::{Array, BooleanArray, Float64Array, StringArray, TimestampNanosecondArray},
144        datatypes::{DataType, TimeUnit},
145    };
146    use nautilus_model::{
147        enums::{LiquiditySide, OrderType},
148        events::order::spec::OrderFilledSpec,
149        identifiers::{ClientOrderId, InstrumentId, PositionId, TradeId, VenueOrderId},
150        types::{Currency, Money, Price, Quantity},
151    };
152    use rstest::rstest;
153
154    use super::*;
155
156    fn make_fill(instrument_id: &str, commission: Option<Money>, ts: u64) -> OrderFilled {
157        OrderFilledSpec::builder()
158            .instrument_id(InstrumentId::from(instrument_id))
159            .client_order_id(ClientOrderId::from("O-001"))
160            .venue_order_id(VenueOrderId::from("V-001"))
161            .trade_id(TradeId::new("T-001"))
162            .order_type(OrderType::Limit)
163            .last_qty(Quantity::from(100))
164            .last_px(Price::from("50.25"))
165            .liquidity_side(LiquiditySide::Maker)
166            .ts_event(ts.into())
167            .ts_init((ts + 1).into())
168            .position_id(PositionId::from("P-001"))
169            .maybe_commission(commission)
170            .build()
171    }
172
173    #[rstest]
174    fn test_encode_order_fills_schema() {
175        let batch = encode_order_fills(&[]).unwrap();
176        let schema = batch.schema();
177        let fields = schema.fields();
178        assert_eq!(fields.len(), 19);
179        assert_eq!(fields[0].name(), "trader_id");
180        assert_eq!(fields[0].data_type(), &DataType::Utf8);
181        assert_eq!(fields[9].name(), "last_qty");
182        assert_eq!(fields[9].data_type(), &DataType::Float64);
183        assert_eq!(fields[10].name(), "last_px");
184        assert_eq!(fields[10].data_type(), &DataType::Float64);
185        assert_eq!(fields[14].name(), "ts_event");
186        assert_eq!(
187            fields[14].data_type(),
188            &DataType::Timestamp(TimeUnit::Nanosecond, None)
189        );
190        assert_eq!(fields[16].name(), "reconciliation");
191        assert_eq!(fields[16].data_type(), &DataType::Boolean);
192        assert_eq!(fields[18].name(), "commission");
193        assert!(fields[18].is_nullable());
194    }
195
196    #[rstest]
197    fn test_encode_order_fills_values() {
198        let commission = Money::new(10.50, Currency::USD());
199        let fills = vec![make_fill("AAPL.XNAS", Some(commission), 1_000)];
200        let batch = encode_order_fills(&fills).unwrap();
201
202        assert_eq!(batch.num_rows(), 1);
203
204        let last_qty_col = batch
205            .column(9)
206            .as_any()
207            .downcast_ref::<Float64Array>()
208            .unwrap();
209        let last_px_col = batch
210            .column(10)
211            .as_any()
212            .downcast_ref::<Float64Array>()
213            .unwrap();
214        let ts_event_col = batch
215            .column(14)
216            .as_any()
217            .downcast_ref::<TimestampNanosecondArray>()
218            .unwrap();
219        let reconciliation_col = batch
220            .column(16)
221            .as_any()
222            .downcast_ref::<BooleanArray>()
223            .unwrap();
224        let commission_col = batch
225            .column(18)
226            .as_any()
227            .downcast_ref::<StringArray>()
228            .unwrap();
229
230        assert!((last_qty_col.value(0) - 100.0).abs() < 1e-9);
231        assert!((last_px_col.value(0) - 50.25).abs() < 1e-9);
232        assert_eq!(ts_event_col.value(0), 1_000);
233        assert!(!reconciliation_col.value(0));
234        assert_eq!(commission_col.value(0), "10.50 USD");
235    }
236
237    #[rstest]
238    fn test_encode_order_fills_null_commission() {
239        let fills = vec![make_fill("AAPL.XNAS", None, 1_000)];
240        let batch = encode_order_fills(&fills).unwrap();
241
242        let commission_col = batch
243            .column(18)
244            .as_any()
245            .downcast_ref::<StringArray>()
246            .unwrap();
247        assert!(commission_col.is_null(0));
248    }
249
250    #[rstest]
251    fn test_encode_order_fills_empty() {
252        let batch = encode_order_fills(&[]).unwrap();
253        assert_eq!(batch.num_rows(), 0);
254        assert_eq!(batch.schema().fields().len(), 19);
255    }
256
257    #[rstest]
258    fn test_encode_order_fills_mixed_instruments() {
259        let fills = vec![
260            make_fill("AAPL.XNAS", None, 1),
261            make_fill("MSFT.XNAS", None, 2),
262        ];
263        let batch = encode_order_fills(&fills).unwrap();
264
265        let instrument_id_col = batch
266            .column(2)
267            .as_any()
268            .downcast_ref::<StringArray>()
269            .unwrap();
270        assert_eq!(instrument_id_col.value(0), "AAPL.XNAS");
271        assert_eq!(instrument_id_col.value(1), "MSFT.XNAS");
272    }
273}
nautilus_serialization/arrow/display/order_filled.rs

nautilus_serialization/arrow/display/
order_filled.rs
