Getting Started

Running GraphDB as a Desktop Installation

The easiest way to set up and run GraphDB is to use the native installations provided for the GraphDB Desktop distribution. This kind of installation is the best option for your laptop/desktop computer, and does not require the use of a console, as it works in a graphic user interface (GUI). For this distribution, you do not need to download Java, as it comes bundled together with GraphDB.

Go to the GraphDB download page and request your GraphDB copy. You will receive an email with the download link. According to your OS, proceed as follows:


GraphDB Desktop is a new application that is similar to but different from the previous application GraphDB Free.

If you are upgrading from the old GraphDB Free application, you need to stop GraphDB Free and uninstall it before or after installing GraphDB Desktop. Once you run GraphDB Desktop for the first time, it will convert some of the data files and GraphDB Free will no longer work correctly.

On Windows

  1. Download the GraphDB Desktop .msi installer file.

  2. Double-click the application file and follow the on-screen installer prompts.

  3. Locate the GraphDB Desktop application in the Windows Start menu and start it. The GraphDB Workbench opens at http://localhost:7200/.

On MacOS

  1. Download the GraphDB Desktop .dmg file.

  2. Double-click it and get a virtual disk on your desktop. Copy the program from the virtual disk to your hard disk Applications folder, and you’re set.

  3. Start GraphDB Desktop by clicking the application icon. The GraphDB Workbench opens at http://localhost:7200/.

On Linux

  1. Download the GraphDB Desktop .deb or .rpm file.

  2. Install the package with sudo dpkg -i or sudo rpm -i and the name of the downloaded package. Alternatively, you can double-click the package name.

  3. Start GraphDB Desktop by clicking the application icon. The GraphDB Workbench opens at http://localhost:7200/.

Configuring GraphDB

Once GraphDB Desktop is running, a small icon appears in the status bar/menu/tray area (varying depending on OS). It allows you to check whether the database is running, as well as to stop it or change the configuration settings. Additionally, an application window is also opened, where you can go to the GraphDB documentation, configure settings (such as the port on which the instance runs), and see all log files. You can hide the window from the Hide window button and reopen it by choosing Show GraphDB window from the menu of the aforementioned icon.


Configuring the JVM

You can add and edit the JVM options (such as Java system properties or parameters to set memory usage) of the GraphDB native app from the GraphDB Desktop config file. It is located at:

  • On Mac: /Applications/GraphDB Desktop.cfg

  • On Windows: \Users\<username>\AppData\Local\GraphDB Desktop\app\GraphDB Desktop.cfg

  • On Linux: /opt/graphdb-desktop/lib/app/graphdb-desktop.cfg

The JVM options are defined at the end of the file and will look very similar to this:


Each java-options= line provides a single argument passed to the JVM when it starts. To be on the safe side, it is recommended not to remove or change any of the existing options provided with the installation. You can add your own options at the end. For example, if you want to run GraphDB Desktop with 8 gigabytes of maximum heap memory, you can set the following option:


Stopping GraphDB

To stop the database, simply quit it from the status bar/menu/tray area icon, or close the GraphDB Desktop application window.


On some Linux systems, there is no support for status bar/menu/tray area. If you have hidden the GraphDB window, you can quit it by killing the process.

Running GraphDB as a Standalone Server

The default way of running GraphDB is as a standalone server. The server is platform-independent, and includes all recommended JVM (Java virtual machine) parameters for immediate use.


Before downloading and running GraphDB, please make sure to have JDK (Java Development Kit, recommended) or JRE (Java Runtime Environment) installed. GraphDB requires Java 11 or greater.

Running GraphDB

  1. Download the GraphDB distribution file and unzip it.

  2. Start GraphDB by executing the graphdb startup script located in the bin directory of the GraphDB distribution.

    A message appears in the console telling you that GraphDB has been started in Workbench mode. To access the Workbench, open http://localhost:7200/ in your browser.

See the supported startup script options here.

Configuring GraphDB

Paths and network settings

