ODATA DELTAS

Deltas provide a hypermedia-driven solution for retrieving changes to a given set of data

WHY DELTAS?

• Client Change Tracking• Clients often have local copies of data• Want to figure out what has changed

• Large Data Sets• OData is good for retrieving small/moderate sizes

of data• OData is not optimized for large data transfer

o But is good for returning small/moderate sizes of changes to slowly changing data sets

REQUIREMENTS

• Keep it Simple!• 80-20 rule

• Support Web Scale• Don't require per-client state

• NOT designed for multi-master sync• Service is "truth"• Payloads don't carry "exceptions"• No per-client state on server• Clients don't know about other clients

DESIGN

• Server generates opaque "delta link" URL• Generally contains encoding of request and "high

water mark" so as to avoid per-client state on the servero Multiple clients can maintain their data sets from a single

service

• Link is returned on the last page of a result

• Clients can use link to get newly added, deleted, or changed records• Could be combined with general notification model to

alert clients to changes

INITIAL POPULATION

RESULT MAINTENANCE

DELTAS AND QUERY OPTIONS

• Query options "preserved" in delta links• $filter, $select

• Query options that can be applied to delta queries• $top, $skip, $format, $inlinecount

• Query options that are not applicable to deltas• $orderby• $count, $value

DELTA RESULTS

• Delta results are ordered by when change occurred• Payload shows current values• Clients can merge with local results

• Add Tombstones to represent removed rows• Contains ID of removed entry• May contain a "reason"

o Hard-delete versus no longer member of the group (i.e., due to change)

DELTAS AND SERVER DRIVEN PAGING• Delta Link returned on last page of results• Makes sure deltas aren't applied to incomplete

results

• Results of delta queries may be paged• Each interim page has a next link• Final page may have a delta link for getting

changes

ATOM FORMAT

• <feed> contains a delta Link as a <link> element• href is the url to retrieve deltas• rel is "http://odata.org/delta"

• <feed> contains Atom "deleted-entry" elements for each deleted object

deletedEntry = element at:deleted-entry { atomCommonAttributes, attribute ref { atomUri }, attribute when { atomDateConstruct }, attribute m:reason { 'deleted' | 'changed' }  }

Where m: is the metadata namespace for data services: "http://schemas.microsoft.com/ado/2007/08/dataservices/metadata"

<feed><title type="text">Customers</title><id>http://DeltaService.svc/Customers</id><entry> <id>http://DeltaService.svc/Customers('BOTTM')</id> <title type="text" /> <link rel="edit" title="Customer" href="Customers('BOTTM')" /> <category term="NorthwindModel.Customer" scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme" /> <content type="application/xml"> <m:properties> <d:CustomerID>BOTTM</d:CustomerID> <d:CompanyName>Bottom-Dollar Markets</d:CompanyName> <d:ContactName>Elizabeth Lincoln</d:ContactName> </m:properties> </content></entry><deleted-entry ref="http://DeltaService.svc/Customers('Cust10')" when="2011-02-16T01:00:25Z" xmlns=http://purl.org/atompub/tombstones/1.0 m:reason="deleted" /><link rel=http://odata.org/delta href="http://DeltaService.svc/Customers?$deltatoken=8015" /></feed>

ATOM EXAMPLE

JSON FORMAT

• "results" array has a "__link" property• Value is the URL

• Tombstones• "results" array contains "__deleted" objects for

each deleted entryo "id" propertyo "when" propertyo "reason" property

JSON EXAMPLE{ "d": { "results": [ { "__metadata": { "id":"http://DeltaService.svc/Customers('BOTTM')", "uri":"http://DeltaService.svc/Customers('BOTTM')", "type":"NorthwindModel.Customer" }, "CustomerID":"BOTTM", "CompanyName":"Bottom-Dollar Markets", "ContactName":"Elizabeth Lincoln" }, { "__deleted": { "id":"http://DeltaService.svc/Customers('Cus10')", "when":"\/Date(1297187419617)\/" "reason": "deleted" } }, ], "__delta":"http://DeltaService.svc/Customers?$deltatoken=8015" }}

OPEN ISSUES

• How do we treat $expand in a delta query?• Is deleted reason optional? Is it hard to

determine in some cases? What does the client do if not known?• Does a server always return a delta link if it

can? Might it be expensive to generate?