If it is possible to modify existing order by id using current interface

[daviddwlee84]

Based on my current understanding (considering the L3_MBO scenario), the OrderBook’s underlying BookLadder maintains a cache keyed by order_id that points to a BookLevel, and each BookLevel implements a FIFO queue of the original BookOrders.

However, with the current interface, modifying an order requires using OrderBookDelta, and the only implemented operation related to this I see is BookAction.Update.

The issue is that update expects the target volume after the change; if the exchange/data source only provides a volume delta (e.g. some exchanges send ticks that amend orders by order_id (e.g., change volume)), I need a way to fetch the original volume for that order_id.

In these cases, I find myself maintaining an additional table to track each order’s remaining quantity or filled status (with logic possibly living in the Actor/Strategy). This feels like duplicating dummy information, and the maintenance overhead ends up being comparable to running a second OrderBook in parallel.

Any recommended approaches or patterns to address this?
For example, would it make sense to expose a query to retrieve the current volume by order_id, or to support delta-based updates directly in OrderBookDelta?

---

nautilus_trader/nautilus_trader/core/nautilus_pyo3.pyi

Lines 3706 to 3785 in a9e985b

	class OrderBook:
	def __init__(
	self,
	instrument_id: InstrumentId,
	book_type: BookType,
	) -> None: ...
	@property
	def instrument_id(self) -> InstrumentId: ...
	@property
	def book_type(self) -> BookType: ...
	@property
	def sequence(self) -> int: ...
	@property
	def ts_event(self) -> int: ...
	@property
	def ts_init(self) -> int: ...
	@property
	def ts_last(self) -> int: ...
	@property
	def update_count(self) -> int: ...
	def reset(self) -> None: ...
	def add(self, order: BookOrder, flags: int, sequence: int, ts_event: int) -> None: ...
	def update(self, order: BookOrder, flags: int, sequence: int, ts_event: int) -> None: ...
	def delete(self, order: BookOrder, flags: int, sequence: int, ts_event: int) -> None: ...
	def clear(self, sequence: int, ts_event: int) -> None: ...
	def clear_bids(self, sequence: int, ts_event: int) -> None: ...
	def clear_asks(self, sequence: int, ts_event: int) -> None: ...
	def apply_delta(self, delta: OrderBookDelta) -> None: ...
	def apply_deltas(self, deltas: OrderBookDeltas) -> None: ...
	def apply_depth(self, depth: OrderBookDepth10) -> None: ...
	def bids(self, depth: int | None = None) -> list[BookLevel]: ...
	def asks(self, depth: int | None = None) -> list[BookLevel]: ...
	def bids_to_dict(self, depth: int | None = None) -> dict[Decimal, Decimal]: ...
	def asks_to_dict(self, depth: int | None = None) -> dict[Decimal, Decimal]: ...
	def group_bids(self, group_size: Decimal, depth: int | None = None) -> dict[Decimal, Decimal]: ...
	def group_asks(self, group_size: Decimal, depth: int | None = None) -> dict[Decimal, Decimal]: ...
	def bids_filtered_to_dict(
	self,
	depth: int | None = None,
	own_book: OwnOrderBook | None = None,
	status: set[OrderStatus] | None = None,
	accepted_buffer_ns: int | None = None,
	ts_now: int | None = None,
	) -> dict[Decimal, Decimal]: ...
	def asks_filtered_to_dict(
	self,
	depth: int | None = None,
	own_book: OwnOrderBook | None = None,
	status: set[OrderStatus] | None = None,
	accepted_buffer_ns: int | None = None,
	ts_now: int | None = None,
	) -> dict[Decimal, Decimal]: ...
	def group_bids_filtered(
	self,
	group_size: Decimal,
	depth: int | None = None,
	own_book: OwnOrderBook | None = None,
	status: set[OrderStatus] | None = None,
	accepted_buffer_ns: int | None = None,
	ts_now: int | None = None,
	) -> dict[Decimal, Decimal]: ...
	def group_asks_filtered(
	self,
	group_size: Decimal,
	depth: int | None = None,
	own_book: OwnOrderBook | None = None,
	status: set[OrderStatus] | None = None,
	accepted_buffer_ns: int | None = None,
	ts_now: int | None = None,
	) -> dict[Decimal, Decimal]: ...
	def best_bid_price(self) -> Price | None: ...
	def best_ask_price(self) -> Price | None: ...
	def best_bid_size(self) -> Quantity | None: ...
	def best_ask_size(self) -> Quantity | None: ...
	def spread(self) -> float | None: ...
	def midpoint(self) -> float | None: ...
	def get_avg_px_for_quantity(self, qty: Quantity, order_side: OrderSide) -> float: ...
	def get_quantity_for_price(self, price: Price, order_side: OrderSide) -> float: ...
	def simulate_fills(self, order: BookOrder) -> list[tuple[Price, Quantity]]: ...
	def pprint(self, num_levels: int = 3, group_size: Decimal | None = None) -> str: ...