The configuration of all GraphDB directory paths and network settings is read from the conf/ file. It controls where to store the database data, log files, and internal data. To assign a new value, modify the file or override the setting by adding -D<property>=<new-value> as a parameter to the startup script. For example, to change the database port number:

graphdb -Dgraphdb.connector.port=<your-port>

The configuration properties can also be set in the environment variable GDB_JAVA_OPTS, using the same -D<property>=<new-value> syntax.


The order of precedence for GraphDB configuration properties is as follows: command line supplied arguments > GDB_JAVA_OPTS > config file.

The GraphDB home directory

The GraphDB home defines the root directory where GraphDB stores all of its data. The home can be set through the system or config file property graphdb.home.

The default value for the GraphDB home directory depends on how you run GraphDB:

  • Running as a standalone server: the default is the same as the distribution directory.

  • All other types of installations: OS-dependent directory.

    • On Mac: ~/Library/Application Support/GraphDB.

    • On Windows: \Users\<username>\AppData\Roaming\GraphDB.

    • On Linux and other Unixes: ~/.graphdb.

GraphDB does not store any files directly in the home directory, but uses several sub-directories for data or configuration.

Java Virtual Machine settings

We strongly recommend setting explicit values for the Java heap space. You can control the heap size by supplying an explicit value to the startup script such as graphdb -Xms10g -Xmx10g or setting one of the following environment variables:

  • GDB_HEAP_SIZE: environment variable to set both the minimum and the maximum heap size (recommended);

  • GDB_MIN_MEM: environment variable to set only the minimum heap size;

  • GDB_MAX_MEM: environment variable to set only the maximum heap size.

For more information on how to change the default Java settings, check the instructions in the bin/graphdb file.


The order of precedence for JVM options is as follows: command line supplied arguments > GDB_JAVA_OPTS > GDB_HEAP_SIZE > GDB_MIN_MEM/GDB_MAX_MEM.


Every JDK package contains a default garbage collector (GC) that can potentially affect performance. We benchmarked GraphDB’s performance against the LDBC SPB and BSBM benchmarks with JDK 8 and 11. With JDK 8, the recommended GC is Parallel Garbage Collector (ParallelGC). With JDK 11, the most optimal performance can be achieved with either G1 GC or ParallelGC.

Stopping the database

To stop the database, find the GraphDB process identifier and send kill <process-id>. This sends a shutdown signal and the database stops. If the database is run in non-daemon mode, you can also send Ctrl+C interrupt to stop it.

Set up Your License

GraphDB is available in three different editions: Free, Standard Edition (SE), and Enterprise Edition (EE).

The Free edition is free to use and does not require a license. This is the default mode in which GraphDB will start. However, it is not open-source.

SE and EE are RDBMS-like commercial licenses on a per-server-CPU basis. They are neither free nor open-source. To purchase a license or obtain a copy for evaluation, please contact

When installing GraphDB, the SE/EE license file can be set through the GraphDB Workbench or programmatically.

To do that, follow the steps:

  1. Add, view, or update your license from Setup ‣ Licenses ‣ Set new license.


    From here, you can also Revert to Free license. If you do so, GraphDB will ask you to confirm.

  2. Select the license file and register it.


    You can also copy and paste it in the text area.

  3. Validate your license.

  4. After completing these steps, you will be able to view your license details.

Interactive User Guides

GraphDB 10.1 introduces a set of interactive tutorials that will walk you through key GraphDB functionalities using the Workbench user interface. They can be accessed from Help ‣ Interactive guides, as well as via the Take me to the guides button in the center panel of the GraphDB Workbench startup screen.


Available guides

Each guide has a name, a description, a level (Beginner, Intermediate, or Advanced), and a Run button, which starts the tutorial. Currently, GraphDB 10.1 offers two such tutorials:

  • The Star Wars guide: Designed for beginners and using the Star Wars dataset, which you can download within the guide, this tutorial will walk you through some basic GraphDB functionalities such as creating a repository, importing RDF data from a file in it, and exploring the data through the Visual graph.

  • The Movies database guide: Also designed for beginners and using a dataset with movie information, this tutorial will show you some additional functionalities like exploring your data from the class hierarchy perspective, some SPARQL queries, as well as exploring RDF through the tabular view.

