GraphQL Query Tutorial¶

Retrieve a List of Objects¶

All we have to do to fetch multiple object types using the Semantic Objects is to define a valid nested GraphQL query.

Let’s say that we need some basic information about all the characters in the Star Wars saga. We need to:

• define a name for our query

query allCharacters {}

• set the type of objects (character) and properties (id, name, gender, birthYear, height) that we want to retrieve.

 query allCharacters {
    character {
        id
        name
        gender
        birthYear
        height
    }
}

And that’s it! We have our first query that can retrieve all the characters within the Star Wars dataset. You can edit the query directly in the integrated GraphiQL editor.

query allCharacters {
  character {
    id
    name
    gender
    birthYear
    height
  }
}

Using the same approach, we can define as many queries as we need. The next example fetches all Star Wars films including some of their properties.

query allFilms {
    film {
        name
        episodeId
        role {
          roleType
          person {
            name
          }
        }
        releaseDate
    }
}

Retrieve a Single Object¶

To retrieve a single object, we can filter a list of objects using a known, unique property value.

For example, let’s say we want to retrieve information about a single Star Wars character Luke Skywalker that has a unique ID property which equals https://swapi.co/resource/human/1.

We can do this by altering the allCharacters query (above), by adding a ID filter upon the set of all characters:

 query character {
    character(ID: "https://swapi.co/resource/human/1") {
        id
        name
        gender
        birthYear
        height
    }
}

Ordering of LangString Values¶

When fetching a multi-valued string or langString field, you can use orderBy, limit, and offset to order the values, but only if the language specification in effect is using ALL. Otherwise, an error will be returned.

Here is an example use of the orderBy to return and sort the English and French language values in ascending order:

 query humanDescriptions {
    human(where: {desc: {}}) {
        id
        name
        desc(lang: "ALL:en~,fr~", orderBy: ASC) {
            value
            lang
        }
    }
}

Other examples of ordering a multi-valued literal properties:

Ordering by Single LangString Value¶

When fetching a multi-valued object field, you can order by a string or langString field if the field is single-valued, or if the language specification in effect does not contain ALL.

Note that the langString fields have different arguments when ordering by them. The format is as follows:

<object>(orderBy : {<langStringProperty>: {dir: <ASC/DESC>, lang: <filterPattern>}}) {
  <langStringProperty> {
    value
    lang
  }
}

The ordering could be ASC, which is the default if not specified, or could be DESC in Unicode collation order ignoring any language tags.

Due to technical limitations, only values matching the first positive language tag are used for ordering.

If an object does not have a matching value, it comes last for both ASC and DESC directions. There must be a single matching value, otherwise the result of ordering is indeterminate.

It is recommended, but not required, that the ordering field has a UNIQ constraint for that language tag.

Let’s illustrate this with an example:

 query humanDescriptions {
    human(where: {desc: {}}, orderBy: {desc: {dir: DESC, lang: "en"}}) {
        id
        name
        desc {
            value
            lang
        }
    }
}

Other examples of ordering by langString properties, where desc is a multi-valued langString, label a single-valued langString:

Comparison Operators¶

Comparison operators come in pairs:

• EQ:NEQ: - equality/inequality. Should be used for single values filter expressions.

<object> (where: {<property>: {EQ:<value>}})   {<properties>}

The following query will filter the list of characters to only include those that have the male gender type.

 query allMaleCharacters {
    character (where: {gender: {EQ:"male"}}) {
        id
        name
        gender
        birthYear
        height
    }
}

• IN:NIN: - inside/outside of an array of values (put them in square brackets).

<object> (where: {<property>: {IN:[<value1, value2>]}}) {<properties>}
<object> (where: {<property>: {IN:<value>}})   {<properties>}

<object> (where: {<property>: {IN:[3]}}) {<properties>} # looks for a value equal to 3
<object> (where: {<property>: {NIN:3}})   {<properties>} # looks for a value different from 3

The following query will filter the list of characters to include only those that have a birthYear IN 19BBY.

 query allCharactersBornIn19BBY {
    character (where: {birthYear: {IN:"19BBY"}}) {
        id
        name
        gender
        birthYear
        height
    }
}

• LT:GTE and LTE:GT: - less-than/greater-than-or-equal and less-than-or-equal/greater-than. Comparison of numbers, strings, or IRIs.

The following GraphQL query will filter the list of Character objects so that it does not include any characters who have height greater than 2 meters.

 query allCharactersTallerThan200 {
    character (where: {height: {GT: 200}}) {
        id
        name
        gender
        birthYear
        height
    }
}

• RE:NRE and IRE:NIRE: - regular expression match/mismatch. The I variants make case-insensitive comparisons using Unicode alphabet collation.

The following query will filter the list of characters to only include those with sky in their name.

 query allCharactersWithNameContainingSky  {
    character (where: {name: {IRE: "sky"}}) {
        id
        name
        gender
        birthYear
        height
    }
}

• ID: - access an object or object property by IRI (id).

<object> (ID:"<value>") {<properties>}
<object> (ID:["<value1>",""<value1>""]) {<properties>}
<object> (where: {<object_property>: {ID:"<value>"}}) {<properties>}

Characters starring in a A New Hope film.

 query allCharactersInANewHope {
    character (where: {film: {ID: "https://swapi.co/resource/film/1"}}) {
        id
        name
        gender
        birthYear
        height
        film {
            name
        }
    }
}

Logical Connectives¶

You can also use the following logical connectives:

