Aggregate Merging
=================
.. Index:: Analysis; Aggregate Merging

The boolean parameter ``enable_aggregate_merging`` of `NetworkAnalysisStreamRequest <../api_reference.html#are-v1-analysis-NetworkAnalysisStreamRequest>`__
is used to control whether :doc:`_NodePath <../node_path>` resolution is maintained in the ledger when
``include_node_paths`` is not requested in a `LedgerExportDescriptor <../api_reference.html#ledgerexportdescriptor>`__.

When ``enable_aggregate_merging`` is unset, the default is determined by a feature flag on your Graphene environment.
Reach out to your account manager for information on your specific instance.

When ``enable_aggregate_merging`` is ``True`` and ``include_node_paths`` is ``False`` then for every merge of two
or more inwards ledgers, an aggregation is applied such that otherwise identical rows differing only by
`_NodePath` can be aggregated.

.. note::

  You may find that not all records that appear identical are aggregated when using this option. For algorithmic
  efficiency reasons, not all mergeable records are guaranteed to be merged.

Use Case
--------

For graphs that contain many splits and recombinations, the number of records in the ledger grows to account for
node path resolution. If node path resolution is not needed, the analysis can be more memory efficient by aggregating
records.

Inuring contract relationships are a common source of this graph shape. If you have many inuring relationships in your
graph, setting ``enable_aggregate_merging`` may improve memory performance. Alternatively, if you require node path
resolution but in limited parts of your graph, you can try using :doc:`../templates/core_operations/projection` nodes
(with ``enable_aggregate_merging`` set to ``False``) to control where the aggregation occurs and still see some benefit.

Here is an example of a graph where B and C both source A, and B inures to the benefit of C:

.. graphviz::

    digraph G {
        graph [ fontname="Courier", fontsize=12, size="7,5"];
        node [ shape=rect, fontname="Courier", fontcolor=blue, fontsize=10, margin=0.1];
        edge [ fontname="Courier", fontcolor=blue, fontsize=10];

        a [label="A"];
        b [label="B"];
        negate [label="* -1", shape=circle];
        c [label="C"];

        a -> b -> negate -> c;
        a -> c;
    }