RetrieveFunction and UpdateAction for aggregated entities

examples/Analytics.AggregateEntity-result.json

@@ -0,0 +1,80 @@
+{
+  "@odata.context": "$metadata#Sales",
+  "value": [
+    {
+      "Customer": {
+        "Country": "Netherlands"
+      },
+      "Product": {
+        "Name": "Paper"
+      },
+      "Amount": 3,
+      "@Analytics.AggregateEntity": {
+        "Aggregate": "Z3JvdXBieSgoQ3VzdG9tZXIvQ291bnRyeSxQcm9kdWN0L05hbWUpLGFnZ3JlZ2F0ZShBbW91bnQpKS9maWx0ZXIoQ3VzdG9tZXIvQ291bnRyeSBlcSAnTmV0aGVybGFuZHMnIGFuZCBQcm9kdWN0L05hbWUgZXEgJ1BhcGVyJyk=",
+        "RetrieveFunctionImport": "RetrieveAggregateSales",
+        "UpdateActionImport": "UpdateAggregateSales",
+        "UpdatableProperties": ["Amount"]
+      }
+    },
+    {
+      "Customer": {
+        "Country": "Netherlands"
+      },
+      "Product": {
+        "Name": "Sugar"
+      },
+      "Amount": 2,
+      "@Analytics.AggregateEntity": {
+        "Aggregate": "Z3JvdXBieSgoQ3VzdG9tZXIvQ291bnRyeSxQcm9kdWN0L05hbWUpLGFnZ3JlZ2F0ZShBbW91bnQpKS9maWx0ZXIoQ3VzdG9tZXIvQ291bnRyeSBlcSAnTmV0aGVybGFuZHMnIGFuZCBQcm9kdWN0L05hbWUgZXEgJ1N1Z2FyJyk=",
+        "RetrieveFunctionImport": "RetrieveAggregateSales",
+        "UpdateActionImport": "UpdateAggregateSales",
+        "UpdatableProperties": ["Amount"]
+      }
+    },
+    {
+      "Customer": {
+        "Country": "USA"
+      },
+      "Product": {
+        "Name": "Coffee"
+      },
+      "Amount": 12,
+      "@Analytics.AggregateEntity": {
+        "Aggregate": "Z3JvdXBieSgoQ3VzdG9tZXIvQ291bnRyeSxQcm9kdWN0L05hbWUpLGFnZ3JlZ2F0ZShBbW91bnQpKS9maWx0ZXIoQ3VzdG9tZXIvQ291bnRyeSBlcSAnVVNBJyBhbmQgUHJvZHVjdC9OYW1lIGVxICdDb2ZmZWUnKQ==",
+        "RetrieveFunctionImport": "RetrieveAggregateSales",
+        "UpdateActionImport": "UpdateAggregateSales",
+        "UpdatableProperties": ["Amount"]
+      }
+    },
+    {
+      "Customer": {
+        "Country": "USA"
+      },
+      "Product": {
+        "Name": "Paper"
+      },
+      "Amount": 5,
+      "@Analytics.AggregateEntity": {
+        "Aggregate": "Z3JvdXBieSgoQ3VzdG9tZXIvQ291bnRyeSxQcm9kdWN0L05hbWUpLGFnZ3JlZ2F0ZShBbW91bnQpKS9maWx0ZXIoQ3VzdG9tZXIvQ291bnRyeSBlcSAnVVNBJyBhbmQgUHJvZHVjdC9OYW1lIGVxICdQYXBlcicp",
+        "RetrieveFunctionImport": "RetrieveAggregateSales",
+        "UpdateActionImport": "UpdateAggregateSales",
+        "UpdatableProperties": ["Amount"]
+      }
+    },
+    {
+      "Customer": {
+        "Country": "USA"
+      },
+      "Product": {
+        "Name": "Sugar"
+      },
+      "Amount": 2,
+      "@Analytics.AggregateEntity": {
+        "Aggregate": "Z3JvdXBieSgoQ3VzdG9tZXIvQ291bnRyeSxQcm9kdWN0L05hbWUpLGFnZ3JlZ2F0ZShBbW91bnQpKS9maWx0ZXIoQ3VzdG9tZXIvQ291bnRyeSBlcSAnVVNBJyBhbmQgUHJvZHVjdC9OYW1lIGVxICdTdWdhcicp",
+        "RetrieveFunctionImport": "RetrieveAggregateSales",
+        "UpdateActionImport": "UpdateAggregateSales",
+        "UpdatableProperties": ["Amount"]
+      }
+    }
+  ]
+}

