Show TOC

Defining RequestsLocate this document in the navigation structure

A defining request is a read request that targets the OData endpoint associated with the offline store and retrieves a subset of the endpoint data. Multiple defining requests can be defined for each endpoint.

Defining requests retrieve data from the OData Producer that is sent to the client, either during initialization of the offline store or during a refresh.

To set up defining requests, use the ODataOfflineStoreOptions object from the OData Offline API. The application automatically populates the “definingRequests” parameter. You can then reference each request in the application configuration file, as shown below:


Keep the following in mind when writing defining requests:

  • Currently, only defining requests where the resource path identifies an entity set or entity type instance are supported.
  • Shared request names must be unique, and must be identical on both the client and server.
  • If you are using a mix of delta-enabled and nondelta-enabled defining requests, and you are using referential constraints to build relationships, the dependent entity in a relationship cannot be in a delta-enabled defining request if the principal entity is in a nondelta-enabled relationship.
  • If you are not using deltas, you can use the same entity type in more than one defining request, but you cannot perform a selective refresh of one of those defining requests without the others.
  • If you are using a mix of delta-enabled and nondelta-enabled requests, you cannot use the same entity type in both a delta-enabled and a nondelta-enabled defining request, either directly referenced in the resource path or through an $expand.
Using Defining Requests to Build Entity Relationships

To build relationships in your application, you can use $expand queries, referential constraints, or a combination of the two.

  • Referential constraints

    If you are tracking deltas using the OData Producer and require entity relationships in the offline store, you cannot use $expand queries but instead must have associations with a referential constraint. Ensure that each defining request references a single entity set. The server detects the associations with referential constraints and uses these referential constraints to build the relationships between the types selected in your defining requests.

    For example, the sample metadata document has an association between CustomerType and OrderType, called CustomerType_OrderType, which defines a referential constraint. If you specify two defining requests, ~/Customers and ~/Orders, the server uses the referential constraint defined in the association CustomerType_OrderType to build the relationship between the Customers and Orders entity sets in the offline store.

  • $expand queries

    Use $expand queries to build relationships between entity sets only if you are not tracking deltas, or if you are tracking deltas using the server. You cannot use $expand queries if you are tracking deltas using the OData Producer.

  • Combining referential constraints and $expand queries

    When you use an $expand to expand the relationship between two top-level entity sets, an association set is being implicitly referenced. For example, ~/Customer?$expand=Orders implicitly references the Customers_Orders association set. The SAP Mobile Platform server allows you to mix referential constraints and $expand to build relationships. However, you cannot mix referential constraints and $expand for the same implicitly referenced association set.

    Consider the following example, which uses entity sets from the sample metadata document:


    The relationship between Customers and Orders is computed using the $expand, but relationships between Orders, OrderItems, and Products are computed using referential constraints.

    In the example below, the relationships between Orders, OrderItems, and Products is computed using referential constraints. However, only the relationship between Orders and Customers in Canada is computed using the $expand. The relationship between Customers in the US and Orders is not computed using referential constraints because the Customers_Orders association set is implicitly expanded in the first defining request.

    ~/Customers?$expand=Orders&$filter=Country eq 'CAN'
    ~/Customers?$filter=Country eq 'US'