Rules¶

The rule engine in Mulgara is called "Krule", so named because it was originally the "Kowari Rules Engine".

Apply Command¶

Running Rules in Mulgara is available as a TQL command. The format of the command is:

  apply <ruleGraph> to <dataGraph>;

If you want entailed data to go into a different graph, then use:

  apply <ruleGraph> to <dataGraph> destination <entailmentGraph>;

h2. Base Graphs

The rule engine operates by applying a set of rules to a base graph containing a set of "known" facts, and inserting the entailed statements into a destination graph.  It is common practice when working with ontologies to separate facts into a TBox graph that contains class and property descriptions and an ABox graph that contains individual descriptions.  In order to simplify the process of applying rules to distributed data, Krule accepts base graphs that are complex expressions composed of graph unions and intersections in addition to simple graph URIs.

For instance, in the simple case where the base facts are all in a single graph, the format of the @apply@ command is:
<pre>
  apply <ruleGraph> to <dataGraph> destination <entailmentGraph>;
</pre>

The command to apply rules to a base graph that is the logical union of two graphs will look like:
<pre>
  apply <ruleGraph> to <tboxGraph> or <aboxGraph> destination <entailmentGraph>;
</pre>

The syntax for specifying graph expressions for the base of an @apply@ command is the same syntax used in the [[Select#fromClause|FROM clause]] of a SELECT statement.

h2. Destination Graphs

The rule engine needs a destination graph to hold entailed statements when it applies rules.  Use the @destination@ keyword to specify the URI of a graph to hold entailed statements as illustrated above.  Specifying a destination graph is optional; if none is given as part of the command then a destination graph is chosen according to the following rules:
* If the base graph is a simple graph URI, then the base graph URI is chosen as the destination graph URI.
* If the base graph is a complex expression containing one or more unions or intersections, then it cannot be used as the destination (you can only insert statements into individual graphs, not complex expressions).  In this case, the system default graph @<sys:default>@ is chosen as the destination.

h2. Rule Graphs

Rule graphs can be defined in RDF (using the [[RulesFormat|Krule rule schema] found at "ruleskruleowl"httpmulgaraorgsvnmulgaratrunkruleskruleowl) or in the [wikiRLog RLog]] language.

RLog is a logic language designed specifically to work with RDF, and outputs its data using the Krule schema. RLog is significantly easier to use than the Krule schema, however Krule does provide a couple of options not available in RLog (such as rule-triggering reduction), so there may be some circumstances where Krule is preferable. RLog files are identified by the filename extensions: *.dl*, *.rl*, *.rlog*

Graphs may be applied directly from the filesystem, or may be pre-loaded into an internal graph. To preload a rule graph from */tmp/rules.dl* into a graph named *data:,rules* before applying it, then use the following instructions:
<pre>
  create <data:,rules>;
  load <file:///tmp/rules.dl> into <data:,rules>;
  apply <data:,rules> to <dataGraph>;
</pre>

Alternatively, the rules can be applied directly from the filesystem:
<pre>
  apply <file:///tmp/rules.dl> to <dataGraph>;
</pre>

Rules graphs may be inspected as RLog by exporting a *VALID* RLog file to a filename ending with one of the RLog extensions:

<pre>
  export <data:,rules> to <file:///tmp/program.dl>;
</pre>

h2. Result of Applying Rules

When rules are applied to a graph, every possible entailment is generated and stored. When fundamental schemas such as RDFS are applied, the level of detail can be surprising, with a number of overly obvious entailments, along with a few unexpected ones. If a separate entailment graph is used, then it is very common for a lot of the original data to be entailed, as internal consistency often refers to some level of redundancy to the information.

Rule application is an idempotent operation. This means that Rules can be run multiple times with no consequences. Consequently, rules can be re-applied after loading new data, with no impact on existing data or existing entailments.

Rule programs may also include consistency test. If a test fails then the operation is abandoned with no effect on the data. If a transaction is in progress when a test fails, then the entire transaction is rolled back.

h2. RDFS Rules

A graph describing the RDFS entailment rules is found in the Mulgara sources as "rules/rdfs-krule.rdf":http://mulgara.org/svn/mulgara/trunk/rules/rdfs-krule.rdf. An example for using this is given in the script in "rules/example.itql":http://mulgara.org/svn/mulgara/trunk/rules/example.itql.