This specification defines the following terms:

• Aggregatable Expression – an expression not involving term casts and resulting in a value of a complex or entity or an aggregatable primitive type
• Aggregate Expression – argument of the aggregate transformation or function defined in section 3.2.1.1
• Aggregatable Primitive Type – a primitive type other than Edm.Stream or subtypes of Edm.Geography or Edm.Geometry
• Data Aggregation Path – a path that consists of one or more segments joined together by forward slashes (/). Segments are names of declared or dynamic structural or navigation properties, or type-cast segments consisting of the (optionally qualified) name of a structured type that is derived from the type identified by the preceding path segment to reach properties declared by the derived type.
• Expression – derived from the commonExpr rule (see OData-ABNF)
• Single-Valued Property Path – property path ending in a single-valued primitive, complex, or navigation property

The following non-exhaustive list contains variable names that are used throughout this document:

• \(A,B,C\) – collections of instances
• \(H\) – hierarchical collection
• \(H'\) – subset of nodes from a hierarchical collection
• \(u,v,w\) – instances in a collection
• \(x\) – an instance in a hierarchical collection, called a node
• \(p,q,r\) – paths
• \(S,T\) – transformation sequences
• \(α\) – aggregate expression, defined in section 3.2.1.1
• \(\Gamma(A,p)\) – the collection that results from evaluating a data aggregation path \(p\) relative to a collection \(A\), defined in section 3.1.3
• \(γ(u,p)\) – the collection that results from evaluating a data aggregation path \(p\) relative to an instance \(u\), defined in section 3.1.3
• \(\Pi_G(s)\) – a transformation of a collection that injects grouping properties into every instance of the collection, defined in section 3.2.3.1
• \(σ(x)\) – instance containing a grouping property that represents a node \(x\), defined in section 6.2.2

Keywords defined by this specification use this monospaced font.

Some sections of this specification are illustrated with non-normative examples.

Non-normative examples use this paragraph style.

All examples in this document are non-normative and informative only. Examples labeled with ⚠ contain advanced concepts or make use of keywords that are defined only later in the text, they can be skipped at first reading.

All other text is normative unless otherwise labeled.

All input sets and output sets in one transformation sequence are collections of the input type, that is the entity type or complex type of the first input set, or in other words, of the resource to which the transformation sequence is applied. The input type is determined by the entity model element identified within the metadata document by the context URL of that resource OData-Protocol, section 10. Individual instances in an input or output set can have a subtype of the input type. (See example 74.) The transformation sequence given as the $apply system query option is applied to the resource addressed by the resource path. The transformations defined below can have nested transformation sequences as parameters, these are then applied to resources that can differ from the current input set.

The structure of an instance that occurs in an input or output set is defined by the names of the structural and navigation properties that the instance contains. Instances of an input type can have different structures, subject to the following rules:

• Declared properties of the input type or a nested or related type thereof or of a subtype of one of these MUST have their declared type and meaning when they occur in an input or output set.
• Single- or collection-valued primitive properties addressed by a property path starting at a non-transient entity MUST keep their values from the addressed resource path collection throughout the transformation sequence. Likewise, single- or collection-valued navigation property paths starting at a non-transient entity MUST keep addressing the same non-transient entities as in the addressed resource path collection.
• Instances in an output set need not have all declared or dynamic properties that occurred in the input set.
• Instances in an output set can have dynamic properties that did not occur in the input set. The name for such a dynamic property is called an alias, it is a simple identifier (see OData-CSDL, section 15.2). Aliases MUST differ from names of declared properties in the input type, from names of properties in the first input set, and from names of properties in the current input set. Aliases in one collection MUST also differ from each other.

Here is an overview of the structural changes made by different transformations:

• During aggregation or nest, many instances are replaced by one instance, properties that represent the aggregation level are retained, and others are replaced by dynamic properties holding the aggregate value of the many instances or a transformed copy of them.
• During compute, dynamic properties are added to each instance.
• During addnested, dynamic properties are added to each occurrence of a related collection.
• During join, one instance with a collection of related instances is replaced by many copies, each of which is related via a dynamic property to one of the related instances.
• During concatenation, the same instances are transformed multiple times and the output sets with their potentially different structures are concatenated.

An output set thus consists of instances with different structures. This is the same situation as with a collection of an open type (OData-CSDL, section 6.3 and OData-CSDL, section 9.3) and it is handled in the same way.

If the first input set is a collection of entities from a given entity set, then so are all input sets and output sets in the transformation sequence. The {select-list} in the context URL OData-Protocol, section 10 MUST describe only properties that are present or annotated as absent (for example, if Core.Permissions is None OData-Protocol, section 11.2.2) in all instances of the collection, after applying any $select and $expand system query options. The {select-list} SHOULD describe as many such properties as possible, even if the request involves a concatenation that leads to a non-homogeneous structure. If the server cannot determine any such properties, the {select-list} MUST consist of just the instance annotation AnyStructure defined in the Core vocabulary. (See example 75.)

Input sets and output sets are not sets of instances in the mathematical sense but collections, because the same instance can occur multiple times in them. In other words: A collection contains values (which can be instances of structured types or primitive values), possibly with repetitions. The occurrences of the values in the collection form a set in the mathematical sense. The cardinality of a collection is the total number of occurrences in it. When this text describes a transformation algorithmically and stipulates that certain steps are carried out for each occurrence in a collection, this means that the steps are carried out multiple times for the same value if it occurs multiple times in the collection.

A collection addressed by the resource path is returned by the service either as an ordered collection OData-Protocol, section 11.4.10 or as an unordered collection. The same applies to collections that are nested in or related to the addressed resource as well as to collections that are the result of evaluating an expression starting with $root, which occur, for example, as the first parameter of a hierarchical transformation.

But when such a collection is transformed by the $apply system query option, additional cases can arise that are neither ordered nor totally unordered. For example, the groupby transformation retains any order within a group but not between groups.

GET /service/Sales?$apply=groupby((Customer),orderby(Amount desc)/top(10))

For every transformation defined in the following sections, it will be specified how it orders its output set, based on the order of its input set. The order of the last output set can be further influenced by a $orderby system query option before it is observed in the response payload.

An order of a collection is more precisely defined as follows: Given two different occurrences \(u_1\) and \(u_2\) in a collection, which may be of the same value or of different values, \(u_1\) precedes \(u_2\) or \(u_2\) precedes \(u_1\), but not both. It can be neither, in which case the relative order of \(u_1\) and \(u_2\) does not matter. If \(u_1\) precedes \(u_2\) and \(u_2\) precedes \(u_3\), then \(u_1\) also precedes \(u_3\), and \(u_1\) never precedes \(u_1\). (This is a partial order in the mathematical sense defined on the set of occurrences.)

When transformations are defined in the following sections, the algorithmic description sometimes contains an order-preserving loop over a collection. Such a loop processes the occurrences in an order chosen by the service in such a way that \(u_1\) is processed before \(u_2\) whenever \(u_1\) precedes \(u_2\). Likewise, in an order-preserving sequence \(u_1,…,u_n\) we have \(i<j\) whenever \(u_i\) precedes \(u_j\).

A collection can be stable-sorted by a list of expressions. In the stable-sorted collection an occurrence \(u_1\) precedes \(u_2\) if and only if either

• \(u_1\) precedes \(u_2\) according to the rules of OData-Protocol, section 11.2.6.2 or
• these rules do not determine a precedence in either direction between \(u_1\) and \(u_2\) but \(u_1\) preceded \(u_2\) in the collection before the sort.

Stable-sorting of an ordered collection produces another ordered collection. A stable-sort does not necessarily produce a total order, the sorted collection may still contain two occurrences whose relative order does not matter. The transformation orderby performs a stable-sort.

The output set of a basic aggregation transformation can contain instances of an entity type without entity-id. After a concat transformation, different occurrences of the same entity can differ in individual non-declared properties. To account for such cases, the definition of sameness given in OData-URL, section 5.1.1.1.1 is refined here. Instances of structured types are the same if

• both are instances of complex types and both are null or both have the same structure and same values with null considered different from absent or
• both are instances of entity types without entity-id (see OData-Protocol, section 4.3) and both are null or both have the same structure and same values with null considered different from absent (informally speaking, they are compared like complex instances) or
• (1) both are instances of the same entity type with the same entity-id (non-transient entities, see OData-Protocol, section 4.1) and (2) the structural and navigation properties contained in both have the same values (for non-primitive properties the sameness of values is decided by a recursive invocation of this definition).
  • If this is fulfilled, the instances are called complementary representations of the same non-transient entity. If this case is encountered at some recursion level while the sameness of non-transient entities \(u_1\) and \(u_2\) is established, a merged representation of the entity \(u_1=u_2\) exists that contains all properties of \(u_1\) and \(u_2\). But if the instances both occur in the last output set, services MUST represent each with its own structure in the response payload.
  • If the first condition is fulfilled but not the second, the instances are not the same and are called contradictory representations of the same non-transient entity. (Example 103 describes a use case for this.)

Collections are the same if there is a one-to-one correspondence \(f\) between them such that

• corresponding occurrences are of the same value and
• an occurrence \(u_1\) precedes another occurrence \(u_2\) if and only if the occurrence \(f(u_1)\) precedes the occurrence \(f(u_2)\), where the occurrences \(u_1\) and \(u_2\) may be of the same value or of different values. (A one-to-one correspondence with this second property is called order-preserving.)

This document specifies how a data aggregation path that occurs in a request is evaluated by the service. If such an evaluation fails, the service MUST reject the request.

For a data aggregation path to be a common expression according to OData-URL, section 5.1.1, its segments must be single-valued with the possible exception of the last segment, and it can then be evaluated relative to an instance of a structured type. For the transformations defined in this document, a data aggregation path can also be evaluated relative to a collection \(A\), even if it has arbitrary collection-valued segments itself.

To this end, the following notation is used in the subsequent sections: If \(A\) is a collection and \(p\) a data aggregation path, optionally followed by a type-cast segment, the result of such a path evaluation is denoted by \(\Gamma(A,p)\) and defined as the unordered concatenation, possibly containing repetitions, of the collections \(γ(u,p)\) for each \(u\) in \(A\) that is not null. The function \(γ(u,p)\) takes a non-null value and a path as arguments and returns a collection of instances of structured types or primitive values, depending on the type of the final segment of \(p\). It is recursively defined as follows:

1. If \(p\) is an empty path, let \(B\) be a collection with \(u\) as its single member and continue with step 9.
2. Let \(p_1\) be the first segment of \(p\) and \(p_2\) the remainder, if any, such that \(p\) equals the concatenated path \(p_1/p_2\).
3. If \(p_1\) is a type-cast segment and \(u\) is of its type or a subtype thereof, let \(v=u\) and continue with step 8.
4. If \(p_1\) is a type-cast segment and \(u\) is not of its type or a subtype thereof, let \(B\) be an empty collection and continue with step 9. (This rule follows OData-URL, section 4.11 rather than OData-CSDL, section 14.4.1.1.)
5. Otherwise, \(p_1\) is a non-type-cast segment. If \(u\) does not contain a structural or navigation property \(p_1\), let \(B\) be an empty collection and continue with step 9.
6. If \(p_1\) is single-valued, let \(v\) be the value of the structural or navigation property \(p_1\) in \(u\). If \(v\) is null, let \(B\) be an empty collection and continue with step 9; otherwise continue with step 8.
7. Otherwise, \(p_1\) is collection-valued. Let \(C\) be the collection addressed by the structural or navigation property \(p_1\) in \(u\), and let \(B=\Gamma(C,p_2)\). Then continue with step 9.
8. Let \(B=γ(v,p_2)\).
9. Return \(B\).

This notation is extended to the case of an empty path \(e\) by setting \(\Gamma(A,e)=A\) with null values removed. Note the collections returned by \(\Gamma\) and \(γ\) never contain the null value. Also, every instance \(u\) in \(\Gamma(A,p)\) occurs also in \(A\) or nested into \(A\), therefore an algorithmic step like “Add a dynamic property to each \(u\) in \(\Gamma(A,p)\)” effectively changes \(A\).

The concat transformation takes two or more parameters, each of which is a sequence of set transformations.

It applies each transformation sequence to the input set and concatenates the intermediate output sets in the order of the parameters into the output set, preserving the ordering of the individual output sets as well as the structure of each instance in these sets, potentially leading to a non-homogeneously structured output set. If different intermediate output sets contain dynamic properties with the same alias, clients SHOULD ensure they have the same type and meaning in each intermediate output set.

GET /service/Sales?$apply=concat(topcount(2,Amount),
                                 aggregate(Amount))

{
  "@context": "$metadata#Sales(Amount)",
  "value": [
    { "ID": 4, "Amount": 8 },
    { "ID": 3, "Amount": 4 },
    { "Amount": 24 }
  ]
}

The groupby transformation takes one or two parameters where the second is a list of set transformations, separated by forward slashes to express that they are consecutively applied. If the second parameter is not specified, it defaults to a single transformation whose output set consists of a single instance of the input type without properties and without entity-id.

GET /service/Sales?$apply=groupby((Customer/Country,Product/Name),
                                  aggregate(Amount with sum as Total))

{
  "@context": "$metadata#Sales(Customer(Country),Product(Name),Total)",
  "value": [
    { "Customer": { "Country": "Netherlands" },
      "Product": { "Name": "Paper" },
      "Total@type": "Decimal", "Total":  3 },
    { "Customer": { "Country": "Netherlands" },
      "Product": { "Name": "Sugar" },
      "Total@type": "Decimal", "Total":  2 },
    { "Customer": { "Country": "USA" },
      "Product": { "Name": "Coffee" },
      "Total@type": "Decimal", "Total": 12 },
    { "Customer": { "Country": "USA" },
      "Product": { "Name": "Paper" },
      "Total@type": "Decimal", "Total":  5 },
    { "Customer": { "Country": "USA" },
      "Product": { "Name": "Sugar" },
      "Total@type": "Decimal", "Total":  2 }
  ]
}

GET /service/Sales?$apply=groupby((Product/Name,Amount))

{
  "@context": "$metadata#Sales(Product(Name),Amount)",
  "value": [
    { "Product": { "Name": "Coffee" }, "Amount": 4 },
    { "Product": { "Name": "Coffee" }, "Amount": 8 },
    { "Product": { "Name": "Paper"  }, "Amount": 1 },
    { "Product": { "Name": "Paper"  }, "Amount": 2 },
    { "Product": { "Name": "Paper"  }, "Amount": 4 },
    { "Product": { "Name": "Sugar"  }, "Amount": 2 }
  ]
}

GET /service/Sales?$expand=Product($select=Name)&$select=Amount

GET /service/Sales?$apply=groupby((rollup(Customer/Country,Customer/Name),
                                   rollup(Product/Category/Name,Product/Name)),
                                  aggregate(Amount with sum as Total))

{
  "@context": "$metadata#Sales(Customer(Country),
                               Product(Category(Name)),Total)",
  "value": [
    { "Customer": { "Country": "USA", "Name": "Joe" },
      "Product":  { "Category": { "Name": "Non-Food" }, "Name": "Paper" },
      "Total@type": "Decimal", "Total": 1 },
    …

    { "Customer": { "Country": "USA" },
      "Product":  { "Category": { "Name": "Food" }, "Name": "Sugar" },
      "Total@type": "Decimal", "Total":  2 },
    …

    { "Customer": { "Country": "USA", "Name": "Joe" },
      "Product":  { "Category": { "Name": "Food" } },
      "Total@type": "Decimal", "Total":  6 },
    …

    { "Customer": { "Country": "USA" },
      "Product":  { "Category": { "Name": "Food" } },
      "Total@type": "Decimal", "Total": 14 },
    …
  ]
}

