Get Objects
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 4 months ago