• AND (conjunction) is implicit between clauses in the same input object

  To compare two properties of the same object, put them together.

  <object> (where: {<property1>: {EQ:"<value1>"}, <property2>: {IRE:"<value2>"}}) {<properties>}
  

  Filter the list of characters to only include those with a height less than 100 and a mass greater than or equal to 45.0. (note: commas are optional in GraphQL)

  Loading...

  https://swapi-platform.ontotext.com/graphql

  eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImJNODctcWV3SldXTWRMRjIzNUtXUmluTlp4TDA0ZngzIn0.eyJhdWQiOiI2NzJjYTdiMy1jMzcyLTRkZjMtODJkOC05YTFhMGQ3ZDY4YzEiLCJleHAiOjE3MjkyNDk4MTksImlhdCI6MTY5ODE0NTgxOSwiaXNzIjoic3dhcGktcGxhdGZvcm0ub250b3RleHQuY29tIiwic3ViIjoiZTlmOWQzNGQtZThmMS00ODM1LTlkMzAtOWRjNmU5YjQ4ZmMzIiwianRpIjoiODZjNTIzYzEtYzQzNC00MWZiLWFkOTctYWU2MDY5MjgxYWM4IiwiYXV0aGVudGljYXRpb25UeXBlIjoiUEFTU1dPUkQiLCJlbWFpbCI6InJlYWRvbmx5dXNlckBleGFtcGxlLmNvbSIsImVtYWlsX3ZlcmlmaWVkIjp0cnVlLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJSZWFkT25seVVzZXIiLCJhcHBsaWNhdGlvbklkIjoiNjcyY2E3YjMtYzM3Mi00ZGYzLTgyZDgtOWExYTBkN2Q2OGMxIiwicm9sZXMiOlsiUmVhZE9ubHkiXSwiZGF0YSI6e319.yVwuhsZQQgbk6ASaaA5iS2z_E7ThqPpMtYKfxjVcND8

  true

  
  query characterHeightMassFilter {
      character(where: {height: {LT: 100}, mass: {GTE: 45.0}}) {
          id
          name
          gender
          birthYear
          height
          mass
      }
  }
  
  

  To apply two comparisons to one property (e.g., a range check), put them together.

  <object> (where: {<property1>: {GTE:"<value1>", LT:"<value2>"}) {<properties>}
  

  Filter the list of characters to only include those with a height greater than 150 and less than 165.

  Loading...

  https://swapi-platform.ontotext.com/graphql

  eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImJNODctcWV3SldXTWRMRjIzNUtXUmluTlp4TDA0ZngzIn0.eyJhdWQiOiI2NzJjYTdiMy1jMzcyLTRkZjMtODJkOC05YTFhMGQ3ZDY4YzEiLCJleHAiOjE3MjkyNDk4MTksImlhdCI6MTY5ODE0NTgxOSwiaXNzIjoic3dhcGktcGxhdGZvcm0ub250b3RleHQuY29tIiwic3ViIjoiZTlmOWQzNGQtZThmMS00ODM1LTlkMzAtOWRjNmU5YjQ4ZmMzIiwianRpIjoiODZjNTIzYzEtYzQzNC00MWZiLWFkOTctYWU2MDY5MjgxYWM4IiwiYXV0aGVudGljYXRpb25UeXBlIjoiUEFTU1dPUkQiLCJlbWFpbCI6InJlYWRvbmx5dXNlckBleGFtcGxlLmNvbSIsImVtYWlsX3ZlcmlmaWVkIjp0cnVlLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJSZWFkT25seVVzZXIiLCJhcHBsaWNhdGlvbklkIjoiNjcyY2E3YjMtYzM3Mi00ZGYzLTgyZDgtOWExYTBkN2Q2OGMxIiwicm9sZXMiOlsiUmVhZE9ubHkiXSwiZGF0YSI6e319.yVwuhsZQQgbk6ASaaA5iS2z_E7ThqPpMtYKfxjVcND8

  true

  
  query characterHeightBetween {
      character(where: {height: {GT: 150, LT: 165}}) {
          id
          name
          gender
          birthYear
          height
      }
  }
  
  

  AND is an explicit conjunction: you will need to use it in two cases:

  1. To check two different instances of the same property.

  <object> (where: {AND: [{<object_property1>: {<property2>: {EQ:<value1>}}},
                          {<object_property1>: {<property2>: {EQ:<value2>}}}]}) {<properties>}
  

  Filter the list of characters to only include those that have appeared in films with episodeId 1 AND episodeId 5.

  Loading...

  https://swapi-platform.ontotext.com/graphql

  eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImJNODctcWV3SldXTWRMRjIzNUtXUmluTlp4TDA0ZngzIn0.eyJhdWQiOiI2NzJjYTdiMy1jMzcyLTRkZjMtODJkOC05YTFhMGQ3ZDY4YzEiLCJleHAiOjE3MjkyNDk4MTksImlhdCI6MTY5ODE0NTgxOSwiaXNzIjoic3dhcGktcGxhdGZvcm0ub250b3RleHQuY29tIiwic3ViIjoiZTlmOWQzNGQtZThmMS00ODM1LTlkMzAtOWRjNmU5YjQ4ZmMzIiwianRpIjoiODZjNTIzYzEtYzQzNC00MWZiLWFkOTctYWU2MDY5MjgxYWM4IiwiYXV0aGVudGljYXRpb25UeXBlIjoiUEFTU1dPUkQiLCJlbWFpbCI6InJlYWRvbmx5dXNlckBleGFtcGxlLmNvbSIsImVtYWlsX3ZlcmlmaWVkIjp0cnVlLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJSZWFkT25seVVzZXIiLCJhcHBsaWNhdGlvbklkIjoiNjcyY2E3YjMtYzM3Mi00ZGYzLTgyZDgtOWExYTBkN2Q2OGMxIiwicm9sZXMiOlsiUmVhZE9ubHkiXSwiZGF0YSI6e319.yVwuhsZQQgbk6ASaaA5iS2z_E7ThqPpMtYKfxjVcND8

  true

  
  query commonCharactersInFilms {
      character (where: {AND: [{film: {episodeId: {EQ: 1}}},
                               {film: {episodeId: {EQ: 5}}}]}){
          id
          name
          gender
          birthYear
          height
          film {
              episodeId
          }
      }
  }
  
  

  NOTE: You cannot write this query using IN because that would look for all characters starred in the selected episodes.

  <object> (where: {<object_property1>: {<property2>: {IN: [<value1>, <value2>]}}}) {<properties>}
  

  Loading...

  https://swapi-platform.ontotext.com/graphql

  eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImJNODctcWV3SldXTWRMRjIzNUtXUmluTlp4TDA0ZngzIn0.eyJhdWQiOiI2NzJjYTdiMy1jMzcyLTRkZjMtODJkOC05YTFhMGQ3ZDY4YzEiLCJleHAiOjE3MjkyNDk4MTksImlhdCI6MTY5ODE0NTgxOSwiaXNzIjoic3dhcGktcGxhdGZvcm0ub250b3RleHQuY29tIiwic3ViIjoiZTlmOWQzNGQtZThmMS00ODM1LTlkMzAtOWRjNmU5YjQ4ZmMzIiwianRpIjoiODZjNTIzYzEtYzQzNC00MWZiLWFkOTctYWU2MDY5MjgxYWM4IiwiYXV0aGVudGljYXRpb25UeXBlIjoiUEFTU1dPUkQiLCJlbWFpbCI6InJlYWRvbmx5dXNlckBleGFtcGxlLmNvbSIsImVtYWlsX3ZlcmlmaWVkIjp0cnVlLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJSZWFkT25seVVzZXIiLCJhcHBsaWNhdGlvbklkIjoiNjcyY2E3YjMtYzM3Mi00ZGYzLTgyZDgtOWExYTBkN2Q2OGMxIiwicm9sZXMiOlsiUmVhZE9ubHkiXSwiZGF0YSI6e319.yVwuhsZQQgbk6ASaaA5iS2z_E7ThqPpMtYKfxjVcND8

  true

  
  query allCharactersInFilms {
      character (where: {film: {episodeId: {IN: [1,5]}}}){
          id
          name
          gender
          birthYear
          height
      }
  }
  
  

• OR takes an array of clauses and applies a disjunction.

  <object> (where: {OR: [{<property1>: {IRE: <value1>}},
                         {<property2>: {IRE: <value2>}}]}) {<properties>}
  

  Filter the list of characters with name Skywalker or eyeColor green:

  Loading...

  https://swapi-platform.ontotext.com/graphql

  eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImJNODctcWV3SldXTWRMRjIzNUtXUmluTlp4TDA0ZngzIn0.eyJhdWQiOiI2NzJjYTdiMy1jMzcyLTRkZjMtODJkOC05YTFhMGQ3ZDY4YzEiLCJleHAiOjE3MjkyNDk4MTksImlhdCI6MTY5ODE0NTgxOSwiaXNzIjoic3dhcGktcGxhdGZvcm0ub250b3RleHQuY29tIiwic3ViIjoiZTlmOWQzNGQtZThmMS00ODM1LTlkMzAtOWRjNmU5YjQ4ZmMzIiwianRpIjoiODZjNTIzYzEtYzQzNC00MWZiLWFkOTctYWU2MDY5MjgxYWM4IiwiYXV0aGVudGljYXRpb25UeXBlIjoiUEFTU1dPUkQiLCJlbWFpbCI6InJlYWRvbmx5dXNlckBleGFtcGxlLmNvbSIsImVtYWlsX3ZlcmlmaWVkIjp0cnVlLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJSZWFkT25seVVzZXIiLCJhcHBsaWNhdGlvbklkIjoiNjcyY2E3YjMtYzM3Mi00ZGYzLTgyZDgtOWExYTBkN2Q2OGMxIiwicm9sZXMiOlsiUmVhZE9ubHkiXSwiZGF0YSI6e319.yVwuhsZQQgbk6ASaaA5iS2z_E7ThqPpMtYKfxjVcND8

  true

  
   query charactersWithGreenEyesOrNameSkywalker {
      character (where: {OR: [{name: {IRE: "Skywalker"}}, {eyeColor: {IRE: "green"}}]}) {
          id
          name
          eyeColor
          birthYear
          height
      }
  }
  
  

  NOTE: If you need to check for one of several values in the same field, it is easier to use RE with | (for text comparison) or IN (for fixed values).

  <object> (where: {<property>: {IRE: "<value1>|<value2>"}}) {<properties>}
  

  Filter the list of characters to only include those with a name property Anakin or Luke in the name:

  Loading...

  https://swapi-platform.ontotext.com/graphql

  eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImJNODctcWV3SldXTWRMRjIzNUtXUmluTlp4TDA0ZngzIn0.eyJhdWQiOiI2NzJjYTdiMy1jMzcyLTRkZjMtODJkOC05YTFhMGQ3ZDY4YzEiLCJleHAiOjE3MjkyNDk4MTksImlhdCI6MTY5ODE0NTgxOSwiaXNzIjoic3dhcGktcGxhdGZvcm0ub250b3RleHQuY29tIiwic3ViIjoiZTlmOWQzNGQtZThmMS00ODM1LTlkMzAtOWRjNmU5YjQ4ZmMzIiwianRpIjoiODZjNTIzYzEtYzQzNC00MWZiLWFkOTctYWU2MDY5MjgxYWM4IiwiYXV0aGVudGljYXRpb25UeXBlIjoiUEFTU1dPUkQiLCJlbWFpbCI6InJlYWRvbmx5dXNlckBleGFtcGxlLmNvbSIsImVtYWlsX3ZlcmlmaWVkIjp0cnVlLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJSZWFkT25seVVzZXIiLCJhcHBsaWNhdGlvbklkIjoiNjcyY2E3YjMtYzM3Mi00ZGYzLTgyZDgtOWExYTBkN2Q2OGMxIiwicm9sZXMiOlsiUmVhZE9ubHkiXSwiZGF0YSI6e319.yVwuhsZQQgbk6ASaaA5iS2z_E7ThqPpMtYKfxjVcND8

  true

  
   query charactersWithAnakinOrLukeInName {
      character (where: {name: {IRE: "Anakin|Luke"}}){
          id
          name
          eyeColor
          birthYear
          height
      }
  }
  
  

  NOTE: You can use OR at the operator level if you need a disjunction of two comparisons on the same field.

  <object> (where: {<property>: {OR: [{LT: <value1>} {GT: value2}]}}) {<properties>}
  

  Look for characters with height outside the range 100..200.

  Loading...

  https://swapi-platform.ontotext.com/graphql

  eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImJNODctcWV3SldXTWRMRjIzNUtXUmluTlp4TDA0ZngzIn0.eyJhdWQiOiI2NzJjYTdiMy1jMzcyLTRkZjMtODJkOC05YTFhMGQ3ZDY4YzEiLCJleHAiOjE3MjkyNDk4MTksImlhdCI6MTY5ODE0NTgxOSwiaXNzIjoic3dhcGktcGxhdGZvcm0ub250b3RleHQuY29tIiwic3ViIjoiZTlmOWQzNGQtZThmMS00ODM1LTlkMzAtOWRjNmU5YjQ4ZmMzIiwianRpIjoiODZjNTIzYzEtYzQzNC00MWZiLWFkOTctYWU2MDY5MjgxYWM4IiwiYXV0aGVudGljYXRpb25UeXBlIjoiUEFTU1dPUkQiLCJlbWFpbCI6InJlYWRvbmx5dXNlckBleGFtcGxlLmNvbSIsImVtYWlsX3ZlcmlmaWVkIjp0cnVlLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJSZWFkT25seVVzZXIiLCJhcHBsaWNhdGlvbklkIjoiNjcyY2E3YjMtYzM3Mi00ZGYzLTgyZDgtOWExYTBkN2Q2OGMxIiwicm9sZXMiOlsiUmVhZE9ubHkiXSwiZGF0YSI6e319.yVwuhsZQQgbk6ASaaA5iS2z_E7ThqPpMtYKfxjVcND8

  true

  
  query characterHeightBetween {
      character(where: {height: {OR: [{LT: 100}, {GT: 200}]}}) {
          id
          name
          gender
          birthYear
          height
      }
  }
  
  

• NOT negates a clause. Most of the time you will not need it because you can use negation at the operator level.

  Loading...

  https://swapi-platform.ontotext.com/graphql

  eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImJNODctcWV3SldXTWRMRjIzNUtXUmluTlp4TDA0ZngzIn0.eyJhdWQiOiI2NzJjYTdiMy1jMzcyLTRkZjMtODJkOC05YTFhMGQ3ZDY4YzEiLCJleHAiOjE3MjkyNDk4MTksImlhdCI6MTY5ODE0NTgxOSwiaXNzIjoic3dhcGktcGxhdGZvcm0ub250b3RleHQuY29tIiwic3ViIjoiZTlmOWQzNGQtZThmMS00ODM1LTlkMzAtOWRjNmU5YjQ4ZmMzIiwianRpIjoiODZjNTIzYzEtYzQzNC00MWZiLWFkOTctYWU2MDY5MjgxYWM4IiwiYXV0aGVudGljYXRpb25UeXBlIjoiUEFTU1dPUkQiLCJlbWFpbCI6InJlYWRvbmx5dXNlckBleGFtcGxlLmNvbSIsImVtYWlsX3ZlcmlmaWVkIjp0cnVlLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJSZWFkT25seVVzZXIiLCJhcHBsaWNhdGlvbklkIjoiNjcyY2E3YjMtYzM3Mi00ZGYzLTgyZDgtOWExYTBkN2Q2OGMxIiwicm9sZXMiOlsiUmVhZE9ubHkiXSwiZGF0YSI6e319.yVwuhsZQQgbk6ASaaA5iS2z_E7ThqPpMtYKfxjVcND8

  true

  
   query notMaleCharacters {
      character (where: {NOT: {gender: {IRE: "male"}}}){
          id
          name
          eyeColor
          birthYear
          height
      }
  }
  
  

• exists is implicit when checking properties and sub-properties (one value is enough to satisfy the condition).

  <object> (where: {<property>: {}}) {<properties>}
  

  Look for characters with at least one starship and vehicle.

  Loading...

  https://swapi-platform.ontotext.com/graphql

  eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImJNODctcWV3SldXTWRMRjIzNUtXUmluTlp4TDA0ZngzIn0.eyJhdWQiOiI2NzJjYTdiMy1jMzcyLTRkZjMtODJkOC05YTFhMGQ3ZDY4YzEiLCJleHAiOjE3MjkyNDk4MTksImlhdCI6MTY5ODE0NTgxOSwiaXNzIjoic3dhcGktcGxhdGZvcm0ub250b3RleHQuY29tIiwic3ViIjoiZTlmOWQzNGQtZThmMS00ODM1LTlkMzAtOWRjNmU5YjQ4ZmMzIiwianRpIjoiODZjNTIzYzEtYzQzNC00MWZiLWFkOTctYWU2MDY5MjgxYWM4IiwiYXV0aGVudGljYXRpb25UeXBlIjoiUEFTU1dPUkQiLCJlbWFpbCI6InJlYWRvbmx5dXNlckBleGFtcGxlLmNvbSIsImVtYWlsX3ZlcmlmaWVkIjp0cnVlLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJSZWFkT25seVVzZXIiLCJhcHBsaWNhdGlvbklkIjoiNjcyY2E3YjMtYzM3Mi00ZGYzLTgyZDgtOWExYTBkN2Q2OGMxIiwicm9sZXMiOlsiUmVhZE9ubHkiXSwiZGF0YSI6e319.yVwuhsZQQgbk6ASaaA5iS2z_E7ThqPpMtYKfxjVcND8

  true

  
   query charactersWithStarshipAndVehicle {
      character (where: {starship: {}, vehicle: {}}){
          id
          name
          starship (limit: 1) {name}
          vehicle (limit: 1) {name}
      }
  }
  
  

• ALL is applicable to multi-valued properties and checks that all values satisfy the condition.

  <object> (where: {All: {<object_property>: {<property>: {GTE: <value>}}}}) {<properties>}
  

  Find characters all of whose starships have maxAtmospheringSpeed higher than 1000.

  Loading...

  https://swapi-platform.ontotext.com/graphql

  eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImJNODctcWV3SldXTWRMRjIzNUtXUmluTlp4TDA0ZngzIn0.eyJhdWQiOiI2NzJjYTdiMy1jMzcyLTRkZjMtODJkOC05YTFhMGQ3ZDY4YzEiLCJleHAiOjE3MjkyNDk4MTksImlhdCI6MTY5ODE0NTgxOSwiaXNzIjoic3dhcGktcGxhdGZvcm0ub250b3RleHQuY29tIiwic3ViIjoiZTlmOWQzNGQtZThmMS00ODM1LTlkMzAtOWRjNmU5YjQ4ZmMzIiwianRpIjoiODZjNTIzYzEtYzQzNC00MWZiLWFkOTctYWU2MDY5MjgxYWM4IiwiYXV0aGVudGljYXRpb25UeXBlIjoiUEFTU1dPUkQiLCJlbWFpbCI6InJlYWRvbmx5dXNlckBleGFtcGxlLmNvbSIsImVtYWlsX3ZlcmlmaWVkIjp0cnVlLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJSZWFkT25seVVzZXIiLCJhcHBsaWNhdGlvbklkIjoiNjcyY2E3YjMtYzM3Mi00ZGYzLTgyZDgtOWExYTBkN2Q2OGMxIiwicm9sZXMiOlsiUmVhZE9ubHkiXSwiZGF0YSI6e319.yVwuhsZQQgbk6ASaaA5iS2z_E7ThqPpMtYKfxjVcND8

  true

  
   query charactersWithFastStarshipOrMissing  {
      character (where: {ALL: {starship: {maxAtmospheringSpeed: {GTE: 1000}}}}){
          id
          name
          starship (limit: 1) {maxAtmospheringSpeed}
      }
  }
  
  

• Please note that characters without any starship will also be returned by the above query (a vacuous truth), so you may want to add an existence check:

  <object> (where: {All: {<object_property1>: {<property2>: {GTE: <value>}}}
                          <object_property1>: {<property2>: {GTE: <value>}}}) {<properties>}
  

  Loading...

  https://swapi-platform.ontotext.com/graphql

  eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImJNODctcWV3SldXTWRMRjIzNUtXUmluTlp4TDA0ZngzIn0.eyJhdWQiOiI2NzJjYTdiMy1jMzcyLTRkZjMtODJkOC05YTFhMGQ3ZDY4YzEiLCJleHAiOjE3MjkyNDk4MTksImlhdCI6MTY5ODE0NTgxOSwiaXNzIjoic3dhcGktcGxhdGZvcm0ub250b3RleHQuY29tIiwic3ViIjoiZTlmOWQzNGQtZThmMS00ODM1LTlkMzAtOWRjNmU5YjQ4ZmMzIiwianRpIjoiODZjNTIzYzEtYzQzNC00MWZiLWFkOTctYWU2MDY5MjgxYWM4IiwiYXV0aGVudGljYXRpb25UeXBlIjoiUEFTU1dPUkQiLCJlbWFpbCI6InJlYWRvbmx5dXNlckBleGFtcGxlLmNvbSIsImVtYWlsX3ZlcmlmaWVkIjp0cnVlLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJSZWFkT25seVVzZXIiLCJhcHBsaWNhdGlvbklkIjoiNjcyY2E3YjMtYzM3Mi00ZGYzLTgyZDgtOWExYTBkN2Q2OGMxIiwicm9sZXMiOlsiUmVhZE9ubHkiXSwiZGF0YSI6e319.yVwuhsZQQgbk6ASaaA5iS2z_E7ThqPpMtYKfxjVcND8

  true

  
   query charactersWithFastStarship {
      character (where: {ALL: {starship: {maxAtmospheringSpeed: {GT: 1000}}}
                               starship: {maxAtmospheringSpeed: {GT: 1000}}}){
          id
          name
          starship (limit: 1) {maxAtmospheringSpeed}
      }
  }
  
  

• ALL_EXISTS is applicable to multi-valued properties and checks both ALL and exists.

  <object> (where: {ALL_EXISTS: {<object_property>: {<property>: {GTE: <value>}}}}) {<properties>}
  

  The query below filters the list of characters that have starship with only tall pilots (over 180cm) and have at least one such pilot, and returns all their pilots:

  Loading...

  https://swapi-platform.ontotext.com/graphql

  eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImJNODctcWV3SldXTWRMRjIzNUtXUmluTlp4TDA0ZngzIn0.eyJhdWQiOiI2NzJjYTdiMy1jMzcyLTRkZjMtODJkOC05YTFhMGQ3ZDY4YzEiLCJleHAiOjE3MjkyNDk4MTksImlhdCI6MTY5ODE0NTgxOSwiaXNzIjoic3dhcGktcGxhdGZvcm0ub250b3RleHQuY29tIiwic3ViIjoiZTlmOWQzNGQtZThmMS00ODM1LTlkMzAtOWRjNmU5YjQ4ZmMzIiwianRpIjoiODZjNTIzYzEtYzQzNC00MWZiLWFkOTctYWU2MDY5MjgxYWM4IiwiYXV0aGVudGljYXRpb25UeXBlIjoiUEFTU1dPUkQiLCJlbWFpbCI6InJlYWRvbmx5dXNlckBleGFtcGxlLmNvbSIsImVtYWlsX3ZlcmlmaWVkIjp0cnVlLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJSZWFkT25seVVzZXIiLCJhcHBsaWNhdGlvbklkIjoiNjcyY2E3YjMtYzM3Mi00ZGYzLTgyZDgtOWExYTBkN2Q2OGMxIiwicm9sZXMiOlsiUmVhZE9ubHkiXSwiZGF0YSI6e319.yVwuhsZQQgbk6ASaaA5iS2z_E7ThqPpMtYKfxjVcND8

  true

  
   query charactersWithStarshipAnaHeightPilots {
      character (where: {starship: {ALL_EXISTS: {pilot: {height: {GTE:180}}}}}){
          id
          name
          starship {
              pilot{
                  height
              }
          }
      }
  }
  
  

Type Selectors¶

Version 3.1 of the Semantic Objects introduces a special type selector that acts as a shortcut for type checking as well as provides access to specific type properties when we filter properties with interface range.

The type selector has the form _ifType where Type will be any concrete sub-type for the current interface.

Let’s demonstrate this with an example. In the Star Wars model, we have an interface Character that has many sub-types. Some of them has additional properties that are not present in the parent:

Loading...

https://swapi-platform.ontotext.com/graphql

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImJNODctcWV3SldXTWRMRjIzNUtXUmluTlp4TDA0ZngzIn0.eyJhdWQiOiI2NzJjYTdiMy1jMzcyLTRkZjMtODJkOC05YTFhMGQ3ZDY4YzEiLCJleHAiOjE3MjkyNDk4MTksImlhdCI6MTY5ODE0NTgxOSwiaXNzIjoic3dhcGktcGxhdGZvcm0ub250b3RleHQuY29tIiwic3ViIjoiZTlmOWQzNGQtZThmMS00ODM1LTlkMzAtOWRjNmU5YjQ4ZmMzIiwianRpIjoiODZjNTIzYzEtYzQzNC00MWZiLWFkOTctYWU2MDY5MjgxYWM4IiwiYXV0aGVudGljYXRpb25UeXBlIjoiUEFTU1dPUkQiLCJlbWFpbCI6InJlYWRvbmx5dXNlckBleGFtcGxlLmNvbSIsImVtYWlsX3ZlcmlmaWVkIjp0cnVlLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJSZWFkT25seVVzZXIiLCJhcHBsaWNhdGlvbklkIjoiNjcyY2E3YjMtYzM3Mi00ZGYzLTgyZDgtOWExYTBkN2Q2OGMxIiwicm9sZXMiOlsiUmVhZE9ubHkiXSwiZGF0YSI6e319.yVwuhsZQQgbk6ASaaA5iS2z_E7ThqPpMtYKfxjVcND8

true

query planetHumanResidentsWithFriendsOrDroidsWithPrimaryFunctionOrWookiee{
  planet(where: {resident: {
                  _ifHuman: {friend: {}},
                  _ifDroid: {primaryFunction: {}},
                  _ifWookiee: {}}
                 }
  ) {
    name
    resident {
      name
      ... on Human {
        friend {
          name
        }
      }
      ... on Droid {
        primaryFunction
      }
    }
  }
}

If we run the example, we would get:

• All Humans that have any friends
• All Droids with set primary function
• All Wookiees

As we can see, the type selector allows accessing concrete properties for the type, as well as filtering the objects from the same type. As the sub-types are disjoint and we combine multiple type selectors, they all are grouped with implicit OR along with any common filters that apply for all of them.

Language Fetching¶

The Ontotext Semantic Objects use a specially formatted language string to specify language tags and a preference order for fetching values.

Language elements:

• lang: exact language match, e.g., en or en-US
• lang~: language and its “dialects”, i.e., prefix match at the end of a language tag component, for example en~
• ~: match any non-empty language, i.e., values with rdf:langString type
• NONE: match values without language tag, i.e., values with xsd:string type
• ANY: match any language tag, including empty language. Note that this is nearly the same but not equivalent to ~,NONE because that prefers non-empty language first.
• BROWSER: match language tags passed via the HTTP Accept-Language header. The keyword could be used for fetching and ordering the results. For more information, see the HTTP Accept-Language section.

Exclusions: these discard values with the indicated language:

• -lang: exclude this language, e.g., -en or -en-US
• -lang~: exclude this language and any of its “dialects”, e.g., -en~
• -~: exclude all non-empty languages so it will match values without a language tag
• -NONE: exclude values without a language tag
• -ANY is not allowed because it would forbid all values
• -BROWSER is not allowed

A sequence of elements can also be specified:

• By default, there are no restrictions on lang, so ALL values are returned.
• If you specify lang, then only the first value with matching language is returned.
  • Use lang: "ANY" to return a single value, regardless of its language (or whether it has a language at all).
• Use ALL as first element (with trailing colon :) to return all values with matching languages (e.g., ALL:en,fr should return all values in English and French). If you use this, the order of languages does not matter, and you should not have generic tags that subsume more specific tags (e.g., ALL:en-GB,en-GB~ should not appear).
  • If you use ALL:ANY, then do not use any other language.
• lang1,lang2,lang3: comma-separated sequence of languages in preference order.
  • You should list more specific tags earlier (e.g., en-GB,en-GB~ or en,en~), else they will have no effect.
  • There should be no duplicates.
• -lang1,-lang2,-lang3: comma-separated set of exclusions. All are checked, so their order does not matter (and they are customarily specified last). Each exclusion should be less general than any specified language, or it will prevent the language from having an effect. For example, en-GB,en,-en~ makes no sense because the exclusion kills the two preceding languages.
• BROWSER: the Accept-Language header (see HTTP Accept-Language) is parsed, ordered by specificity, then by q value, converted to lang~ ranges, and inserted instead of the BROWSER keyword.
  • The lang spec is validated as described above (duplicates, lang subsumption and exclusions) before the BROWSER element is replaced, because the Accept-Language header is under user control, not under SOML designer’s control.
  • If the request does not have such header or the value of the header is invalid then the BROWSER keyword is ignored. In this case the following behavior could be expected:
    • lang: "ALL:BROWSER" will have the same effect as lang: "ALL" and will fetch all possible values
    • lang: "BROWSER" will have the same effect as lang: "~" and will fetch the first found language
    • orderBy: {desc: {lang: "BROWSER"}} will have undetermined order result

In order to use any of the above to filter the returned literal values, the fetch spec needs to be used on a lang argument for the given property like in the example below. It returns all characters and a single description in German, or, if no German language description is present, in English.

query charactersWithGermanDescription {
    character(where: {desc: {}}) {
        name
        desc(lang: "de,en") {
          value
          lang
        }
    }
}

Here are some examples of language specs that return one value (or no values). “First” means the first value that matches a condition. In case there are several, one is picked at random.

Examples of language specs that return many values. The language order is irrelevant.

Examples of invalid language specs:

HTTP Accept-Language¶

The HTTP protocol uses an Accept-Language header defined in RFC 2616 Section 14.4 and RFC 3282.

It is based on RFC 4647 and allows the HTTP client (i.e., browser) to:

• Specify languages acceptable to the user
• Use “basic lang range” (prefix) matching
• Match the most specific (longest) range first
• Use wildcard (*) to match any non-empty lang tag
• Specify lang precedence by using quality values (q=); the default is 1.0.

Below are some examples and their interpretation:

In these interpretations, lang ranges are first ordered by specificity, then by quality value.

Please note that examples 2 and 4 do not make a lot of sense since they give more preference to a less specific lang range:

• Example 2 says “prefer any English to British English” but any does include British English.
• Example 4 says “prefer any language to English” but any does include English.

In order to access the HTTP header value, the BROWSER keyword must be used.

The header value, if present, is parsed, ordered by specificity, then by q value, converted to lang~ ranges, and inserted instead of the BROWSER keyword.

• The language spec is validated as described in the previous Language Fetching section (duplicates, lang subsumption, and exclusions) before the BROWSER element is replaced, because the Accept-Language header is controlled by the user and not by the designer of the SOML.
• If the request does not have such a header or the value of the header is invalid, then the BROWSER keyword is ignored. In this case, the following behavior can be expected:
  • lang: "ALL:BROWSER" will have the same effect as lang: "ALL" and will fetch all possible values.
  • lang: "BROWSER" will have the same effect as lang: "~" and will fetch the first found language.
  • orderBy: {desc: {lang: "BROWSER"}} will have undetermined order result, as for the ordering functionality to work properly, it needs a single value to be selected (preferably in the same language). To minimize the impact of the missing header, add a default to your sort argument, such as orderBy: {desc: {lang: "BROWSER,en"}}.

The following example demonstrates the use of the BROWSER keyword and the HTTP Accept-Language header.

Consider the following SOML schema:

objects:
  skos:Concept:
    props:
      skos:prefLabel:  {max: inf, range: stringOrLangString}
      skos:definition: {max: inf, range: stringOrLangString}

Assume the following data:

<https://nomenclature.info/nom/5313>
  a skos:Concept;
  skos:prefLabel
    "Two-Handed Crosscut Saw"@en,
    "Godendard"@fr-CA,
    "Passe-partout"@fr;
  skos:definition
    "A tool consisting of a stationary, wide, heavy, serrated blade..."@en,
    "Outil composé d'une longue lame dentelée à dos convexe..."@fr.

You can use it to fetch a concept with values for its multi-lingual properties based on the Accept-Language HTTP header with the following query:

query {
  skos_Concept(ID:"https://nomenclature.info/nom/5313") {
    skos_prefLabel (lang:"BROWSER,en") {value lang}
    skos_definition(lang:"ALL:BROWSER") {value lang}
  }
}

It will return:

• skos:prefLabel - the first value that matches the header value or English value
• skos:definition - all values matching the header value

Let’s assume the BROWSER Accept-Language is set to "fr, fr-CA". This will effectively set the query lang argument to:

query {
  skos_Concept(ID:"https://nomenclature.info/nom/5313") {
    skos_prefLabel (lang:"fr-CA~,fr~,en") {value lang}
    skos_definition(lang:"ALL:fr~") {value lang}
  }
}

Note that for the skos_definition fetching language pattern the fr-CA~ is ignored, as it is included in the fr~ spec.

Then the following response is returned:

{
  "data": [{
    "skos_Concept": {
      "skos_prefLabel": [
        {"value": "Godendard", "lang": "fr-CA"}
      ],
      "skos_definition": [
        {"value": "Outil composé d'une longue lame dentelée à dos convexe...", "lang": "fr"}
      ]
    }
  }]
}

Now let’s assume the HTTP header Accept-Language is missing. The following response will be returned:

{
  "data": [{
    "skos_Concept": {
      "skos_prefLabel": [
        {"value": "Two-Handed Crosscut Saw", "lang": "en"},
      ],
      "skos_definition": [
        {"value": "A tool consisting of a stationary, wide, heavy, serrated blade...", "lang": "en"},
        {"value": "Outil composé d'une longue lame dentelée à dos convexe...",         "lang": "fr"}
      ]
    }
  }]
}

If the lang pattern with``BROWSER`` is applicable for ordering, like in the example below, only the first value of the pattern will take effect.

query {
  skos_Concept(lang: "BROWSER,en", orderBy: {skos_prefLabel: {dir: DESC}}) {
    skos_prefLabel {value lang}
    skos_definition(lang:"ALL:BROWSER") {value lang}
  }
}

Let’s assume the BROWSER Accept-Language is set to "fr, fr-CA" again. This will set the effective query lang arguments as in the example below.

query {
  skos_Concept(orderBy: {skos_prefLabel: {lang: "fr-CA~", dir: DESC}}) {
    skos_prefLabel(lang: "fr-CA~,fr~,en") {value lang}
    skos_definition(lang:"ALL:fr~") {value lang}
  }
}

For more information about result sorting, see the Ordered Object List section.

Language Preference Order for Fetching¶

Language specs can be provided at different levels. The spec at a given level will apply to lower levels if they do not specify their own lang fetching option. Consider the example:

query humanInEnglish {
  human(lang: "en") {
    name
    desc {
      value
      lang
    }
    film(lang: "it,de") {
      name
      desc {
        value
        lang
      }
      vehicle {
        name
        desc(lang: "de") {
          value
          lang
        }
      }
    }
    homeworld {
      name
      desc {
        value
        lang
      }
    }
  }
}

In this example query, the language spec for fetching is applied at multiple levels:

• When applied at the query level, it will apply for all Literal properties. For our example, it means that Planet.desc and Planet.resident.homeworld.desc will have only English language descriptions, if any.
• When applied to a complex property like Planet.film, it overrides the upper level (the query in this case) and changes the default behavior for the Planet.film.desc to English, or, if an English language description is not present, to German.
• When applied to a literal property’s lang argument, it will override any spec coming from an upper level. In our example, the Planet.film.vehicle.desc and Planet.resident.desc have their own language fetch specs, so they will be used for fetching the descriptions for these objects.

If the query does not define any language fetch spec (or lang: null is provided), there are two possible outcomes:

• The values will be filtered based on the language fetch configuration in the SOML model for the langString or stringOrLangString properties. For more information, see the SOML property language configurations.
• All values will be returned.

Language Filtering¶

While the previous section describes using language specs to fetch language-tagged values, here we will see how to filter objects by language-tagged values of a field. Make sure that the object has values and/or does not have values with specified languages.

Language specs for filtering are similar to language specs for fetching, but simpler:

• An object satisfies a language spec if it has at least one matching value.
• To find objects that do not have matching values, you cannot use exclusion (-). Use NOT at the outer level (see examples below).
• The mode is always ALL because all conditions are checked.
• ANY is not allowed because it is a vacuous check.
• -ANY is not allowed because it would exclude all objects.
• The same conditions about language subsumption and exclusion compatibility apply as in the previous section.
• BROWSER is not allowed because it makes no sense to search for objects having a value in a user-determined language.

Language specs for filtering add the following features:

• UNIQ: find objects that do not have multiple values in the same language. This is intended to check SKOS Integrity Condition S14.
• -UNIQ: find objects that have multiple values in the same language. This can be used to find and fix such objects.
• These checks pertain to empty language tags.
• You can combine them with language tags to refine the list of languages being checked.
• The UNIQ check must come last and be separated with semicolon.

Examples of filtering by language spec:

Examples of invalid language specs for filtering:

Examples:

All objects in the schema.yaml have a multilingual property desc, which can be used for trying the language filtering functionality.

Find all Characters that have values with non-empty language:

query charactersWithNoneEmptyLangs {
    character(where: {desc: {lang: "~"}}) {
        name
        desc {
            value
            lang
        }
    }
}

All Film-s that have description in German, and we fetch only the German descriptions:

query filmsWithGermanDescription {
    film(where: {desc: {lang: "de"}}) {
        name
        desc(lang: "de") {
            value
            lang
        }
    }
}

All Character-s that have non-English description. Try removing the value fetching filter -en to see how the response changes.

query characterWithNoneEnglishDescription {
    character(where: {desc: {lang: "~,-en~"}}) {
        name
        desc(lang: "-en") {
            value
            lang
        }
    }
}

Find Character-s that do not have unique language description. Try changing the filter to UNIQ.

query characterWithNoneUniqueDescription {
    character(where: {desc: {lang: "-UNIQ"}}) {
        name
        desc {
            value
            lang
        }
    }
}

Fragments¶

Fragments are the primary unit of composition in GraphQL.

Fragments allow for the reuse of common repeated selections of fields, reducing duplicated text in the document. Inline Fragments can be used directly within a selection to condition upon a type condition when querying against an interface or union.

For example, if we want to fetch some common information about a film, we would have the following query:

query usingFragments {
  film(ID: "https://swapi.co/resource/film/1") {
    id
    name
    role {
      roleType
      person {
        name
      }
      character {
        name
      }
    }
    planet {
      id
      name
      resident {
        id
        name
        film {
          id
          name
          role {
            roleType
            person {
              name
            }
            character {
              name
            }
          }
        }
      }
    }
  }
}

The repeated fields can be extracted into a fragment and composed by a parent fragment or query.

query usingFragments {
  film(ID: "https://swapi.co/resource/film/1") {
    ...commonFilmProperties
    planet {
      id
      name
      resident {
        id
        name
        film {
          ...commonFilmProperties
        }
      }
    }
  }
}
fragment commonFilmProperties on Film {
  id
  name
  role {
    roleType
    person {
      name
    }
    character {
      name
    }
  }
}

Fragments are consumed by using the spread operator (…). All fields selected by the fragment will be added to the query field selection at the same level as the fragment invocation. This happens through multiple levels of fragment spreads.

query usingFragments {
  film(ID: "https://swapi.co/resource/film/1") {
    ...detailedFilmProperties
    planet {
      id
      name
      resident {
        id
        name
        film {
          ...commonFilmProperties
        }
      }
    }
  }
}
fragment commonFilmProperties on Film {
  id
  name
  role {
    roleType
    person {
      name
    }
    character {
      name
    }
  }
}
fragment detailedFilmProperties on Film {
  releaseDate
  desc {
    value
    lang
  }
  episodeId
  ...commonFilmProperties
}

Inline Fragments¶

Fragments can be defined inline within a selection set. This is done to conditionally include fields based on their runtime type.

query film1 {
    film(ID: "https://swapi.co/resource/film/1") {
        id
        name
        character {
            type
            name
            ... on Droid {
                name
                id
            }
            ... on Human {
                name
                eyeColor
                skinColor
            }
        }
    }
}

Note that the name field is requested separately for character, Droid, and Human, but it is returned only once for each character. When more than one fields of the same name are executed in parallel, their selection sets are merged together when completing the value in order to continue execution of the sub‐selection sets.

Aliases¶

GraphQL Aliases allows you to rename the result of a field to anything you want. Let’s say you want to have the same top level field in the same query with different arguments We can achieve this by using alias for film.

For example:

query usingAliases {
  Film1:film(ID: "https://swapi.co/resource/film/1") {
    id
    name
    releaseDate
  }
  Film2:film(orderBy:{episodeId:DESC}) {
    id
    name
    releaseDate
    episodeId
    openingCrawl
  }
}

Aliases are necessary for the query to work. If you run the query without aliases, it will return an error:

query withoutAliases {
  film(ID: "https://swapi.co/resource/film/1") {
    id
    name
    releaseDate
  }
  film(orderBy:{episodeId:DESC}) {
    id
    name
    releaseDate
    episodeId
    openingCrawl
  }
}

GraphQL Aliases are dynamic, written on the client making the request. This is a workaround for use cases where you want the selection set to be named more readable. It is not prudent to write this for every query from every client making this request for modifying trivial fields.

Dataset selection¶

SPARQL offers ways for changing the dataset against which a given query is evaluated. For queries, this is done using the FROM keyword used to specify what is included in the default dataset and which graphs to be included during query evaluation. In GraphQL, this is represented as the from query argument.

See more about SPARQL datasets in the SPARQL query specification here.

See more about SPARQL queries and datasets in the GraphDB documentation here.

Here is an example GraphQL query that specifies a source dataset when evaluating a query:

query {
  object(from: "https://swapi.co/resource/humans") {
     id
  }
}

Change repository¶

Along with changing the query dataset, GraphQL queries can also be used to change the target repository altogether. The only requirement is that the other repository is accessible on the same server address.

The target repository is specified using the repository argument in GraphQL query like so:

query {
  object(repository: "otherRepository") {
     id
  }
}

Alternatively, the target repository can be provided via the X-Repository HTTP header. When supplied this way, the value will apply to all queries and mutations in the request.

If security is enabled, it can also be read from the JSON Web Token (JWT) claim. To enable this, the configuration sparql.endpoint.repository must be defined as ${ctx.claims.<claim_key>:<default_repository>}, where:

• claim_key is the name of the JWT claim from which the repository identifier can be read
• default_repository is the repository to be used if no such key and value are found in the claims of the authenticated user. An example configuration that reads a claim named repository and default repository named soaas would look like this: ${ctx.claims.repository:soaas}.

The access to the repositories can be restricted by using the Semantic Objects configuration sparql.endpoint.repositoryWhitelist. If not empty, the only accessible repositories will be the ones listed there.

It can also be used to effectively disable the functionality completely by listing the only one available repository like so:

sparql.endpoint.repository: soaas
sparql.endpoint.repositoryWhitelist: soaas

If no specific information about the target repository is provided in the query or the HTTP header, the repository value will be taken from the SOML configuration, if available. The SOML schema configuration looks like this:

config:
  repository: soaas

If the configured SPARQL endpoint server has security enabled, the configured user must have access to all repositories that they need to access.

Inference¶

The default behavior of the Semantic Objects (unless specified otherwise) is to include the inferred statements from the underlying repository when evaluating the queries and mutations.

See more about inference and inferred statements here.

In each query, the includeInferred parameter can be used to change the inference for that particular query:

query {
   object(includeInferred: false) {
       id
       name
   }
}

The HTTP header X-Include-Inferred: false can also be used to disable the inference for the entire GraphQL request.

The way inferred statements are included in the query evaluation can also be changed at SOML schema level in the config section.

The SOML config value will be applied if there is no explicit override in a request via a query argument or an HTTP header.

config:
  includeInferred: false

Expand over owl:sameAs¶

The default behavior of the Semantic Objects (unless specified otherwise) is to join results for subjects that are linked with the owl:sameAs predicate when evaluating the queries and mutations, but only if the support for it is enabled at repository and ruleset level.

See more about owl:sameAs and how it is implemented in GraphDB here.

The default behavior for owl:sameAs expansion can be configured at SOML schema level in the config section. The value there will be applied if a particular request does not override it explicitly.

config:
  expandOwlSameAs: true

In each query, the parameter expandOwlSameAs can be used to change the owl:sameAs behavior for that particular query.

query {
   object(expandOwlSameAs: false) {
       id
       name
   }
}

The HTTP header X-Expand-Over-Owl-SameAs: false can also be used to disable the owl:sameAs resolution for the entire GraphQL request.

An alternative to the argument expandOwlSameAs: false is to use from: "onto:disable-sameAs" as this is the same behavior that the Semantic Objects apply under the hood.

query {
   object(from: "onto:disable-sameAs") {
       id
       name
   }
}

The default behavior for owl:sameAs expansion could be configured on SOML schema level in the config section. The value there will be applied if a particular request does not override it explicitly.

config:
  expandOwlSameAs: true