These transformations take two parameters. The first parameter MUST be an expression that is evaluable on the input set as a collection, without reference to an individual instance (and which therefore cannot be a property path). The second parameter MUST be an expression that is evaluated on each instance of the input set in turn.

The output set is constructed as follows:

1. Let \(A\) be a copy of the input set with a total order that is chosen by the service (it need not preserve any existing order). The total order MUST be stable across requests. (This is the order of the eventual output set of this transformation.)
2. Let \(B\) be a copy of \(A\) that is stable-sorted in ascending (for transformations starting with bottom) or descending (for transformations starting with top) order of the value specified in the second parameter. (This is the order in which contributions to the output set are considered.)
3. Start with an empty output set.
4. Loop over \(B\) in its total order.
5. Exit the loop if a condition is met. This condition depends on the transformation being executed and is given in the subsections below.
6. Insert the current item of the loop into the output set in the order of \(A\).
7. Continue the loop.

For example, if the input set consists of non-transient entities and the datastore contains an index ordered by the second parameter and then the entity-id, a service may implement this algorithm with \(A=B\) ordered like this index.

The order of the output set can be influenced with a subsequent orderby transformation.

GET /service/Sales?$apply=bottomcount(2,Amount)

{
  "@context": "$metadata#Sales",
  "value": [
    { "ID": 1, "Amount": 1 },
    { "ID": 7, "Amount": 1 }
  ]
}

