Migrating GraphQL configurations from Semantic Objects to GraphDB¶

Previous to GraphDB 11, GraphQL integration with GraphDB was supported throuhg Semantic Objects. If you have previously used GraphQL in Semantic Objects and need to migrate from Semantic Objects to GraphDB, there are some important differences you need to keep in mind.

General notes¶

The SHACL validation functionality has not been migrated in GraphDB 11.0 and is planned for a later date.
GraalVM based IRI and value generation has been fully migrated to Kotlin based implementation. However, some custom expressions may need to be updated to be compatible with the Kotlin based expressions format. Note that custom Kotlin expressions may be slower than the GraalVM JS expressions.
The Schema Validation against data has been partially migrated. The persistent validation logic is not available in GraphDB 11, and only the immediate in-memory version is present.

Licence changes¶

GraphQL is generally available in every version of GraphDB 11. The following additional features require a GraphDB GraphQL extended license.

Role-based access control (RBAC)
SPARQL federation
Apollo Federation
Schema validation against data

Warning

Existing Semantic Objects licenses cannot be directly used in GraphDB 11. If you already have a Semantic Objects license, contact your representative or Graphwise sales to receive an updated license.

Deployment migration¶

Do not deploy Semantic Objects and Semantic Objects Workbench.
Deploy GraphDB 11.
Import the models into your GraphDB repositories.

API Calls¶

The GraphQL API available in Semantic Objects has been integrated in GraphDB 11.0 with the following changes:

The GraphQL API has been changed to be per repository as well as to have multiple schemas per repository.
The old Semantic Objects GraphQL endpoint /graphql has been changed to /repositories/<repository>/graphql for the default GraphQL schema.
There are also endpoints per repository that are /rest/repositories/<repository>/graphql/<endpoint_id>.

Note

Semantic Objects 5.0 also has the /graphql/<model_id> that matches the GraphDB multischema definition.

The following controllers have been removed:

```
POST /soml/{id}/validate
```
```
GET /soml/{id}/validate
```
```
GET /soml/{id}/validate/{taskId}
```

The following controllers have been replaced:

Old controller	New controller
GET /soml	GET /rest/repositories/{repositoryId}/graphql/manage/endpoints
GET /soml/{id}	GET /rest/repositories/{repositoryId}/graphql/manage/endpoints/{id} Or: GET /rest/repositories/{repositoryId}/graphql/manage/endpoints/{id}/export
POST /soml	POST /rest/repositories/{repositoryId}/graphql/manage/endpoints/import
PUT /soml/{id}	POST /rest/repositories/{repositoryId}/graphql/manage/endpoints/import
POST /soml/validate	POST /rest/repositories/graphql/manage/validate
GET /soml/{id}/validateNow	GET /rest/repositories/{repository}/graphql/manage/endpoints/{endpointId}/validate
PUT /soml/{id}/soaas	POST /rest/repositories/{targetRepo}/graphql/manage/endpoints/{endpointId} with the following body: { "default": true }

Configuration parameters¶

All configurations have been moved to a new context and now begin with a graphdb. prefix. For more information on changes to the configuration parameters, check the Directories and configuration properties documentation.

Schema changes¶

There is now an option to configure the federated service via the Semantic Objects Modelling Language model (SOML model) using the following configuration:

config:
    sparqlFederatedServices.<service>: <service_url>
    sparqlFederatedServicesPriority: CONFIG_FIRST|MODEL_FIRST

Where the options for sparqlFederatedServicesPriority are:

CONFIG_FIRST: Prioritize the deployment config over the model configurations. Prevents changes in the models to affect the deployment. Mainly applicable for dynamic external services.
MODEL_FIRST: Prioritize the model configurations over deployment configurations. Allows for transferring the models without the need to modify the deployment options. Mainly usable for static external services.

Schema migration¶

There are no breaking changes to the SOML that require special care when migrating schemas from Semantic Objects 5.0 to GraphDB 11.

Migration of SOML from SO to GraphDB¶

Migration via file copy

Download the SOML file from Semantic Objects using the following endpoint:
GET /soml
Import the SOML into the relevant repository in GraphDB where GraphQL will be used.
Optionally, set the schema as default so that it’s accessible at the default repository endpoint.

Migration via system repository export

Open the old or migrated GraphDB that was previously connected to Semantic Objects.
Export the otp-system repository.
Import the data into the relevant repository in GraphDB where GraphQL will be used.

Execute the following SPARQL update that corrects the default schema:

prefix so: <http://www.ontotext.com/semantic-object#>

delete {
    ?s so:bound-schema ?o
}
insert {
    graph ?g {
        so:defaultSchemaId so:bound-schema ?o .
    }
}
where {
    graph ?g {
        ?s so:bound-schema ?o.
    }
}

Note

This should update only a single row in the data.

Migration where the whole system repository cannot be exported

Open the old or migrated GraphDB that was previously connected to Semantic Objects.
Export the http://www.ontotext.com/semantic-object#store.
Import the exported data into the relevant repository in GraphDB where GraphQL will be used.
Optionally, set the default schema.
Optionally, export http://www.ontotext.com/semantic-object#id-store and import it into the relevant target repository.
Optionally, run the SPARQL update found under Migration via system repository export above.

RBAC migration¶

Role-Based Access Control is fully supported in GraphDB 11 with the following changes:

The default role will allow all access by default, but this can be redefined.
Filters with JWT claims are replaced with filters with GraphDB username and GraphDB user roles.
ctx.claims.preferred_username will resolve to the GraphDB user username.
ctx.claims.authorities will resolve to the GraphDB user custom roles without the role CUSTOM_ prefix.

Tip

It is a good idea to replace ctx.claims.preferred_username and ctx.claims.authorities with their new alternative names:

ctx.claims.preferred_username ‣ ctx.username

ctx.claims.authorities ‣ ctx.roles