The Changeset API makes a feature by feature comparison between dataset versions returning data for any feature that is new, updated or deleted.

The Changeset API is very strict in its definition of change. Any alteration to the data, no matter how small, constitutes a change and will be included in the changeset.

For example, in the case of plain text data, any change in white space, case, or special characters are part of the changeset. In the case of geometry data any change in coordinate sequence or value will be included. Schema changes will also trigger a changeset.

Unique feature identifier

LDS knows what information is added, modified or deleted by tracking the unique primary key identifier for the dataset and matches and compares rows or features using this identifier. The primary key is identified under the Technical Details column of the About tab.

Action types

Any change in data will be defined as either an INSERT, DELETE or UPDATE. This is recorded in the “__change__” column of the changeset table.

Each row in the changeset dataset will be separate action and there will only ever be one action for any given feature in a changeset – even if a series of actions have happened for that single feature as the Changeset API processes all actions server-side.

For example if a feature has been inserted and updated one or more times within the timeframe of the changeset, the changeset will only have an insert record but it will have incorporated the updates. Likewise if a feature has been updated and deleted, it will only have a delete action in the changeset.

Action typeDescription
INSERTFeatures are marked as an INSERT if the feature identifier exists in the new version of the dataset but not in the existing version.
DELETEFeatures are marked as a DELETE if the feature identifier is in the existing data but not in the new data.
UPDATEFeatures are marked as an UPDATE if the feature identifier exists in both the new and old data, but any of the feature attributes or geometries are different. While the changeset will tell you that a feature has been affected by an UPDATE, it will not tell you the reason for change, i.e. what specific attribute has changed.

Note: Additional filter parameters applied in the changeset request may impact on the returned changeset actions. See our documentation on changeset filtering for more information.

Changeset examples

Simple example of action types

In the simple example below we have a persons table which has a schema of first and last names, along with a unique identifier for each person. In revision A of the table there is John, Jane and Roger. In revision B, Mary has been added, Jane has married John, and Roger has been deleted.

The end result is a changeset table that has the same schema as revisions A and B with the addition of a “__change__” column, indicating the type of change that occurred to the row between revisions. In this case, Roger Jones has been deleted, Jane has been updated to have a last name of 'Smith' and Mary Pond has been added.

Changeset example using LINZ data

These examples show what an actual changeset result using the LDS Changeset API may look like. 

This example shows records from a changeset table for the NZ Parcel Statutory Actions List. In this example the feature identifier is the ‘id’ attribute.

FID

__change__

id

par_id

status

action

statutory_action

table-51565-changeset.281745

UPDATE

23392

3505013

Historic

Create

Secondary School New Zealand Gazette 1981 p 1975

table-51565-changeset.227552

DELETE

249105

3105056

Current

Referenced

Road New Zealand Gazette 2013 p 956 Pursuant to Sec 5 of the Land Transport Management Act 2003, forms part of State Highway 1 and vests in the Crown.

table-51565-changeset.281362

INSERT

300405

3525650

Historic

Extinguished

New Zealand Gazette 2017 ln 3735

Reference Category: Changesets
Reference Tags: Update, Delete, Modify, Insert, Actions, Primary key
Last Updated: 
2 October 2018