GET /service/Sales?$apply=topcount(2,Amount)

{
  "@context": "$metadata#Sales",
  "value": [
    { "ID": 3, "Amount": 4 },
    { "ID": 4, "Amount": 8 }
  ]
}

GET /service/Sales?$apply=bottompercent(50,Amount)

{
  "@context": "$metadata#Sales",
  "value": [
    { "ID": 1, "Amount": 1 },
    { "ID": 2, "Amount": 2 },
    { "ID": 5, "Amount": 4 },
    { "ID": 6, "Amount": 2 },
    { "ID": 7, "Amount": 1 },
    { "ID": 8, "Amount": 2 }
  ]
}

GET /service/Sales?$apply=toppercent(50,Amount)

{
  "@context": "$metadata#Sales",
  "value": [
    { "ID": 3, "Amount": 4 },
    { "ID": 4, "Amount": 8 }
  ]
}

GET /service/Sales?$apply=bottomsum(7,Amount)

{
  "@context": "$metadata#Sales",
  "value": [
    { "ID": 1, "Amount": 1 },
    { "ID": 2, "Amount": 2 },
    { "ID": 6, "Amount": 2 },
    { "ID": 7, "Amount": 1 },
    { "ID": 8, "Amount": 2 }
  ]
}

GET /service/Sales?$apply=topsum(15,Amount)

{
  "@context": "$metadata#Sales",
  "value": [
    { "ID": 3, "Amount": 4 },
    { "ID": 4, "Amount": 8 },
    { "ID": 5, "Amount": 4 }
  ]
}

The filter transformation takes a Boolean expression that could also be passed as a $filter system query option. Its output set is the subset of the input set containing all instances (possibly with repetitions) for which this expression, evaluated relative to the instance, yields true. No order is defined on the output set.

GET /service/Sales?$apply=filter(Amount gt 3)

{
  "@context": "$metadata#Sales",
  "value": [
    { "ID": 3, "Amount": 4 },
    { "ID": 4, "Amount": 8 },
    { "ID": 5, "Amount": 4 }
  ]
}

The orderby transformation takes a list of expressions that could also be passed as a $orderby system query option. Its output set consists of the instances of the input set in the same order $orderby would produce for the given expressions, but keeping the relative order from the input set if the given expressions do not distinguish between two instances. The orderby transformation thereby performs a stable-sort. A service supporting this transformation MUST at least offer sorting by values addressed by property paths, including dynamic properties, with both suffixes asc and desc.

GET /service/Sales?$apply=groupby((Product/Name),
                           aggregate(Amount with sum as Total))
                   /orderby(Total desc)

{
  "@context": "$metadata#Sales(Product(Name),Total)",
  "value": [
    { "Product": { "Name": "Coffee" },
      "Total@type": "Decimal", "Total": 12 },
    { "Product": { "Name": "Paper" },
      "Total@type": "Decimal", "Total":  8 },
    { "Product": { "Name": "Sugar" },
      "Total@type": "Decimal", "Total":  4 }
  ]
}

