Edits
*****

What are edits?
===============
An edit within bframe refers to an overwrite on a source model (e.g. customers, products, etc). This is most commonly used to update fields. Since bframe is append-only edits are not made directly on the row, but are accomplished through versioning. When a new version is created bframe automatically references the latest copy.

.. figure:: /_static/images/features/edits_before_after.png
    :width: 500px

bframe does not respect references to prior versions since edits are considered a global change. To preserve historical references please see the `amendments </features/amendments.html>`_ feature.

Why are edits important?
========================
Dealing with change is one of the more challenging pieces of business modeling. Edits are a key feature to enable an efficient and safe resolution path when change is necessary. It's simple to delete or directly update a row, but this can leave a system open to compounding mistakes or with a dead end audit trail. The edit feature is a method to make changes with an exit strategy. This is possible since prior versions are persisted in the source. For example, rolling back versions or recovering the history of a model is straightforward with the edit feature.

How do edits work in bframe?
============================
Edits are simple to make and can be performed on any source model with a ``version`` field. To make an edit, a larger version with the same ``id`` field is inserted into the table. The bframe library manages the process to ensure that the latest version is always returned. If prior versions are desired they can be accessed through querying the source directly. Let's cover a simple example to demonstrate how all of this works.

Making an edit
--------------
Using the `Wikipedia case study </case_study/index.html>`_ as base, we can make an edit and see the impact. In this case let's update the quantity of the platform fee product from ``1`` to ``2``.

Below is the current state of the list price.

.. tab-set::

    .. tab-item:: Result

        .. csv-table::
            :file: /_static/ex_tables/edit_feat_1_1.csv
            :class: bmodel-table
            :header-rows: 1

    .. tab-item:: Query

        .. literalinclude:: /_static/ex_sql/edit_feat_1_1.sql
            :language: sql

Two changes need to be made to the existing model. The ``fixed_quantity`` needs to be set to ``2`` and the version needs to be set to ``1``.

.. tab-set::

    .. tab-item:: Query
        
        .. literalinclude:: /_static/ex_sql/edit_feat_1_2.sql
            :language: sql

    .. tab-item:: Result

        .. csv-table::
            :file: /_static/ex_tables/edit_feat_1_2.csv
            :class: bmodel-table
            :header-rows: 1

Once inserted the edit is live. This can be confirmed by querying the list price directly.

.. tab-set::

    .. tab-item:: Result

        .. csv-table::
            :file: /_static/ex_tables/edit_feat_1_3.csv
            :class: bmodel-table
            :header-rows: 1

    .. tab-item:: Query

        .. literalinclude:: /_static/ex_sql/edit_feat_1_3.sql
            :language: sql

Exploring the change
--------------------

All contracts associated with this list price now will generate line items with this change in place. Looking at a line item we can see that each platform fee product indeed has a quantity of ``2``.

.. tab-set::

    .. tab-item:: Result

        .. csv-table::
            :file: /_static/ex_tables/edit_feat_1_4.csv
            :class: bmodel-table
            :header-rows: 1

    .. tab-item:: Query

        .. literalinclude:: /_static/ex_sql/edit_feat_1_4.sql
            :language: sql

Since this is an edit all past, present and future transformations will be affected by this change. For example, the line item that was shown has a finalized `status </business_modeling/rating/status.html>`_. In this scenario the goal is not stated, so we can't be sure if such a change is good or bad.

Most business systems persist finalized invoices and line items on a regular cadence. This could cause a divergence between invoices and line items generated by bframe and what's already stored in the destination. To keep both systems aligned it would be best to update the destination to match bframe's output. Alternatively, it may be intentional that bframe is only correct on a go-forward basis and the destination is considered the definitive source of truth.