Run guide

To start a guide, click Run. This will activate a series of dialogs that will guide you through the steps of the tutorial. While the guide is running, the remaining part of the Workbench remains darker and is inactive.

Each window explains what is going to happen next or asks you to perform a certain action. The window title shows the name of the current action, the number of steps it comprises, and the progress of the action, e.g., step 1 of the Create repository action that consists of 7 steps. Before each major action, you are provided with an overview of what the particular view of the Workbench is used for.


The little icon left of the title of each step provides additional information about it, for example:


To proceed to the next step, either click/type in the highlighted active area in the Workbench (Setup in the above example), or press the Next button. We recommend the former as it essentially is exactly what you would be doing in the user interface if you were not in the guide, thus familiarizing yourself with it more easily.

If you attempt to close the dialog window, GraphDB will ask you to confirm the action before closing it.

Create a Repository

Now let’s create your first repository.


When started, GraphDB creates the GraphDB-HOME/data directory to store local repository data. To change the directory, see Configuring GraphDB Data directory.

  1. Go to Setup ‣ Repositories.

  2. Click Create new repository.

  3. Select GraphDB repository.

  4. For Repository ID, enter my_repo and leave all other optional configuration settings at their default values.


    For repositories with over several tens of millions of statements, see Configuring a Repository.

  5. Click the Connect button to set the newly created repository as the repository for this location.

  6. Use the pin to select it as the default repository.



You can also use cURL command to perform basic location and repository management through the GraphDB REST API.

Load Your Data

All examples given below are based on the News sample dataset provided in the distribution folder.


You can also use public datasets such as the Wine ontology by pasting its data URL - - in Import ‣ User data ‣ Get RDF data from a URL.

Load data through the GraphDB Workbench

Let’s load your data from a local file:

  1. Go to Import.

  2. Open the User data tab and click the Upload RDF files to upload the files from the News sample dataset provided in the examples/data/news directory of the GraphDB distribution.

  3. Click Import.

  4. Enter the Import settings in the pop-up window.


    Import Settings

    • Base IRI: the default prefix for all local names in the file;

    • Target graphs: imports the data into one or more graphs.

    For more details, see Loading data using the Workbench.

  5. Click Import.


You can also import data from files on the server where the Workbench is located, from a remote URL (with a format extension or by specifying the data format), by typing or pasting the RDF data in a text area, or by executing a SPARQL INSERT.

Import execution

  • Imports are executed in the background while you continue working on other things.

  • Interrupt is supported only when the location is local.

  • Parser config options are not available for remote locations.

Load data through SPARQL or RDF4J API

The GraphDB database also supports a powerful API with a standard SPARQL or RDF4J endpoint, to which data can be posted with cURL, a local Java client API, or an RDF4J console. It is compliant with all standards, and allows every database operation to be executed via an HTTP client request.

  1. Locate the correct GraphDB URL endpoint:

    • Go to Setup ‣ Repositories.

    • Click the link icon next to the repository name.

    • Copy the repository URL.

  2. Go to the folder where your local data files are.

  3. Execute the script:

    curl -X POST -H "Content-Type:application/x-turtle" -T <local_file_name.ttl> \

    where local_file_name.ttl is the data file you want to import, and http://localhost:7200/repositories/repository-id/statements is the GraphDB URL endpoint of your repository.


    Alternatively, use the full path to your local file.

Load data through the ImportRDF tool

ImportRDF is a low-level bulk load tool that writes directly in the database index structures. It is ultra-fast and supports parallel inference. For more information, see Loading Data Using the ImportRDF Tool.


Loading data through the GraphDB ImportRDF tool can be performed only if the repository is empty, e.g., the initial loading after the database has been inactive. If you use it on a non-empty repository, it will overwrite all of the data in it.

Explore Your Data and Class Relationships

Explore instances

To explore instances and their relationships, first enable the Autocomplete index from Setup ‣ Autocomplete, which makes the lookup of IRIs easier. Then navigate to Explore ‣ Visual graph, and find an instance of interest through the Easy graph search box. You can also do it from the View resource search field in GraphDB’s home page - search for the name of your graph, and press the Visual button.

