.. index:: Core Operations; Occurrence Limit
.. _core-operation-occurrence-limit:

OccurrenceLimit
==================================

Applies a limit to the sum of a group of records that share equal values for
their ``Trial``, ``Time``, and ``OccurrenceKey`` fields. Once the limit is applied,
the result is proportionally allocated to all records in the group.

Structure
---------

.. code-block:: json

    {
        "_schema": "OccurrenceLimit_1.0",
        "limit": 1000,
        "currency": "GBP"
    }

Parameters
----------

+----------------------+----------+------------------+--------------------------------------------------------+
| Parameter Name       | Required | Type             | Description                                            |
+======================+==========+==================+========================================================+
| ``limit``            | Yes      | ``double``       | The limit value in currency units. Cannot be negative. |
+----------------------+----------+------------------+--------------------------------------------------------+
| ``currency``         | No       | ``string``       | The currency in which ``limit`` is defined.            |
+----------------------+----------+------------------+--------------------------------------------------------+

Behaviour
--------------

This is equivalent to :doc:`scoped_limit` with
``span_columns`` set to ``[Time, OccurrenceKey]`` and ``erode_columns`` set to
``[Time, OccurrenceKey]``.
In other words, it applies a non-eroding limit to occurrences generated by
combining records with matching ``Time`` and ``OccurrenceKey`` values.