UltraGraphQL-docker (Based upon UltraGraphQL)

• A UltraGraphQL-docker Container with no root access (except using sudo ... and you can remove it using sudo apt-get remove sudo to protect your Container).

If [ you are looking for such a common requirement as a base Container ] and 
   [ UltraGraphQL inside the container ]:
   Then [ this one may be for you ]

Optional RDF Docker Services to work together:

• Apache Jena Fuseki: e.g. openkbs/jena-fuseki-docker (verified! and recommended!)
• Eclipse RDF4J: e.g., openkbs/rdf4j-docker (Not verified!)
• UCO SHACL Validator: e.g., uco-shacl-validator-docker

Components:

• UltraGraphQL
• No root setup: using /home/developer
  • It has sudo for dev phase usage. You can "sudo apt-get remove sudo" to finalize the product image.
  • Note, you should consult Docker security experts in how to secure your Container for your production use!)
• Gradle: v7.3.3
• Java: v11

Release

• This is also a fix to mitigate the Log4Shell vulnerability.
  • update to the latest versions to avoid the Log4Shell vulnerability

Related Projects

• UltraGraphQL:
  • UltraGraphQL-Upstream
  • UltraGraphQL
  • UltraGraphQL-docker
• HyperGrahQL:
  • HyperGraphQL-Upstream
  • HyperGraphQL
  • HyperGraphQL-docker

Build (do this first!)

• Note that it is necessary to use Java v11 to build this Container.
• Make sure you modify "openkbs/java-nonroot-docker" (git clone locally) Dockerfile to generate image tag "11" before you build this Container:

  JAVA_VERSION_LIST=11 23-slim-bullseye
  

• Then, you can proceed to build this Container with errors due to Java version incompatibility issues.

  ./build.sh
  

Build (Optional, when encountering GIT SSL issues)

• If your Docker is located inside corporate SSL firewall, the build might fail.
• To workaround, you want to use the 'Dockerfile-copy-jar' instead, do the followings:

  cp Dockerfile Dockerfile.ORIG
  cp Dockerfile-copy-jar Dockerfile
  
  make build
  

(optional) Run (manual setup and run)

• You can manually go into the container to play around, setup differently, and run - if you like to.
• Use the command below to enter the Container:

  ./run.sh bash
  

• Default, this will bring you into the Container /home/developer/app folder. From there you can manually do your experiment.

  cd ~/app/examples/one-service
  java -jar $HOME/app/UltraGraphQL/build/libs/ultragraphql-1.1.4-exe.jar --config config.json
  

Run (demo with default setup)

1. Don't start the Container yet.
2. First, you modify the 'config/config.json' file to provide specific remote SPARQL Endpoint URL: You need to modify "url" value for your actual SPARQL Endpoint URL, e.g.,

{
  "name": "query-persons-and-cars",
  "extraction": true,
  "server": {
    "port": 8000,
    "graphql": "/graphql",
    "graphiql": "/graphiql"
  },
  "services": [
    {
      "id": "dataset",
      "type": "SPARQLEndpointService",
      "url": "http://192.168.0.124:13030/persons_and_cars/",
      "graph": "",
      "user": "",
      "password": ""
    }
  ]
}

3. Then, run the container:

./run.sh