The graph of the instance and its relationships are shown. The example here is from the wine ontology that we mentioned earlier.


Hover over a node to see a menu for the following actions:

  • Expand a node to show its relationships or collapse to hide them if already expanded. You can also expand the node by double-clicking on it.

  • Copy a node’s IRI to the clipboard.

  • Focus on a node to restart the graph with this instance as the central one. Note that you will lose the current state of your graph.

  • Delete a node to hide its relationships and hide it from the graph.

Click on a node to see more info about it: a side panel opens on the right, including a short description (rdfs:comment), labels (rdfs:label), RDF rank, image (foaf:depiction) if present, and all DataType properties. You can also search by DataType property if you are interested in its value. Click on the node again if you want to hide the side panel.

You can switch between nodes without closing the side panel. Just click on the new node about which you want to see more, and the side panel will automatically show the information about it.

Click on the settings icon on the top right for advanced graph settings. Control number of links, types, and predicates to hide and show.


A side panel opens with the available settings:


Create your own visual graph

Control the SPARQL queries behind the visual graph by creating your own visual graph configuration. To make one, go to Explore ‣ Visual graph ‣ Advanced graph configurations ‣ Create graph config. Use the sample queries to guide you in the configuration.


The following parts of the graph can be configured:

  • Starting point - this is the initial state of your graph.

    • Search box: start with a search box to choose a different start resource each time;

    • Fixed node: you may want to start exploration with the same resource each time;

    • Query results: the initial config state may be the visual representation of a Graph SPARQL query result.

  • Graph expansion: determines how new nodes and links are added to the visual graph when the user expands an existing node. The ?node variable is required and will be replaced with the IRI of the expanded node.

  • Node basics: this SELECT query controls how the type, label, comment and rank are obtained for the nodes in the graph. Node types correspond to different colors. Node rank is a number between 0 and 1 and determines the size of a node. The label is the text over each node, and if empty, IRI local name is used. Again, ?node binding is replaced with node IRI.

  • Predicate label: defines what text to show for each edge IRI. The query should have ?edge variable to replace it with the edge IRI.

  • Node extra: Click on the info icon to see additional node properties. Control what to see in the side panel. ?node variable is replaced with node IRI.

  • Save your config and reload it to explore your data the way you wish to visualize it.

Class hierarchy

To explore your data, navigate to Explore ‣ Class hierarchy. You can see a diagram depicting the hierarchy of the imported RDF classes by number of instances. The biggest circles are the parent classes and the nested ones are their children.


If your data has no ontology (hierarchy), the RDF classes will be visualized as separate circles instead of nested ones.


Various actions for exploring your data:

  • To see what classes each parent has, hover over the nested circles.

  • To explore a given class, click its circle. The selected class is highlighted with a dashed line, and a side panel with its instances opens for further exploration. For each RDF class you can see its local name, IRI, and a list of its first 1,000 class instances. The class instances are represented by their IRIs, which, when clicked, lead to another view where you can further explore their metadata.


    The side panel includes the following:

    • Local name;

    • IRI (Press Ctrl+C / Cmd+C to copy to clipboard and Enter to close);

    • Domain-Range Graph button;

    • Class instances count;

    • Scrollable list of the first 1,000 class instances;

    • View Instances in SPARQL View button. It redirects to the SPARQL view and executes an auto-generated query that lists all class instances without LIMIT.

  • To go to the Domain-Range Graph diagram, double-click a class circle or the Domain-Range Graph button from the side panel.

  • To explore an instance, click its IRI from the side panel.

  • To adjust the number of classes displayed, drag the slider on the left-hand side of the screen. Classes are sorted by the maximum instance count, and the diagram displays only the current slider value.

  • To administrate your data view, use the toolbar options on the right-hand side of the screen.

    • To see only the class labels, click Hide/Show Prefixes. You can still view the prefixes when you hover over the class that interests you.

    • To zoom out of a particular class, click the Focus diagram home icon.

    • To reload the data on the diagram, click the Reload diagram icon. This is recommended when you have updated the data in your repository, or when you are experiencing some strange behavior, for example you cannot see a given class.

    • To export the diagram as an .svg image, click the Export Diagram download icon.

  • You can also filter the hierarchy by graph when there is more than one named graph in your repository. Just expand the All graphs drop-down menu next to the toolbar options and select the graph you want to explore.


