GraphSearch Plugin API Documentation

Abstract

This section introduces GraphSearch Plugin APIs.

Interface

GraphSearch works with three different types of search and storage backends: RDF database, Solr and Elasticsearch. Depending on the backend plugins need to implement their behaviors differently. Accordingly, a custom plugin has to implement one of the following interfaces for the target backend:

biz.poolparty.graphsearch.plugins.SparqlRecommendationPlugin
biz.poolparty.graphsearch.plugins.EsRecommendationPlugin
biz.poolparty.graphsearch.plugins.SolrRecommendationPlugin

They all define one abstract method

getRecommendedDocuments(DocumentRecommendationRequest request, SearchSpaceProvider searchSpaceProvider)

with different types of return values due to differences in data structure. This is the key method a plugin needs to implement since it handles recommendation requests initiated from the client side.

Additionally, all three interfaces inherits a super interface

biz.poolparty.graphsearch.plugins.GenericPlugin

which defines the following 4 abstract methods

boolean canHandle(String documentId, SearchSpaceProvider searchSpaceProvider);
String getName();
int getOrder();
String getSearchSpaceId();

Altogether they control the activation of the plugin based on three dimensions seed resource, priority and search space.

A custom plugin has to implement the aforementioned one interface and five abstract methods.

Abstract Method

getRecommendedDocuments

The core abstract method getRecommendedDocuments is the entrypoint of a plugin. When a client initiates a request, GraphSearch will dispatch the request and the search space configurations to this method as arguments. The custom recommendation algorithm of the plugin needs to be invoked by this method to process the request. Finally, the results need to be returned as return value of the method, which will be further formulated by GraphSearch as JSON response to the client.

The method expects three types of return values depending on the interface, i.e., the target backend of the plugin. The relationship is explained in the following table:

class of return value	interface	description
`java.util.List<biz.poolparty.graphsearch.web.ProposalResult>`	`SparqlRecommendationPlugin`	`ProposalResult` is a class defined in GraphSearch wrapping the URI of a recommended resource. In the case that an RDF database is used as search backend, the plugin should suggest a list of resource URIs as recommendation result. The reference to the connection object of the RDF repository is part of the method argument, which can be used to execute custom SPARQL queries for recommendation. More information about this class is explained in the following chapter about data structures.
`org.elasticsearch.search.SearchHits`	`EsRecommendationPlugin`	This is the class of an Elasticsearch search response. More information about this class can be found at Elasticsearch Java API documentation. In the case that Elasticsearch is used as search backend, the plugin is expected to recommend documents from the same index. From the method argument the plugin can retrieve the connection object to the Elasticsearch server and formulate customized search requests. The result documents are naturally encapsulated into a `SearchHits` object.
`org.apache.solr.client.solrj.response.QueryResponse`	`SolrRecommendationPlugin`	This is the class of a Solr search response. More information about this class can be found at Solr Java API documentation. Similar to the former case, when Solr is used as search backend, the plugin can retrieve the connection details to the Solr server and formulate a search request to recommend other documents in the same search index. The results are wrapped into a Solr `QueryResponse` object.

class of return value

interface

description

java.util.List<biz.poolparty.graphsearch.web.ProposalResult>

SparqlRecommendationPlugin

ProposalResult is a class defined in GraphSearch wrapping the URI of a recommended resource. In the case that an RDF database is used as search backend, the plugin should suggest a list of resource URIs as recommendation result. The reference to the connection object of the RDF repository is part of the method argument, which can be used to execute custom SPARQL queries for recommendation. More information about this class is explained in the following chapter about data structures.

org.elasticsearch.search.SearchHits

EsRecommendationPlugin

This is the class of an Elasticsearch search response. More information about this class can be found at Elasticsearch Java API documentation.

In the case that Elasticsearch is used as search backend, the plugin is expected to recommend documents from the same index. From the method argument the plugin can retrieve the connection object to the Elasticsearch server and formulate customized search requests. The result documents are naturally encapsulated into a SearchHits object.

org.apache.solr.client.solrj.response.QueryResponse

SolrRecommendationPlugin

This is the class of a Solr search response. More information about this class can be found at Solr Java API documentation.

Similar to the former case, when Solr is used as search backend, the plugin can retrieve the connection details to the Solr server and formulate a search request to recommend other documents in the same search index. The results are wrapped into a Solr QueryResponse object.

