Update Objects
Introduction
Updating objects is handled by the update<Object Name>
mutation. For example: updateEpisode
. For convenience in this document, this mutation will be generalised as updateObject
.
Creating objects in Skylark has been expand from legacy Skylark to include a fully featured version system with the ability to roll back/forward versions, and do a patch/partial update based on a specific version, rather than just on the latest version.
There are 4 possible update types:
- Update and create a totally new version (PUT request)
- Partial update based on a previous version (PATCH request)
- Rollback/forward active version
- Updating additional “system” fields
Default updating
The default update behaviour is the equivelant to a PATCH
request. A new version number will be created (either Global, Language or both depending on the fields provided) and all the fields from the previous version will be carried into the new verison.
This example will create a new language and global version, and the values from the previous verison that aren't specified (for example, synopsis from language) would be retained in the new version.
mutation MyMutation {
updateEpisode(uid: "6decc351-6a55-4394-84e0-c97ff6ff2d39", episode: {
title: "New title", episode_number: 1
}) {
uid
synopsis
}
}
Partial Update Based On Previous Versions
This option is also equivalent to a PATCH
request, however a new version number will be created (either Global, Language or both depending on the fields provided) and any fields not provided in the update will be carried over from the version specified in the update.
Updates take the following 2 parameters:
- language_version
- global_versiond
These parameters are for specifying which version to use inherit from an expect the version number as an int.
If neither are supplied, a new unique version will be created without inheriting (see above). If the version number 0
is supplied, a new version will be created based on the current active version.
If a version number is supplied that does not exist, a NotFound
exception will be thrown.
If a version is supplied, but no fields for that version type (e.g language_version
is supplied but no language fields) no new language version will be created.
In this example, a new global version will be created with the updated episode_number
and fields from global_version
1 will be inherited and a new language version will be created with the updated title and fields from the current active language version:
mutation MyMutation {
updateEpisode(uid: "6decc351-6a55-4394-84e0-c97ff6ff2d39", episode: {
title: "New title", # Language field
episode_number: 10 # Global field
},
global_version: 1,
language_version: 0
) {
uid
title
synopsis
episode_number
}
}
Using this functionality it is also possible to simulate a PUT
request, but specifying version 0
to update against. For example:
mutation MyMutation {
updateEpisode(uid: "6decc351-6a55-4394-84e0-c97ff6ff2d39", episode: {
title: "New title", # Language field
episode_number: 10 # Global field
},
global_version: 0,
language_version: 0
) {
uid
title
synopsis
episode_number
}
}
In this example a new version will be created with just the title
and episode_number
present, all other fields will be reset to null
.
Rollback/forward Active Version
In legacy Skylark, the current version is whatever version has the highest version number so in order to “Rollback” to the content from a previous version, you needed to duplicate the data from that version into a new version.
Skylark introduces the ability to change the active version number.
By supplying a version number to the language_version
or global_version
fields, and not supplying any data changes for those field types, the active version will be changed to the version specified.
In this example, the active language version will be changed to 2 and the active global version will be changed to 1.
mutation MyMutation {
updateEpisode(
uid: "6decc351-6a55-4394-84e0-c97ff6ff2d39",
global_version: 1,
language_version: 2
) {
# Return fields
uid
title
synopsis
episode_number
}
}
In this next example the active global version will be changed to 1 and a new language version will be created based on version 2. This is because a language field was supplied to the update.
As previously outlined, if a version is supplied to language_version
(and corresponding language) or global_version, and that version doesn’t exist, a NotFound
exception will be thrown.
mutation MyMutation {
updateEpisode(
uid: "6decc351-6a55-4394-84e0-c97ff6ff2d39",
global_version: 1,
language_version: 2,
episode: {
title: "New title" # Language version
}) {
# Return fields
uid
title
synopsis
episode_number
}
}
Update System Fields
Some fields live outside global or language data, and are not subject to the versioning system. These are fields which can be set by the user and are used by parts of the system, for example in querying. These fields are:
- external_id
Updating system fields is straightforward:
mutation MyMutation {
updateEpisode(
episode: {
external_id: "some-ext-id-1"
},
uid: "6decc351-6a55-4394-84e0-c97ff6ff2d39"
){
# Return fields
uid
external_id
}
}
Update Object Primary Field
The below query will allow you to update the primary field for a given object - in this example an Episode.
mutation {
Episode: setObjectConfiguration(
object: Episode
object_config: {primary_field: "title"}
) {
primary_field
}
}
Response
{
"data": {
"Episode": {
"primary_field": "title"
}
}
}
Update Object UI Pill Colour
The below query will allow to update and change the colour of the pill that the UI uses to display a given object type. In the below image for example, the Movie object has been assigned the colour red.
This example query changes an episode object's colour.
mutation {
Episode: setObjectConfiguration(
object: Episode
object_config: {colour: "#ff7ba8" }
) {
colour
}
}
Response:
{
"data": {
"Episode": {
"colour": "#ff7ba8"
}
}
}
Updated about 2 months ago