Skip to main content

nautilus_serialization/arrow/
trade.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
16use std::{collections::HashMap, str::FromStr, sync::Arc};
17
18use arrow::{
19    array::{Decimal128Array, StringArray, StringBuilder, StringViewArray, UInt64Array},
20    datatypes::{DataType, Field, Schema},
21    error::ArrowError,
22    record_batch::RecordBatch,
23};
24#[cfg(test)]
25use nautilus_model::identifiers::InstrumentId;
26use nautilus_model::{data::TradeTick, enums::AggressorSide, identifiers::TradeId};
27
28use super::{
29    DecodeDataFromRecordBatch, EncodingError, KEY_IDENTIFIER, decode_required_decimal_price,
30    decode_required_decimal_quantity, decode_required_timestamp, enum_dictionary_array,
31    enum_dictionary_data_type, extract_column, extract_column_string, fixed_decimal_data_type,
32    identifier_array_from_display, metadata_with_type_name, parse_metadata,
33    required_price_decimal_array, required_quantity_decimal_array, validate_required_column,
34};
35#[cfg(test)]
36use super::{KEY_INSTRUMENT_ID, KEY_PRICE_PRECISION};
37use crate::arrow::{ArrowSchemaProvider, Data, DecodeFromRecordBatch, EncodeToRecordBatch};
38
39impl ArrowSchemaProvider for TradeTick {
40    fn get_schema(metadata: Option<HashMap<String, String>>) -> Schema {
41        let fields = vec![
42            Field::new("price", fixed_decimal_data_type(), false),
43            Field::new("size", fixed_decimal_data_type(), false),
44            Field::new("aggressor_side", enum_dictionary_data_type(), false),
45            Field::new("trade_id", DataType::Utf8, false),
46            Field::new("ts_event", crate::arrow::timestamp_data_type(), false),
47            Field::new("ts_init", crate::arrow::timestamp_data_type(), false),
48            Field::new(KEY_IDENTIFIER, DataType::Utf8, true),
49        ];
50
51        Schema::new_with_metadata(fields, metadata_with_type_name("TradeTick", metadata))
52    }
53}
54
55impl EncodeToRecordBatch for TradeTick {
56    fn encode_batch<T>(
57        metadata: &HashMap<String, String>,
58        data: &[T],
59    ) -> Result<RecordBatch, ArrowError>
60    where
61        T: std::borrow::Borrow<Self>,
62    {
63        let mut trade_id_builder = StringBuilder::new();
64        let mut ts_event_builder = UInt64Array::builder(data.len());
65        let mut ts_init_builder = UInt64Array::builder(data.len());
66
67        for tick in data.iter().map(std::borrow::Borrow::borrow) {
68            trade_id_builder.append_value(tick.trade_id.to_string());
69            ts_event_builder.append_value(tick.ts_event.as_u64());
70            ts_init_builder.append_value(tick.ts_init.as_u64());
71        }
72
73        let price_array = Arc::new(required_price_decimal_array(
74            data.iter()
75                .map(std::borrow::Borrow::borrow)
76                .map(|tick| tick.price.raw()),
77            "price",
78        )?);
79        let size_array = Arc::new(required_quantity_decimal_array(
80            data.iter()
81                .map(std::borrow::Borrow::borrow)
82                .map(|tick| tick.size.raw()),
83            "size",
84        )?);
85        let aggressor_side_array = Arc::new(enum_dictionary_array(
86            data.iter()
87                .map(std::borrow::Borrow::borrow)
88                .map(|tick| tick.aggressor_side),
89        )?);
90        let trade_id_array = Arc::new(trade_id_builder.finish());
91        let ts_event_array = Arc::new(ts_event_builder.finish());
92        let ts_init_array = Arc::new(ts_init_builder.finish());
93
94        crate::arrow::record_batch_with_timestamps(
95            Self::get_schema(Some(metadata.clone())).into(),
96            vec![
97                price_array,
98                size_array,
99                aggressor_side_array,
100                trade_id_array,
101                ts_event_array,
102                ts_init_array,
103                Arc::new(identifier_array_from_display(
104                    data.iter()
105                        .map(std::borrow::Borrow::borrow)
106                        .map(|tick| tick.instrument_id),
107                )),
108            ],
109        )
110    }
111
112    fn metadata(&self) -> HashMap<String, String> {
113        Self::get_metadata(
114            &self.instrument_id,
115            self.price.precision,
116            self.size.precision,
117        )
118    }
119}
120
121impl DecodeFromRecordBatch for TradeTick {
122    fn decode_batch(
123        metadata: &HashMap<String, String>,
124        record_batch: RecordBatch,
125    ) -> Result<Vec<Self>, EncodingError> {
126        let (instrument_id, price_precision, size_precision) = parse_metadata(metadata)?;
127        let record_batch = crate::arrow::record_batch_with_u64_timestamps(&record_batch)?;
128        let record_batch = &record_batch;
129        let cols = record_batch.columns();
130
131        let price_values =
132            extract_column::<Decimal128Array>(cols, "price", 0, fixed_decimal_data_type())?;
133
134        let size_values =
135            extract_column::<Decimal128Array>(cols, "size", 1, fixed_decimal_data_type())?;
136
137        let aggressor_side_values = extract_column_string(cols, "aggressor_side", 2)?;
138        validate_required_column(cols[2].as_ref(), "aggressor_side")?;
139        let ts_event_values = extract_column::<UInt64Array>(cols, "ts_event", 4, DataType::UInt64)?;
140        let ts_init_values = extract_column::<UInt64Array>(cols, "ts_init", 5, DataType::UInt64)?;
141
142        // Datafusion reads trade_ids as StringView
143        let trade_id_values: Vec<TradeId> = if record_batch
144            .schema()
145            .field_with_name("trade_id")?
146            .data_type()
147            == &DataType::Utf8View
148        {
149            extract_column::<StringViewArray>(cols, "trade_id", 3, DataType::Utf8View)?
150                .iter()
151                .enumerate()
152                .map(|(i, id)| {
153                    let id = id.ok_or_else(|| {
154                        EncodingError::ParseError("trade_id", format!("NULL value at row {i}"))
155                    })?;
156
157                    TradeId::new_checked(id)
158                        .map_err(|e| EncodingError::ParseError("trade_id", format!("row {i}: {e}")))
159                })
160                .collect::<Result<Vec<_>, _>>()?
161        } else {
162            extract_column::<StringArray>(cols, "trade_id", 3, DataType::Utf8)?
163                .iter()
164                .enumerate()
165                .map(|(i, id)| {
166                    let id = id.ok_or_else(|| {
167                        EncodingError::ParseError("trade_id", format!("NULL value at row {i}"))
168                    })?;
169
170                    TradeId::new_checked(id)
171                        .map_err(|e| EncodingError::ParseError("trade_id", format!("row {i}: {e}")))
172                })
173                .collect::<Result<Vec<_>, _>>()?
174        };
175
176        let result: Result<Vec<Self>, EncodingError> = (0..record_batch.num_rows())
177            .map(|i| {
178                let price =
179                    decode_required_decimal_price(price_values, price_precision, "price", i)?;
180                let size =
181                    decode_required_decimal_quantity(size_values, size_precision, "size", i)?;
182                let aggressor_side_value = aggressor_side_values.value(i);
183                let aggressor_side =
184                    AggressorSide::from_str(aggressor_side_value).map_err(|e| {
185                        EncodingError::ParseError(stringify!(AggressorSide), e.to_string())
186                    })?;
187                let trade_id = trade_id_values[i];
188                let ts_event = decode_required_timestamp(ts_event_values, "ts_event", i)?;
189                let ts_init = decode_required_timestamp(ts_init_values, "ts_init", i)?;
190
191                Ok(Self {
192                    instrument_id,
193                    price,
194                    size,
195                    aggressor_side,
196                    trade_id,
197                    ts_event,
198                    ts_init,
199                })
200            })
201            .collect();
202
203        result
204    }
205}
206
207impl DecodeDataFromRecordBatch for TradeTick {
208    fn decode_data_batch(
209        metadata: &HashMap<String, String>,
210        record_batch: RecordBatch,
211    ) -> Result<Vec<Data>, EncodingError> {
212        let ticks: Vec<Self> = Self::decode_batch(metadata, record_batch)?;
213        Ok(ticks.into_iter().map(Data::from).collect())
214    }
215}
216
217#[cfg(test)]
218mod tests {
219    use std::sync::Arc;
220
221    use arrow::array::{Array, Decimal128Array, TimestampNanosecondArray, UInt64Array};
222    use nautilus_model::{
223        data::stubs::stub_trade_ethusdt_buy,
224        types::{Price, Quantity, fixed::FIXED_SCALAR, price::PriceRaw, quantity::QuantityRaw},
225    };
226    use rstest::rstest;
227
228    use super::*;
229    use crate::arrow::{KEY_TYPE_NAME, get_raw_price, get_raw_quantity};
230
231    #[rstest]
232    fn test_get_schema() {
233        let instrument_id = InstrumentId::from("AAPL.XNAS");
234        let metadata = TradeTick::get_metadata(&instrument_id, 2, 0);
235        let schema = TradeTick::get_schema(Some(metadata.clone()));
236
237        let mut expected_fields = Vec::with_capacity(7);
238
239        expected_fields.push(Field::new("price", fixed_decimal_data_type(), false));
240
241        expected_fields.extend(vec![
242            Field::new("size", fixed_decimal_data_type(), false),
243            Field::new("aggressor_side", enum_dictionary_data_type(), false),
244            Field::new("trade_id", DataType::Utf8, false),
245            Field::new("ts_event", crate::arrow::timestamp_data_type(), false),
246            Field::new("ts_init", crate::arrow::timestamp_data_type(), false),
247            Field::new(KEY_IDENTIFIER, DataType::Utf8, true),
248        ]);
249
250        let mut expected_metadata = metadata;
251        expected_metadata.insert(KEY_TYPE_NAME.to_string(), "TradeTick".to_string());
252        let expected_schema = Schema::new_with_metadata(expected_fields, expected_metadata);
253        assert_eq!(schema, expected_schema);
254    }
255
256    #[rstest]
257    fn test_get_schema_map() {
258        let schema_map = TradeTick::get_schema_map();
259        let mut expected_map = HashMap::new();
260
261        let precision_bytes = "Decimal128(38, 16)".to_string();
262        expected_map.insert("price".to_string(), precision_bytes.clone());
263        expected_map.insert("size".to_string(), precision_bytes);
264        expected_map.insert(
265            "aggressor_side".to_string(),
266            "Dictionary(Int8, Utf8)".to_string(),
267        );
268        expected_map.insert("trade_id".to_string(), "Utf8".to_string());
269        expected_map.insert(
270            "ts_event".to_string(),
271            "Timestamp(Nanosecond, Some(\"UTC\"))".to_string(),
272        );
273        expected_map.insert(
274            "ts_init".to_string(),
275            "Timestamp(Nanosecond, Some(\"UTC\"))".to_string(),
276        );
277        expected_map.insert(KEY_IDENTIFIER.to_string(), "Utf8".to_string());
278        assert_eq!(schema_map, expected_map);
279    }
280
281    #[rstest]
282    fn test_encode_trade_tick() {
283        let instrument_id = InstrumentId::from("AAPL.XNAS");
284        let metadata = TradeTick::get_metadata(&instrument_id, 2, 0);
285
286        let tick1 = TradeTick {
287            instrument_id,
288            price: Price::from("100.10"),
289            size: Quantity::from(1000),
290            aggressor_side: AggressorSide::Buy,
291            trade_id: TradeId::new("1"),
292            ts_event: 1.into(),
293            ts_init: 3.into(),
294        };
295
296        let tick2 = TradeTick {
297            instrument_id,
298            price: Price::from("100.50"),
299            size: Quantity::from(500),
300            aggressor_side: AggressorSide::Sell,
301            trade_id: TradeId::new("2"),
302            ts_event: 2.into(),
303            ts_init: 4.into(),
304        };
305
306        let data = vec![tick1, tick2];
307        let record_batch = TradeTick::encode_batch(&metadata, &data).unwrap();
308        let columns = record_batch.columns();
309
310        let price_values = columns[0]
311            .as_any()
312            .downcast_ref::<Decimal128Array>()
313            .unwrap();
314        assert_eq!(
315            get_raw_price(price_values.value(0)),
316            (100.10 * FIXED_SCALAR) as PriceRaw
317        );
318        assert_eq!(
319            get_raw_price(price_values.value(1)),
320            (100.50 * FIXED_SCALAR) as PriceRaw
321        );
322
323        let size_values = columns[1]
324            .as_any()
325            .downcast_ref::<Decimal128Array>()
326            .unwrap();
327        assert_eq!(
328            get_raw_quantity(size_values.value(0)),
329            (1000.0 * FIXED_SCALAR) as QuantityRaw
330        );
331        assert_eq!(
332            get_raw_quantity(size_values.value(1)),
333            (500.0 * FIXED_SCALAR) as QuantityRaw
334        );
335
336        let aggressor_side_values = extract_column_string(columns, "aggressor_side", 2).unwrap();
337        let trade_id_values = columns[3].as_any().downcast_ref::<StringArray>().unwrap();
338        let ts_event_values = columns[4]
339            .as_any()
340            .downcast_ref::<TimestampNanosecondArray>()
341            .unwrap();
342        let ts_init_values = columns[5]
343            .as_any()
344            .downcast_ref::<TimestampNanosecondArray>()
345            .unwrap();
346
347        assert_eq!(columns.len(), 7);
348        assert_eq!(size_values.len(), 2);
349        assert_eq!(
350            get_raw_quantity(size_values.value(0)),
351            (1000.0 * FIXED_SCALAR) as QuantityRaw
352        );
353        assert_eq!(
354            get_raw_quantity(size_values.value(1)),
355            (500.0 * FIXED_SCALAR) as QuantityRaw
356        );
357        assert_eq!(aggressor_side_values.len(), 2);
358        assert_eq!(aggressor_side_values.value(0), "BUY");
359        assert_eq!(aggressor_side_values.value(1), "SELL");
360        assert_eq!(trade_id_values.len(), 2);
361        assert_eq!(trade_id_values.value(0), "1");
362        assert_eq!(trade_id_values.value(1), "2");
363        assert_eq!(ts_event_values.len(), 2);
364        assert_eq!(ts_event_values.value(0), 1);
365        assert_eq!(ts_event_values.value(1), 2);
366        assert_eq!(ts_init_values.len(), 2);
367        assert_eq!(ts_init_values.value(0), 3);
368        assert_eq!(ts_init_values.value(1), 4);
369    }
370
371    #[rstest]
372    fn test_decode_batch() {
373        let instrument_id = InstrumentId::from("AAPL.XNAS");
374        let metadata = TradeTick::get_metadata(&instrument_id, 2, 0);
375
376        let raw_price1 = (100.00 * FIXED_SCALAR) as PriceRaw;
377        let raw_price2 = (101.00 * FIXED_SCALAR) as PriceRaw;
378        let price = crate::arrow::test_support::decimal_array_from_bytes(vec![
379            &raw_price1.to_le_bytes(),
380            &raw_price2.to_le_bytes(),
381        ]);
382
383        let size = crate::arrow::test_support::decimal_array_from_bytes(vec![
384            &((1000.0 * FIXED_SCALAR) as QuantityRaw).to_le_bytes(),
385            &((900.0 * FIXED_SCALAR) as QuantityRaw).to_le_bytes(),
386        ]);
387        let aggressor_side =
388            enum_dictionary_array([AggressorSide::NoAggressor, AggressorSide::Buy]).unwrap();
389        let trade_id = StringArray::from(vec!["1", "2"]);
390        let ts_event = UInt64Array::from(vec![1, 2]);
391        let ts_init = UInt64Array::from(vec![3, 4]);
392
393        let record_batch = crate::arrow::record_batch_with_timestamps(
394            crate::arrow::schema_without_identifier_column(&TradeTick::get_schema(Some(
395                metadata.clone(),
396            )))
397            .into(),
398            vec![
399                Arc::new(price),
400                Arc::new(size),
401                Arc::new(aggressor_side),
402                Arc::new(trade_id),
403                Arc::new(ts_event),
404                Arc::new(ts_init),
405            ],
406        )
407        .unwrap();
408
409        let decoded_data = TradeTick::decode_batch(&metadata, record_batch).unwrap();
410        assert_eq!(decoded_data.len(), 2);
411        assert_eq!(decoded_data[0].price, Price::from_raw(raw_price1, 2));
412        assert_eq!(decoded_data[1].price, Price::from_raw(raw_price2, 2));
413    }
414
415    #[rstest]
416    #[case::valid(Some("trade-2"), None)]
417    #[case::max_length(Some("12345678-1234-1234-1234-123456789012"), None)]
418    #[case::empty(Some(""), Some("row 1: String is empty"))]
419    #[case::overlength(
420        Some("12345678-1234-1234-1234-1234567890123"),
421        Some("row 1: String exceeds maximum length of 36 characters, was 37")
422    )]
423    #[case::non_ascii(Some("é"), Some("row 1: String contains non-ASCII character"))]
424    #[case::whitespace(Some(" "), Some("row 1: String contains only whitespace"))]
425    #[case::interior_nul(Some("a\0b"), Some("row 1: String contains interior NUL byte"))]
426    #[case::null(None, Some("NULL value at row 1"))]
427    fn test_decode_batch_trade_ids(
428        #[case] trade_id: Option<&str>,
429        #[case] expected_error: Option<&str>,
430        #[values(false, true)] string_view: bool,
431    ) {
432        let tick1 = TradeTick {
433            price: Price::from("1234.56"),
434            size: Quantity::from("1.23456"),
435            ts_event: 12.into(),
436            ts_init: 34.into(),
437            ..stub_trade_ethusdt_buy()
438        };
439
440        let mut tick2 = TradeTick {
441            price: Price::from("2345.67"),
442            size: Quantity::from("8.90123"),
443            aggressor_side: AggressorSide::Sell,
444            trade_id: TradeId::new("trade-2"),
445            ts_event: 123.into(),
446            ts_init: 456.into(),
447            ..tick1
448        };
449
450        let metadata = TradeTick::get_metadata(&tick1.instrument_id, 2, 5);
451        let batch = TradeTick::encode_batch(&metadata, &[tick1, tick2]).unwrap();
452        let ids = vec![Some(tick1.trade_id.as_str()), trade_id];
453        let ids: Arc<dyn Array> = if string_view {
454            Arc::new(StringViewArray::from(ids))
455        } else {
456            Arc::new(StringArray::from(ids))
457        };
458
459        let mut fields = batch.schema().fields().to_vec();
460        fields[3] = Arc::new(Field::new("trade_id", ids.data_type().clone(), true));
461        let schema = Schema::new_with_metadata(fields, batch.schema().metadata().clone());
462        let mut columns = batch.columns().to_vec();
463        columns[3] = ids;
464        let batch = RecordBatch::try_new(Arc::new(schema), columns).unwrap();
465
466        let result = TradeTick::decode_batch(&metadata, batch);
467
468        if let Some(expected_error) = expected_error {
469            assert!(matches!(
470                result,
471                Err(EncodingError::ParseError("trade_id", ref message))
472                    if message == expected_error
473            ));
474        } else {
475            tick2.trade_id = TradeId::new(trade_id.unwrap());
476            let decoded = result.unwrap();
477            assert_eq!(decoded, vec![tick1, tick2]);
478            assert_eq!(decoded[0].price.precision, 2);
479            assert_eq!(decoded[0].size.precision, 5);
480            assert_eq!(decoded[1].price.precision, 2);
481            assert_eq!(decoded[1].size.precision, 5);
482        }
483    }
484
485    #[rstest]
486    #[case::null_key(true)]
487    #[case::null_value(false)]
488    fn test_decode_batch_rejects_null_aggressor_side_with_field_and_row(#[case] null_key: bool) {
489        use arrow::{
490            array::{DictionaryArray, Int8Array},
491            datatypes::Int8Type,
492        };
493
494        let instrument_id = InstrumentId::from("AAPL.XNAS");
495        let metadata = TradeTick::get_metadata(&instrument_id, 2, 0);
496        let raw_price = (100.00 * FIXED_SCALAR) as PriceRaw;
497        let price =
498            crate::arrow::test_support::decimal_array_from_bytes(vec![&raw_price.to_le_bytes()]);
499        let size = crate::arrow::test_support::decimal_array_from_bytes(vec![
500            &((1000.0 * FIXED_SCALAR) as QuantityRaw).to_le_bytes(),
501        ]);
502
503        let aggressor_side = if null_key {
504            DictionaryArray::<Int8Type>::try_new(
505                Int8Array::from(vec![None]),
506                Arc::new(StringArray::from(vec!["BUY"])),
507            )
508            .unwrap()
509        } else {
510            DictionaryArray::<Int8Type>::try_new(
511                Int8Array::from(vec![0]),
512                Arc::new(StringArray::from(vec![None::<&str>])),
513            )
514            .unwrap()
515        };
516
517        let trade_id = StringArray::from(vec!["1"]);
518        let ts_event = UInt64Array::from(vec![1]);
519        let ts_init = UInt64Array::from(vec![2]);
520        let fields = vec![
521            Field::new("price", fixed_decimal_data_type(), false),
522            Field::new("size", fixed_decimal_data_type(), false),
523            Field::new("aggressor_side", enum_dictionary_data_type(), true),
524            Field::new("trade_id", DataType::Utf8, false),
525            Field::new("ts_event", crate::arrow::timestamp_data_type(), false),
526            Field::new("ts_init", crate::arrow::timestamp_data_type(), false),
527        ];
528        let schema = Schema::new_with_metadata(fields, metadata.clone());
529        let record_batch = crate::arrow::record_batch_with_timestamps(
530            Arc::new(schema),
531            vec![
532                Arc::new(price),
533                Arc::new(size),
534                Arc::new(aggressor_side),
535                Arc::new(trade_id),
536                Arc::new(ts_event),
537                Arc::new(ts_init),
538            ],
539        )
540        .unwrap();
541
542        let result = TradeTick::decode_batch(&metadata, record_batch);
543
544        assert!(matches!(
545            result,
546            Err(EncodingError::ParseError("aggressor_side", ref message))
547                if message == "row 0: required value is null"
548        ));
549    }
550
551    #[rstest]
552    fn test_decode_batch_invalid_price_returns_error() {
553        let instrument_id = InstrumentId::from("AAPL.XNAS");
554        let metadata = TradeTick::get_metadata(&instrument_id, 2, 0);
555
556        let invalid_price: PriceRaw = PriceRaw::MAX - 1000;
557        let price = crate::arrow::test_support::decimal_array_from_bytes(vec![
558            &invalid_price.to_le_bytes(),
559        ]);
560        let size = crate::arrow::test_support::decimal_array_from_bytes(vec![
561            &((1000.0 * FIXED_SCALAR) as QuantityRaw).to_le_bytes(),
562        ]);
563        let aggressor_side = enum_dictionary_array([AggressorSide::NoAggressor]).unwrap();
564        let trade_id = StringArray::from(vec!["1"]);
565        let ts_event = UInt64Array::from(vec![1]);
566        let ts_init = UInt64Array::from(vec![2]);
567
568        let record_batch = crate::arrow::record_batch_with_timestamps(
569            crate::arrow::schema_without_identifier_column(&TradeTick::get_schema(Some(
570                metadata.clone(),
571            )))
572            .into(),
573            vec![
574                Arc::new(price),
575                Arc::new(size),
576                Arc::new(aggressor_side),
577                Arc::new(trade_id),
578                Arc::new(ts_event),
579                Arc::new(ts_init),
580            ],
581        )
582        .unwrap();
583
584        let result = TradeTick::decode_batch(&metadata, record_batch);
585        assert!(result.is_err());
586        let err = result.unwrap_err();
587        assert!(
588            err.to_string().contains("price") && err.to_string().contains("row 0"),
589            "Expected price error at row 0, was: {err}"
590        );
591    }
592
593    #[rstest]
594    fn test_decode_batch_invalid_size_returns_error() {
595        use nautilus_model::types::{fixed::FIXED_PRECISION, quantity::QUANTITY_RAW_MAX};
596
597        let instrument_id = InstrumentId::from("AAPL.XNAS");
598        // Decode the size at full precision so the out-of-range raw value bypasses the
599        // precision-0 correction, which would otherwise round it back within the bound.
600        let metadata = TradeTick::get_metadata(&instrument_id, 2, FIXED_PRECISION);
601
602        let raw_price = (100.00 * FIXED_SCALAR) as PriceRaw;
603        let price =
604            crate::arrow::test_support::decimal_array_from_bytes(vec![&raw_price.to_le_bytes()]);
605
606        let invalid_size = QUANTITY_RAW_MAX + 1;
607        let size =
608            crate::arrow::test_support::decimal_array_from_bytes(vec![&invalid_size.to_le_bytes()]);
609        let aggressor_side = enum_dictionary_array([AggressorSide::NoAggressor]).unwrap();
610        let trade_id = StringArray::from(vec!["1"]);
611        let ts_event = UInt64Array::from(vec![1]);
612        let ts_init = UInt64Array::from(vec![2]);
613
614        let record_batch = crate::arrow::record_batch_with_timestamps(
615            crate::arrow::schema_without_identifier_column(&TradeTick::get_schema(Some(
616                metadata.clone(),
617            )))
618            .into(),
619            vec![
620                Arc::new(price),
621                Arc::new(size),
622                Arc::new(aggressor_side),
623                Arc::new(trade_id),
624                Arc::new(ts_event),
625                Arc::new(ts_init),
626            ],
627        )
628        .unwrap();
629
630        let result = TradeTick::decode_batch(&metadata, record_batch);
631        assert!(result.is_err());
632        let err = result.unwrap_err();
633        assert!(
634            err.to_string().contains("size") && err.to_string().contains("row 0"),
635            "Expected size error at row 0, was: {err}"
636        );
637    }
638
639    #[rstest]
640    fn test_decode_batch_invalid_aggressor_side_returns_error() {
641        let instrument_id = InstrumentId::from("AAPL.XNAS");
642        let metadata = TradeTick::get_metadata(&instrument_id, 2, 0);
643
644        let raw_price = (100.00 * FIXED_SCALAR) as PriceRaw;
645        let price =
646            crate::arrow::test_support::decimal_array_from_bytes(vec![&raw_price.to_le_bytes()]);
647        let size = crate::arrow::test_support::decimal_array_from_bytes(vec![
648            &((1000.0 * FIXED_SCALAR) as QuantityRaw).to_le_bytes(),
649        ]);
650
651        let aggressor_side = enum_dictionary_array(["INVALID"]).unwrap();
652        let trade_id = StringArray::from(vec!["1"]);
653        let ts_event = UInt64Array::from(vec![1]);
654        let ts_init = UInt64Array::from(vec![2]);
655
656        let record_batch = crate::arrow::record_batch_with_timestamps(
657            crate::arrow::schema_without_identifier_column(&TradeTick::get_schema(Some(
658                metadata.clone(),
659            )))
660            .into(),
661            vec![
662                Arc::new(price),
663                Arc::new(size),
664                Arc::new(aggressor_side),
665                Arc::new(trade_id),
666                Arc::new(ts_event),
667                Arc::new(ts_init),
668            ],
669        )
670        .unwrap();
671
672        let result = TradeTick::decode_batch(&metadata, record_batch);
673        assert!(result.is_err());
674        let err = result.unwrap_err();
675        assert!(
676            err.to_string().contains("AggressorSide"),
677            "Expected AggressorSide error, was: {err}"
678        );
679    }
680
681    #[rstest]
682    fn test_decode_batch_missing_instrument_id_returns_error() {
683        let instrument_id = InstrumentId::from("AAPL.XNAS");
684        let mut metadata = TradeTick::get_metadata(&instrument_id, 2, 0);
685        metadata.remove(KEY_INSTRUMENT_ID);
686
687        let raw_price = (100.00 * FIXED_SCALAR) as PriceRaw;
688        let price =
689            crate::arrow::test_support::decimal_array_from_bytes(vec![&raw_price.to_le_bytes()]);
690        let size = crate::arrow::test_support::decimal_array_from_bytes(vec![
691            &((1000.0 * FIXED_SCALAR) as QuantityRaw).to_le_bytes(),
692        ]);
693        let aggressor_side = enum_dictionary_array([AggressorSide::NoAggressor]).unwrap();
694        let trade_id = StringArray::from(vec!["1"]);
695        let ts_event = UInt64Array::from(vec![1]);
696        let ts_init = UInt64Array::from(vec![2]);
697
698        let record_batch = crate::arrow::record_batch_with_timestamps(
699            crate::arrow::schema_without_identifier_column(&TradeTick::get_schema(Some(
700                metadata.clone(),
701            )))
702            .into(),
703            vec![
704                Arc::new(price),
705                Arc::new(size),
706                Arc::new(aggressor_side),
707                Arc::new(trade_id),
708                Arc::new(ts_event),
709                Arc::new(ts_init),
710            ],
711        )
712        .unwrap();
713
714        let result = TradeTick::decode_batch(&metadata, record_batch);
715        assert!(result.is_err());
716        let err = result.unwrap_err();
717        assert!(
718            err.to_string().contains("instrument_id"),
719            "Expected missing instrument_id error, was: {err}"
720        );
721    }
722
723    #[rstest]
724    fn test_decode_batch_missing_price_precision_returns_error() {
725        let instrument_id = InstrumentId::from("AAPL.XNAS");
726        let mut metadata = TradeTick::get_metadata(&instrument_id, 2, 0);
727        metadata.remove(KEY_PRICE_PRECISION);
728
729        let raw_price = (100.00 * FIXED_SCALAR) as PriceRaw;
730        let price =
731            crate::arrow::test_support::decimal_array_from_bytes(vec![&raw_price.to_le_bytes()]);
732        let size = crate::arrow::test_support::decimal_array_from_bytes(vec![
733            &((1000.0 * FIXED_SCALAR) as QuantityRaw).to_le_bytes(),
734        ]);
735        let aggressor_side = enum_dictionary_array([AggressorSide::NoAggressor]).unwrap();
736        let trade_id = StringArray::from(vec!["1"]);
737        let ts_event = UInt64Array::from(vec![1]);
738        let ts_init = UInt64Array::from(vec![2]);
739
740        let record_batch = crate::arrow::record_batch_with_timestamps(
741            crate::arrow::schema_without_identifier_column(&TradeTick::get_schema(Some(
742                metadata.clone(),
743            )))
744            .into(),
745            vec![
746                Arc::new(price),
747                Arc::new(size),
748                Arc::new(aggressor_side),
749                Arc::new(trade_id),
750                Arc::new(ts_event),
751                Arc::new(ts_init),
752            ],
753        )
754        .unwrap();
755
756        let result = TradeTick::decode_batch(&metadata, record_batch);
757        assert!(result.is_err());
758        let err = result.unwrap_err();
759        assert!(
760            err.to_string().contains("price_precision"),
761            "Expected missing price_precision error, was: {err}"
762        );
763    }
764
765    #[rstest]
766    fn test_encode_decode_round_trip() {
767        let instrument_id = InstrumentId::from("AAPL.XNAS");
768        let metadata = TradeTick::get_metadata(&instrument_id, 2, 0);
769
770        let tick1 = TradeTick {
771            instrument_id,
772            price: Price::from("100.10"),
773            size: Quantity::from(1000),
774            aggressor_side: AggressorSide::Buy,
775            trade_id: TradeId::new("trade-123"),
776            ts_event: 1_000_000_000.into(),
777            ts_init: 1_000_000_001.into(),
778        };
779
780        let tick2 = TradeTick {
781            instrument_id,
782            price: Price::from("100.50"),
783            size: Quantity::from(500),
784            aggressor_side: AggressorSide::Sell,
785            trade_id: TradeId::new("trade-456"),
786            ts_event: 2_000_000_000.into(),
787            ts_init: 2_000_000_001.into(),
788        };
789
790        let original = vec![tick1, tick2];
791        let record_batch = TradeTick::encode_batch(&metadata, &original).unwrap();
792        let decoded = TradeTick::decode_batch(&metadata, record_batch).unwrap();
793
794        assert_eq!(decoded.len(), original.len());
795        for (orig, dec) in original.iter().zip(decoded.iter()) {
796            assert_eq!(dec.instrument_id, orig.instrument_id);
797            assert_eq!(dec.price, orig.price);
798            assert_eq!(dec.size, orig.size);
799            assert_eq!(dec.aggressor_side, orig.aggressor_side);
800            assert_eq!(dec.trade_id, orig.trade_id);
801            assert_eq!(dec.ts_event, orig.ts_event);
802            assert_eq!(dec.ts_init, orig.ts_init);
803        }
804    }
805}