The search transformation takes a search expression that could also be passed as a $search system query option. Its output set is the subset of the input set containing all instances (possibly with repetitions) that match this search expression. Closing parentheses in search expressions must be within single or double quotes in order to avoid syntax errors like search()). No order is defined on the output set.

GET /service/Sales?$apply=search(coffee)

{
  "@context": "$metadata#Sales",
  "value": [
    { "ID": 3, "Amount": 4 },
    { "ID": 4, "Amount": 8 }
  ]
}

The skip transformation takes a non-negative integer \(c\) as argument. Let \(A\) be a copy of the input set with a total order that extends any existing order of the input set but is otherwise chosen by the service. The total order MUST be stable across requests.

The transformation excludes from the output set the first \(c\) occurrences in \(A\). It keeps all remaining instances in the same order as they occur in \(A\).

GET /service/Sales?$apply=orderby(Customer/Name desc)/skip(2)/top(2)

{
  "@context": "$metadata#Sales",
  "value": [
    { "ID": 6, "Amount": 2 },
    { "ID": 7, "Amount": 1 }
  ]
}

The top transformation takes a non-negative integer \(c\) as argument. Let \(A\) be a copy of the input set with a total order that extends any existing order of the input set but is otherwise chosen by the service. The total order MUST be stable across requests.

If \(A\) contains more than \(c\) instances, the output set consists of the first \(c\) occurrences in \(A\). Otherwise, the output set equals \(A\). The instances in the output set are in the same order as they occur in \(A\).

Note the transformation top(0) produces an empty output set.

GET /service/Sales?$apply=orderby(Customer/Name desc)/top(2)

{
  "@context": "$metadata#Sales",
  "value": [
    { "ID": 4, "Amount": 8 },
    { "ID": 5, "Amount": 4 }
  ]
}

When the system query options $top and $skip OData-Protocol, section 11.2.6.3 are executed after the system query option $apply and after $filter and $orderby, if applicable, they operate on a collection with a total order that extends any existing order but is otherwise chosen by the service. The total order MUST be stable across requests.

The output set of the identity transformation is its input set in unchanged order.

GET /service/Sales?$apply=concat(identity,aggregate(Amount with sum as Total))

The compute transformation takes a comma-separated list of one or more compute expressions as parameters.

A compute expression is a common expression followed by the as keyword, followed by an alias.

The output set is constructed by copying the instances of the input set and adding one dynamic property per compute expression to each occurrence in the output set. The name of each added dynamic property is the alias of the corresponding compute expression. The value of each added dynamic property is computed relative to the corresponding instance. Services MAY support expressions that address dynamic properties added by other expressions within the same compute transformation, provided that the service can determine an evaluation sequence. The type of the property is determined by the rules for evaluating common expressions and numeric promotion defined in OData-URL, section 5.1.1.

GET /service/Sales?$apply=compute(Amount mul Product/TaxRate as Tax)

{
  "@context": "$metadata#Sales(*,Tax)",
  "value": [
    { "ID": 1, "Amount": 1, "Tax@type": "Decimal", "Tax": 0.14 },
    { "ID": 2, "Amount": 2, "Tax@type": "Decimal", "Tax": 0.12 },
    { "ID": 3, "Amount": 4, "Tax@type": "Decimal", "Tax": 0.24 },
    { "ID": 4, "Amount": 8, "Tax@type": "Decimal", "Tax": 0.48 },
    { "ID": 5, "Amount": 4, "Tax@type": "Decimal", "Tax": 0.56 },
    { "ID": 6, "Amount": 2, "Tax@type": "Decimal", "Tax": 0.12 },
    { "ID": 7, "Amount": 1, "Tax@type": "Decimal", "Tax": 0.14 },
    { "ID": 8, "Amount": 2, "Tax@type": "Decimal", "Tax": 0.28 }
  ]
}

The addnested transformation expands a path relative to the input set, applies one or more transformation sequences to the addressed resources, and adds the transformed resources as dynamic (navigation) properties to the output set. The output set \(A\) is initially a clone of the input set.

The first parameter of the addnested transformation is a path \(p\) or a concatenated path \(p/q\). Here, \(p=p_1/…/p_k\) with \(k≥1\) is a data aggregation path with single- or collection-valued segments. The path \(p\) MUST NOT contain any navigation properties prior to the last segment \(p_k\), which MUST either be a navigation or a complex structural property. If the optional \(q\) is present, it MUST be a type-cast segment. This is an extension of the definition in OData-URL, section 5.1.3 in that the first parameter need not contain a navigation property.

Further parameters are one or more transformation sequences followed by the as keyword followed by an alias whose name need not differ from names in the input set but MUST differ from names already in \(\Gamma(A,p_1/…/p_{k-1})\) (using the \(\Gamma\) notation) as well as from aliases for other transformation sequences.

If \(p_k\) is single-valued, the transformation sequences MUST consist of only identity or compute or addnested transformations, because these transform one-element collections into one-element collections. This makes it meaningful to speak (in this section only) of a transformation sequence applied to a single instance; this means applying it to a collection containing the single instance and taking as result the single instance from the output set.

For each occurrence \(u\) in \(\Gamma(A,p_1/…/p_{k-1})\), let \(B=γ(u,p_k/q)\) and let the resource \(v\) be

• the collection \(B\) if \(p_k\) is collection-valued
• the single instance in \(B\) if \(p_k\) is single-valued and \(B\) is non-empty
• undefined if \(p_k\) is single-valued and \(B\) is empty.

If \(v\) is defined, then for each transformation sequence, a dynamic property is added to \(u\) as follows: If \(p_k\) is a navigation property, the added property is a dynamic navigation property, which is expanded by default, otherwise it is a dynamic structural property. Its name is the alias of the transformation sequence. The value of the added property is the result of the transformation sequence applied to \(v\). The dynamic property carries as control information the context URL of \(v\).

GET /service/Customers?$apply=addnested(Sales,
                                        filter(Amount gt 3) as FilteredSales)

{
  "@context": "$metadata#Customers(FilteredSales())",
  "value": [
    { "ID": "C1", "Name": "Joe", "Country": "USA",
      "FilteredSales@context": "#Sales",
      "FilteredSales": [{ "ID": "3", "Amount": 4 }]},
    { "ID": "C2", "Name": "Sue", "Country": "USA",
      "FilteredSales@context": "#Sales",
      "FilteredSales": [{ "ID": "4", "Amount": 8 },
                        { "ID": "5", "Amount": 4 }]},
    { "ID": "C3", "Name": "Sue", "Country": "Netherlands",
      "FilteredSales@context": "#Sales",
      "FilteredSales": []},
    { "ID": "C4", "Name": "Luc", "Country": "France",
      "FilteredSales@context": "#Sales",
      "FilteredSales": []}
  ]
}