Domain-Range graph

To explore the connectedness of a given class, double-click the class circle or the Domain-Range Graph button from the side panel. You can see a diagram that shows this class and its properties with their domain and range, where domain refers to all subject resources and range - to all object resources. For example, if you start from class pub:Company, you see something like: <pub-old:Mention pub-old:hasInstance pub:Company> <pub:Company pub:description xsd:string>.


You can also further explore the class connectedness by clicking:

  • the green nodes (object property class);

  • the labels - they lead to the View resource page, where you can find more information about the current class or property;

  • the slider Show collapsed predicates to hide all edges sharing the same source and target nodes;


To see all predicate labels contained in a collapsed edge, click the collapsed edge count label, which is always in the format <count> predicates. A side panel opens with the target node label, a list of the collapsed predicate labels and the type of the property (explicit or implicit). You can click these labels to see the resource in the View resource page.


Administrating the diagram view

To administrate your diagram view, use the toolbar options on the right-hand side of the screen.

  • To go back to your class in the Class hierarchy, click the Back to Class hierarchy diagram button.

  • To collapse edges with common source/target nodes, in order to see the diagram more clearly, click the Show all predicate/Show collapsed predicates button. The default is collapsed.

  • To export the diagram as an .svg image, click the Export Diagram download icon.

Class relationships

To explore the relationships between the classes, navigate to Explore ‣ Class relationships. You can see a complicated diagram showing only the top relationships, where each of them is a bundle of links between the individual instances of two classes. Each link is an RDF statement, where the subject is an instance of one class, the object is an instance of another class, and the link is the predicate. Depending on the number of links between the instances of two classes, the bundle can be thicker or thinner and gets the color of the class with more incoming links. These links can be in both directions.

In the example below, you can see the relationships between the classes of the News sample dataset provided in the distribution folder. You can observe that the class with the biggest number of links (the thickest bundle) is pub-old:Document.


To remove all classes, use the X icon.


To control which classes to display in the diagram, use the add/remove icon next to each class.


To see how many annotations (mentions) there are in the documents, click on the blue bundle representing the relationship between the classes pub-old:Document and pub-old:TextMention. The tooltip shows that there are 6,197 annotations linked by the pub-old:containsMention predicate.


To see how many of these annotations are about people, click on light purple bundle representing the relationship between the classes pub-old:TextMention and pub:Person. The tooltip shows that 274 annotations are about people linked by the pub-old:hasInstance predicate.


Just like in the Class hierarchy view, you can also filter the class relationships by graph when there is more than one named graph in the repository. Expand the All graphs drop-down menu next to the toolbar options and select the graph you want to explore.

Query Your Data

Query data through the Workbench


SPARQL is a SQL-like query language for RDF graph databases with the following types:

  • SELECT: returns tabular results;

  • CONSTRUCT: creates a new RDF graph based on query results;

  • ASK: returns YES if the query has a solution, otherwise “NO”;

  • DESCRIBE: returns RDF data about a resource; useful when you do not know the RDF data structure in the data source;

  • INSERT: inserts triples into a graph;

  • DELETE: deletes triples from a graph.

For more information, see the Additional resources section.

