Link Search Menu Expand Document
Start for Free

Using ICV Programmatically

This page demonstrates how to use ICV programmatically via Stardog’s Java API.

Page Contents
  1. Creating Constraints
  2. Adding Constraints to Stardog
  3. IC Validation
  4. ICV and Transactions

Here we describe how to use Stardog Integrty Constraint Validation (ICV) via the SNARL APIs (Stardog’s Java API). For more information on using SNARL in general, please refer to the chapter on Java.

There is command-line interface support for many of the operations necessary to using ICV with a Stardog database. Please see the ICV CLI section for more information.

To use ICV in Stardog, one must:

  1. create some constraints
  2. associate those constraints with a Stardog database

Creating Constraints

Constraints can be created using a ConstraintFactory which provides methods for creating integrity constraints. ConstraintFactory expects your constraints, if they are defined as OWL axioms, as RDF triples (or graph). To aid in authoring constraints in OWL, ExpressionFactory is provided for building the RDF equivalent of the OWL axioms of your constraint.

You can also write your constraints in OWL in your favorite editor and load them into the database from your OWL file.

We recommend defining your constraints as OWL axioms, but you are free to define them using SPARQL SELECT queries. If you choose to define a constraint using a SPARQL SELECT query, please keep in mind that if your query returns results, those are interpreted as the violations of the integrity constraint.

An example of creating a simple constraint using ExpressionFactory:

IRI product = Values.iri("urn:Product");
IRI manufacturer = Values.iri("urn:Manufacturer");
IRI manufacturedBy = Values.iri("urn:manufacturedBy");

// we want to say that a product should be manufactured by a Manufacturer:
Constraint aConstraint = ConstraintFactory.constraint(subClassOf(product,
                                                                 some(manufacturedBy, manufacturer)));

Adding Constraints to Stardog

The ICVConnection interface provides programmatic access to the ICV support in Stardog. It provides support for adding, removing and clearing integrity constraints in your database as well as methods for checking whether or not the data is valid; and when it’s not, retrieving the list of violations.

This example shows how to add an integrity constraint to a Stardog database.

// We'll start out by creating a validator from our SNARL Connection
ICVConnection aValidator = aConn.as(ICVConnection.class);

// add add a constraint, which must be done in a transaction.
aValidator.addConstraint(aConstraint);

Here we show how to add a set of constraints as defined in a local OWL ontology.

// We'll start out by creating a validator from our SNARL Connection
ICVConnection aValidator = aConn.as(ICVConnection.class);

// add add a constraint
aValidator.addConstraints()
	  .format(RDFFormat.RDFXML)
 	  .file(Paths.get("myConstraints.owl"));

IC Validation

Checking whether or not the contents of a database are valid is easy. Once you have an ICVConnection you can simply call its isValid() method which will return whether or not the contents of the database are valid with respect to the constraints associated with that database. Similarly, you can provide some Constraints to the isValid() method to see if the data in the database is invalid for those specific constraints; which can be a subset of the constraints associated with the database, or they can be new constraints you are working on.

If the data is invalid for some constraints—either the explicit constraints in your database or a new set of constraints you have authored—you can get some information about what the violation was from the SNARL IC Connection. ICVConnection.getViolationBindings() will return the constraints which are violated, and for each constraint, you can get the violations as the set of bindings that satisfied the constraint query. You can turn the bindings into the individuals which are in the violation using ICV.asIndividuals().

ICV and Transactions

In addition to using the ICVConnection as a data oracle to tell whether or not your data is valid with respect to some constraints, you can also use Stardog’s ICV support to protect your database from invalid data by using ICV as a guard within transactions.

When guard mode for ICV is enabled in Stardog, each commit is inspected to ensure that the contents of the database are valid for the set of constraints that have been associated with it. Should someone attempt to commit data which violates one or more of the constraints defined for the database, the commit will fail and the data will not be added/removed from your database.

By default, reasoning is not used when you enable guard mode, however you are free to specify any of the reasoning types supported by Stardog when enabling guard mode. If you have provided a specific reasoning type for guard mode it will be used during validation of the integrity constraints. This means you can author your constraints with the expectation of inference results satisfying a constraint.

try (AdminConnection dbms = AdminConnectionConfiguration.toEmbeddedServer().credentials("admin", "admin").connect()) {
  dbms.disk("icvWithGuard")			// disk db named 'icvWithGuard'
      .set(ICVOptions.ICV_ENABLED, true)	// enable icv guard mode
      .set(ICVOptions.ICV_REASONING_ENABLED, true)	// specify that guard mode should use reasoning
      .create(new File("data/sp2b_10k.n3"));	// create the db, bulk loading the file(s) to start
}

This illustrates how to create a persistent disk database with ICV guard mode and reasoning enabled. Guard mode can also be enabled when the database is created on the CLI.