This section introduces GraphSearch Plugin APIs.
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:
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
which defines the following 4 abstract methods
boolean canHandle(String documentId, SearchSpaceProvider searchSpaceProvider);
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.
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|
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
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
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.
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.
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
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.
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:
The following classes encapsulate input and output data of the plugin API. They are all implemented as standard beans with getter and setter methods.
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
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 ExpandConcepthas the following fields
String concept: URI of the concept
Double weight: weight of the concept in the recommendation
searchSpaceProvider of method
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.eclipse.rdf4j.repository.Repositoryfor 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
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.
id: URI of the suggested resource
score: relevancy score of the suggestion resource with respect to the recommendation