API ReferenceSkylark User Guide
API Reference

Get Objects

Suggest Edits

Introduction

Getting objects is handled by the get query. For example: getEpisode. Examples in this document will continue to use getEpisode for convenience.

The get object handler in Skylark is broken into 2 different parts. They are:

  • Object Data
  • Object Meta

Get Object Data

The object data are fields which are set by the user, and are the main fields for an object, for example the title, slug, description, etc.

Getting just the object data is the most efficient query you can make. Example of getting just object data:

query GetEpisode {
  getEpisode(uid: "4220f2b2-db6c-4c26-b870-204066bf534a") {
    uid
    title
    synopsis
    episode_number
  }
}

Response:

{
  "data": {
    "getEpisode": {
      "uid": "4220f2b2-db6c-4c26-b870-204066bf534a",
      "title": "The Mandalorian",
      "synopsis": "An armored bounty hunter takes on a well-paying yet cryptic assignment.",
      "episode_number": 1
    }
  }
}

Note that getting object is subject to availability (See here). It is possible to bypass the availability by supplying the ignore_availability argument. Example:

query GetEpisode {
  getEpisode(uid: "4220f2b2-db6c-4c26-b870-204066bf534a", ignore_availability: true) {
    uid
  }
}

Get Additional Object Data

The object "meta" is all the information about an object that is not set by the user. This includes the created/modified date, version history and available languages.

Get Created and Modified Information

This example shows how to retrieve the created and modified information for an object.

query GetEpisode {
  getEpisode(uid: "4220f2b2-db6c-4c26-b870-204066bf534a") {
    uid
    _meta {
      modified {
        user
        date
      }
      created {
        user
        date
      }
    }
  }
}

Response:

{
  "data": {
    "getEpisode": {
      "uid": "4220f2b2-db6c-4c26-b870-204066bf534a",
      "_meta": {
        "modified": {
          "user": "[email protected]",
          "date": "2021-08-10T08:43:02.372061+00:00"
        },
        "created": {
          "user": "[email protected]",
          "date": "2021-08-10T08:43:02.372061+00:00"
        }
      }
    }
  }
}

Get Object Complete Version History

You can get the complete version history for both language and meta versions in the object's _meta.

🚧

Warning

Getting the complete history is an inefficient query and should be used sparingly!

Example:

query GetEpisode {
  getEpisode(uid: "4220f2b2-db6c-4c26-b870-204066bf534a", ignore_availability: true) {
    uid
    _meta {
      global_data {
        history {
          episode_number
          version
        }
      }
      language_data {
        history {
          title
          version
          synopsis
        }
      }
    }
  }
}

Response:

{
  "data": {
    "getEpisode": {
      "uid": "4220f2b2-db6c-4c26-b870-204066bf534a",
      "_meta": {
        "global_data": {
          "history": [
            {
              "episode_number": 1,
              "version": 1
            }
          ]
        }
        "language_data": {
          "history": [
            {
              "title": "The Mandolorian",
              "version": 1,
              "synopsis": "An armored bounty hunter takes on a well-paying yet cryptic assignment"
            },
            {
              "title": "The Mandalorian",
              "version": 2,
              "synopsis": "An armored bounty hunter takes on a well-paying yet cryptic assignment."
            }
          ]
        }
      }
    }
  }
}

Get via External ID

It is also possible to get an object via it’s external_id, if you don’t have the UID. Everything in the response remains the same, the only difference is that external_id is passed as an argument rather than the UID.

This does require that you set an external_id on the object prior to attempting to retrieve it.

Querying by external_id is particularly helpful when syncing data between third-party applications/data stores and Skylark.

📘

Note

Querying by external_id is slightly less efficient than querying by UID since the external ID must first be resolved into the UID meaning that an extra database query has to be made. While this is still a very efficient query, if every request is made with external_id the number of queries to the database is effectively doubled.

Therefore, we recommend using this for integrating backend systems to Skylark moreso than for directly accessing from end-user streaming products.

query GetEpisode {
  getEpisode(external_id: "mandolorian_s01e01") {
    uid
    title
    synopsis
    episode_number
  }
}

Working With Versions

Its possible to get any version of an object in its _meta.

By specifying a version number, the language_data / global_data object in the _meta will be that version. If a version is not supplied, or the version supplied is 0 the current active version will be returned.

Get the latest version and default translation

Example getting the latest version and default language:

query GetEpisode {
  getEpisode(uid: "4220f2b2-db6c-4c26-b870-204066bf534a", ignore_availability: true) {
    uid
    _meta {
      language_data {
        title
        synopsis
        version
      }
      global_data {
        episode_number
        version
      }
    }
  }
}

Response:

{
  "data": {
    "getEpisode": {
      "uid": "4220f2b2-db6c-4c26-b870-204066bf534a",
      "_meta": {
        "language_data": {
          "title": "The Mandalorian",
          "synopsis": "An armored bounty hunter takes on a well-paying yet cryptic assignment.",
          "version": 1
        },
        "global_data": {
          "episode_number": 1,
          "version": 1
        }
      }
    }
  }
}

Get specific version and translation

query GetEpisode {
  getEpisode(uid: "4220f2b2-db6c-4c26-b870-204066bf534a") {
    uid
    _meta(language_version: 1, global_version: 3, language: "en-GB") {
      language_data {
        title
        synopsis
        version
      }
      global_data {
        episode_number
        version
      }
    }
  }
}

Response:

{
  "data": {
    "getEpisode": {
      "uid": "4220f2b2-db6c-4c26-b870-204066bf534a",
      "_meta": {
        "language_data": {
          "title": "The Mandalorian",
          "synopsis": "An armored bounty hunter takes on a well-paying yet cryptic assignment.",
          "version": 1
        },
        "global_data": {
          "episode_number": 1,
          "version": 3
        }
      }
    }
  }
}

Attempt to get a version that does not exist

If the version supplied does not exist, or doesn’t exist for the language, the a NotFound exception will be thrown.

Updated 7 months ago