We've already seen version numbers in some examples. When we edited our Blueprint, the version number increased from 1 to 2. When querying for previous data, version numbers can be more convenient than timestamps. We'll see this in the section on querying by version. With versioning, we bump the version number when we edit any data within the composite. For Blueprints, this means that we bump the version number when we edit the Blueprint itself, when we replace the ImgurImage, when we replace the blueprint string, and when we add or remove tags. We'll take a closer look in the section on Composites.

As-of queries by version over rest are performed by adding a query parameter to the URL. Our template is . Plugging in the key from our running example, and the version number 1, we GET This is similar to the as-of query by timestamp from the previous section, and the response is identical so we won't repeat it here. version GET /api/blueprint/{blueprintKey}?version={version} /api/blueprint/6ed1f638-a63c-3a54-af67-ba494f27bff2?version=1

At the SQL layer, queries by version number are implemented by starting with the version table. This query returns version 1, which existed for the duration . systemFrom systemTo key createdById lastUpdatedById number createdOn 2001-01-03 23:59:59.0 2001-01-04 23:59:59.0 6ed1 User ID User ID 1 2001-01-03 23:59:59.0 2001-01-04 23:59:59.0 9999-12-01 23:59:00.0 6ed1 User ID User ID 2 2001-01-03 23:59:59.0 At this point we take the system_from value of and use it in our subsequent queries. The queries on all other tables are identical to the queries in the previous section. For example, to query the BLUEPRINT table: select * from BLUEPRINT_VERSION t0 where t0.key = '6ed1f638-a63c-3a54-af67-ba494f27bff2' and t0.number = 1 [2001-01-03, 2001-01-04) 2001-01-03 23:59:59.000 select * from BLUEPRINT t0 where t0.key = '6ed1f638-a63c-3a54-af67-ba494f27bff2' and t0.system_from <= '2001-01-03 23:59:59.000' and t0.system_to > '2001-01-03 23:59:59.000'

In the previous example, we edited the Blueprint's title and markdown description, creating version 2. Now we'll replace the Blueprint string, the ImgurImage, and add two more tags. We want to bump the version number just once more, to 3. We update the blueprint by ing . PATCH /api/blueprint/{id}?version=2

As desired, we performed the several edits while bumping the version number by only one. In addition, all of the new times are identical: . At the SQL level, all the edits were performed in a single transaction. systemFrom 2001-01-05T23:59:59Z { "key": "6ed1f638-a63c-3a54-af67-ba494f27bff2", - "systemFrom": "2001-01-04T23:59:59Z", + "systemFrom": "2001-01-05T23:59:59Z", "systemTo": null, "version": { - "number": 2, - "systemFrom": "2001-01-04T23:59:59Z", + "number": 3, + "systemFrom": "2001-01-05T23:59:59Z", "systemTo": null, "createdOn": "2001-01-03T23:59:59Z", "createdBy": { "userId": "User ID" }, "lastUpdatedBy": { "userId": "User ID" } }, "title": "Edited blueprint title", "voteSummary": { "numberOfUpvotes": 0, "systemFrom": "2001-01-03T23:59:59Z", "systemTo": null }, "blueprintString": { - "sha": "cc341849b4086ce7b1893b366b0dc8e99ce4e595", - "createdOn": "2001-01-02T23:59:59Z", + "sha": "b11911083a0cf471a5156108389f9899675ccb0c", + "createdOn": "2001-01-03T00:00:00Z", "createdBy": { "userId": "User ID" } }, "imgurImage": { - "imgurId": "Imgur ID 1", - "imgurType": "image/png", - "height": 300, - "width": 300, + "imgurId": "2nd Imgur ID", + "imgurType": "2nd Imgur Type", + "height": 200, + "width": 200, "systemFrom": "2001-01-01T23:59:59Z", "systemTo": null }, "descriptionMarkdown": "Edited Blueprint description markdown", "tags": [ { "tagCategory": "belt", "tagName": "balancer", "systemFrom": "2001-01-03T23:59:59Z", "systemTo": null, "tag": { "category": "belt", "name": "balancer", "ordinal": 1, "systemFrom": "2000-01-01T00:00:00Z", "systemTo": null } + }, + { + "tagCategory": "belt", + "tagName": "prioritizer", + "systemFrom": "2001-01-05T23:59:59Z", + "systemTo": null, + "tag": { + "category": "belt", + "name": "prioritizer", + "ordinal": 2, + "systemFrom": "2000-01-01T00:00:00Z", + "systemTo": null + } + }, + { + "tagCategory": "moderation", + "tagName": "scheduled for deletion", + "systemFrom": "2001-01-05T23:59:59Z", + "systemTo": null, + "tag": { + "category": "moderation", + "name": "scheduled for deletion", + "ordinal": 18, + "systemFrom": "2000-01-01T00:00:00Z", + "systemTo": null + } } ] }

sits in the middle of a many-to-many relationship between and . In this example, we considered to be part of the composite making up the . Should we also consider it to be part of the as well? This is our choice as application designers. In this case, it makes sense for to be part of the , but not part of . Stack Overflow makes a similar choice. and s are both versioned. Applying new tags to a question creates a new version of the , but not the . In the UML diagram above, composite relationships are denoted by black diamonds. Composites are subtle, so let's walk through a few examples. Editing a Blueprint's title or description creates a new version. These are properties directly on the root type. Adding or removing BlueprintTag mappings creates a new version. These objects live within the composite. BlueprintTag mappings don't have any mutable properties. If they did, editing those properties would create a new version. For example, if we persisted their relative ordering with an ordinal property, then reordering the Blueprint's tags would create a new version. When the Blueprint author changes their display name, this does not create a new version. The User object is not part of the composite. We don't allow reassigning Blueprints to another author. If we did, repointing the author would create a new version. This works well with a temporal schema, because Blueprint.createdById would be swapped. BlueprintTag Blueprint Tag BlueprintTag Blueprint Tag BlueprintTag Blueprint Tag Questions Tag Question Tag