@innotrade/enapso-graphdb-admin

ENAPSO Ontotext GraphDB 8.x/9.x Admin Tools for Node.js

Usage no npm install needed!

<script type="module">
  import innotradeEnapsoGraphdbAdmin from 'https://cdn.skypack.dev/@innotrade/enapso-graphdb-admin';
</script>

README

enapso-graphdb-admin

enapso Ontotext GraphDB 8.x/9.x Administration Toolbox for Node.js

Admin client for OntoText GraphDB to easily perform administrative and monitoring operations against your RDF stores, your OWL ontologies or knowledge graphs in nodes.js applications. This client supports an easy import of existing RDF stores and ontologies to GraphDB by upload via file, strings or URLs as well as an export in numerous formats and also a context management. You can monitor the cpu load and memory usage of GraphDB and run the garbage collector on demand to optimally trigger huge batch operations also provide the user managememt, the creation and listing of new repositories as well as an location and cluster management of Ontotext GraphDB.

The following demos require a running GraphDB 8.x/9.x instance on localhost at port 7200. The demos as well as the automated tests require a fully working Ontotext GraphDB repository "Test" and a user "admin" with the password "root" being set up as an administrator and repository ruleset must have OWL Horst(Optimizes) Base URL: http://ont.enapso.com/test#, graph: http://ont.enapso.com/test#** Get the latest version of GraphDB for free at https://www.ontotext.com/free-graphdb-download-copy/.

This project is actively developed and maintained. To discuss questions and suggestions with the enapso and GraphDB community, we'll be happy to meet you in our forum at https://www.innotrade.com/forum/.

Installation

npm i @innotrade/enapso-graphdb-admin --save

Example

Instantiate an enapso GraphDB and Admin Client

// require the enapso GraphDB Client and Admin packages
const { EnapsoGraphDBClient } = require('@innotrade/enapso-graphdb-client');
const { EnapsoGraphDBAdmin } = require('@innotrade/enapso-graphdb-admin');
// connection data to the running GraphDB instance
const GRAPHDB_BASE_URL = 'http://localhost:7200',
    GRAPHDB_REPOSITORY = 'Test',
    GRAPHDB_USERNAME = 'Test',
    GRAPHDB_PASSWORD = 'Test',
    GRAPHDB_CONTEXT_TEST = 'http://ont.enapso.com/repo',
    GRAPHDB_CONTEXT_SHACL = 'http://rdf4j.org/schema/rdf4j#SHACLShapeGraph';

// the default prefixes for all SPARQL queries
const GRAPHDB_DEFAULT_PREFIXES = [
    EnapsoGraphDBClient.PREFIX_OWL,
    EnapsoGraphDBClient.PREFIX_RDF,
    EnapsoGraphDBClient.PREFIX_RDFS
];

Connection with GraphDB to create an Endpoint

Create an endpoint client with graphdb to perform operation:

let graphDBEndpoint = new EnapsoGraphDBClient.Endpoint({
    baseURL: GRAPHDB_BASE_URL,
    repository: GRAPHDB_REPOSITORY,
    prefixes: GRAPHDB_DEFAULT_PREFIXES
});

Login to GraphDB

Login to authenticate the user against GraphDB and authorize the user according to his roles:

graphDBEndpoint
    .login(GRAPHDB_USERNAME, GRAPHDB_PASSWORD)
    .then((result) => {
        console.log(result);
    })
    .catch((err) => {
        console.log(err, 'process error here...');
    });

Upload a File to GraphDB

Upload an ontology and import it into a GraphDB repository and optional context (graph) automatically if upload was successful:

graphDBEndpoint
    .uploadFromFile({
        filename: '../ontologies/EnapsoTest.owl',
        format: 'application/rdf+xml',
        baseIRI: 'http://ont.enapso.com/test#',
        context: 'http://ont.enapso.com/test'
    })
    .then((result) => {
        console.log(result);
    })
    .catch((err) => {
        console.log(err, 'process error here...');
    });

