Skip to main content

Build Deltas

A build delta reports what changed between two builds of one vehicle. It does not classify the change. Each metric that reads a delta applies its own criteria. See Build deltas and ADR-004.

How a change is reported​

A delta reports the model_id and the MSRP of each build, and the features that changed between them.

A delta compares the two builds at package level. Before comparing, the delta leaves out each feature that a package in the same build contains, because the package already includes it. An OMS can return a build that lists a package without its contents. So when both builds list a package, the package is not a change, even if the builds list different contents.

A feature changed when its option_code is in one build and not the other.

Each changed feature is reported in one of three lists:

  • replaced: a member of a mutually exclusive group in one build, and a different member of the same group in the other. The pair is reported only when each build has exactly one member of the group.
  • added and removed: every other changed feature.

Each element resolves to a feature_id against the model of its own build. Every property of the feature entity joins to an element through its feature_id, so a metric can limit its count to some features, such as elective ones. A metric that counts the contents of a changed package finds them in the feature entity by parent_package_code.

Each OEM declares its mutually exclusive groups with MutuallyExclusiveGroup, the same definition that synthetic candidates use.

The builds a delta compares​

build_before and build_after name where each build comes from:

  • recommended and cured are the builds on the ordering events.
  • inventory is a capture from the OEM's private inventory. For an inventory build, captured_on_before or captured_on_after holds the date of the capture.

A partition of private inventory holds the latest capture of each order. We do not capture every dealer's orders every day, so a partition repeats an order's last capture until the next one. A capture's date can therefore be days earlier than the date of the partition that holds it.

Assets​

Each asset is written to <oem>/<market>/reporting/.

AssetPartitionbuild_before → build_afterRows
order_curing_deltasOrdering runrecommended → curedOne for each recommendation that was cured
placed_order_deltasDay of private inventorycured → inventoryOne for each order we placed that the day's partition lists, up to and including the order's first locked capture
existing_order_deltasOrdering runinventory → curedOne for each order the run placed that existed before we first placed it

A recommendation joins its validated event on recommendation_id, so events published without a recommendation_id produce no rows.

placed_order_deltas compares the cured build of our latest placement of an order with the order's capture in the day's partition. So once the dealer reverts a change, the order's later rows show no change. When the capture is dated on or before the day of that placement, the order gets no row. The asset exists only for an OEM that sets locked_when. Each row also has these columns:

  • placed_on is the date of our latest placement.
  • is_locked is true when the capture satisfies locked_when.
  • cured_features lists the feature_id of each feature of our cured build that no package of the build contains.

placed_order_deltas reads our placements from placed_orders. A capture is matched to a placement when the capture's order_key column equals the placement's order_number. A staged Audi order has an order_number only after placed_orders resolves it to an inventory record, so the asset compares the order from that day on. When two placements have the same order number, the asset compares the placement with the later run_timestamp.

existing_order_deltas compares our cured build with an earlier capture of the order. That capture is the last one dated on or before the day we first placed the order. Build deltas use only the date of a capture, not its time. So when a capture and our placement are on the same day, we cannot tell which came first. The delta then treats the capture as the earlier one, because we usually place an order soon after a capture lists it. When the capture was in fact taken after our placement, it already has our build, and the delta shows no change. The asset exists only for an OEM that sets existing_orders.

Each OEM declares its private inventory as private_inventory, with these fields:

  • tier and table name the asset.
  • order_key names the column that holds the order number.
  • capture_column names the column that holds the date of each row's capture.
  • msrp_field names the MSRP column. An MSRP of 0 or less counts as missing.
  • locked_when is an optional SQL condition on a capture's columns. The condition is true once the OEM no longer accepts changes to the order. A capture whose condition evaluates to null counts as unlocked.
  • fields lists columns that BuildDeltasComponent computes on each capture before it computes the deltas. Each entry has a name and a Polars-SQL expr, in the format of a consolidated entity's derived_fields. An OEM uses fields to give an inventory column the name that consolidated models and features use.

features configures how BuildDeltasComponent resolves each option code to a feature in consolidated features. match_field names the field of a capture's feature_refs that holds the option code. row_keys names the columns that identify a model in consolidated models. An option code resolves to the feature that matches it on all of these:

  • The feature's option_code equals the option code.
  • The feature has the same parent_package_code as the option code.
  • The feature has the same values in the row_keys columns as the build's model.

A day's partition of placed_order_deltas reads that day's partition of private inventory and the partition of the day before. When the day's partition is missing, materializing fails. The asset reads the day's partition of consolidated models and features. Materializing fails when one of those tables has no partition for that day. The asset also reads the day's partition of placed_orders, and uses only the placements made before that day. The asset's automation condition acts only on the latest day's partition. It materializes that partition once the partitions of private inventory, placed_orders and consolidated tables that it reads exist, and again when one of them is rematerialized.

A run's partition of order_curing_deltas or existing_order_deltas reads consolidated models, features and dealers at the warehouse partition the run read. That partition is the partition_date in the run's row of ordering/runs. When the run has curing pairs (order_curing_deltas) or placements (existing_order_deltas), materializing fails if the run recorded no partition_date or a consolidated table has no partition for that date. Otherwise the asset writes an empty partition. See Input partitions.