API ReferenceSkylark User Guide
API Reference

Update Objects

Suggest Edits

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 7 months ago