Skip to content

Home

Jump to bottom
Muhammad Yasir edited this page Oct 18, 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.

Login to graph database

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

graphDBEndpoint
    .login('admin', 'root')
    .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 the graph database

Upload an ontology and import it into the Graph Database repository automatically if the upload was successful. context (graph) and baseIRI parameters 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) are optional parameters:

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,
        context: 'http://ont.enapso.com/dotnetpro'	
    })
    .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,
     context: 'http://ont.enapso.com/dotnetpro'  
    })
    .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 the Garbage Collection user role needs to be Administrator else operation is not performed

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

Get Resources of graph database Instance

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

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

Result

{
  "success": true,
  "status": 200,
  "message": "OK",
  "data": {
    "heapMemoryUsage": {
      "max": 2090860544,
      "committed": 1073741824,
      "init": 1073741824,
      "used": 857364480
    },
    "nonHeapMemoryUsage": {
      "max": -1,
      "committed": 183107584,
      "init": 7667712,
      "used": 179122440
    },
    "threadCount": 45,
    "cpuLoad": 7.866284408596376,
    "classCount": 20638
  }
}

Create New User and Assign a Role

Create a new user and provide the user with reading/write access to certain repositories in a graph database instance: if security is on then for Creating a new User, the user role needs to be Administrator else operation is 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, the user role needs to be Administrator else operation is 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 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 the graph database instance:

graphDBEndpoint
    .assignRoles({
        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);
    });

Remove Role

Remove existing roles of a user in the 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 assigned authorities (roles)! This operation cannot be undone! Deletes a user from the graph database instance: if security is on then for Deleting User, the user role needs to be Administrator else operation is 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 the 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 locations that 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 a new Repository in your Graph Database Instance

Create a new repository in your Graph Database instance, isShacl parameter is optional by default it is false. if security is on then for creating the repository, the user role needs to be Repository Manager else operation is 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 the repository, the user role needs to be Repository Manager else operation is 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 graph Database Instance

The following code demonstrates how to upload and manage a shacl shape in a graph database instance: Here we are using different methods of graph database first we get to read some SPARQL queries and shacl from files and save them in variables after this we drop the existing shacl using the dropShaclGraph method of admin, clear our repository, upload ontology to graph database insert some valid and invalid data successfully in ontology then read it again clear the repository to upload the ontology again and also upload the shacl using upload from data method of our package 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 that's 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 the 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