Alternative Graph Backend deployment

We are moving away from Stardog as a graph backend, mostly because they no longer provide a free academic license but instead provide short-term "trials".

Take a look at https://github.com/neurobagel/planning/issues/9 to see our progress in picking a replacement.

In the meantime, here are instructions for deploying graphDB as our graph backend instead of Stardog.

Changes to config files

Follow the Launch the API section of our public docs, but change the following variables in the .env file from the defaults described in the docs:

NB_GRAPH_IMG=ontotext/graphdb:10.3.1
NB_GRAPH_ROOT_CONT=/opt/graphdb/home
NB_GRAPH_PORT=7200
NB_GRAPH_DB=my_db

Make a copy of the default docker-compose.yml file in the same directory and then run docker compose up -d to launch the Neurobagel services.

Refer to the API readme for additional instructions.

First time setup commands

When the API, graph, and query tool have been started and are running for the first time, you will have to do some first-run configuration.

Create a graph database

In graphDB, graph databases are called resources. To create a new one, you will also have to prepare a data-config.ttl file that contains the settings for the resource you will create (see the graphDB docs).

make sure to that the value for rep:repositoryID in the data-configl.ttl file matches the value of NB_GRAPH_DB in your .env file. For example, if NB_GRAPH_DB=my_db, then rep:repositoryID "my_db" ;.

You can use this example file and save it as data-config.ttl locally:

#
# RDF4J configuration template for a GraphDB repository
#
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#>.
@prefix rep: <http://www.openrdf.org/config/repository#>.
@prefix sr: <http://www.openrdf.org/config/repository/sail#>.
@prefix sail: <http://www.openrdf.org/config/sail#>.
@prefix graphdb: <http://www.ontotext.com/config/graphdb#>.

[] a rep:Repository ;
    rep:repositoryID "my_db" ;
    rdfs:label "" ;
    rep:repositoryImpl [
        rep:repositoryType "graphdb:SailRepository" ;
        sr:sailImpl [
            sail:sailType "graphdb:Sail" ;

            graphdb:read-only "false" ;

            # Inference and Validation
            graphdb:ruleset "rdfsplus-optimized" ;
            graphdb:disable-sameAs "true" ;
            graphdb:check-for-inconsistencies "false" ;

            # Indexing
            graphdb:entity-id-size "32" ;
            graphdb:enable-context-index "false" ;
            graphdb:enablePredicateList "true" ;
            graphdb:enable-fts-index "false" ;
            graphdb:fts-indexes ("default" "iri") ;
            graphdb:fts-string-literals-index "default" ;
            graphdb:fts-iris-index "none" ;

            # Queries and Updates
            graphdb:query-timeout "0" ;
            graphdb:throw-QueryEvaluationException-on-timeout "false" ;
            graphdb:query-limit-results "0" ;

            # Settable in the file but otherwise hidden in the UI and in the RDF4J console
            graphdb:base-URL "http://example.org/owlim#" ;
            graphdb:defaultNS "" ;
            graphdb:imports "" ;
            graphdb:repository-type "file-repository" ;
            graphdb:storage-folder "storage" ;
            graphdb:entity-index-size "10000000" ;
            graphdb:in-memory-literal-properties "true" ;
            graphdb:enable-literal-index "true" ;
        ]
    ].

Then you can create a new graph db with the following command:

curl -X PUT http://localhost:7200/repositories/my_db --data-binary "@data-config.ttl" -H "Content-Type: application/x-turtle"

Upload test data to the graph

Once the graph database has been created, you can add data to it with the following command:

curl -i -X POST http://localhost:7200/repositories/<graph-name>/rdf-graphs/default -H "Content-Type: application/ld+json" --data-binary "@./ds001618.jsonld

Make sure to replace <graph-name> with the name of the graph database you have created in the previous step (e.g. my_db).