Skip to main content

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 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 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.

[{
"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.

[{
"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 GetAggregates. To replace a definition, combine RemoveAggregate and CreateAggregate in one transaction.