Skip to content

Home

Jump to bottom
Muhammad Yasir edited this page Oct 11, 2022 · 8 revisions

ENAPSO Graph Database Admin client to easily perform administrative and monitoring operations against your RDF stores, your OWL ontologies, or knowledge graphs in nodes.js applications.

Feature List of triplestores

Feature Ontotext GraphDB Apache Jena Fuseki Stardog
Login ✔ ✘ ✔
Query ✔ ✔ ✔
Update ✔ ✔ ✔
Create Repository ✔ ✔ ✔
Delete Repository ✔ ✔ ✔
Clear Repository ✔ ✔ ✔
Get Repositories ✔ ✔ ✔
Create User ✔ ✘ ✔
Get Users ✔ ✘ ✔
Update User ✔ ✘ ✘
Assign Role ✘ ✘ ✔
Remove Role ✘ ✘ ✔
Delete User ✔ ✘ ✔
Drop SHACL Graph ✔ ✘ ✘
Get Contexts ✔ ✔ ✔
Upload From File ✔ ✔ ✔
Upload From Data ✔ ✘ ✔
Download To File ✔ ✔ ✔
Download To Text ✔ ✔ ✔
Clear Context ✔ ✔ ✔
Get Query ✔ ✘ ✔
Get Locations ✔ ✘ ✘
Perform Garbage Collections ✔ ✘ ✘
Get Saved Queries ✔ ✘ ✘

Login to Graph Database

Login to authenticate the user against Graph Database 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...');
    });

Querying against the Graph Database

graphDBEndpoint
    .query(
        'select *
where {
    ?class rdf:type owl:Class
    filter(regex(str(?class), "http://ont.enapso.com/test#TestClass", "i")) .
}',
        { transform: 'toJSON' }
    )
    .then((result) => {
        console.log(
            'Read the classes name:\n' + JSON.stringify(result, null, 2)
        );
    })
    .catch((err) => {
        console.log(err);
    });

Updating Triples in Graph Database

graphDBEndpoint
    .update(
        `insert data {
	   graph <http://ont.enapso.com/test> {
             entest:TestClass rdf:type owl:Class}
           }`
    )
    .then((result) => {
        console.log('inserted a class :\n' + JSON.stringify(result, null, 2));
    })
    .catch((err) => {
        `console.log(err);
    });

Upload a File to Graph Database

Upload an ontology and import it into Graph Database repository automatically if upload was successful. context (graph) and baseIRI paramters are optional :

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 Graph Database

Upload data (rather than a file) and automatically import the data into a Graph Database repository and context (graph) is optional paramters:

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 Graph Database 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 Graph Database 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 Graph Database 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 Graph Database 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 user with read/write access to certain repositories in a Graph Database 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 Existing 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);
    });

Update User

Update a user roles in Graph Database instance:

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

Assign Role

Assign new roles to the user of Graph Database instance:

graphDBEndpoint
    .assignRoles({
        userName: 'ashesh',
        authorities: [
            {
                action: 'READ',
                resource_type: 'db',
                resource: ['Test']
            },
            {
                action: 'WRITE',
                resource_type: 'db',
                resource: ['Test']
            }
        ]
    })
    .then((result) => {
        console.log(result);
    })
    .catch((err) => {
        console.log(err);
    });

Remove Role

Remove existing roles of user in Graph Database instance:

graphDBEndpoint
    .removeRoles({
        username: 'TestUser',
        authorities: [
            {
                action: 'READ',
                resource_type: 'db',
                resource: ['Test']
            },
            {
                action: 'WRITE',
                resource_type: 'db',
                resource: ['Test']
            }
        ]
    })
    .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 Graph Database 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 the Graph Database Instance

Get details of all repositories of the Graph Database 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 Graph Database 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 Graph Database Instance

Get all details of all users of a certain Graph Database 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 Graph Database

Get Query from Graph Database:

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('http://ont.enapso.com/test')
    .then((result) => {
        console.log(result);
    })
    .catch((err) => {
        console.log(err, 'process error here...');
    });

Result

{
    "success": true
}

List all Graph Database Locations

Get details of all location which are assosciated with the connected Graph Database 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 Graph Database Instance

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

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

Result

{
    "success": true,
    "": 200,
    "status": "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 Graph Database Instance

Create a new repository in your Graph Database instance, isShacl paramter is optional by defult 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,
    "": 201,
    "status": "OK"
}

Delete Repository in a Graph Database Instance

Delete a repository in the connected Graph Database 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,
    "": 200,
    "status": "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

Import SHACL Shapes:
{
  "success": true,
  "": 200,
  "message": "OK"
}

Drop SHACL Shape in a Graph Database instance

Drop a shacl Shape from Graph Database to remove all validations:

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

Result

DropShaclGraph :
{
  "success": true,
  "": 200,
  "message": "OK"
}
Clone this wiki locally