Upload from Data to GraphDB

Upload data (rather than a file) and automatically import the data into a GraphDB repository and optional context (graph):

fsPromises
    .readFile('../ontologies/EnapsoTest.owl', 'utf-8')
    .then((data) => {
        graphDBEndpoint
            .uploadFromData({
                data: data,
                context: 'http://ont.enapso.com/test',
                format: 'application/rdf+xml'
            })
            .then((result) => {
                console.log(result);
            })
            .catch((err) => {
                console.log(err, 'process error here...');
            });
    })
    .catch((err) => {
        console.log(err);
    });

Download a Graph from GraphDB to a Text Variable

For the available export formats, please refer to the EnapsoGraphDBClient.FORMAT_xxx constants. The context (graph) is optional. If you do not pass a context (graph), the entire repository is exported.

graphDBEndpoint
    .downloadToText({
        format: EnapsoGraphDBClient.FORMAT_TURTLE.type
    })
    .then((result) => {
        console.log(result);
    })
    .catch((err) => {
        console.log(err, 'process error here...');
    });

Download a graph from GraphDB directly to a Local File

For the available export formats, please refer to the EnapsoGraphDBClient.FORMAT_xxx constants. The context is optional. If you do not pass a context, the entire repository is exported.

let lFormat = EnapsoGraphDBClient.FORMAT_TURTLE;
graphDBEndpoint
    .downloadToFile({
        format: lFormat.type,
        filename:
            '../ontologies/' +
            graphDBEndpoint.getRepository() +
            lFormat.extension
    })
    .then((result) => {
        console.log(result);
    })
    .catch((err) => {
        console.log(err, 'process error here...');
    });

Perform Garbage Collection in your GraphDB Instance

Perform the garbage collection on the server side to release allocated resources: if security is on then for Garbage Collection user role need to be Adminstrator else operation not performed

graphDBEndpoint
    .performGarbageCollection()
    .then((result) => {
        console.log(result);
    })
    .catch((err) => {
        console.log(err, 'process error here...');
    });

Get Resource of GraphDB Instance

Get resource details of the repository current connected to the endpoint:

graphDBEndpoint
    .getResources()
    .then((result) => {
        console.log(result);
    })
    .catch((err) => {
        console.log(err, 'process error here...');
    });

Create New User and Assign Role

Create a new user and provide him/her with read/write access to certain repositories in a GraphDB instance: if security is on then for Creating new User user role need to be Adminstrator else operation not performed

graphDBEndpoint
    .createUser({
        authorities: [
            'WRITE_REPO_Test', // Writing excess wrote WRITE_ and in last name of Repository which excess provided like REPO_Test
            'READ_REPO_Test', // Reading excess wrote READ_ and in last name of Repository which excess provided like REPO_Test
            'READ_REPO_EnapsoDotNetProDemo',
            'ROLE_USER' // Role of the user
        ],
        username: 'TestUser2', // Username
        password: 'TestUser2' // Password for the user
    })
    .then((result) => {
        console.log(result);
    })
    .catch((err) => {
        console.log(err);
    });

Update User Role and Authorities

Update the user's roles (read/write rights) for certain repositories: if security is on then for Updating Exisiting User user role need to be Adminstrator else operation not performed

graphDBEndpoint
    .updateUser({
        authorities: [
            // Writing excess wrote WRITE_ and in last name of Repository which excess provided like REPO_Test
            'READ_REPO_Test', // Reading excess wrote READ_ and in last name of Repository which excess provided like REPO_Test
            'WRITE_REPO_EnapsoDotNetProDemo',
            'READ_REPO_EnapsoDotNetProDemo',
            'ROLE_USER' // Role of the user
        ],
        username: 'TestUser' // Username
    })
    .then((result) => {
        console.log(result);
    })
    .catch((err) => {
        console.log(err);
    });

Delete User

