Skip to main content

Version specification

Whenever a dataset or project is updated--e.g., by adding or updating a file--data.world saves the old version of the dataset or project and creates a new version. The saved versions allow for back-in-time querying, and comparison between current and previous data. The data in those versions is accessed by using special named graphs.

Warning

The availability of previous versions of your datasets and projects is subject to data.world data retention policies, which may depend on the level of data.world support you have purchased. A saved query referencing a version of a dataset which becomes unavailable may cease to work.

There are a few different ways you can specify previous versions of your data:

  • Version by offset

  • Version by temporal offset

  • Version by timestamp

  • Explicit version

Important

All the links in the following examples open datasets/projects in the data.world open data community. For best experience, make sure you are logged in to the application when you click these links.

Version by offset

The simplest way to specify that you wish to use a past version of a dataset or project graph is with a version offset IRI.  The IRI of the current version of a dataset or project takes the form https://<agent_id>.linked.data.world/d/<dataset_id> or https://<agent_id>.linked.data.world/d/<project_id> .

A synonym for the current version which serves as the base for offset versions is https://<agent_id>.linked.data.world/d/<dataset_id>/v/tip. Data for the immediately previous version of a dataset is available in the graph with the IRI https://<agent_id>.linked.data.world/d/<dataset_id>/v/tip-1. This formula extends back to the nth prior version of the dataset or project: https://<agent_id>.linked.data.world/d/<dataset_id>/v/tip-<n>.

Note

Note: https://<agent_id>.linked.data.world/d/<dataset_id>/v/prev is a synonym for https://<agent_id>.linked.data.world/d/<dataset_id>/v/tip-1

Example - Version by offset

Here is an example of a version by offset query which shows how to access data from a previous version of a dataset, three versions prior to the current one:

PREFIX : <https://ddw-doccorp.linked.data.world/d/sparql-rdf-dataset/>
PREFIX version: <https://ddw-doccorp.linked.data.world/d/sparql-rdf-dataset/v/>
PREFIX airports: <https://airports.com/>

SELECT ?nameFROM version:tip-3
{
    ?s a             airports:airport.
    ?s airports:name ?name.
}

Run query

This is what it looks like when run on data.world:

version_by_offset.png

Version by temporal offset

In addition to numeric version offsets (like tip-1, tip-2), you can reference dataset versions using relative time expressions. Temporal offsets allow you to query data as it existed a specific duration ago, without needing to calculate exact timestamps or count version numbers.

To specify a temporal offset version, use an IRI of the form:

https://<agent_id>.linked.data.world/d/<dataset_id>/v/offset-<value><unit>

Syntax

Temporal offsets use the pattern offset-<value><unit> where:

  • <value> is a positive integer

  • <unit> is a time unit identifier

Supported Time Units

Table 1.

Unit

Description

Example

s

Second

soffset-30s (30 seconds ago)

m

Minutes

offset-15m (15 minutes ago)

h

Hours

offset-2h (2 hours ago)

d

Days

offset-5d (5 days ago)

w

Weeks

offset-1w (1 week ago)

M

Months

offset-3M (3 months ago)

y

Years

offset-1y (1 year ago)



Note

Use uppercase M for months and lowercase m for minutes.

Complex Temporal Expressions

You can combine multiple time units in a single offset expression. Units are processed from largest to smallest (years → months → weeks → days → hours → minutes → seconds).

Examples:

  • offset-1y3M2d (1 year, 3 months, and 2 days ago)

  • offset-2d12h (2 days and 12 hours ago)

  • offset-1M2w3d (1 month, 2 weeks, and 3 days ago)

Example - Version by temporal offset (2 hours ago)

Here is an example query showing how to access data from 2 hours ago:

PREFIX : <https://ddw-doccorp.linked.data.world/d/sparql-rdf-dataset/>
PREFIX version: <https://ddw-doccorp.linked.data.world/d/sparql-rdf-dataset/v/>
PREFIX airports: <https://airports.com/>

SELECT ?name
FROM version:offset-2h
{
  ?s a airports:airport.
  ?s airports:name ?name.
}

Example - Version by temporal offset (complex)

Here is an example query showing how to access data using a complex temporal expression (1 year, 3 months, and 2 days ago):

PREFIX : <https://ddw-doccorp.linked.data.world/d/sparql-rdf-dataset/>
PREFIX version: <https://ddw-doccorp.linked.data.world/d/sparql-rdf-dataset/v/>
PREFIX airports: <https://airports.com/>