The join and outerjoin transformations take as their first parameter \(p\) a collection-valued complex or navigation property, optionally followed by a type-cast segment to address only instances of that derived type or one of its sub-types, followed by the as keyword, followed by an alias. The optional second parameter specifies a transformation sequence \(T\).

For each occurrence \(u\) in an order-preserving loop over the input set

1. the instance collection \(A\) addressed by \(p\) is identified.
2. If \(T\) is provided, \(A\) is replaced with the result of applying \(T\) to \(A\).
3. In case of an outerjoin, if \(A\) is empty, a null instance is added to it.
4. For each occurrence \(v\) in an order-preserving loop over \(A\) an instance \(w\) is appended to the output set of the transformation:
   • The instance \(w\) is a clone of \(u\) with an additional dynamic property whose name is the given alias and whose value is \(v\).
   • The dynamic property is a navigation property if \(p\) is a collection-valued navigation property, otherwise it is a complex property.
   • The dynamic property carries as control information the context URL of \(v\).

GET /service/Products?$apply=join(Sales as Sale)&$select=ID&$expand=Sale

{
  "@context": "$metadata#Products(ID,Sale())",
  "value": [
    { "ID": "P1",
      "Sale": {
        "@context": "#Sales/$entity",
        "ID": 2, "Amount": 2 } },
    { "ID": "P1",
      "Sale": {
        "@context": "#Sales/$entity",
        "ID": 6, "Amount": 2 } },
    { "ID": "P2",
      "Sale": {
        "@context": "#Sales/$entity",
        "ID": 3, "Amount": 4 } },
    { "ID": "P2",
      "Sale": {
        "@context": "#Sales/$entity",
        "ID": 4, "Amount": 8 } },
    { "ID": "P3",
      "Sale": {
        "@context": "#Sales/$entity",
        "ID": 1, "Amount": 1 } },
    { "ID": "P3",
      "Sale": {
        "@context": "#Sales/$entity",
        "ID": 5, "Amount": 4 } },
    { "ID": "P3",
      "Sale": {
        "@context": "#Sales/$entity",
        "ID": 7, "Amount": 1 } },
    { "ID": "P3",
      "Sale": {
        "@context": "#Sales/$entity",
        "ID": 8, "Amount": 2 } }
  ]
}

The nest transformation takes as parameters one or more transformation sequences followed by the as keyword followed by an alias.

The output set consists of a single instance of the input type without entity-id having one dynamic property per transformation sequence. The name of the dynamic property is the alias for this transformation sequence. The value of the dynamic property is the collection resulting from the transformation sequence applied to the input set. The dynamic property carries as control information the context URL of the transformed input set.

GET /service/Sales?$apply=nest(groupby((Customer/ID)) as Customers)

{
  "@context": "$metadata#Sales(Customers())",
  "value": [
    { "Customers@context": "#Sales(Customer(ID))",
      "Customers": [ { "Customer": { "ID": "C1" } },
                     { "Customer": { "ID": "C2" } },
                     { "Customer": { "ID": "C3" } } ] }
  ]
}

The aggregate function allows the use of aggregated values in expressions. It takes a single parameter accepting an aggregate expression and returns the aggregated value of type Edm.PrimitiveType as the result from applying the aggregate expression on its input collection.

More precisely, if \(α\) is an aggregate expression, the function \(p/{\tt aggregate}(α)\) or \({\tt\$these}/{\tt aggregate}(α)\) evaluates to the value of the property \(D\) in the single instance of the output set that is produced when the transformation \({\tt aggregate}(α{\tt\ as\ }D)\) is applied with the input collection as input set.

GET /service/Sales?$filter=Amount mul 3 ge $these/aggregate(Amount with sum)

{
  "@context": "$metadata#Sales",
  "value": [
    { "ID": "4", "Amount": 8 }
  ]
}

GET /service/Products?$filter=Sales/aggregate(Amount mul $it/TaxRate with sum)
                              gt 1

GET /service/Products?$filter=Sales/any(s:s/Amount ge
                              Sales/aggregate(Amount with average) mul 2)

{
  "@context": "$metadata#Products",
  "value": [
    { "ID": "P3", "Name": "Paper", "Color": "White", "TaxRate": 0.14 }
  ]
}

The expression $count evaluates to the cardinality of the input collection.

GET /service/Sales?$apply=topcount($these/$count div 3,Amount)

{
  "@context": "$metadata#Sales",
  "value": [
    { "ID": 3, "Amount": 4 },
    { "ID": 4, "Amount": 8 }
  ]
}

A definition that is equivalent to a $count expression after a collection-valued path was made in OData-URL, section 4.8.

A leveled hierarchy has a fixed number of levels each of which is represented by a grouping property. The values of a lower-level property depend on the property value of the level above.

A leveled hierarchy can be defined for a collection of instances of an entity or complex type and is described with the term LeveledHierarchy that lists the properties used to form the hierarchy.

The order of the collection is significant: it lists paths from the entity or complex type where the term is applied to groupable properties representing the levels, starting with the root level (coarsest granularity) down to the lowest (finest-grained) level of the hierarchy.

The term LeveledHierarchy MUST be applied with a qualifier that can be used to reference the hierarchy in grouping with rollup.

A recursive hierarchy is defined on a collection of entities by

• determining which entities are part of the hierarchy and giving every such entity a single primitive non-null value that uniquely identifies it within the hierarchy. These entities are called nodes, and the primitive value is called the node identifier, and
• associating with every node zero or more nodes from the same collection, called its parent nodes.

The recursive hierarchy is described in the model by an annotation of the entity type with the complex term RecursiveHierarchy with these properties:

• The NodeProperty MUST be a path with single-valued segments ending in a primitive property. This property holds the node identifier of an entity that is a node in the hierarchy.
• The ParentNavigationProperty MUST be a collection-valued or nullable single-valued navigation property path that addresses the entity type annotated with this term. It navigates from an entity that is a node in the hierarchy to its parent nodes.

The term RecursiveHierarchy can only be applied to entity types, and MUST be applied with a qualifier, which is used to reference the hierarchy in transformations operating on recursive hierarchies, in grouping with rolluprecursive, and in hierarchy functions. The same entity can serve as nodes in different recursive hierarchies, given different qualifiers.

A root node is a node without parent nodes. A recursive hierarchy can have one or more root nodes. A node is a child node of its parent nodes, a node without child nodes is a leaf node. Two nodes with a common parent node are sibling nodes and so are two root nodes.