• You will see something like the output below:

    | | | | | |_ _ __ __ _ / ___|_ __ __ _ _ __ | |__  / _ \| |
    | | | | | __| '__/ _` | |  _| '__/ _` | '_ \| '_ \| | | | |
    | |_| | | |_| | | (_| | |_| | | | (_| | |_) | | | | |_| | |___
     \___/|_|\__|_|  \__,_|\____|_|  \__,_| .__/|_| |_|\__\_\_____|
                                          |_|
----------------------------------------------------------------------

18:40:48 INFO  Application :: Starting controller...
HGQL service name: query-persons-and-cars
GraphQL server started at: http://localhost:8000/graphql
GraphiQL UI available at: http://localhost:8000/graphiql

• And, then use your web-browser to access the URLs above. Note the ports, default, is mapped to 48000. Hence, you need to access URL as

GraphQL server started at: http://<your-docker-host-IP>:48000/graphql
GraphiQL UI available at: http://<your-docker-host-IP>:48000/graphiql
e.g.,
http://localhost:48000/graphiql

Create your own image from this

FROM openkbs/ultragraphql-docker

Quick commands

• build.sh - build local image
• logs.sh - see logs of container
• run.sh - run the container
• shell.sh - shell into the container
• stop.sh - stop the container

==== README.md from Original UltraGrapQL ====

Note: Docker version Guide (see above)

The following is for reference only

Source: UltraGraphQL

UltraGraphQL

UltraGraphQL is a GraphQL interface for querying and modifying RDF data on the Web. It extends HyperGraphQL by providing a automatic bootstrapping phase of the service and a more feature rich schema support with additional support for GraphQL mutations. Because it is based on HyperGraphQL features like the support of federated querying and exposing data from multiple linked data services using GraphQL query language and schemas were maintained and extended. The core of the response is a JSON-LD object, which extends the standard JSON with the JSON-LD context enabling semantic disambiguation of the contained data.

Table of Contents

• Features
  • Bootstrapping
  • Queries
  • Mutations
• Examples
• Getting started
• Documentation
• Differences to HyperGraphQL
• Licence note

Features

Bootstrapping (OPTIONAL)

Only needs to be done if the schema is not known or was updated

Requirements: All service of the type SPARQLEndpointService MUST allow SPARQL 1.1 queries and the runtime limitation SHOULD be deactivated because the schema summarization can have a long execution time on large datasets.

If the schema extraction is enabled in the configuration, no schema is required to start UGQL. UGQL will summarize the RDF schema from the defined services and map the summarized schema to a corresponding UGQL schema as shown in the Figure. The default extraction query and schema vocabulary used to summarize the schema are by Gleim et. al. (PDF) and can be configured if needed. This example shows how to configure the schema vocabulary and the effect those changes. If multiple service are defined in the configuration the schema is summarized on all services and then mapped to one unified schema

Queries

For each object type of the provided or extracted schema a query field is generated. To query for specific IRIs (IDs in UGQL) the argument _id can be used to filter for the provided IRIs. A detailed description of the query translation and is provided here and an overview of all possible query modifiers is provided here. To test the different features of UGQL the provided examples can be used to write and test the query features.

Note: The service MUST not be defined in the query. Based on the UGQL schema (UGQLS) the different services will be queried accordingly.

Mutations

Insert and delete mutations are generated for each object type of the UGQLS which corresponds to the output type of the mutation allowing to directly query the modified data. The mutation actions are only performed on one service of the services defined in the configuration.

As shown in the examples the mutations allow to insert and delete object data. In case of the delete mutation the performed action depends on the provided information. Allowing deletions based on matching criterions. Detailed information about the mutations can be found here.

mutation{
    insert_ex_Person(_id: "https://example.org/Bob", ex_name: "Bob", ex_age: "42", ex_relatedWith: {_id: "https://example.org/Alice"}){
        _id
        ex_name
        ex_relatedWith{
            ex_name
        }
    }
}

mutation{
    delete_ex_Person(_id: "https://example.org/Bob", ex_name: "Bob", ex_age: "42", ex_relatedWith: {_id: "https://example.org/Alice"}){
        _id
        ex_name
        ex_relatedWith{
            ex_name
        }
    }
}

Examples

A set of examples is avaliable here, featuring different use cases and features of UGQL.

Getting Started

You may find prebuilt nightly binaries here.

Building from Source

To build an executable UGQL jar run

gradle clean build shadowJar

This will generate the two jars:

• ultragraphql-< version >.jar
  • e.g. ultragraphql-1.0.0.jar
• ultragraphql-< version >-exe.jar
  • e.g. ultragraphql-1.0.0-exe.jar

A UGQL instance can then be started with the command

java -jar build/libs/<exe-jar> --config <path to config>

For example UGQL service setups look into the examples and their configurations.

Documentation

A detailed documentation about the endpoint configuration, query writing and internal query translation is provided here.

---

Differences to HyperGraphQL

• Automatic bootstrapping phase (through schema summarization)
  • Configurable summarization querying
  • Configurable mapping vocabulary
• Mutation support
  • Insert and delete mutation fields are generated for all objects in the schema
  • Mutation action is limited to one service (MUST be LocalModelSPARQLService or SPARQLEndpointService)
• Support for multiple services per schema entity
• Support of equivalence relations in the schema and during querying
• Interafaces and Unions supported in the schema
• Filter options now also avaliable for fields (prior only avaliable for the root query fields)
• Simplified query naming schema
• Additional web server framework to host the UltraGraphQL instance to allow multiple instances running on the same system
• Simplified and more efficient result transformation (v1.1.0 or higher)

License note:

This software is a further development of HyperGraphQL which has been developed and is maintained by Semantic Integration Ltd.. It is released under Apache License 2.0. See LICENSE.TXT for more infromation.