Quick Start¶

Docker¶

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.

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:

• Move on to the next section and start the Semantic Objects and Set up a license from the Workbench using http://localhost:9993/, or
• Update the Semantic Objects volumes configuration in the Docker Compose file following the instructions for Setting up a license through a file.

cURL¶

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

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.

   Hint

   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/
   

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"}' \
      --compressed

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.