examples/Analytics.AggregateEntity-sample.json

@@ -0,0 +1,73 @@
+{
+  "$Version": "4.0",
+  "$Reference": {
+    "https://sap.github.io/odata-vocabularies/vocabularies/Analytics.json": {
+      "$Include": [{ "$Namespace": "com.sap.vocabularies.Analytics.v1", "$Alias": "Analytics" }]
+    },
+    "https://oasis-tcs.github.io/odata-vocabularies/vocabularies/Org.OData.Aggregation.V1.json": {
+      "$Include": [{ "$Namespace": "Org.OData.Aggregation.V1", "$Alias": "Aggregation" }]
+    }
+  },
+  "example.Analytics.AggregateEntity": {
+    "$Alias": "SalesModel",
+    "Customer": {
+      "$Kind": "EntityType",
+      "$Key": ["ID"],
+      "ID": {},
+      "Name": { "$Nullable": true },
+      "Country": { "$Nullable": true }
+    },
+    "Product": {
+      "$Kind": "EntityType",
+      "$Key": ["ID"],
+      "ID": {},
+      "Name": { "$Nullable": true },
+      "Color": { "$Nullable": true },
+      "TaxRate": { "$Type": "Edm.Decimal", "$Nullable": true, "$Scale": 2 }
+    },
+    "Sale": {
+      "$Kind": "EntityType",
+      "$Key": ["ID"],
+      "ID": {},
+      "Amount": { "$Type": "Edm.Decimal", "$Nullable": true, "$Scale": 2 },
+      "Product": { "$Kind": "NavigationProperty", "$Type": "SalesModel.Product", "$Nullable": true },
+      "Customer": { "$Kind": "NavigationProperty", "$Type": "SalesModel.Customer", "$Nullable": true }
+    },
+    "UpdateAggregateSales": [
+      {
+        "$Kind": "Action",
+        "@Core.Description": "Updates an aggregate entity in the `Sales` entity set",
+        "$Parameter": [
+          { "$Name": "Aggregate", "@Core.Description": "String identifying the aggregate entity to be updated" },
+          {
+            "$Name": "Updates",
+            "$Type": "SalesModel.Sale",
+            "@Core.Description": "Aggregate entity with nested properties that are to be updated, like the body of a PATCH request"
+          }
+        ],
+        "$ReturnType": { "$Type": "SalesModel.Sale", "@Core.Description": "Aggregate entity with updates applied" }
+      }
+    ],
+    "RetrieveAggregateSales": [
+      {
+        "$Kind": "Function",
+        "@Core.Description": "Retrieves an aggregate entity in the `Sales` entity set",
+        "$Parameter": [
+          { "$Name": "Aggregate", "@Core.Description": "String identifying the aggregate entity to be retrieved" }
+        ],
+        "$ReturnType": { "$Type": "SalesModel.Sale" }
+      }
+    ],
+    "container": {
+      "$Kind": "EntityContainer",
+      "Sales": {
+        "$Collection": true,
+        "$Type": "SalesModel.Sale",
+        "@Aggregation.CustomAggregate#Amount": "Edm.Decimal"
+      },
+      "UpdateAggregateSales": { "$Action": "SalesModel.UpdateAggregateSales", "$EntitySet": "Sales" },
+      "RetrieveAggregateSales": { "$Function": "SalesModel.RetrieveAggregateSales", "$EntitySet": "Sales" }
+    }
+  },
+  "$EntityContainer": "example.Analytics.AggregateEntity.container"
+}

