Change tracking

What’s in this document?

GraphDB allows the tracking of changes that you have made in your data. Two tools offer this capability: the change tracking plugin, and the data history and versioning plugin.

What the plugin does

The change tracking plugin is useful for tracking changes within the context of a transaction identified by a unique ID. Different IDs allow tracking of multiple independent changes, e.g., user A tracks his updates and user B tracks her updates without interfering with each other. The tracked data is stored only in-memory and is not available after a restart.

As part of the GraphDB Plugin API, the change tracking plugin provides the ability to track the effects of SPARQL updates. These can be:

  • Tracking what triples have been inserted or deleted;

  • Distinguishing explicit from implicit triples;

  • Running SPARQL using these triples.

Usage

The plugin introduces the following special graphs:

  • http://www.ontotext.com/added/xxx – contains all added statements, including inferred ones

  • http://www.ontotext.com/removed/xxx – contains all removed statements, including inferred ones

In both cases, xxx is a user-provided unique ID that must be assigned when activating the tracking function. The usage pattern goes like this:

  1. Start a transaction.

  2. Activate tracking for this transaction:

    INSERT DATA {
       [] <http://www.ontotext.com/track-changes> "xxx"
    }
    

    where xxx must be a unique ID assigned by the user.

  3. Add or remove some data.

  4. Commit the transaction.

  5. Retrieve all added triples and their graph:

    SELECT * FROM <http://www.ontotext.com/added/xxx> {
       graph ?g {
           ?s ?p ?o
       }
    }
    

    where xxx is the ID assigned previously.

  6. Retrieve the number of removed triples:

    SELECT (COUNT(*) as ?c) FROM <http://www.ontotext.com/removed/xxx> {
       ?s ?p ?o
    }
    

    where xxx is the previously assigned ID.

  7. CONSTRUCT query using data that has just been added (advanced example):

    BASE <http://ontotext.com/resource/>
    PREFIX foaf: <http://xmlns.com/foaf/0.1/>
    PREFIX test: <http://ontotext.com/vocabulary/test/>
    
    CONSTRUCT {
       ?person test:knows ?knows ;
               foaf:givenName ?givenName
    } FROM <http://www.ontotext.com/added/xxx> WHERE {
       ?person foaf:givenName ?givenName ;
               foaf:knows     ?knows
    }
    

    where xxx is the previously assigned ID.

  8. Forget the tracked data:

    INSERT DATA {
       <http://www.ontotext.com/track-changes> <http://www.ontotext.com/delete-changes> "xxx"
    }
    

    where xxx is the ID assigned previously.

Note

Note that you must explicitly delete the tracked changes when you no longer need to query them. Otherwise they will stay in memory until the same ID is used again, or until GraphDB is restarted.

Tip

A good way to ensure unique tracking IDs is to use UUIDs. A random UUID can be generated in Java by calling UUID.randomUUID().toString().