A defining query is a read query that targets the OData service associated with the offline store and retrieves a subset of the endpoint data. Multiple defining queries can be defined for each endpoint.
Defining queries retrieve data from the OData service that is sent to the client, either during initialization of the offline store or during a download.
Defining queries are set up in both the application source code and in the application configuration file (if non-default behaviors are expected). In the source code, use the
add() method from
OfflineODataProvider class with an instance of the
OfflineODataDefiningQuery class constructed with a name, a query, and a flag for whether or not automatically retrieving streams. The example below demonstrates how the defining queries retrieve all information for one event.
/// Expand is needed to create a many-to-many relationship between Event and Feature /// since there is no referential constraint defined on the relationship. /// Data sharing should be enabled as all users see the same information try provider.add(definingQuery: OfflineODataDefiningQuery(name: "Events_10000", query: "/Events?$filter=EventID eq 10000L&$expand=Features", automaticallyRetrievesStreams: false)) /// One-to-many relationship between Event and Session is built via referential constraint. /// Data sharing should be enabled try provider.add(definingQuery: OfflineODataDefiningQuery(name: "Sessions_10000", query: "/Sessions?$filter=EventID eq 10000L", automaticallyRetrievesStreams: false)) /// Data sharing should be enabled try provider.add(definingQuery: OfflineODataDefiningQuery(name: "Tracks_10000", query: "/Tracks?$filter=EventID eq 10000L", automaticallyRetrievesStreams: false)) /// User Specific data; data sharing should be off try provider.add(definingQuery: OfflineODataDefiningQuery(name: "UserSessionAgendas", query: "/UserSessionAgendas?$filter=EventID eq 10000L", automaticallyRetrievesStreams: false)) /// Data sharing should be enabled try provider.add(definingQuery: OfflineODataDefiningQuery(name: "Features", query: "/Features", automaticallyRetrievesStreams: false))
In the application configuration file, reference each defining query using the same name as the one written in the source code (the first parameter to the
OfflineODataDefiningQuery constructor), as shown in the following example:
[defining_query] name=Events_10000 is_shared_data=Y download_interval=10 track_deltas=AUTO delta_token_lifetime=36000 [defining_query] name=UserSessionsAgendas is_shared_data=N
In the example, the defining query Events_10000 is declared as shareable, which means that the event and related features can be accessed by all users.
Usually, you'll specify defining queries before opening the offline store for the first time, but they can also be added or removed afterwards if appropriate. You can use the
getDefiningQueries method from the
OfflineODataProvider class to fetch all existing defining queries.
Keep the following in mind when writing defining queries:
- Currently, only defining queries where the resource path identifies an entity set or entity type instance (a single entity) are supported.
- Shared defining query names must be unique, and must be identical on both the client and server. Otherwise, expected settings will not be applied to the correct defining query and the query will be using the default settings instead.
- If you are using a mix of delta enabled and non-delta enabled defining queries, and you are using referential constraints to build relationships, the dependent entity in a relationship cannot be in a delta enabled defining query if the principal entity is in a non-delta enabled relationship. For example, say you have two defining queries, Events and Sessions (based on the sample metadata). Since there is a referential constraint between them and no expands are specified, the mobile service automatically uses the referential constraint to build relationships. The events are principal entities and the sessions are dependent entities. If the Events defining query is not delta enabled, then the Sessions defining query must not be delta enabled. However, if the Events defining query is delta enabled, the Sessions defining query may or may not be delta enabled.
- If you are not using deltas, you can use the same entity sets in more than one defining query, but you cannot perform a selective download of one of those defining queries without the others.
- If you are using a mix of delta enabled and non-delta enabled defining queries, you cannot use the same entity set in both a delta enabled and a non-delta enabled defining query, either directly referenced in the resource path or through an $expand.
Removing Defining Queries¶
You can always remove a stream-defining query. For non-stream defining queries, before opening the offline store, if a defining query is specified for the first time then you can remove it immediately. After opening the offline store, in the default configuration, neither existing defining queries, nor new specifying defining queries can be removed. To remove a defining query and its entities in the local store, you need to set
Y. This will allow the server and local store to keep track of the mapping between defining queries and entities. If you do not need to remove any general defining queries, leave
N for better performance. Turning
allow_defining_query_removal on or off will cause the server to reinitialize the offline store for the client during a download. This will take more time than the normal download and if the client has any pending changes, they will not take place until pending changes are uploaded or deleted.
Using Defining Queries to Build Entity Relationships¶
To build relationships in your application, you can use
$expand in queries, referential constraints, or a combination of the two.
$expand in queries
$expand in queries to build relationships between entity sets only if you are not tracking deltas, or if you are tracking deltas using the mobile service. You cannot use
$expand in queries if you are tracking deltas using the OData service.
: If you are tracking deltas using the OData service and require entity relationships in the offline store, you cannot use
$expand in queries but instead must have associations with referential constraints. Ensure that each defining query references a single entity set. The mobile service detects the associations with referential constraints and uses these referential constraints to build relationships between the entity sets selected in your defining queries.
Combining referential constraints and
$expand in queries
: When you use
$expand to expand the relationship between two top-level entity sets, an association set is being implicitly referenced. For example,
/Events?$expand=Sessions implicitly references the
Event_Session_One_Many0Set association set. The mobile service allows you to mix referential constraints and
$expand to build relationships.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
!!! note This is not an exhaustive list. The choice of defining query is highly dependent on the needs of the offline application.
The table below lists parameters that can be used to configure defining queries in an application configuration file.
||(Required) Name of the defining query.|
||Whether the data is shared among different clients or users.
||The interval time, in minutes, between downloads of the shared data. The default is 15 minutes.|
||How to track OData deltas.
||The time, in minutes, until the OData delta token expires. While a token is valid, only changed data is downloaded to the offline store. When the delta token expires, the entire data set is replaced. The default is