Now it is time to delve into your data. The following is one possible scenario for querying it.

  1. Select the repository you want to work with, in this example News, and click the SPARQL menu tab.

  2. Let’s say you are interested in people. Paste the query below into the query field, and click Run to find all people mentioned in the documents from this news articles dataset.

    PREFIX pub: <>
    PREFIX pub-old: <>
    select distinct ?x ?Person  where {
    ?x a pub:Person .
    ?x pub:preferredLabel ?Person .
    ?doc pub-old:containsMention / pub-old:hasInstance ?x .
  3. Run a query to calculate the RDF rank of the instances based on their interconnectedness.

    PREFIX rank: <>
    INSERT DATA { _:b1 rank:compute _:b2. }
  4. Find all people mentioned in the documents, ordered by popularity in the repository.

    PREFIX pub: <>
    PREFIX pub-old: <>
    PREFIX rank: <>
    select distinct ?x ?PersonLabel ?rank where {
        ?x a pub:Person .
        ?x pub:preferredLabel ?PersonLabel .
        ?doc pub-old:containsMention / pub-old:hasInstance ?x .
        ?x rank:hasRDFRank ?rank .
    } ORDER by DESC (?rank)
  5. Find all people who are mentioned together with their political parties.

    PREFIX pub-old: <>
    PREFIX pub: <>
    select distinct ?personLabel ?partyLabel where {
        ?document pub-old:containsMention ?mention .
        ?mention pub-old:hasInstance ?person .
        ?person pub:preferredLabel ?personLabel .
        ?person pub:memberOfPoliticalParty ?party .
        ?party pub:hasValue ?value .
        ?value pub:preferredLabel ?partyLabel .
  6. Did you know that Marlon Brando was from the Democratic Party? Find what other mentions occur together with Marlon Brando in the given news article.

    PREFIX pub: <>
    PREFIX pub-old: <>
    select distinct ?Mentions where {
    <> pub-old:containsMention / pub-old:hasInstance ?x .
    ?x pub:preferredLabel ?Mentions .
  7. Find everything available about Marlon Brando in the database.

    PREFIX pub: <>
    PREFIX pub-old: <>
    select distinct ?p ?objectLabel where {
    <> ?p ?o .
    ?o pub:hasValue ?value .
        ?value pub:preferredLabel ?objectLabel .
        } union {
            ?o pub:hasValue ?objectLabel .
            filter (isLiteral(?objectLabel)) .
  8. Find all documents that mention members of the Democratic Party and the names of these people.

    PREFIX pub-old: <>
    PREFIX pub: <>
    select distinct ?document ?personLabel where {
        ?document pub-old:containsMention ?mention .
        ?mention pub-old:hasInstance ?person .
        ?person pub:preferredLabel ?personLabel .
        ?person pub:memberOfPoliticalParty ?party .
        ?party pub:hasValue ?value .
        ?value pub:preferredLabel "Democratic Party"@en .
  9. Find when these people were born and died.

    PREFIX pub-old: <>
    PREFIX pub: <>
    select distinct ?person ?personLabel ?dateOfbirth ?dateOfDeath where {
        ?document pub-old:containsMention / pub-old:hasInstance ?person .
        ?person pub:preferredLabel ?personLabel .
        OPTIONAL {
           ?person pub:dateOfBirth / pub:hasValue ?dateOfbirth .
        OPTIONAL {
           ?person pub:dateOfDeath / pub:hasValue ?dateOfDeath .
        ?person pub:memberOfPoliticalParty / pub:hasValue / pub:preferredLabel "Democratic Party"@en .
    } order by ?dateOfbirth


You can play with more example queries from the Example_queries.rtf file provided in the examples/data/news directory of the GraphDB distribution.

Query data programmatically

SPARQL is not only a standard query language, but also a protocol for communicating with RDF databases. GraphDB stays compliant with the protocol specification, and allows querying data with standard HTTP requests.

Execute the example query with an HTTP GET request:

curl -G -H "Accept:application/x-trig" \
  -d query=CONSTRUCT+%7B%3Fs+%3Fp+%3Fo%7D+WHERE+%7B%3Fs+%3Fp+%3Fo%7D+LIMIT+10 \

Execute the example query with a POST operation:

curl -X POST --data-binary @file.sparql -H "Accept: application/rdf+xml" \
  -H "Content-type: application/x-www-form-urlencoded" \

where file.sparql contains an encoded query:



For more information on how to interact with GraphDB APIs, refer to the RDF4J and SPARQL protocols or the Linked Data Platform specifications.