Caution! This deletes the user including all assigend authorities (roles)! This operation cannot be undone! Deletes a user from the GraphDB instance: if security is on then for Deleting User user role need to be Adminstrator else operation not performed

graphDBEndpoint
    .deleteUser({
        user: 'TestUser2' // username which you want to delete
    })
    .then((result) => {
        console.log(result);
    })
    .catch((err) => {
        console.log(err);
    });

List all Repositories operated in a GraphDB Instance

Get details of all repositories of the GraphDB repositories operated on the connected host:

graphDBEndpoint
    .getRepositories()
    .then((result) => {
        console.log(result);
    })
    .catch((err) => {
        console.log(err);
    });

Result

[
  {
    "id": "SYSTEM",
    "title": "System configuration repository",
    "uri": "http://[your ip or hostname]:7200/repositories/SYSTEM",
    "externalUrl": "http://[your ip or hostname]:7200/repositories/SYSTEM",
    "type": "system",
    "sesameType": "openrdf:SystemRepository",
    "location": "",
    "readable": true,
    "writable": true,
    "unsupported": false,
    "local": true
  },
  :
  :
  {
    "id": "Test",
    "title": "Test",
    "uri": "http://[your ip or hostname]:7200/repositories/Test",
    "externalUrl": "http://[your ip or hostname]:7200/repositories/Test",
    "type": "free",
    "sesameType": "graphdb:FreeSailRepository",
    "location": "",
    "readable": true,
    "writable": true,
    "unsupported": false,
    "local": true
  }
]

Clear entire Repository of your GraphDB Instance

Caution! This removes ALL triples of the given repository! This operation cannot be undone! The entire repository will be emptied, i.e. all data of this repository will be removed. The repository remains active.

graphDBEndpoint
    .clearRepository()
    .then((result) => {
        console.log(result);
    })
    .catch((err) => {
        console.log(err);
    });

Result

{
    "success": true
}

List all Users of a GraphDB Instance

Get all details of all users of a certain GraphDB instance:

graphDBEndpoint
    .getUsers()
    .then((result) => {
        console.log(result);
    })
    .catch((err) => {
        console.log(err);
    });

Result

[
    {
        "username": "Test",
        "password": "",
        "grantedAuthorities": [
            "WRITE_REPO_Test",
            "READ_REPO_Test",
            "ROLE_USER"
        ],
        "appSettings": {
            "DEFAULT_SAMEAS": true,
            "DEFAULT_INFERENCE": true,
            "EXECUTE_COUNT": true
        },
        "dateCreated": 1549545975380
    },
    {
        "username": "admin",
        "password": "",
        "grantedAuthorities": ["ROLE_ADMIN"],
        "appSettings": {
            "DEFAULT_INFERENCE": true,
            "DEFAULT_SAMEAS": true,
            "EXECUTE_COUNT": true
        },
        "dateCreated": 1478943858311
    }
]

Get Query from GraphDB

Get Query from GraphDB:

graphDBEndpoint
    .getQuery()
    .then((result) => {
        console.log(result);
    })
    .catch((err) => {
        console.log(err);
    });

List all Contexts (Name Graphs) used in a given Repository

List all named graphs inside a given repository:

graphDBEndpoint
    .getContexts()
    .then((result) => {
        console.log(result);
    })
    .catch((err) => {
        console.log(err, 'process error here...');
    });

Result

{
    "total": 1,
    "success": true,
    "records": [
        {
            "contextID": "http://ont.enapso.com/test"
        }
    ]
}

Clear entire Context (Named Graph) of a given Repository

Caution! This removes ALL triples of the given context! This operation cannot be undone! The entire context will be emptied, i.e. all data from this context will be removed. The repository and other contexts remain active.

graphDBEndpoint
    .clearContext(GRAPHDB_CONTEXT_TEST)
    .then((result) => {
        console.log(result);
    })
    .catch((err) => {
        console.log(err, 'process error here...');
    });

Result

{
    "success": true
}

List all GraphDB Locations