SELECT ?name
FROM version:offset-1y3M2d
{
  ?s a airports:airport.
  ?s airports:name ?name.
}

Example - Multiple temporal references

You can use different temporal offsets within the same query:

PREFIX : <https://ddw-doccorp.linked.data.world/d/sparql-rdf-dataset/>
PREFIX version: <https://ddw-doccorp.linked.data.world/d/sparql-rdf-dataset/v/>
PREFIX airports: <https://airports.com/>

SELECT ?name1 ?name2
FROM version:offset-1d
FROM NAMED version:offset-1w
{
  ?s1 airports:name ?name1.
  GRAPH version:offset-1w {
    ?s2 airports:name ?name2.
  }
}

Note

How it works: Temporal offsets are automatically converted to fixed timestamp versions at query time, so they use the same underlying infrastructure as timestamp-based versioning.

Version by timestamp

Versioning by offset is easy, but it is not always sensible if a dataset is updating frequently. Instead, you might wish to know the data that was available in a dataset at a specific point in the past--no matter how many versions the dataset has had since then. To specify the version of a dataset that was current at a specific time, use an IRI of the form http://<agent_id>.linked.data.world/d/<dataset_id>/v/at-<timestamp>. Timestamps can be specified in the form yyyyMMdd to get the dataset as it was on midnight of a specific day, or yyyyMMdd’T’HHmmssX to specify the time more precisely.

Example - Version by timestamp

Here is an example of a query showing how to access data from a previous version of a dataset at a given timestamp:

PREFIX : <https://ddw-doccorp.linked.data.world/d/sparql-rdf-dataset/>
PREFIX : <https://ddw-doccorp.linked.data.world/d/sparql-rdf-dataset/>
PREFIX version: <https://ddw-doccorp.linked.data.world/d/sparql-rdf-dataset/v/>
PREFIX airports: <https://airports.com/>

SELECT ?name
FROM version:at-20221024T122903Z
{
    ?s a             airports:airport.
    ?s airports:name ?name.
}

Run query

This is what the query looks like when run on data.world:

timestamp_version.png

Explicit version

The version UUID of each version of a dataset or project is available as an IRI in the form http://<agent_id>.linked.data.world/d/<dataset_id>/v/<version_uuid>.

For a specific file in a version, use: http://<agent_id>.linked.data.world/d/<dataset_id>/v/<version_uuid>/file/<filename>

Examples

Example - Current version

Here is a an example of a query you can use to find the current version of a dataset:

PREFIX : <https://ddw-doccorp.linked.data.world/d/sparql-rdf-dataset/>
PREFIX dw: <https://ontology.data.world/v0#>

SELECT ?dataset ?agentId ?datasetId ?versionId
{
    ?dataset dw:agentId   ?agentId;
             dw:datasetId ?datasetId;
             dw:versionId ?versionId.
}

Run query

And here is what the query looks like on data.world:

Current_version.png

Example - Find version IRI

If you have identified a version you wish to continue to analyze, you can find its IRI with a query like this:

PREFIX : <https://ddw-doccorp.linked.data.world/d/sparql-rdf-dataset/>
PREFIX dw: <https://ontology.data.world/v0#>

SELECT ?dataset ?agentId ?datasetId ?versionId
FROM <https://ddw-doccorp.linked.data.world/d/sparql-rdf-dataset/v/tip-1>
{
    ?dataset dw:agentId   ?agentId;
             dw:datasetId ?datasetId;
             dw:versionId ?versionId.
}

Run query

And this is what it looks like on data.world:

version_query_offset.png

Example - Explicit version

Here is an example of a query showing how to access data from a previous version of a dataset at a given version id:

PREFIX : <https://ddw-doccorp.linked.data.world/d/sparql-rdf-dataset/>
PREFIX : <https://ddw-doccorp.linked.data.world/d/sparql-rdf-dataset/>
PREFIX version: <https://ddw-doccorp.linked.data.world/d/sparql-rdf-dataset/v/>
PREFIX airports: <https://airports.com/>

SELECT ?nameFROM version:d3362ea7-820d-4239-bca9-3494a0d7ce51
{
    ?s a             airports:airport.
    ?s airports:name ?name.
}

Run query

Here is what query looks like on data.world:

Explicit_version.png
In this section: