feat: Entity versioning

[cvauclair]

Goals

The goal of this versioning feature are:

1. Allow users to browse a past (or future, given pending edit) state of a space
2. View all of an entity's past changes (or future changes, given pending edit) and associated states

Implementation

The idea is for the space edit to serve as the unit of change (similar to how commits work in a git repository). In other words, space version ids would be derived from edit and space ids.

The data service would be responsible for keeping track of the triples set, updated or deleted for each edit within a space, thus enabling developers to navigate a space after a specific edit was applied to the space.

Querying

For querying a single entity, the API design is pretty natural: we simply add an optional version argument to the entity field

query {
  # Return an entity at a specific version of a space 
  entity(
    id: "ENTITY-ID",
    space_id: "SPACE-ID",
    version: "VERSION-ID" # optional, defaults to current version
  ) {
    # Every nested selection will fetch data from the space at version VERSION_ID 
    name
    description
    ...
  }
}

However, to retrieve multiple versions of an entity in a single query, the API design is less obvious. Here are a few ideas

Querying past versions of entity

To query the past versions of an entity, go through the Space and SpaceVersion entities

query {
  # Select a specfic space
  space(id: "SPACE-ID") {
    # Select its space versions
    versions(
      # Filter space versions where our entity has been updated
      where: {entities: [
        {id: "ENTITY-ID", "updated": true},
      ]}
    ) {
      # Select our entity
      entity(id: "ENTITY-ID") {
        name
        description
        ...
     }
    }
  }
}

(Note: Not fully satisfied with this design, ideas welcome!)

These new entities would be the same as the ones mentioned in #23

Selecting multiple entities at some space version

query {
  entities(
    space_id: ["SPACE-ID-A", "SPACE-ID-B"],
    versions: ["VERSION-ID-A", "VERSION-ID-B"],
  ) {
    # Returns a list of entities, one for each (SPACE-ID-N, VERSION-ID-B) if it exists
    # Any relation traversed from these entities will consider the version at the time (e.g.: kind of like browsing the wayback machine)
    name
    description
    ...
  }
}

Leaving the versions field empty would return the entities for the current versions of the selected spaces.

Alternatively the version argument could be nested within the spaces argument:

query {
  entities(
    spaces: [
      {"id": "SPACE-ID-A", "versions": ["VERSION-A", "VERSION-B"]},
      {"id": "SPACE-ID-B", "versions": ["VERSION-C", "VERSION-D"]},
    ] 
  ) {
    # Returns a list of entities, one for each (SPACE-ID-N, VERSION-ID-B) if it exists
    # Any relation traversed from these entities will consider the version at the time (e.g.: kind of like browsing the wayback machine)
    name
    description
    ...
  }
}

Note: The entities defined in the [[#Querying past versions of entity]] section (Space and SpaceVersion entities) could also be used to query entities in a space at a given version. Open question which one should be used.

Implementation

• Update Neo4j data model
• Add version filter to GraphQL API