Quick start guide¶

On Windows¶

1. Download your GraphDB .exe file.
2. Double click the application file and follow the on-screen installer prompts.
3. Locate the GraphDB application on the Windows Start menu and start the database. The GraphDB Server and Workbench open at http://localhost:7200/.

On Mac OS¶

1. Download the GraphDB .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 the database by clicking the application icon. The GraphDB Server and Workbench open at http://localhost:7200/.

On Linux¶

1. Download the GraphDB .rpm or .deb file.
2. Install the package with sudo rpm -i or sudo dpkg -i and the name of the downloaded package. Alternatively, you can double click the package name.
3. Start the database by clicking the application icon. The GraphDB Server and Workbench open at http://localhost:7200/.

Configuring GraphDB¶

Once the GraphDB database is running, a small icon appears in the Status/Menu bar. To change the configuration, click the icon and click Settings...:

All settings will be applied only after you click the Save and Restart button. To increase the maximum memory allocated by the Java process to 4GB, add -Xmx4G.

Stopping GraphDB¶

To stop the database simply close the GraphDB Free window.

Running GraphDB¶

1. Download your GraphDB distribution file and unzip it.

2. Start the GraphDB Server and Workbench interface by executing the startup script located in the $graphdb_home/bin folder:

   graphdb
   

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

Configuring GraphDB¶

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

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 a non-daemon mode, you can also send Ctrl+C interrupt to stop it.

Load data through the GraphDB Workbench¶

Load data from local files

Let’s load your data.

1. Go to Import -> RDF.
2. Open the User data tab and click the Upload RDF files to upload the files from the News sample dataset provided in the distribution folder.

3. Click the Import button.
4. Enter the Import settings in the pop-up window.

5. Start importing by clicking Import button.

Load data through SPARQL or RDF4J API¶

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

1. Locate the correct GraphDB URL endpoint:

   • select 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 localfilename.ttl
     http://localhost:7200/repositories/repository-id/statements
   

   where localfilename.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.

   Tip

   Alternatively, use the full path to your local file.

Load data through the GraphDB LoadRDF tool¶

LoadRDF is a low level bulk load tool, which writes directly in the database index structures. It is ultra fast and supports parallel inference. For more information, see the Loading data using the LoadRDF tool.

Explore instances¶

To explore instances and their relationships, navigate to Explore -> Visual graph and find an instance of interest through the Easy graph search box or from the Resource view click the Visual Graph button. The graph of the instance and its relationships is shown.

Click on a node to see a menu for the following actions

• Expand node to show its relationships or collapse to hide them if already expanded
• Click the info icon to show more info about the node. The side panel includes a short description (rdfs:comment), labels (rdfs:label), RDF rank, image (foaf:depiction) if present and all DataType properties. You can search by DataType property if you are interested in a its value.
• Focus the node to restart the graph with this instance as central one. Note that you will lose the current state of your graph.
• Delete a node to hide its relationships and remove the node itself from the graph.

Click on the settings icon 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, click on 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 each time a different start resource.
  • Fixed node - you may want to start exploration each time with the same resource.
  • 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 colours. Node rank is a number between 0 and 1 and determines the size of a node. The label is the text on top of 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 show additional properties for a node. 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 want to see 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 the number of instances. The biggest circles are the parent classes and the nested ones are their children.

Explore your data - different actions

• 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, URI and a list of its first 1000 class instances. The class instances are represented by their URIs, which when clicked, lead to another view, where you can further explore their metadata.

  

  The side panel includes the following:

  • Local name;
  • URI (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 1000 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 URI 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 administer your data view, use the toolbar options on the right-hand side of the screen.

  
  • To see only the class labels, click the 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 you experience some strange behaviour, for example you cannot see a given class.
  • To export the diagram as an .svg image, click the Export Diagram download icon.

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.

Administering the diagram view

To administer 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 predicates/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 colour 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) are there 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 6197 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.

Query data through the Workbench¶

Now it’s time to delve into your data. The following is one possible scenario for searching in 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. Find all people mentioned in the documents from this news articles dataset.

   PREFIX pub: <http://ontology.ontotext.com/taxonomy/>
   PREFIX pub-old: <http://ontology.ontotext.com/publishing#>
   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: <http://www.ontotext.com/owlim/RDFRank#>
   INSERT DATA { _:b1 rank:compute _:b2. }
   

4. Find all people mentioned in the documents, ordered by popularity in the repository.

   PREFIX pub: <http://ontology.ontotext.com/taxonomy/>
   PREFIX pub-old: <http://ontology.ontotext.com/publishing#>
   PREFIX rank: <http://www.ontotext.com/owlim/RDFRank#>
   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: <http://ontology.ontotext.com/publishing#>
   PREFIX pub: <http://ontology.ontotext.com/taxonomy/>
   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: <http://ontology.ontotext.com/taxonomy/>
   PREFIX pub-old: <http://ontology.ontotext.com/publishing#>
   select distinct ?Mentions where {
   <http://www.reuters.com/article/2014/10/06/us-art-auction-idUSKCN0HV21B20141006> pub-old:containsMention / pub-old:hasInstance ?x .
   ?x pub:preferredLabel ?Mentions .
   
   }
   

   

7. Find everything available about Marlon Brando in the database.

   PREFIX pub: <http://ontology.ontotext.com/taxonomy/>
   PREFIX pub-old: <http://ontology.ontotext.com/publishing#>
   select distinct ?p ?objectLabel where {
   <http://ontology.ontotext.com/resource/tsk78dfdet4w> ?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: <http://ontology.ontotext.com/publishing#>
   PREFIX pub: <http://ontology.ontotext.com/taxonomy/>
   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: <http://ontology.ontotext.com/publishing#>
   PREFIX pub: <http://ontology.ontotext.com/taxonomy/>
   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
   

   

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 a 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
  http://localhost:7200/repositories/yourrepository

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"
  http://localhost:7200/repositories/worker-node

where, file.sparql contains an encoded query:

query=CONSTRUCT+%7B%3Fs+%3Fp+%3Fo%7D+WHERE+%7B%3Fs+%3Fp+%3Fo%7D+LIMIT+10