CreateAggregate =============== Maintain a numeric property on the source (parent) using values from its outgoing connections or their destinations (children). Creation includes existing connections. Adding or removing a connection, or editing a field used by the expression, updates the parent before the next command in the transaction. The resulting property can be read, filtered, sorted, or indexed. Parameters ---------- Supply the three class names in ``class`` (source, connection, and destination) and both endpoint types in ``target``. Both endpoint categories must exist. The connection category can be empty or new. Built-in ownership links, such as an Image owning a BoundingBox or a Video owning a Frame, have no selectable connection class or user-defined link properties. They do not contribute to an aggregate. Alongside the selector, supply ``src_property``, ``operation``, and exactly one of ``dst_expression`` and ``connection_expression``. * ``dst_expression``, a value expression evaluated on the destination. For example, ``"$price"`` reads the child's stored ``price``. * ``connection_expression``, a value expression evaluated on the connection. For example, ``"$quantity"`` reads the quantity on that particular connection. Parallel connections to the same child can have different quantities. * ``operation``, one of ``sum``, ``avg``, ``min``, ``max``, or ``count``. The first four aggregate finite numeric results. They clear the output property when no eligible results remain. ``count`` counts non-null results, including zero and false, and stores zero for an empty group. Use a constant expression such as ``1`` with ``count`` to count all edges. * ``src_property``, the user-defined property name to maintain on the source category. The property name may already exist, including on another category or in an index. If any parent in the selected category already stores a value in this property, creation fails and preserves that value. Zero, false, and a stored JSON null all count as existing values. An identical active definition succeeds idempotently. Each output has a single owner. Client assignments and removals of a managed property fail with a schema error. All field references in an expression read stored user-defined properties from the selected child or connection. Functions and literals are supported. A corpus-dependent ``fulltext`` score is rejected. See the :ref:`expression grammar `. Each matching outgoing connection contributes once. For example, if an order has two connections to the same item, a ``dst_expression`` of ``"$quantity"`` and an item quantity of 3 contribute 6 to the order's sum. An incoming connection from the item to the order contributes nothing to that order's sum. Deleting the child removes both outgoing connections. An expression error or a nonfinite aggregate result rolls back the transaction. Sums and averages accumulate their inputs exactly and round once. A result that is exactly zero or rounds to zero is stored as positive zero. The output of one aggregate can be an input to another. For example, ``Customer.total`` can sum the ``Order.line_total`` of each connected order. An edit that changes an order's total then updates the customer in the same transaction. Creating a dependency cycle fails. Nested counts and sums include one contribution per matching path. If two Programs belonging to the same Provider both link to a Claim with an amount of 7, summing their subtotals on the Provider yields a count of 2 and a sum of 14. A :doc:`FindEntity` query for Claims connected to those Programs returns a count of 1 and a sum of 7 because it selects each Claim once. Parallel connections at either level also add paths. Examples -------- Given existing ``Order`` and ``LineItem`` entity classes, maintain the total value of each order's connected line items. .. code-block:: json [{ "CreateAggregate": { "class": {"src": "Order", "connection": "HasLine", "dst": "LineItem"}, "target": {"src": "entity", "dst": "entity"}, "src_property": "line_total", "operation": "sum", "dst_expression": {"multiply": ["$quantity", "$unit_price"]} } }] If quantities are stored on ``HasLine`` connections, use ``connection_expression`` to maintain their sum on each order. Changing one connection's quantity from 2 to 5 increases its order's total by 3, even when another connection reaches the same line item. .. code-block:: json [{ "CreateAggregate": { "class": {"src": "Order", "connection": "HasLine", "dst": "LineItem"}, "target": {"src": "entity", "dst": "entity"}, "src_property": "total_quantity", "operation": "sum", "connection_expression": "$quantity" } }] Requires both ``indexes.create`` and ``objects.update``. Success returns ``{"status": 0}``. List definitions with :doc:`GetAggregates`. To replace a definition, combine :doc:`RemoveAggregate` and CreateAggregate in one transaction.