Semantics Developer's Guide — Chapter 7

Using Rulesets

Inference rules enable you to search over both asserted triples and inferred triples. The semantic inference engine uses rulesets to create new triples from existing triples at query time. You can associate one or more rulesets with a database, so that by default, queries made against that database will include the ruleset. You can also specify one or more rulesets for each query at query time.

A ruleset location is either a URI in the Schemas database for the database you are using, or a file name in <MarkLogic Install Directory>/Config, which contains standard, pre-defined rulesets such as rdfs, rdfs+ and OWL-Horst. The pre-defined rulesets can be specified as a simple name rather than a URI in a Schemas database (like /rules/livesIn.rules) .

These standards-based rulesets (RDFS, RDFS-Plus, and OWL Horst) are included with MarkLogic. Each ruleset has two versions; the full ruleset (xxx-full.rules) and the optimized version (xxx.rules). The components of each of these rulesets are available separately so that you can do fine-grained inference for queries. You can create your own rulesets by importing some of those rulesets and/or writing your own rules.

To see these rulesets (in Linux), go to your MarkLogic install directory, then the Config directory under that (/<MarkLogic_install_dir>/Config/*.rules). There you will see a set of files with a .rules extension.

/opt/MarkLogic/Config/*.rules

Each of these .rules files is a ruleset. If you open one in a text editor you will see that the rulesets are componentized - that is, they are defined in small component rulesets, then built up into larger rulesets. Here is an example of the rule domain.rules:

PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns>
PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema/>

...

rule "domain rdfs2" CONSTRUCT {
  ?x a ?c
} {
  ?x ?p ?y .
  ?p rdfs:domain ?c
}

In this example, a means 'type of' (rdf:type or rdfs:type). This rule states that if all the things in the second set of braces matches a triple (p has domain c - that is, for every triple that has the predicate p, the object must be in the domain c), then construct the triple in the first set of braces (if you see x p y, then x is a c).

By using a building block approach to creating and using rules, you can enable only the rules you really need, so that your query can be as efficient as possible.

If you have a default ruleset associated with a database and you specify a ruleset as part of your query, both rulesets will be used. Rulesets are additive. Use the no-default-ruleset option to ignore the default ruleset.

This example uses the rdfs.rules ruleset from the <MarkLogic-install-dir>/Config location:

import module namespace sem = "http://marklogic.com/semantics" 
  at "/MarkLogic/semantics.xqy";
let $sup :=
'
PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>
PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>

INSERT DATA
{ <someMedicalCondition> rdf:type <osteoarthritis> .
  <osteoarthritis> rdfs:subClassOf <bonedisease> . }'
return sem:sparql-update($sup)
; (: transaction separator :)

let $sq := 
'PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>
PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>
PREFIX d: <http://diagnoses#>
PREFIX foaf: <http://xmlns.com/foaf/0.1/>
SELECT ?diagnosis
WHERE { ?diagnosis rdf:type <bonedisease>. } '
  
let $rs := sem:ruleset-store("rdfs.rules", sem:store())  
(: rdfs:rules is a predefined rule set in <MarkLogic-install-dir>/Config :)
return sem:sparql($sq, (), (), $rs)  
(: the rules specify that query for <bonedisease> will return the subclass <osteoarthritis> :)

You can manage rulesets using the REST Mangement API or XQuery Admin API. For details see the default-ruleset property in PUT /manage/v2/databases/{id|name}/properties and admin:database-add-default-ruleset.

Choosing Rulesets for Queries

You can choose which rulesets to use for your SPARQL query by using sem:ruleset-store. The sem:ruleset-store function returns a set of triples that result from the application of the ruleset to the triples defined by the sem:store function provided in $store (for example, 'all of the triples that can be inferred from the rule').

This statement specifies the rdfs.rules ruleset as part of sem:ruleset-store:

let $rdfs-store := sem:ruleset-store("rdfs.rules",sem:store() )

So this says, let the $rdf-store contain triples derived by inference using the rdfs.rules against the sem:store. If no value is provided for sem:store, the query uses the triples in the current database's triple index. The built-in functions sem:store and sem:ruleset-store are used to define the triples over which to query and the rulesets (if any) to use with the query. The $store definition includes a ruleset, as well as other ways of restricting a query's domain, such as a cts:query.

This example executes a SPARQL query against the data in $triples, using the inference rules rdfs:subClassOf and rdfs:subPropertyOf:

xquery version "1.0-ml";
import module namespace sem = "http://marklogic.com/semantics" 
  at "/MarkLogic/semantics.xqy";

PREFIX skos: <http://www.w3.org/2004/02/skos/core#Concept/>

sem:sparql("select * { ?c a skos:Concept; rdfs:label ?l }",(),(),
sem:ruleset-store(("subClassOf.rules","subPropertyOf.rules"),
  ($triples)
)

Specifying a Default Ruleset for a Database

In addition to the Admin API with XQuery, you can also use the Admin UI to set the default ruleset to be used with a database for queries. To specify the ruleset or rulesets for a database, click the database name under Databases in left-hand navigation in the Admin UI. Click the database name to expand the list. Scroll to Default Rulesets.

Click Default Rulesets to see the rulesets currently associated with the Documents database.

To add your own ruleset, click Add to enter the name and location of the ruleset.

Your custom rulesets will be located in the Schemas database. The rulesets supplied by MarkLogic are located in the Config directory under your MarkLogic installation directory (/<MarkLogic_install_dir>/Config/*.rules).

Click more items to associate additional rulesets with this database.

Security for rulesets is managed the same way that security is handled for MarkLogic schemas.

You can use Query Console to find out what default rulesets are currently associated with a database using the admin:database-get-default-rulesets function.

This example will return the name and location of the default rulesets for the Documents database:

xquery version "1.0-ml";
import module namespace admin = "http://marklogic.com/xdmp/admin" 
  at "/MarkLogic/admin.xqy";

let $config := admin:get-configuration()
let $dbid := admin:database-get-id($config, "Documents")
return admin:database-get-default-rulesets($config, $dbid)

=>

<default-ruleset xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns="http://marklogic.com/xdmp/database">
    <location>/rules/livesin.rules</location>
</default-ruleset>

Overriding the Default Ruleset

You can turn off or ignore a ruleset set as the default on a database. In this example, a SPARQL query is executed against the database, ignoring the default rulesets and using the rdfs:subClassOf inference ruleset for the query:

xquery version "1.0-ml";
import module namespace sem = "http://marklogic.com/semantics" 
  at "/MarkLogic/semantics.xqy";

PREFIX skos: <http://www.w3.org/2004/02/skos/core#Concept/>

sem:sparql("SELECT * { 
  ?c a skos:Concept; 
  rdfs:label ?l }",(),(),
sem:ruleset-store("subClassOf.rules",sem:store("no-default-rulesets"))
)

You can also turn off or ignore a ruleset as part of a query, through the Admin UI, or by using XQuery or JavaScript to specify the ruleset.

You can also change the default ruleset for a database in the Admin UI by 'deleting' the default ruleset from that database. In the Admin UI, select the database name from the left-hand navigation panel, click the database name. Click Default Rulesets.

On the Database: Documents panel, select the default ruleset you want to remove, and click delete. Click OK when you are done. The ruleset is no longer the default ruleset for this database.

This action does not delete the ruleset, only removes it as the default ruleset.

You can also use admin:database-delete-default-ruleset with XQuery to change a database's default ruleset. This example removes subClassOf.rules as the default ruleset for the Documents database.

xquery version "1.0-ml"; 
import module namespace admin = "http://marklogic.com/xdmp/admin" 
  at "/MarkLogic/admin.xqy";

let $config := admin:get-configuration()
let $dbid := admin:database-get-id($config, "Documents")
let $rules := admin:database-ruleset("subClassOf.rules")
let $c := admin:database-delete-default-ruleset($config, $dbid, $rules)

return admin:save-configuration($c)

Creating a Ruleset

One way to think of inference rules is as a way to construct some inferred triples, then search over the new data set (one that includes the database - the sem:store - plus the inferred triples). MarkLogic rulesets have the .rules extension and are located in the install directory:

/<MarkLogic_install_dir>/Config/*.rules

When you create your own rulesets, you will store them in the Schemas database.

The syntax of an inference rule uses the grammar of a SPARQL CONSTRUCT with the WHERE clause restricted to a combination of only triple patterns, joins, and filters.

The ruleset must have a unique name. If the name is used more than once, the operation will return an error. The import statement in the prolog of the ruleset file includes all rules from the ruleset found at the location given.

This ruleset from the /<MarkLogic Install>/Config directory includes four rules named rdfs8, rdfs9, rdfs10, and rdfs11. The ruleset includes prefixes, and each rule has a rule name and a CONSTRUCT clause:

PREFIX rdf:     <http://www.w3.org/1999/02/22-rdf-syntax-ns#>
PREFIX rdfs:    <http://www.w3.org/2000/01/rdf-schema#>

rule "rdfs8" CONSTRUCT {
  ?c rdfs:subClassOf rdfs:Resource
} {
  ?c a rdfs:Class
}

rule "rdfs9" CONSTRUCT {
  ?x a ?c2
} {
  ?x a ?c1 .
  ?c1 rdfs:subClassOf ?c2 .
  FILTER(?c1!=?c2)
}

rule "rdfs10" CONSTRUCT {
  ?c rdfs:subClassOf ?c
} {
  ?c a rdfs:Class
}

rule "rdfs11" CONSTRUCT {
  ?c1 rdfs:subClassOf ?c3
} {
  ?c1 rdfs:subClassOf ?c2 .
  ?c2 rdfs:subClassOf ?c3 .
  FILTER(?c1!=?c2 && ?c2!=?c3 && ?c1!=?c3)
}

Note that two of the rules also include a FILTER clause.

This ruleset from same directory imports smaller rulesets to make a ruleset approximating the full RDFS ruleset:

import "rdf.rules"
import "domain.rules"
import "range.rules"
import "subPropertyOf.rules"
import "subClassOf.rules"

PREFIX rdf:     <http://www.w3.org/1999/02/22-rdf-syntax-ns#>
PREFIX rdfs:    <http://www.w3.org/2000/01/rdf-schema#>

# Miscellaneous other axiomatic triples

rule "rdfs properties" CONSTRUCT {
  rdf:type rdfs:domain rdfs:Resource .
  rdf:type rdfs:range rdfs:Class .
}

If a ruleset at a given location is imported more than once, the effect of the import will be the same as if it had only been imported once. If a ruleset is imported more than once from different locations (for example from the /<MarkLogic Install>/Config directory and from the Schemas database directory), MarkLogic will assume they are different rulesets and raise an error if they contain duplicate rule names.

Here is a rule that you could create to infer geographic locations:

# geographic rules for inference
PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns>
PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema/>
PREFIX ex: <http://example.com/>
PREFIX gn: <http://www.geonames.org/ontology/>

rule "lives in" CONSTRUCT {
  ?person ex:livesIn ?place2
} {
  ?person ex:livesIn ?place1 .
  ?place1 gn:parentFeature ?place2
}

In Query Console, you can add the livesIn rule to the Schemas database using xdmp:document-insert. Make sure the Schemas database is selected as the Content Source before you run the code:

xquery version "1.0-ml";

xdmp:document-insert(
'/rules/livesin.rules',
text{
'
# geographic rules for inference
PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns>
PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema/>
PREFIX ex: <http://example.com/>
PREFIX gn: <http://www.geonames.org/ontology/>

rule "lives in" CONSTRUCT {
  ?person ex:livesIn ?place2
} {
  ?person ex:livesIn ?place1 .
  ?place1 gn:parentFeature ?place2
  }
'
}
)

The example stores the livesin.rule in the Schemas database, in the rules directory (/rules/livesin.rules).

You can include your ruleset as part of inference in the same way you can include the supplied rulesets. MarkLogic will check the location for rules in the Schemas database and then the location for the supplied rulesets.