Get details of all location which are assosciated with the connected GraphDB instance:

graphDBEndpoint
    .getLocations()
    .then((result) => {
        console.log(result);
    })
    .catch((err) => {
        console.log(err);
    });

Result

[
    {
        "uri": "",
        "label": "Local",
        "username": null,
        "password": null,
        "active": true,
        "local": true,
        "system": true,
        "errorMsg": null,
        "defaultRepository": null
    }
]

List all saved Queries in a GraphDB Instance

Get details of all queries which are saved in a GraphDB instance:

graphDBEndpoint
    .getSavedQueries()
    .then((result) => {
        console.log(result);
    })
    .catch((err) => {
        console.log(err);
    });

Result

{
    "success": true,
    "statusCode": 200,
    "statusMessage": "OK",
    "data": [
        {
            "name": "[Name of your query 1]",
            "body": "[SPARQL query saved with this name]"
        },
        {
            "name": "[Name of your query 2]",
            "body": "[SPARQL query saved with this name]"
        }
    ]
}

Create new Repository in your GraphDB Instance

Create a new repository in your GraphDB instance isShacl option is optional if want to enable then set it as true and by default it is false: if security is on then for creating repository user role need to be Repository Manager else operation not performed

graphDBEndpoint
    .createRepository({
        id: 'AutomatedTest4',
        title: 'enapso Automated Test Repository',
        location: '',
        isShacl: true
    })
    .then((result) => {
        console.log(result);
    })
    .catch((err) => {
        console.log(err);
    });

Result

{
    "success": true,
    "statusCode": 201,
    "statusMessage": "OK"
}

Delete Repository in a GraphDB Instance

Delete a repository in the connected GraphDB instance: if security is on then for deleting repository user role need to be Repository Manager else operation not performed

graphDBEndpoint
    .deleteRepository({
        id: 'AutomatedTest'
    })
    .then((result) => {
        console.log(result);
    })
    .catch((err) => {
        console.log(err);
    });

Result

{
    "success": true,
    "statusCode": 200,
    "statusMessage": "OK"
}

Upload SHACL Shape to a GraphDB Instance

The following code demonstrate how to upload and manage a shacl shape in a GraphDB instance: Here we are using different method of GraphDB first we get read some sparql queries and shacl from files save them in variables after this we drop the existing shacl using dropShaclGraph method of admin, clear our repository, upload ontology to GraphDB insert some valid and invalid data successfully in ontology then read it again clear the repository upload the ontology again and also upload the shacl using uploadFromData method of our pacakge now again insert valid and invalid data now after uploading shacl you can see it show errors when you insert invalid data which violated restriction which applied through shacl so thats the benefit of shacl to not deal with data which didn't follow restriction rules.

