Getting Started with Semantics

MarkLogic Semantics is a great data format for storing metadata, improving data integration, and building applications using that integrated, highly connected data. MarkLogic Semantic technologies and APIs include:

A SPARQL query language interpreter
Tools and APIs for directly loading semantic data encoded in a variety of RDF triple formats
A set of REST endpoints for interacting and querying stored RDF triples
Tight integration of this with MarkLogic’s document store, indexes, and search and analytics APIs

Prerequisites

This tutorial contains a series of exercises to introduce MarkLogic Semantic features, with a number of challenges for you to work through. We assume you:

- Have installed MarkLogic and the mlcp tool.
- Are generally familiar with MarkLogic architectural concepts and terms.
- Maintain some fluency in XQuery or JavaScript and can use Query Console.

The first exercise is a simple "Hello World" style introduction. The second has you go through the necessary steps to load the data needed by the subsequent exercises, which include some basic use of SPARQL, use of related XQuery and/or JavaScript APIs and the underlying triple index.

For your convenience in working through the exercises, we’ve provided a download-able semantics-exercises.zip (~5 MB) file that includes

The necessary datasets and utility scripts for loading the data, along with
A set of Query Console workspaces that contain the queries used by each exercise

NOTE: This is not a SPARQL language tutorial or an introduction to the Semantic Web.

Semantics: “Hello World”

In this exercise, you will:

Insert RDF triples into a database
Query the triples using SPARQL

This is a highly-simplified example. We’ll break some rules, but that’s OK!

Enable the Triple Index

Point your browser to the MarkLogic Administrative Interface on http://localhost:8001(replace localhost with the hostname).
Choose the Documents database in the Databases section.
In the Configure tab, scroll down the page until you see the triple index option.
If the value is false, click the radio button for true to enable the triple index. If the value is already true, there is no need to change it.
Click the ok button at the top of the page to save any changes.

Inserting Triples

Point your browser to http://localhost:8000 (Replace localhost with the hostname of your MarkLogic server if necessary). If you’re doing this from a fresh install, Query Console will be pointing at the Documents database (look at the top left in the dropdown). If the Query Type is set to the default, JavaScript, the text box shows a single line with a JavaScript comment. If you change the Query Type to XQuery a “hello world” XQuery example displays in the text area. Both XQuery and JavaScript examples are given so select which one you would like in the Query Type dropdown.
Remove any code from the text box.
Paste this into the text box and hit “run”:

import module namespace sem = "http://marklogic.com/semantics" 
  at "/MarkLogic/semantics.xqy";
  
sem:rdf-insert( 
  (
  sem:triple(
    sem:iri("http://example.org/marklogic/people/John_Smith"),
    sem:iri("http://example.org/marklogic/predicate/livesIn"),
    "London"
    )
  ,
  sem:triple(
    sem:iri("http://example.org/marklogic/people/Jane_Smith"),
    sem:iri("http://example.org/marklogic/predicate/livesIn"),
    "London"
    )
  ,
  sem:triple(
    sem:iri("http://example.org/marklogic/people/Jack_Smith"),
    sem:iri("http://example.org/marklogic/predicate/livesIn"),
    "Glasgow"
    )
  )
)

declareUpdate();
const sem = require('/MarkLogic/semantics.xqy');
  
sem.rdfInsert( 
  [
  sem.triple(
    sem.iri('http://example.org/marklogic/people/John_Smith'),
    sem.iri('http://example.org/marklogic/predicate/livesIn'),
    'London'
    ),
  sem.triple(
    sem.iri('http://example.org/marklogic/people/Jane_Smith'),
    sem.iri('http://example.org/marklogic/predicate/livesIn'),
    'London'
    ),
  sem.triple(
    sem.iri('http://example.org/marklogic/people/Jack_Smith'),
    sem.iri('http://example.org/marklogic/predicate/livesIn'),
    'Glasgow'
    )
  ]
);

Here, you are inserting 3 triples. Each triple is of the form (“subject”, “predicate”, “object”) where the subject and predicate are IRIs (like URIs, but internationalized) and the object is, in this case, a simple string. It will generate output, something like:

/triplestore/b2a859731e9449c1.xml

Verify Triple Count

Check that you have some triples.

In Query Console, click “+” to open a new tab.
Select XQuery or JavaScript as a Query Type and remove any code from the text box.
Paste this query into the text box and hit “run”:

fn:count( cts:triples() )

fn.count( cts.triples() );

It should return 3.

Run a SPARQL Query

Let’s run a query that asks “Who lives in London?”.

In Query Console, click “+” to open a new tab.
Select XQuery or JavaScript as a Query Type and remove any code from the text box.
Paste this query into the text box and hit “run”:

import module namespace sem = "http://marklogic.com/semantics" 
  at "/MarkLogic/semantics.xqy";
      
sem:sparql('
  SELECT ?person
  WHERE { ?person <http://example.org/marklogic/predicate/livesIn> "London" }
  ')

const sem = require('/MarkLogic/semantics.xqy');
      
sem.sparql(
  'SELECT ?person WHERE { ?person <http://example.org/marklogic/predicate/livesIn> "London" }'
);

It should return:

<http://example.org/marklogic/people/Jane_Smith>
<http://example.org/marklogic/people/John_Smith>

Next Steps

If you want to work through more examples using Semantics, or simply learn more about it, there are a good number of online resources for learning SPARQL, including:

As well, we recommend the following books:

Learning SPARQL, by Bob DuCharme
Semantic Web for the Working Ontologist, by Jim Hendler and Dean Allemang

And, of course, there is the W3C SPARQL spec and their published Glossary of Linked Data terms. Again, we assume you can learn SPARQL syntax elsewhere.

Written Tutorial