The descendants with maximum distance \(d≥1\) of a node are its child nodes and, if \(d>1\), the descendants of these child nodes with maximum distance \(d-1\). The descendants are the descendants with maximum distance \(d=∞\). A node together with its descendants forms a sub-hierarchy of the hierarchy.

The ancestors with maximum distance \(d≥1\) of a node are its parent nodes and, if \(d>1\), the ancestors of these parent nodes with maximum distance \(d-1\). The ancestors are the ancestors with maximum distance \(d=∞\). The ParentNavigationProperty MUST be such that no node is an ancestor of itself, in other words: cycles are forbidden.

The term UpPath can be used in hierarchical result sets to associate with each instance one of its ancestors, one ancestor of that ancestor and so on. This instance annotation is introduced in section 6.2.2.

The hierarchy terms can be applied to the Example Data Model.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<edmx:Edmx xmlns:edmx="http://docs.oasis-open.org/odata/ns/edmx"
           Version="4.0">
  <edmx:Reference Uri="https://docs.oasis-open.org/odata/odata-data-
    aggregation-ext/v4.0/cs03/vocabularies/Org.OData.Aggregation.V1.xml">
    <edmx:Include Alias="Aggregation"
                  Namespace="Org.OData.Aggregation.V1" />
  </edmx:Reference>
  <edmx:DataServices>
    <Schema xmlns="http://docs.oasis-open.org/odata/ns/edm"
            Alias="SalesModel" Namespace="org.example.odata.salesservice">
      <Annotations Target="SalesModel.Product">
        <Annotation Term="Aggregation.LeveledHierarchy"
                    Qualifier="ProductHierarchy">
          <Collection>
            <PropertyPath>Category/Name</PropertyPath>
            <PropertyPath>Name</PropertyPath>
          </Collection>
        </Annotation>
      </Annotations>

      <Annotations Target="SalesModel.Time">
        <Annotation Term="Aggregation.LeveledHierarchy"
                    Qualifier="TimeHierarchy">
          <Collection>
            <PropertyPath>Year</PropertyPath>
            <PropertyPath>Quarter</PropertyPath>
            <PropertyPath>Month</PropertyPath>
          </Collection>
        </Annotation>
      </Annotations>

      <Annotations Target="SalesModel.SalesOrganization">
        <Annotation Term="Aggregation.RecursiveHierarchy"
                    Qualifier="SalesOrgHierarchy">
          <Record>
            <PropertyValue Property="NodeProperty"
                           PropertyPath="ID" />
            <PropertyValue Property="ParentNavigationProperty"
                           PropertyPath="Superordinate" />
          </Record>
        </Annotation>
      </Annotations>
    </Schema>
  </edmx:DataServices>
</edmx:Edmx>

The recursive hierarchy SalesOrgHierarchy can be used in functions with the $filter system query option.

GET /service/SalesOrganizations?$filter=Aggregation.isdescendant(
  HierarchyNodes=$root/SalesOrganizations,
  HierarchyQualifier='SalesOrgHierarchy',
  Node=ID,
  Ancestor='EMEA')

{
  "@context": "$metadata#SalesOrganizations",
  "value": [
    { "ID": "EMEA Central",      "Name": "EMEA Central" },
    { "ID": "Sales Netherlands", "Name": "Sales Netherlands" },
    { "ID": "Sales Germany",     "Name": "Sales Germany" },
    { "ID": "EMEA South",        "Name": "EMEA South" },
    …
    { "ID": "EMEA North",        "Name": "EMEA North" },
    …
  ]
}

GET /service/SalesOrganizations?$filter=Aggregation.isdescendant(
  HierarchyNodes=$root/SalesOrganizations,
  HierarchyQualifier='SalesOrgHierarchy',
  Node=ID,
  Ancestor='EMEA',
  MaxDistance=1)

{
  "@context": "$metadata#SalesOrganizations",
  "value": [
    { "ID": "EMEA Central", "Name": "EMEA Central" },
    { "ID": "EMEA South",   "Name": "EMEA South" },
    { "ID": "EMEA North",   "Name": "EMEA North" },
    …
  ]
}

GET /service/SalesOrganizations?$filter=Aggregation.isleaf(
  HierarchyNodes=$root/SalesOrganizations,
  HierarchyQualifier='SalesOrgHierarchy',
  Node=ID)

{
  "@context": "$metadata#SalesOrganizations",
  "value": [
    { "ID": "Sales Office London",   "Name": "Sales Office London" },
    { "ID": "Sales Office New York", "Name": "Sales Office New York" },
    …
  ]
}

GET /service/SalesOrganizations?$filter=Aggregation.isleaf(
  HierarchyNodes=$root/SalesOrganizations,
  HierarchyQualifier='SalesOrgHierarchy',
  Node=ID)
&$expand=Superordinate($select=ID)

{
  "@context": "$metadata#SalesOrganizations(*,Superordinate(ID))",
  "value": [
    { "ID": "Sales Office London",   "Name": "Sales Office London",
      "Superordinate": { "ID": "EMEA United Kingdom" } },
    { "ID": "Sales Office New York", "Name": "Sales Office New York",
      "Superordinate": { "ID": "US East" } },
    …
  ]
}

GET /service/Sales?$select=ID&$filter=Aggregation.isdescendant(
  HierarchyNodes=$root/SalesOrganizations,
  HierarchyQualifier='SalesOrgHierarchy',
  Node=SalesOrganization/ID,
  Ancestor='EMEA')

{
  "@context": "$metadata#Sales(ID)",
  "value": [
    { "ID": 6 },
    { "ID": 7 },
    { "ID": 8 }
  ]
}

Further examples for recursive hierarchies using transformations operating on the hierarchy structure are provided in section 7.9.

In the simple case, the ancestors transformation takes an input set consisting of instances that belong to a recursive hierarchy \((H,Q)\). It determines a subset \(A\) of the input set and then determines the set of ancestors of \(A\) that were already contained in the input set. Its output set is the ancestors set, optionally including \(A\).

In the more complex case, the instances in the input set are instead related to nodes in a recursive hierarchy. Then the ancestors transformation determines a subset \(A\) of the input set consisting of instances that are related to certain nodes in the hierarchy, called start nodes. The ancestors of these start nodes are then determined, and the output set consists of instances of the input set that are related to the ancestors, or optionally to the start nodes.

The descendants transformation works analogously, but with descendants.

\(H\), \(Q\) and \(p\) are the first three parameters defined above.

The fourth parameter is a transformation sequence \(T\) composed of transformations listed section 3.3 or section 6.2.1 and of service-defined bound functions whose output set is a subset of their input set. \(A\) is the output set of this sequence applied to the input set.