nautilus_trader/crates/model/src/orderbook/ladder.rs

Lines 141 to 209 in a9e985b

	/// Updates an existing order in the ladder, moving it to a new price level if needed.
	pub fn update(&mut self, order: BookOrder) {
	let price = self.cache.get(&order.order_id).copied();
	if let Some(price) = price
	&& let Some(level) = self.levels.get_mut(&price)
	{
	if order.price == level.price.value {
	// Update at current price level
	let level_len_before = level.len();
	level.update(order);
	// If level.update removed the order due to zero size, remove from cache too
	if order.size.raw == 0 {
	self.cache.remove(&order.order_id);
	debug_assert_eq!(
	level.len(),
	level_len_before - 1,
	"Level should have one less order after zero-size update"
	);
	} else {
	debug_assert!(
	self.cache.contains_key(&order.order_id),
	"Cache should still contain order {0} after update",
	order.order_id
	);
	}
	// Remove empty price level
	if level.is_empty() {
	self.levels.remove(&price);
	debug_assert!(
	!self.cache.values().any(|p| *p == price),
	"Cache should not contain removed price level {price:?}"
	);
	}
	// Validate cache consistency after same-price update
	debug_assert_eq!(
	self.cache.len(),
	self.levels.values().map(|level| level.len()).sum::<usize>(),
	"Cache size should equal total orders across all levels"
	);
	return;
	}
	// Price update: delete and insert at new level
	self.cache.remove(&order.order_id);
	level.delete(&order);
	if level.is_empty() {
	self.levels.remove(&price);
	debug_assert!(
	!self.cache.values().any(|p| *p == price),
	"Cache should not contain removed price level {price:?}"
	);
	}
	}
	// Only add if the order has positive size
	if order.size.is_positive() {
	self.add(order);
	}
	// Validate cache consistency after update
	debug_assert_eq!(
	self.cache.len(),
	self.levels.values().map(|level| level.len()).sum::<usize>(),
	"Cache size should equal total orders across all levels"
	);
	}

nautilus_trader/crates/model/src/orderbook/level.rs

Lines 31 to 42 in a9e985b

	/// Represents a discrete price level in an order book.
	///
	/// Orders are stored in an [`IndexMap`] which preserves FIFO (insertion) order.
	#[derive(Clone, Debug, Eq)]
	#[cfg_attr(
	feature = "python",
	pyo3::pyclass(module = "nautilus_trader.core.nautilus_pyo3.model")
	)]
	pub struct BookLevel {
	pub price: BookPrice,
	pub(crate) orders: IndexMap<OrderId, BookOrder>,
	}

nautilus_trader/nautilus_trader/core/nautilus_pyo3.pyi

Lines 823 to 865 in a9e985b

	class OrderBookDelta:
	def __init__(
	self,
	instrument_id: InstrumentId,
	action: BookAction,
	order: BookOrder | None,
	flags: int,
	sequence: int,
	ts_event: int,
	ts_init: int,
	) -> None: ...
	@property
	def instrument_id(self) -> InstrumentId: ...
	@property
	def action(self) -> BookAction: ...
	@property
	def order(self) -> BookOrder: ...
	@property
	def flags(self) -> int: ...
	@property
	def sequence(self) -> int: ...
	@property
	def ts_event(self) -> int: ...
	@property
	def ts_init(self) -> int: ...
	@staticmethod
	def fully_qualified_name() -> str: ...
	@staticmethod
	def get_metadata() -> dict[str, str]: ...
	@staticmethod
	def get_fields() -> dict[str, str]: ...
	@staticmethod
	def from_dict(values: dict[str, Any]) -> OrderBookDelta: ...
	@staticmethod
	def from_json(data: bytes) -> OrderBookDelta: ...
	@staticmethod
	def from_msgpack(data: bytes) -> OrderBookDelta: ...
	def as_pycapsule(self) -> object: ...
	def to_dict(self) -> dict[str, Any]: ...
	def to_json_bytes(self) -> bytes: ...
	def to_msgpack_bytes(self) -> bytes: ...

nautilus_trader/nautilus_trader/core/nautilus_pyo3.pyi

Lines 1286 to 1290 in a9e985b

	class BookAction(Enum):
	ADD = "ADD"
	UPDATE = "UPDATE"
	DELETE = "DELETE"
	CLEAR = "CLEAR"

[cjdsellers]

Hi @daviddwlee84,

Thanks for reaching out with your thoughtful feedback and questions.

I don't think we should consider maintaining a separate map of quantity by order ID in the book (for performance overhead reasons), but we could consider adding a method to at least expose a way of querying that (would be a couple of calls to get to it).

I agree this would be more efficient than maintaining a mapping or book in parallel, especially in Python.

Do you have a suggested API? Otherwise, if you wanted to make a PR including tests then this would be appreciated and I'd be happy to review 👍