examples/Analytics.AggregateEntity-sample.xml

@@ -0,0 +1,66 @@
+<?xml version="1.0" encoding="utf-8"?>
+<edmx:Edmx xmlns:edmx="http://docs.oasis-open.org/odata/ns/edmx" Version="4.0">
+  <edmx:Reference Uri="https://sap.github.io/odata-vocabularies/vocabularies/Analytics.xml">
+    <edmx:Include Namespace="com.sap.vocabularies.Analytics.v1" Alias="Analytics" />
+  </edmx:Reference>
+  <edmx:Reference Uri="https://oasis-tcs.github.io/odata-vocabularies/vocabularies/Org.OData.Aggregation.V1.xml">
+    <edmx:Include Namespace="Org.OData.Aggregation.V1" Alias="Aggregation" />
+  </edmx:Reference>
+
+  <edmx:DataServices>
+    <Schema xmlns="http://docs.oasis-open.org/odata/ns/edm" Namespace="example.Analytics.AggregateEntity" Alias="SalesModel">
+      <EntityType Name="Customer">
+        <Key>
+          <PropertyRef Name="ID" />
+        </Key>
+        <Property Name="ID" Type="Edm.String" Nullable="false" />
+        <Property Name="Name" Type="Edm.String" />
+        <Property Name="Country" Type="Edm.String" />
+      </EntityType>
+      <EntityType Name="Product">
+        <Key>
+          <PropertyRef Name="ID" />
+        </Key>
+        <Property Name="ID" Type="Edm.String" Nullable="false" />
+        <Property Name="Name" Type="Edm.String" />
+        <Property Name="Color" Type="Edm.String" />
+        <Property Name="TaxRate" Type="Edm.Decimal" Scale="2"/>
+      </EntityType>
+      <EntityType Name="Sale">
+        <Key>
+          <PropertyRef Name="ID" />
+        </Key>
+        <Property Name="ID" Type="Edm.String" Nullable="false" />
+        <Property Name="Amount" Type="Edm.Decimal" Scale="2" />
+        <NavigationProperty Name="Product" Type="SalesModel.Product" />
+        <NavigationProperty Name="Customer" Type="SalesModel.Customer"/>
+      </EntityType>
+      <Action Name="UpdateAggregateSales">
+        <Annotation Term="Core.Description" String="Updates an aggregate entity in the `Sales` entity set" />
+        <Parameter Name="Aggregate" Type="Edm.String" Nullable="false">
+          <Annotation Term="Core.Description" String="String identifying the aggregate entity to be updated" />
+        </Parameter>
+        <Parameter Name="Updates" Type="SalesModel.Sale" Nullable="false">
+          <Annotation Term="Core.Description" String="Aggregate entity with nested properties that are to be updated, like the body of a PATCH request" />
+        </Parameter>
+        <ReturnType Type="SalesModel.Sale" Nullable="false">
+          <Annotation Term="Core.Description" String="Aggregate entity with updates applied" />
+        </ReturnType>
+      </Action>
+      <Function Name="RetrieveAggregateSales">
+        <Annotation Term="Core.Description" String="Retrieves an aggregate entity in the `Sales` entity set" />
+        <Parameter Name="Aggregate" Type="Edm.String" Nullable="false">
+          <Annotation Term="Core.Description" String="String identifying the aggregate entity to be retrieved" />
+        </Parameter>
+        <ReturnType Type="SalesModel.Sale" Nullable="false" />
+      </Function>
+      <EntityContainer Name="container">
+        <EntitySet Name="Sales" EntityType="SalesModel.Sale">
+          <Annotation Term="Aggregation.CustomAggregate" Qualifier="Amount" String="Edm.Decimal" />
+        </EntitySet>
+        <ActionImport Name="UpdateAggregateSales" Action="SalesModel.UpdateAggregateSales" EntitySet="Sales" />
+        <FunctionImport Name="RetrieveAggregateSales" Function="SalesModel.RetrieveAggregateSales" EntitySet="Sales" />
+      </EntityContainer>
+    </Schema>
+  </edmx:DataServices>
+</edmx:Edmx>