The fifth parameter \(d\) is optional and takes an integer greater than or equal to 1 that specifies the maximum distance between start nodes and ancestors or descendants to be considered. An optional final keep start parameter drives the optional inclusion of the subset or start nodes.

The output set of the transformation \({\tt ancestors}(H,Q,p,T,d,{\tt keep\ start})\) or \({\tt descendants}(H,Q,p,T,d,{\tt keep\ start})\) is defined as the union of the output sets of transformations \(F(u)\) applied to the input set for all \(u\) in \(A\). For a given instance \(u\), the transformation \(F(u)\) determines all instances of the input set whose node identifier is an ancestor or descendant of the node identifier of \(u\):

If \(p\) contains only single-valued segments, then, for ancestors, \[\matrix{ F(u)={\tt filter}(\hbox{\tt Aggregation.isancestor}(\hfill\\ \quad {\tt HierarchyNodes}=H,\;{\tt HierarchyQualifier}=\hbox{\tt{'$Q$'}},\hfill\\ \quad {\tt Node}=p,\;{\tt Descendant}=u[p],\;{\tt MaxDistance}=d,\;{\tt IncludeSelf}={\tt true}))\hfill }\] or, for descendants, \[\matrix{ F(u)={\tt filter}(\hbox{\tt Aggregation.isdescendant}(\hfill\\ \quad {\tt HierarchyNodes}=H,\;{\tt HierarchyQualifier}=\hbox{\tt{'$Q$'}},\hfill\\ \quad {\tt Node}=p,\;{\tt Ancestor}=u[p],\;{\tt MaxDistance}=d,\;{\tt IncludeSelf}={\tt true})).\hfill }\]

Otherwise \(p=p_1/…/p_k/r\) with \(k≥1\), in this case the output set of the transformation \(F(u)\) is defined as the union of the output sets of transformations \(G(n)\) applied to the input set for all \(n\) in \(γ(u,p)\). The output set of \(G(n)\) consists of the instances of the input set whose node identifier is an ancestor or descendant of the node identifier \(n\):

For ancestors, \[\matrix{ G(n)={\tt filter}(\hfill\\ \hskip1pc p_1/{\tt any}(y_1:\hfill\\ \hskip2pc y_1/p_2/{\tt any}(y_2:\hfill\\ \hskip3pc ⋱\hfill\\ \hskip4pc y_{k-1}/p_k/{\tt any}(y_k:\hfill\\ \hskip5pc \hbox{\tt Aggregation.isancestor}(\hfill\\ \hskip6pc {\tt HierarchyNodes}=H,\;{\tt HierarchyQualifier}=\hbox{\tt{'$Q$'}},\hfill\\ \hskip6pc {\tt Node}=y_k/r,\;{\tt Descendant}=n,\;{\tt MaxDistance}=d,\;{\tt IncludeSelf}={\tt true}\hfill\\ \hskip5pc )\hfill\\ \hskip4pc )\hfill\\ \hskip3pc ⋰\hfill\\ \hskip2pc )\hfill\\ \hskip1pc )\hfill\\ )\hfill }\] or, for descendants, \[\matrix{ G(n)={\tt filter}(\hfill\\ \hskip1pc p_1/{\tt any}(y_1:\hfill\\ \hskip2pc y_1/p_2/{\tt any}(y_2:\hfill\\ \hskip3pc ⋱\hfill\\ \hskip4pc y_{k-1}/p_k/{\tt any}(y_k:\hfill\\ \hskip5pc \hbox{\tt Aggregation.isdescendant}(\hfill\\ \hskip6pc {\tt HierarchyNodes}=H,\;{\tt HierarchyQualifier}=\hbox{\tt{'$Q$'}},\hfill\\ \hskip6pc {\tt Node}=y_k/r,\;{\tt Ancestor}=n,\;{\tt MaxDistance}=d,\;{\tt IncludeSelf}={\tt true}\hfill\\ \hskip5pc )\hfill\\ \hskip4pc )\hfill\\ \hskip3pc ⋰\hfill\\ \hskip2pc )\hfill\\ \hskip1pc )\hfill\\ )\hfill }\] where \(y_1,…,y_k\) denote lambdaVariableExprs as defined in OData-ABNF and \({}/r\) may be absent.

If parameter \(d\) is absent, the parameter \({\tt MaxDistance}=d\) is omitted. If keep start is absent, the parameter \({\tt IncludeSelf}={\tt true}\) is omitted.

Since the output set of ancestors is constructed as a union, no instance from the input set will occur more than once in it, even if, for example, a sale is related to both a sales organization and one of its ancestor organizations. For descendants, analogously.

GET /service/SalesOrganizations?$apply=
    ancestors($root/SalesOrganizations,SalesOrgHierarchy,ID,
              filter(contains(Name,'East') or contains(Name,'Central')))
  &$expand=Superordinate/$ref

{
  "@context": "$metadata#SalesOrganizations",
  "value": [
    { "ID": "EMEA",  "Name": "EMEA",
      "Superordinate": { "@id": "SalesOrganizations('Sales')" } },
    { "ID": "US",    "Name": "US",
      "Superordinate": { "@id": "SalesOrganizations('Sales')" } },
    { "ID": "Sales", "Name": "Sales",
      "Superordinate": null }
  ]
}

GET /service/SalesOrganizations?$apply=
    descendants($root/SalesOrganizations,SalesOrgHierarchy,ID,
                filter(Name eq 'US'),keep start)
  &$expand=Superordinate/$ref

{
  "@context": "$metadata#SalesOrganizations",
  "value": [
    { "ID": "US West", "Name": "US West",
      "Superordinate": { "@id": "SalesOrganizations('US')" } },
    { "ID": "US",      "Name": "US",
      "Superordinate": { "@id": "SalesOrganizations('Sales')" } },
    { "ID": "US East", "Name": "US East",
      "Superordinate": { "@id": "SalesOrganizations('US')" } }
  ]
}

GET /service/Sales?$apply=
    ancestors($root/SalesOrganizations,
              SalesOrgHierarchy,
              SalesOrganization/ID,
              filter(contains(SalesOrganization/Name,'East')
                  or contains(SalesOrganization/Name,'Central')),
              keep start)

{
  "@context": "$metadata#Sales",
  "value": [
    { "ID": "4", "Amount": 8,
      "SalesOrganization": { "ID": "US East",      "Name": "US East" } },
    { "ID": "5", "Amount": 4,
      "SalesOrganization": { "ID": "US East",      "Name": "US East" } },
    { "ID": "6", "Amount": 2,
      "SalesOrganization": { "ID": "EMEA Central", "Name": "EMEA Central" } },
    { "ID": "7", "Amount": 1,
      "SalesOrganization": { "ID": "EMEA Central", "Name": "EMEA Central" } },
    { "ID": "8", "Amount": 2,
      "SalesOrganization": { "ID": "EMEA Central", "Name": "EMEA Central" } }
  ]
}

