Lucene GraphDB Connector

compared with
Key
This line was removed.
This word was removed. This word was added.
This line was added.

Changes (67)

View Page History
h1. Overview

TThe GraphDB Connectors provide extremely fast keyword and faceted (aggregation) searches that are typically implemented by an external component or service, but have the additional benefit of staying automatically up-to-date with the GraphDB repository data.
The GraphDB Connectors provide extremely fast normal and facet (aggregation) searches that are typically implemented by an external component or service such as Lucene, but have the additional benefit to stay automatically up-to-date with the GraphDB repository data.

The Connectors provide synchronisation at the _entity_ level, where an entity is defined as having a unique identifier (a URI) and a set of properties and property values. In terms of RDF, this corresponds to a set of triples that have the same subject. In addition to simple properties (defined by a single triple), the Connectors support _property chains_. A property chain is defined as a sequence of triples where each triple's object is the subject of the subsequent following triple.

h1. Features

* multiple independent instances per repository
* the entities for synchronisation are defined by:
** a list of fields (on the Lucene side) and property chains (on the GraphDB side), the side) whose values of which are to will be synchronised
** a list of the rdf:type rdf:type's of the entities for synchronisation
** a list of languages for synchronisation (the default is all languages)
** additional filtering by property and value
* full-text search using native Lucene queries
* sorting by any preconfigured field
* paging of results using _offset_ and _limit_
* specifying the Lucene analyzer to use (the default is Lucene's StandardAnalyzer)
* stripping HTML/XML tags in literals (the default is not to strip markup)
* stripping HTML/XML tags in literals (default is to not strip markup)
* boosting an entity by the \[numeric\] value of one or more predicates
* custom scoring expressions at query time to evaluate score based on Lucene score and entity boost

Each feature is described in detail below.

h1. Sample data

All examples below use sample data, describing five fictitious wines: Yoyowine, Franvino, Noirette, Blanquito and Rozova, as well as the grape varieties needed to make these wines. The minimum ruleset level needed in GraphDB is RDFS
All examples use the following sample data. It describes five fictitious wines: Yoyowine, Franvino, Noirette, Blanquito and Rozova, as well as the grape varieties needed to make these wines. The minimum needed ruleset level in GraphDB is RDFS.

{code}
h1. Usage

All interactions with the Lucene GraphDB Connector are shall be done through SPARQL queries.

There are three types of SPARQL queries:
h2. Creating a connector

Creating a connector is should be done by sending a SPARQL query with the following configuration data:

* the name of the connector (e.g. my_index),
* classes to synchronise,
* properties to synchronise.

The configuration data must be provided as a JSON string representation and passed together with the create command.

{tip:title=What we recommend}
Use the GraphDB Connectors management interface provided by the GraphDB Workbench. It lets will let you create the configuration easily and then create the connector directly or copy the configuration and execute it elsewhere.
{tip}

The create command is triggered by a SPARQL *INSERT* with the *createConnector* predicate, e.g. this creates will create a connector called *my_index* that will synchronise the wines from the sample data above:

{code}
{code}

Note that one of the fields has _"sort": true_. This is explained in more details when discussing sorting below. further under [Sorting|#sorting].

The above command creates will create a new Lucene connector.

The "types" key defines the RDF type of the entities for synchronisation and, to synchronise and in the example, it is only entities of the type <http://www.ontotext.com/example/wine#Wine> (and its subtypes). The "fields" key defines the mapping from RDF to Elasticsearch. Lucene. The basic building block is the property chain, i.e. a sequence of RDF properties where the object of each property is the subject of the following property. In the example, we map three bits of information - the wine's grape, the sugar content, and the year. Each chain is assigned a short and convenient field name: "grape", "sugar", and "year". The field names are later used in the queries.

Grape is an example of a property chain composed of more than one property. First, we take the wine's madeFromGrape property, the object of which is an instance of type Grape, and then we take the rdfs:label of this instance. Sugar and year are both composed of a single property that links the value directly to the wine.





h2. Dropping a connector

{code}

*?cntUri* is will be bound to the prefixed URI of the connector that was used during creation, e.g. <http://www.ontotext.com/connectors/elasticsearch/instance#my_index>, <http://www.ontotext.com/connectors/lucene/instance#my_index>, while *?cntStr* is will be bound to a string, representing the part after the prefix, e.g. "my_index".

h2. Status check
{code}

*?cntUri* is will be bound to the connector prefixed URI, while *?cntStatus* is will be bound to a string representation of the status of the connector represented by this URI. The status is key-value based.

h2. Adding, updating and deleting data

From the user's point of view all synchronisation happens will happen transparently without using any additional predicates or naming a specific store explicitly, i.e. the user should simply execute standard SPARQL INSERT/DELETE queries. This is achieved by intercepting all changes in the plugin and determining which abstract documents need to be updated.

h2. Querying data

Once a connector has been created it is will be possible to query data from it through SPARQL. For each matching abstract document, the connector returns the document's subject. In its simplest form querying is achieved by using a *SELECT* and providing the Lucene query as the object of the *:query* predicate:

{code}
The result will bind ?entity to the two wines made from grapes that have "cabernet" in their name, namely :Yoyowine and :Franvino.

Note that you must use the field names you chose when you created the connector. It is perfectly valid to have field names identical to the property URIs but then you have to make sure you escape responsible for escaping any special characters according to what Elasticsearch Lucene expects.

First, we get an instance of the requested connector by using the RDF notation "X a Y" (= X rdf:type Y), where X is a variable and Y is a connector. X is will be bound to an instance of this connector. Then, we assign a query to this that instance by using the system predicate *:query*. Finally we request the matching entities through the *:entities* predicate.

It is also possible to provide per query search options by using one or more option predicates. The option predicates are described in further detail details below.



h3. Combining Lucene results with GraphDB data

The bound ?entity can be used in other SPARQL triples in order to build complex queries that fetch additional data from GraphDB. For example, to see the actual grapes in the matching wines as well as the year they were made:

{code}
{code}

The result will look like this:

|| ?entity || ?grape || ?sugar ||
h3. Entity match score

It is possible to access the match score returned by Lucene with the *:score* predicate. As each entity has its own score, the predicate must come at the entity level, for level. For example:

{code}
{code}

The result looks will look like this but the actual score might be different as it depends on the specific Lucene version:

|| ?entity || ?score ||
{code}

It is important to specify the fields we want to facet by using the *facetFields* predicate. Its value must be a simple comma-delimited list of field names. In order to get the faceted results, we have to use the *facets* predicate and as each facet has three components (name, value and count), the *facets* facets predicate will bind binds a blank node, which in turn can be used to access the individual values for each component through the predicates *facetName*, *facetValue*, and *facetCount*.

The resulting bindings will look like in the table below:

|| facetName || facetValue || facetCount ||
We can easily see that there are three wines produced in 2012 and two in 2013. We also see that three of the wines are dry, while two are medium. However, it is not necessarily true that the three wines produced in 2012 are the same as the three dry wines as each facet is computed independently.

{anchor:sorting}
h2. Sorting

It is possible to sort the entities returned by a connector query according to one or more fields. In order to be able to use a certain field for sorting, you have to specify this at the time of creating the connector instance. Sorting is achieved by the *orderBy* predicate the value of which must be a comma-delimited list of fields. Each field may be prefixed with a minus to indicate sorting in descending order. For example:


{code}
PREFIX : <http://www.ontotext.com/connectors/lucene#>
{code}

The result will contain wines produced in 2013, sorted according to their sugar content in a descending order:

|| entity ||
| Yoyowine |

By default, entities are sorted according to their matching score in a descending order.

Note that if you join the entity from the connector query to other triples stored in GraphDB, GraphDB might scramble the order. To remedy this, use ORDER BY from SPARQL.
h2. Limit and offset

Limit and offset are supported on the Elasticsearch Lucene side of the query. This is achieved through the predicates *limit* and *offset*. Consider this example in which we specify an offset of 1 and a limit of 1:

{code}
| Blanquito |

Note that the specific order in which GraphDB returns the results, depends on both how Lucene returns the matches, unless you specified sorting.

h2. Snippet extraction

Snippet extraction is used to extract highlighted snippets of text that match the query. The snippets are accessed through the dedicated predicate *:snippets*. It *:snippets*, which binds a blank node, which node that in in turn provides the actual snippets via the predicates *:snippetField* and *:snippetText*. The predicate :snippets must be attached to the entity, as each entity has a different set of snippets. For example, in a search for Cabernet:


{code}
PREFIX : <http://www.ontotext.com/connectors/lucene#>
| :Franvino | grape | <em>Cabernet</em> Franc |

Note that the actual snippets might be somewhat different as this depends on the specific Elasticsearch Lucene implementation.

It is possible to tweak how the snippets are collected/composed by using the following option predicates:
{code}

As there are three wines made in 2012, the value 3 (of type xdd:long) is will be bound to ?totalHits.

h1. Creation parameters

The creation parameters define how a connector instance is created by the :createConnector predicate. Some parameters There are some required parameters and some - that are optional. All parameters are provided together in a JSON object, where the parameter names are the object keys. Parameter values may be simple JSON values such as a string or a boolean, or they can be lists or objects.

All of the creation parameters can also be set conveniently from the Create Connector user interface in the GraphDB Workbench without any knowledge of JSON.
The compulsory parameters must be present in every connector. They are responsible for the core behaviour.


h3. Types of entities to sync: types (list of URI)

h4. Skipping the analyser: syncAsIs (boolean)

When literal fields are indexed in Lucene, they will be analysed according to the analyser settings. Should you require that a given field is not analysed you may use syncAsIs. False by default.

h2. Optional parameters
h3. Lucene Analyzer

The Lucene Connector supports custom Analyzer implementations. They may be specified via the _analyzer_ parameter the whose value of which must be a fully qualified name of a class that extends org.apache.lucene.analysis.Analyzer. The class must have either a default constructor or a constructor with exactly one parameter of type org.apache.lucene.util.Version. For example, these two classes would be valid implementations:

{code}
h3. Entity filtering: entityFilter (string)

The _entityFilter_ parameter is used to fine-tune the set of entities and/or individual values for the configured fields, based on the field value. Entities and field values will be synchronised to Lucene if, and only if, they pass the filter. The entity filter is similar to a FILTER() inside a SPARQL query but not exactly the same. Each configured field can be referred to in the entity filter by prefixing it with a "?", much like referring to a variable in SPARQL. Several operators are supported:

|| Operator || Meaning || Example ||
{code}

Instead of using the values of ?fieldName, the values of ?evaluatedValue is will be used.

In addition to full URIs within < > the filters support the shorthand form *type*, which stands for <http://www.w3.org/1999/02/22-rdf-syntax-ns#type>.
:city "London" .

# the entity below will not be synchronised because it lacks is lacking the property completely: bound(?city)
:beta
rdf:type :gadget ;
{code}

We could create the following index like this to specify a default value for _city_:

{code}
{code}

Now, if we want to map this data to Lucene in such a way that the property *:taggedWith _x_* is mapped to separate fields *taggedWithPerson* and *taggedWithLocation* according to the type of _x_ (we are not interested in events), we can map :taggedWith twice to different fields and then use an entity filter to get the desired values:

{code}
|| Article URI || Entity mapped? || Value in taggedWithPerson || Value in taggedWithLocation || Explanation ||
| :Article1 | yes | :Einstein | :Berlin | :taggedWith has the values :Einstein, :Berlin and :Cannes-FF. The filter leaves only the correct values in the respective fields. The value :Cannes-FF is ignored as it does not match the filter. |
| :Article2 | yes | | :Berlin | :taggedWith has the value :Berlin. After the filter is applied, only taggedWithLocation is populated. |
| :Article3 | yes | :Mozart | | :taggedWith has the value :Mozart. After the filter is applied, only taggedWithPerson is populated |
| :Article4 | yes | :Mozart | :Berlin | :taggedWith has the values :Berlin and :Mozart. The filter leaves only the correct values in the respective fields. |
| :Article5 | yes | | | :taggedWith has no values. The filter is not relevant. |
| :Article6 | yes | | | :taggedWith has the value :Cannes-FF. The filter removes it as it does not match. |

This can be checked by issuing a faceted search for taggedWithLocation and taggedWithPerson:

{code}
{code}

If the filter was applied, you should get only :Berlin for taggedWithLocation and only :Einstein and :Mozart for taggedWithPerson:

|| ?facetName || ?facetValue || ?facetCount ||
}


{plantuml}



h1. Caveats

Even though SPARQL per se is not sensitive to the order of triple patterns, the connectors expect to receive certain predicates before others so that queries can be executed properly. In particular, predicates that specify the query or query options need to come before any predicates that fetch results.

The diagram in [#Overview of connector predicates] provides a quick overview of the predicates.


h1. Migrating from Lucene4 plugin

You can easily migrate your existing [lucene4 plugin|https://confluence.ontotext.com/display/EM/Lucene4+OWLIM+Plug-in] setup to the new connectors interface.

h3. Create index queries

We provide an automated migration tool for your create index queries. The tool is distributed with GraphDB 6.0 onward and can be found in the tools subdirectory. Here is how to use it:

{code}
java -jar migration.jar --file <input-file> <output-file>
{code}
where *input-file* is your old sparql file and *output-file* is the new sparql file

you can find possible options with
{code}
java -jar migration.jar --help
{code}

h3. Select queries using the index
We changed the syntax for the search queries to be able to match our needs for new features and better design. Here is an example query using the lucene4 plugin:

{code}
PREFIX luc4:<http://www.ontotext.com/owlim/lucene4#>
SELECT ?c ?snippet WHERE {
?c rdf:type <http://data.ontotext.com/ontologies/ontology1/Type1> .

?c luc4:content ("gold" "limit=10;snippet.size=200") .
?c luc4:snippet ?snippet .
?c luc4:score ?score .
}
{code}

and here is it's connectors variant:

{code}
PREFIX conn:<http://www.ontotext.com/connectors/lucene#>
PREFIX inst:<http://www.ontotext.com/connectors/lucene/instance#>

SELECT ?c ?snippet WHERE {
[] a inst:content ;
conn:query "gold" ;
conn:limit "10" ;
conn:snippetSize "200" ;
conn:entities ?entity

?entity conn:snippets ?s .
?s conn:snippetText ?snippet .
}
{code}

note the following changes:

* We are using special predicates for everything - no more key value options in a string
* The query is actually an instance of the index
* snippets belong to the entity
* snippets are now first class objects - you can also get the field of the match
* indexes are now an instance of another namespace. This allows you to create indexes with the name "entities" for example.

Look at [#Overview of connector predicates] for more info on the new syntax and how everything is linked together.