vocabularies/Analytics.json

@@ -156,6 +156,51 @@
         "@Core.Description": "The measure has non-negative and additive values; it can be used in whole-part charts, e.g. the Donut"
       }
     },
+    "AggregateEntity": {
+      "$Kind": "Term",
+      "$Type": "Analytics.AggregateEntityType",
+      "$AppliesTo": ["EntityType"],
+      "@Common.Experimental": true,
+      "@Common.IsInstanceAnnotation": true,
+      "@Core.Description": "Function and action for retrieving and updating an aggregate entity",
+      "@Core.LongDescription": "Transient entities that result from the application of a transformation sequence represent an\n          aggregate of persistent entities (for example, aggregate sales per country and product, as in [OData-Data-Agg-v4.0], first example in simple grouping section).\n          Such a transient entity may be annotated with this term to describe<br>\n          - a service-defined function import that can be used to retrieve the transient entity in order to `$expand` additional properties<br>\n          - a service-defined action import that can be used to update the transient entity. This effectively means updating the persistent entities whose aggregate\n          the transient entity represents, how this dis-aggregation happens is defined by the service.",
+      "@Core.Example": {
+        "@odata.type": "https://oasis-tcs.github.io/odata-vocabularies/vocabularies/Org.OData.Core.V1.xml#Core.ExternalExampleValue",
+        "Description": "Based on the [example model](../examples/Analytics.AggregateEntity-sample.xml).\n              The format of the `Aggregate` parameter allows the server to re-create the transient entity\n              without storing an identifier, based solely on the parameter value.",
+        "ExternalValue": "../examples/Analytics.AggregateEntity-result.json"
+      }
+    },
+    "AggregateEntityType": {
+      "$Kind": "ComplexType",
+      "@Common.Experimental": true,
+      "Aggregate": {
+        "@Core.Description": "Value that the first parameter of the function or action invocation must have",
+        "@Core.LongDescription": "This string value identifies the aggregate that the transient entity represents.\n            This value MUST be treated as opaque by the client."
+      },
+      "RetrieveFunctionImport": {
+        "$Type": "Core.SimpleIdentifier",
+        "$Nullable": true,
+        "@Core.Description": "Name of a function import",
+        "@Core.LongDescription": "The function has only one parameter."
+      },
+      "UpdateActionImport": {
+        "$Type": "Core.SimpleIdentifier",
+        "$Nullable": true,
+        "@Core.Description": "Name of an action import",
+        "@Core.LongDescription": "Action parameters after the first define how the identified aggregate entity is updated,\n            they are explained in the action definition in the service metadata."
+      },
+      "ExpandableProperties": {
+        "$Collection": true,
+        "$Type": "Edm.NavigationPropertyPath",
+        "@Core.Description": "Declared navigation properties of the aggregate entity that can be expanded"
+      },
+      "UpdatableProperties": {
+        "$Collection": true,
+        "$Type": "Edm.PropertyPath",
+        "@Core.Description": "Declared properties of the aggregate entity that can be updated with the action",
+        "@Core.LongDescription": "If a declared property whose name equals a custom aggregate can be updated, this means updating the\n            aggregate value."
+      }
+    },
     "$Annotations": {
       "Aggregation.CustomAggregate": {
         "@[email protected]": "Adding a list of other terms that can be annotated to it.",

vocabularies/Analytics.md

@@ -17,6 +17,7 @@ Term|Type|Description
 [AggregatedProperties](./Analytics.xml#L103:~:text=<Term%20Name="-,AggregatedProperties,-") *(Deprecated)*|\[[AggregatedPropertyType](#AggregatedPropertyType)\]|<a name="AggregatedProperties"></a>Deprecated in favor of [`AggregatedProperty`](#AggregatedProperty)
 [AggregatedProperty](./Analytics.xml#L121:~:text=<Term%20Name="-,AggregatedProperty,-")|[AggregatedPropertyType](#AggregatedPropertyType)|<a name="AggregatedProperty"></a>Dynamic property for aggregate expression with specified aggregation method defined on the annotated entity type.
 [AnalyticalContext](./Analytics.xml#L141:~:text=<Term%20Name="-,AnalyticalContext,-")|\[[AnalyticalContextType](#AnalyticalContextType)\]|<a name="AnalyticalContext"></a>Collection of properties that define an analytical context
+[AggregateEntity](./Analytics.xml#L170:~:text=<Term%20Name="-,AggregateEntity,-") *([Experimental](Common.md#Experimental))*|[AggregateEntityType](#AggregateEntityType)|<a name="AggregateEntity"></a>Function and action for retrieving and updating an aggregate entity ([Example](./Analytics.xml#L182))<br>Transient entities that result from the application of a transformation sequence represent an aggregate of persistent entities (for example, aggregate sales per country and product, as in [OData-Data-Agg-v4.0], first example in simple grouping section). Such a transient entity may be annotated with this term to describe<br> - a service-defined function import that can be used to retrieve the transient entity in order to `$expand` additional properties<br> - a service-defined action import that can be used to update the transient entity. This effectively means updating the persistent entities whose aggregate the transient entity represents, how this dis-aggregation happens is defined by the service.
 
 <a name="AggregatedPropertyType"></a>
 ## [AggregatedPropertyType](./Analytics.xml#L124:~:text=<ComplexType%20Name="-,AggregatedPropertyType,-")
@@ -43,3 +44,15 @@ Property|Type|Description
 [Dimension](./Analytics.xml#L159:~:text=<ComplexType%20Name="-,AnalyticalContextType,-")|[Tag](https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#Tag)|The property holds the key of a dimension
 [Measure](./Analytics.xml#L162:~:text=<ComplexType%20Name="-,AnalyticalContextType,-")|[Tag](https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#Tag)|The property holds the numeric value of a measure
 [AccumulativeMeasure](./Analytics.xml#L165:~:text=<ComplexType%20Name="-,AnalyticalContextType,-")|[Tag](https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#Tag)|The measure has non-negative and additive values; it can be used in whole-part charts, e.g. the Donut
+
+<a name="AggregateEntityType"></a>
+## [AggregateEntityType](./Analytics.xml#L193:~:text=<ComplexType%20Name="-,AggregateEntityType,-") *([Experimental](Common.md#Experimental))*
+
+
+Property|Type|Description
+:-------|:---|:----------
+[Aggregate](./Analytics.xml#L195:~:text=<ComplexType%20Name="-,AggregateEntityType,-")|String|Value that the first parameter of the function or action invocation must have<br>This string value identifies the aggregate that the transient entity represents. This value MUST be treated as opaque by the client.
+[RetrieveFunctionImport](./Analytics.xml#L202:~:text=<ComplexType%20Name="-,AggregateEntityType,-")|[SimpleIdentifier?](https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#SimpleIdentifier)|Name of a function import<br>The function has only one parameter.
+[UpdateActionImport](./Analytics.xml#L208:~:text=<ComplexType%20Name="-,AggregateEntityType,-")|[SimpleIdentifier?](https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#SimpleIdentifier)|Name of an action import<br>Action parameters after the first define how the identified aggregate entity is updated, they are explained in the action definition in the service metadata.
+[ExpandableProperties](./Analytics.xml#L215:~:text=<ComplexType%20Name="-,AggregateEntityType,-")|\[NavigationPropertyPath\]|Declared navigation properties of the aggregate entity that can be expanded
+[UpdatableProperties](./Analytics.xml#L218:~:text=<ComplexType%20Name="-,AggregateEntityType,-")|\[PropertyPath\]|Declared properties of the aggregate entity that can be updated with the action<br>If a declared property whose name equals a custom aggregate can be updated, this means updating the aggregate value.