The traverse transformation returns instances of the input set that are or are related to nodes of a given recursive hierarchy in a specified tree order.

\(H\), \(Q\) and \(p\) are the first three parameters defined above.

The fourth parameter \(h\) of the traverse transformation is either preorder or postorder. \(S\) is an optional fifth parameter as defined above. Let \(H'\) be the output set of the transformation sequence \(S\) applied to \(H\), or let \(H'\) be the collection of root nodes in the recursive hierarchy \((H,Q)\) if \(S\) is not specified. Nodes in \(H'\) are called start nodes in this subsection (see example 117).

All following parameters are optional and form a list \(o\) of expressions that could also be passed as a $orderby system query option. If \(o\) is present, the transformation stable-sorts \(H'\) by \(o\).

The instances in the input set are related to one node (if \(p\) is single-valued) or multiple nodes (if \(p\) is collection-valued) in the recursive hierarchy. Given a node \(x\), denote by \(\hat F(x)\) the collection of all instances in the input set that are related to \(x\); these collections can overlap. For each \(u\) in \(\hat F(x)\), the output set contains one instance that comprises the properties of \(u\) and additional properties that identify the node \(x\). These additional properties are independent of \(u\) and are bundled into an instance called \(σ(x)\). For example, if a sale \(u\) is related to two sales organizations and hence contained in both \(\hat F(x_1)\) and \(\hat F(x_2)\), the output set will contain two instances \((u,σ(x_1))\) and \((u,σ(x_2))\) and \(σ(x_i)\) contributes a navigation property SalesOrganization.

A transformation \(F(x)\) is defined below such that \(\hat F(x)\) is the output set of \(F(x)\) applied to the input set of the traverse transformation.

Given a node \(x\), the formulas below contain the transformation \(\Pi_G(σ(x))\) in order to inject the properties of \(σ(x)\) into the instances in \(\hat F(x)\); this uses the function \(\Pi_G\) that is defined in the simple grouping section. Further, \(G\) is a list of data aggregation paths that shall be present in the output set, and \(σ\) is a function that maps each hierarchy node \(x\) to an instance of the input type containing the paths from \(G\). As a consequence of the following definitions, only single-valued properties and “final segments from \(G\)” are nested into \(σ(x)\), therefore the behavior of \(\Pi_G(σ(x))\) is well-defined.

The definition of \(σ(x)\) makes use of a function \(a(ε,t,x)\), which returns a sparsely populated instance \(u\) in which only the path \(t\) has a value, namely \(u[t]=x\).

Three cases are distinguished:

1. Case where the recursive hierarchy is defined on the input set
   This case applies if the paths \(p\) and \(q\) are equal. Let \(σ(x)=x\) and let \(G\) be a list containing all structural and navigation properties of the entity type of \(H\).
   In this case \(\Pi_G(σ(x))\) injects all properties of \(x\) into the instances of the output set. (See example 65.)
2. Case where the recursive hierarchy is defined on the related entity type addressed by a navigation property path
   This case applies if \(p'\) is a non-empty navigation property path and \(p''\) an optional type-cast segment such that \(p\) equals the concatenated path \(p'/p''/q\). Let \(σ(x)=a(ε,p'/p'',x)\) and let \(G=(p')\).
   In this case \(\Pi_G(σ(x))\) injects the whole related entity \(x\) into the instances of the output set. The navigation property path \(p'\) is expanded by default. (See example 66.)
3. Case where the recursive hierarchy is related to the input set only through equality of node identifiers, not through navigation
   If neither case 1 nor case 2 applies, let \(σ(x)=a(ε,p,x[q])\) and let \(G=(p)\).
   In this case \(\Pi_G(σ(x))\) injects only the node identifier of \(x\) into the instances of the output set.

Here paths are considered equal if their non-type-cast segments refer to the same model elements when evaluated relative to the input set (see example 68).

The function \(a(u,t,x)\) takes an instance, a path and another instance as arguments and is defined recursively as follows:

1. If \(u\) equals the special symbol \(ε\), set \(u\) to a new instance of the input type without properties and without entity-id.
2. If \(t\) contains only one segment other than a type cast, let \(t_1=t\), and let \(x'=x\), then go to step 6.
3. Otherwise, let \(t_1\) be the first property segment in \(t\), possibly together with a preceding type-cast segment, let \(t_2\) be any type-cast segment that immediately follows, and let \(t_3\) be the remainder such that \(t\) equals the concatenated path \(t_1/t_2/t_3\) where \({}/t_2\) may be absent.
4. Let \(u'\) be an instance of the type of \(t_1/t_2\) without properties and without entity-id.
5. Let \(x'=a(u',t_3,x)\).
6. If \(t_1\) is single-valued, let \(u[t_1]=x'\).
7. If \(t_1\) is collection-valued, let \(u[t_1]\) be a collection consisting of one item \(x'\).
8. Return \(u\).

(See example 112.)

GET /service/SalesOrganizations?$apply=
    descendants($root/SalesOrganizations,SalesOrgHierarchy,ID,
                Name eq 'US',keep start)
    /ancestors($root/SalesOrganizations,SalesOrgHierarchy,ID,
                contains(Name,'East'),keep start)
    /traverse($root/SalesOrganizations,SalesOrgHierarchy,ID,preorder)
  &$expand=Superordinate/$ref

{
  "@context": "$metadata#SalesOrganizations",
  "value": [
    { "ID": "US",      "Name": "US",
      "Superordinate": { "@id": "SalesOrganizations('Sales')" } },
    { "ID": "US East", "Name": "US East",
      "Superordinate": { "@id": "SalesOrganizations('US')" } }
  ]
}

GET /service/SalesOrganizations?$apply=
    traverse($root/SalesOrganizations,MultiParentHierarchy,ID,preorder)

{
  "@context": "$metadata#SalesOrganizations",
  "value": [
    …
    { "ID": "Atlantis", "Name": "Atlantis",
      "@Aggregation.UpPath#MultiParentHierarchy":
        [ "US", "Sales" ] },
    { "ID": "AtlantisChild", "Name": "Child of Atlantis",
      "@Aggregation.UpPath#MultiParentHierarchy":
         [ "Atlantis", "US", "Sales" ] },
    …
    { "ID": "Atlantis", "Name": "Atlantis",
      "@Aggregation.UpPath#MultiParentHierarchy":
        [ "EMEA", "Sales" ] },
    { "ID": "AtlantisChild", "Name": "Child of Atlantis",
      "@Aggregation.UpPath#MultiParentHierarchy":
        [ "Atlantis", "EMEA", "Sales" ] },
    …
  ]
}