Quick Start

Install and start the Semantic Objects in less than 5 minutes following the steps below.


The Semantic Objects use Docker and Docker containers for all of their services. All of them are published in the Ontotext Docker hub. You will need to install the Docker daemon on the machine on which you will be running the service.

Please follow the Docker installation guide.

Docker Compose

The Semantic Objects can be run using a Docker Compose configuration on your developer machine.

You will need to install Docker Compose on the machine on which you wish to run the service.

Follow the Docker Compose installation guide.

A docker-compose.yaml configuration will download and start the Semantic Objects, GraphDB, and Workbench containers on a single machine.


When deploying the Semantic Objects on an environment different from localhost, you need to set the environment variable GRAPHQL_ENDPOINT to "http://ip-of-deployment-host:9995/graphql".

The Ontotext Semantic Objects are available under a commercial time-based license. To obtain an evaluation license, please contact the Ontotext team and see the documentation on Setting up Licenses.

Once you have obtained the license, you can either:


If you have a pre-existing installation of GraphDB and want to use it instead of setting up a new instance, you can use the following docker-compose-remote-graphdb.yaml

To configure the Semantic Objects to work with an existing/remote GraphDB, you need to set the GraphDB address in the sparql.endpoint.address environment variable. Please note that the Semantic Objects must be able to access the provided address set to the configuration soml.storage.rdf4j.address.

If GraphDB has security enabled, you need to provide the username and password with the following environment variables in the semantic-objects service section:

  • sparql.endpoint.username: "yyyyyyy"
  • sparql.endpoint.credentials: "xxxxxxxxx"

If you want to deploy GraphDB in a cluster topology, follow the GraphDB cluster topologies instructions.


cURL is required only if you intend to use system console to create repositories and load data into GraphDB, manage a Semantic Objects schema, as well as perform GraphQL queries. All of these actions can be executed using the Workbench.

Please follow the cURL installation guide.

Start the Service

Start the docker containers using:

docker-compose -f /path/to/your/docker-compose.yaml up -d


If you are using pre-existing/remote GraphDB, the command should be:

docker-compose -f /path/to/your/docker-compose-remote-graphdb.yaml up -d

If you have problems with old containers, consider using the --force-recreate flag, e.g., docker-compose -f /path/to/your/docker-compose.yaml up -d --force-recreate.

You can check the running containers using the following docker command:

docker ps

It should include Semantic Objects, the Workbench, and GraphDB.

Initialize GraphDB

  1. If your GraphDB distribution is an Enterprise edition like in the example above, you will need to provide a license. You can do it through the GraphDB Workbench using http://localhost:9998/. See the official documentation on Setting up Licenses.


    Alternatively, the license can be provisioned by mounting it in the Docker container in the /opt/graphdb/dist/conf/graphdb.license path.

    If you are using a pre-existing/remote GraphDB you can proceed directly with the repository creation.

  2. Once the license is provisioned, you need to create a repository. First, download the repo.ttl RDF dataset, which contains configurations for a repository named soaas.

  3. Upload it via the GraphDB Workbench following the instructions for Creating a repository.

    Alternatively, you can also upload it using the following cURL command:

    curl -X POST -H "Content-Type: multipart/form-data" -F "config=@repo.ttl" http://localhost:9998/rest/repositories/


A repo can be automatically initialized by GraphDB if repo.ttl is mounted in the GraphDB Docker container under the /opt/graphdb/dist/data/repositories/soaas/config.ttl path.

Put Star Wars Data into GraphDB

  1. Download the starwars-data.ttl RDF dataset.

    It describes Star Wars, films, starships, characters, etc. You can find more details about this dataset here.

  2. Upload it via the GraphDB Workbench following the instructions for Loading data from a local file.

    Alternatively, you can also upload it using the following cURL command:

    curl -X POST -H "Content-Type:application/x-turtle" -T starwars-data.ttl http://localhost:9998/repositories/soaas/statements

Define Star Wars Semantic Objects

  1. Download the Semantic Object schema.yaml.

    It describes the Semantic Object mapping to Star Wars RDF, and is then used to generate a GraphQL schema for querying the Star Wars data.

  2. Load the Semantic Objects schema from the Workbench on http://localhost:9993/ following the instructions for Uploading Schema Wizard.

    Alternatively, you can also load it using the following cURL command:

    curl -X POST -H "Content-Type: text/yaml" -H "Accept: application/ld+json" -T schema.yaml -H "X-Request-ID: GettingStartedTx01" http://localhost:9995/soml
  3. Activate (bind) this schema instance in order to generate a GraphQL schema. You can do this from the Workbench by following the Upload Schema Wizard steps or from the Manage Schema page.

    Alternatively, you can also activate it using the following cURL command for the Semantic Objects:

    curl -X PUT -H "X-Request-ID: GettingStartedTx02" http://localhost:9995/soml/swapi/soaas

Run a Star Wars GraphQL Query

The following query gets all planets that contain “Tatooine” ordered in ascending order. Each resident is ordered by height and name.

query Tatooine { planet( orderBy: {name: ASC} where: {name: {IRE:"tatooi"}}) { id name type climate resident(orderBy: {height: ASC, name: DESC}) { name starship{ id name type passengers } type mass height film { name } hairColor vehicle { name } } } }

You can execute the query by accessing the Workbench GraphiQL Playground on address http://localhost:9993/graphql.

An equivalent cURL request looks like this:

curl 'http://localhost:9995/graphql' \
      -H 'Accept: application/json' \
      -H 'Content-Type: application/json' \
      --data-binary '{"query":"query Tatooine { planet( orderBy: {name: ASC} where: {name: {IRE:\"tatooi\"}}) { id name type climate resident(orderBy: {height: ASC, name: DESC}) { name starship { id name type passengers } type mass height film { name } hairColor vehicle { name }}}}","variables":null,"operationName":"Tatooine"}' \

Stop the Service

Stop and remove all Semantic Objects Docker containers using:

docker-compose -f /path/to/your/docker-compose.yaml down

To remove the volume data as well, use:

docker-compose -f /path/to/your/docker-compose.yaml down --volumes

Docker Compose - Additional Services

With this extended docker-compose-all.yaml file, you can enable the Semantic Objects together with security, federation, monitoring & the Semantic Search.