Update Objects
Introduction
Updating objects is handled by the update<Object Name>
mutation. For example: updateEpisode
.
Creating objects in Skylark includes 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
It is also possible to upsert objects, see here for more.
Default updating
The default update behaviour is the equivalent 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 updateEpisode {
updateEpisode(uid: "6decc351-6a55-4394-84e0-c97ff6ff2d39", episode: {
title: "Chapter 1: The Mandolorian", episode_number: 1
}) {
uid
synopsis
}
}
Saving as draft
By default, all updates are published immediately. However, it's also possible to save changes to draft so that changes can be reviewed then published later.
When making a mutation, set the draft argument to true
to save that mutation as a draft.
mutation {
updateEpisode(
uid: "01HD1SRJ8KD10WVXZQ4WDHKSAA",
draft: true, # Set draft mode
episode: {
title: "Chapter 1: The Mandolorian (draft)"
}) {
uid
title
}
}
You can then view the API in draft mode using the x-draft
header. See more here.
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_version
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 updateEpisode {
updateEpisode(uid: "6decc351-6a55-4394-84e0-c97ff6ff2d39", episode: {
title: "Chapter 8: Redemption", # Language field
episode_number: 8 # 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 updateEpisode {
updateEpisode(uid: "6decc351-6a55-4394-84e0-c97ff6ff2d39", episode: {
title: "Chapter 8: Redemption", # Language field
episode_number: 8 # 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
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 updateEpisode {
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 updateEpisode {
updateEpisode(
uid: "6decc351-6a55-4394-84e0-c97ff6ff2d39",
global_version: 1,
language_version: 2,
episode: {
title: "Chapter 8: Redemption" # 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 updateEpisode {
updateEpisode(
episode: {
external_id: "MandolorianChapter8"
},
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"
}
}
}
Nullifying Field Values
To remove the value of a field, make an update with the field set to null
. This is possible for any field, including the external_id
.
mutation updateEpisode {
updateEpisode(
episode: {
external_id: null,
title: null
},
uid: "6decc351-6a55-4394-84e0-c97ff6ff2d39"
){
# Return fields
uid
external_id
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 4 months ago