demoShacl: async function () {
        let resp;

        // read sparqls
        let validSparql = await fsPromises.readFile('../test/validUpdate.sparql', 'utf-8');
        let invalidSparql = await fsPromises.readFile('../test/invalidUpdate.sparql', 'utf-8');
        let getPersonsSparql = await fsPromises.readFile('../test/selectAllPersons.sparql', 'utf-8');
        // read the shacl turtle
        let shaclTtl = await fsPromises.readFile('../ontologies/EnapsoTestShacl.ttl', 'utf-8');
        // read the shacl json-ld
        let shaclJsonLd = await fsPromises.readFile('../ontologies/EnapsoTestShacl.jsonld', 'utf-8');

        // first drop the shacl graph if exists, if it does not exist, this will not be a problem
        enLogger.info("\nDropping SHACL Graph...");
        resp = await this.graphDBEndpoint.dropShaclGraph();
        enLogger.info("\nDrop SHACL Graph:\n" + JSON.stringify(resp, null, 2));

        // now clear the current repository to ensure that there is no old data inside that could disturb the tests
        enLogger.info("\nClearing repository...");
        resp = await this.graphDBEndpoint.clearRepository();
        enLogger.info("\nCleared repository:\n" + JSON.stringify(resp, null, 2));

        // now upload ontology directly from test ontology file into test graph into the test repository
        enLogger.info("\nUploading ontology from file...");
        resp = await this.graphDBEndpoint.uploadFromFile({
            filename: "./ontologies/EnapsoTest.owl",
            context: GRAPHDB_CONTEXT_TEST,
            format: EnapsoGraphDBClient.FORMAT_RDF_XML.type
        });
        enLogger.info("\nUploaded ontology from file:\n" + JSON.stringify(resp, null, 2));

        resp = await this.graphDBEndpoint.query(getPersonsSparql);
        enLogger.info("\nGet Persons after upload (supposed to work):\n" + JSON.stringify(resp, null, 2));

        // first try all actions w/o a shacl being applied
        resp = await this.graphDBEndpoint.update(validSparql);
        enLogger.info("\nValid SPARQL w/o SHACL (supposed to work):\n" + JSON.stringify(resp, null, 2));

        resp = await this.graphDBEndpoint.update(invalidSparql);
        enLogger.info("\Invalid SPARQL w/o SHACL (supposed to work):\n" + JSON.stringify(resp, null, 2));

        resp = await this.graphDBEndpoint.query(getPersonsSparql);
        enLogger.info("\nGet Persons w/o SHACL (supposed to work):\n" + JSON.stringify(resp, null, 2));

        // now clear the repository again, it contains invalid data from the tests w/o shacl support
        enLogger.info("\nClearing repository...");
        resp = await this.graphDBEndpoint.clearRepository();
        enLogger.info("\nCleared repository:\n" + JSON.stringify(resp, null, 2));

        // and upload ontology again to have the same initital status for shacl tests as w/o the shacl tests
        enLogger.info("\nUploading ontology from file...");
        resp = await this.graphDBEndpoint.uploadFromFile({
            filename: "./ontologies/EnapsoTest.owl",
            context: GRAPHDB_CONTEXT_TEST,
            format: EnapsoGraphDBClient.FORMAT_RDF_XML.type
        });
        enLogger.info("\nUploaded ontology from file:\n" + JSON.stringify(resp, null, 2));

        // now load the shacl on top of the correct ontology
        enLogger.info("\nUploading SHACL from Data...");
        // now upload the shacl file, using correct context (graph name) and format!
        resp = await this.graphDBEndpoint.uploadFromData({
            // data: shaclTtl,
            data: shaclJsonLd,
            context: GRAPHDB_CONTEXT_SHACL,
            // format: EnapsoGraphDBClient.FORMAT_TURTLE.type
            format: EnapsoGraphDBClient.FORMAT_JSON_LD.type
        });
        enLogger.info("\nUploaded SHACL from Data:\n" + JSON.stringify(resp, null, 2));

        // next try all actions w/o a shacl being applied
        resp = await this.graphDBEndpoint.update(validSparql);
        enLogger.info("\nValid SPARQL with SHACL support (supposed to work):\n" + JSON.stringify(resp, null, 2));

        resp = await this.graphDBEndpoint.update(invalidSparql);
        enLogger.info("\nInvalid SPARQL with SHACL support (NOT supposed to work):\n" + JSON.stringify(resp, null, 2));

        resp = await this.graphDBEndpoint.query(getPersonsSparql);
        enLogger.info("\nGet Persons with SHACL support (supposed to work):\n" + JSON.stringify(resp, null, 2));

        enLogger.info("\nDone");
    }

Result

DropShaclGraph :
{
  "success": true,
  "statusCode": 200,
  "message": "OK"
}

Drop SHACL Shape in a GraphDB instance

Drop a shacl Shape from GraphDB to remove all validations:

graphDBEndpoint
    .dropShaclGraph()
    .then((result) => {
        console.log(result);
    })
    .catch((err) => {
        console.log(err);
    });

Result

DropShaclGraph :
{
  "success": true,
  "statusCode": 200,
  "message": "OK"
}