getName

The return value of this method will become the name of a plugin. This name will be used not only for the display caption of the plugin in the UI, but also an identifier uniquely defining the plugin. When a client issues a request to the plugin API endpoint, the request must include such a plugin name to specify the plugin which should handle the request.

getOrder

The return value of this method indicates the order or priority of a plugin in the cases that multiple plugins are available. The higher the value, the higher the priority of the plugin. The plugin with the highest order will be used as the default plugin for a search space in GraphSearch UI and recommendation API requests when the plugin is not specified.

getSearchSpaceId

This method implements a restriction that a plugin is enabled only for a specific search space identified by the search space ID as return value. If the plugin should be available to

canHandle

The return value of this method decides if a plugin can provide recommendations based on the reference resource and configuration of the search space provided as input arguments of the method. Typically, the implementation can always return true so that recommendation is always executed, regardless of whether the operation is meaningful or not. Certainly, depending on the actual requirements, more and finer grained conditions can be implemented in this method so that the recommendation logic proceeds only when reference resources and search spaces have certain characteristics.

Note

Please make sure the search space ID is taken care of by the plugin for security and privacy considerations. The plugin should only return data from the search space a request originates. Otherwise there is a risk that the response contains data from other search spaces or even private search spaces.

Meanwhile, GraphSearch relies on the aforementioned methods to decide if a plugin should be enabled for a given resource in a search space. For example, the following code snippet in GraphSearch uses the following conditions to select the list of qualified plugins:

if (recommendationPlugin.canHandle(documentId, searchSpaceProvider) 
  && (recommendationPlugin.getSearchSpaceId() == null 
    || searchSpaceId.equals(recommendationPlugin.getSearchSpaceId())))

Data Structure

The following classes encapsulate input and output data of the plugin API. They are all implemented as standard beans with getter and setter methods.

DocumentRecommendationRequest

Argument request of method getRecommendedDocuments is an instance of class biz.poolparty.graphsearch.web.recommendation.DocumentRecommendationRequest. It packages the parameters of HTTP requests from the client, detailed as follows:

String id: ID or URI of the reference resource
String text: description of the reference resource
String searchSpaceId: ID of the search space where the request originates from
Object jsonObject: this is a placeholder for 8.0 and improvements around it will be done in the future release. The plugin will be able to to accept additional custom request parameters from the client side which extends the application scope of the plugin. For the time being this field has no use.
List<String> documentFacets: ID of the facets GraphSearch should create from the recommendation results. This feature only supports Solr and Elasticsearch backend.
List<ExpandConcept> conceptList: User defined reference concepts and weights associated with the reference resource. This is up to the plugin to decide how to best make use of such information in the recommendation algorithm. The default recommendation plugin in GraphSearch creates results sorted by their relevance scores, which come from aggregations of weighted matchings against the reference concepts. This feature only supports Solr and Elasticsearch backend.
- class ExpandConcept has the following fields
  - String concept: URI of the concept
  - Double weight: weight of the concept in the recommendation

SearchSpaceProvider

Argument searchSpaceProvider of method getRecommendedDocuments and canHandle is an instance of class biz.poolparty.graphsearch.plugins.SearchSpaceProvider<T>. It packages some configuration of the search space relevant to the recommendation process.

T searchServerDatabase: interface to the storage and search backend. Depending on the type of backend configured for a search space, the object can be an instance of
- org.apache.solr.client.solr.SolrClient for Solr
- org.elasticsearch.client.Client for Elasticsearch
- org.eclipse.rdf4j.repository.Repository for RDF databases
List<String> contexts: URIs of RDF graphs used in the search space, only valid for search spaces with RDF database backends
String local: locale of the search space
List<String> thesaurusFacetIds: IDs of thesaurus projects used for faceting in the search space

ProposalResult

A list of instances of class ProposalResult is the expected return value of method getRecommendedDocuments for plugins implementing interface SparqlRecommendationPlugin, i.e., plugins for RDF database backends. This class describes the structure of a recommendation result. Since the search data is RDF in this case, the required information is rather minimal, only the URI of the suggested resource and a score to rank all results.

IRI id: URI of the suggested resource
BigDecimal score: relevancy score of the suggestion resource with respect to the recommendation

In this section: