User Guide

Skip to end of metadata
Go to start of metadata
Search
This documentation is NOT for the latest version of GraphDB.

Latest version - GraphDB 7.1

GraphDB Documentation

Next versions

GraphDB 6.4
GraphDB 6.5
GraphDB 6.6
GraphDB 7.0
GraphDB 7.1

Previous versions

GraphDB 6.2
GraphDB 6.0 & 6.1

[OWLIM 5.4]
[OWLIM 5.3]
[OWLIM 5.2]
[OWLIM 5.1]
[OWLIM 5.0]
[OWLIM 4.4]
[OWLIM 4.3]
[OWLIM 4.2]
[OWLIM 4.1]
[OWLIM 4.0]

Installation, start-up and shutdown

To run the GraphDB Workbench as a standalone server, unzip the distribution zip file and execute the startup.sh/.bat script.

For Mac, the command line is:

You can also start the workbench by running the line:

These methods of deployment use an embedded Tomcat server, which will deploy the war files in the sesame_graphdb directory. The GraphDB Workbench is accessed and administered though a Web browser. If it is located on the same machine, use a URL such as the following (assuming the default port number):

http://localhost:8080

When it is deployed as a war file, the procedure is the same as deploying any other Web application, i.e. the graphdb-workbench-x.y.z.war file must be copied to the servlet container's webapps directory. In order to access the GraphDB Workbench, use a browser with a URL similar to the following:

http://localhost:8080/graphdb-workbench-webapp-x.y

If you have used the embedded Tomcat method, you can shut down the Workbench with Ctrl-c in the console. If you have started it in a servlet container, use the appropriate tools, e.g. stop the Tomcat server, if Tomcat is used or use the HTML manager tool to unload an individual Web application.

Index page

After logging in, a summary page is displayed showing version number, license details, currently selected repository (if any) and user name. If no location is currently selected, the message 'No location selected/Please select/create one' is displayed. Click this to get to the management page where you can add a location and create a repository.

Invalid GraphDB License

In order to run the GraphDB Workbench application, you need a valid GraphDB license. By default, there is an evaluation license included in the distribution but in case your license has expired, you need to contact Ontotext for a renewal. Once obtained, the recommended way of specifying it is with a java system parameter. Just add the following parameter:

to the java process responsible for the Workbench deployment (Tomcat's setenv.sh file or the startup.sh script). For other methods, see How to setup a GraphDB license.

Managing repositories

The repository management page is accessed by clicking Admin->Repositories from the menu. This displays a list of available repositories and their locations as well as the permissions that the user has for each repository.

Adding a location

If you are unable to detect the Sesame server (i.e. it is not deployed in the same application server), you will have to connect to it manually. To do this:

  1. From admin-repositories, click Add Location;
  2. Enter the URL to a Sesame location;
  3. (Optionally) Specify credentials for the Sesame location (user and password);
  4. (Optionally) Add the JMX Connection parameters (url and credentials) - this allows you to monitor the resources on the external location and do query monitoring.
Currently, you cannot manage the GraphDB cluster setup through the Workbench, even if you add JMX connection parameters.
The JMX connection url is of the form

and the remote process has to be started in order to allow remote JMX connections. For example:

It is possible to use the current interface to create and access a repository on another GraphDB Workbench instance (on another machine) or at a different location on the same machine.

Adding a repository

To create a new repository, click Add repository. This will display the configuration page for the new repository where a new, unique ID has to be entered. The rest of the parameters are described in the GraphDB-SE configuration section of the GraphDB v6.2 documentation.

Selecting a repository

You can connect to a repository in the repositories view by clicking the Slider button next to a repository.

Another way (recommended) is to use the dropdown menu in the top right corner. This will allow you to easily change the repository while running queries as well as importing and exporting data in other views.



Loading data into a repository

There are four ways to import data in the currently selected repository. They can be accessed from the menu by clicking Data->Import.

All import methods support asynchronous running of the import tasks, except for the text area import one, which is intended for a very fast and simple import.

Currently, only one import task of a type is executed at a time, while the others wait in the queue as pending.

For Local repositories, since the parsing is done by Ontotext, we support interruption and additional settings.

When the location is a remote one, we just send the data to the remote endpoint and the parsing and loading is performed there.

Import settings

The settings for each import are saved so that you can use them, in case you want to re-import a file. They are:

  • Base URI - Specifies the base URI against which to resolve any relative URIs found in the uploaded data. Ref Sesame System documentation;
  • Context - If specified, imports the data into the specific context;
  • Chunk size - The number of statements to commit in one chunk. If a chunk fails, the import operations are interrupted and the imported statements are not rollbacked. The default is no chunking. When there is no chunking, all statements are loaded in one transaction.
  • Retry times - How many times to retry the commit, if it fails.
  • Preserve BNode IDs - Assigns its own internal blank node identifiers or uses the blank node IDs it finds in the file.

File upload

The limitation of this method is that it supports files of a limited size. The default is 200MB and it is controlled by the app.maxUploadSize property. The value is in bytes (-Dapp.maxUploadSize=20971520).

Loading data from the Local files directly streams the file to the Sesame's statements endpoint:

  1. Click Select files and browse files for uploading;
  2. When the files appear in the table, either import a file by clicking Import on its line or select multiple files and click Batch import;
  3. The import settings modal will appear, just in case you want to add additional settings.

Import server files

The server files import allows you to load files of arbitrary sizes. Its limitation is that the files must be put (symbolic links are supported) in a specific directory. By default, it is ${user.home}/owlim-impex/.

If you want to tweak the directory location, see the impex.dir system parameter. The directory will be scanned recursively and all files with a semantic mime type will be visible in the impex tab.

URL Import

You can import from a URL with RDF data. Each endpoint that returns RDF data may be used.

If the URL has an extension, it is used to detect the correct data type. (i.e http://linkedlifedata.com/resource/umls-concept/C0024117.rdf).

Otherwise, you have to provide the Data Format parameter, which will be sent as Accept header to the endpoint and then to the import loader.

You can also import data from a SPARQL construct query. Again, you have to provide the Data Format.

Text Import

This is a very simple text import that sends the data to the Repository Statements Endpoint.

Executing queries

Access the SPARQL pages from the menu by clicking SPARQL->Query. The GraphDB Workbench SPARQL view integrates the YASGUI query editor and has some additional features.

The SPARQL Select and Update queries are executed through the same view. It detects the query type and sends the correct Sesame endpoint. Some handy features are:

  • a query area with syntax highlighting and namespace autocompletion - to add/remove namespaces go to Admin->Namespaces;
  • query tabs - saved in your browser local storage, so you can keep them even when switching views;
  • sample queries - use the select/add/remove sample queries and add your own ones; they are saved on the disk;
  • include inferred - a check-box allowing the execution of the query over all RDF statements or just over the explicit statements;
  • keyboard shortcuts - use Ctrl + Enter to execute a query or find other useful shortcuts in the lower right "keyboard shortcuts" link;
  • copy query - use the chain icon to copy your query as URL and share it; the link opens the query editor in a new tab and your query is filled there;
  • "Download As" button - download query results in your preferred format (JSON, XML, CSV, TSV and Binary RDF for Select queries and all RDF formats for Graph query results);
  • query results table - order query results by some column values and filter table values quickly.

The results are displayed on the same page for faster feedback. Multiple results views are also provided.

The query results are limited to 1000, since your browser cannot handle an infinite number of results. To obtain all results, use Download As and select the required format for the data.

You will see the total number of results and the query execution time in the query results header.

The total number of results is obtained by an async request with a default-graph-uri parameter and the value http://www.ontotext.com/count.

Exporting data

Data can be exported in several ways and formats.

Exporting repository or graphs

Click Data->Export from the menu and decide whether you need to export the whole repository (in several different formats) or specific named graphs (in the same variety of formats). Click the appropriate format and the download will begin:

Exporting query results

The SPARQL query results can also be exported from the SPARQL view with results by clicking "Download As".

Exporting resources

From the resource description page, export the RDF triples that make up the resource description to JSON, JSON-LD, RDF-XML, N3/Turtle and N-Triples:

Adding a new resource

To add a new resource to the repository, go to DATA->Add new resource. It opens a window where you write the URI of the new resource. There, you can add, change or delete its properties.

When ready, save the new resource to the repository.

Changing a resource

You can also change the properties of an already stored resource. Click Edit next to the resource namespace and add, change or delete the properties of this resource.

You can not change or delete the inferred statements. For more information, see the FAQ section of the GraphDB v62 documentation.

User administration

The user administration is disabled by default. If you want to enable it, run the workbench with -Dsecurity.enabled=true

User management is accessed by clicking Admin->Users from the menu. The page displays a list of users and the number of repositories they have access to. It is also possible to disable the security for the entire GraphDB Workbench instance by clicking Disable/Enable. Then all users (even anonymous ones) will have read/write access to all repositories.

From here, you can create new users, delete existing users or edit user properties, including setting their role and the read/write permission for each repository. The password can also be changed here.

User Roles:

  • User - a user who can read and write according to his permissions for each repository;
  • Admin - a user with full access, including creating, editing, deleting users;
  • Information Extraction Expert - a user with access only to add new resource page;
  • Search Configuration Expert - a user with full access, except for Repositories and Users management.

Rest API documentation

You can find more information about the Rest APIs in Admin->Rest API Document.

Login and status, if security is enabled

If you start the Workbench with -Dsecurity.enabled=true, the first page you will see is the login page. The default administrator account information is:

username: admin
password: root

It is highly recommended that you change the root password as soon as you log in for the first time. Go to Admin->Users, choose Edit next to your username and change your password.

See section User administration in the current document.

Configuration

In addition to the standard GraphDB command line parameters, the GraphDB Workbench can be controlled with the following parameters. They should be of the form -Dparam=value

Parameter Default Description
app.cors.enable false Enables cross-origin resource sharing.
app.info true Controls the display of build date and revision.
app.maxConnections 15 Sets the maximum number of concurrent connections to a GraphDB instance.
app.datadir ${user.home}/.graphdb-workbench/ Sets the directory where the workbench persistence data will be stored.
impex.dir ${user.home}/owlim-impex/ Changes the location of the file import folder.
jetty.port 8080 Sets the jetty port.
semantic.location <none> Connects to the specified location for repositories.
resource.language 'en' (English) Sets the default language in which to filter results displayed in the resource exploration.
resource.limit 100 Sets the limit for the number of statements displayed in the resource view page.
security.enabled true Enables/disables security.
Labels:
None
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.