Allow to configure SparqlDataProvider.lookup() via lookupQuery and filterInnerPrelude settings

CHANGELOG.md

@@ -22,6 +22,7 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/) and this p
 - Expose `useAsync()` utility hook to simplify data loading from via a single Promise-returning task.
 - Provide `onlySelected` property to link templates the same way as for element templates.
 - Allow to configure whether `ClassTree` and `SearchSectionElementTypes` tree items should be draggable.
+- Allow to configure `SparqlDataProvider.lookup()` via `lookupQuery` and `filterInnerPrelude` settings.
 
 #### 🔧 Maintenance
 - Preparations to extract generic scrollable paper component `Paper` from diagram-specific state and logic:

src/data/dataProvider.ts

@@ -240,15 +240,15 @@ export interface DataProviderLookupItem {
      */
     readonly element: ElementModel;
     /**
-     * Link types by which result `element` is linked from the lookup target
+     * Link types for connections in the form: `refElementId` <-- `element`
      * ({@link DataProviderLookupParams.refElementId refElementId}).
      *
      * Only applicable if {@link DataProviderLookupParams.refElementId refElementId}
      * is specified in {@link DataProvider.lookup}.
      */
     readonly inLinks: ReadonlySet<LinkTypeIri>;
     /**
-     * Link types by which result `element` is linked to the lookup target
+     * Link types for connections in the form: `refElementId` --> `element`
      * ({@link DataProviderLookupParams.refElementId refElementId}).
      *
      * Only applicable if {@link DataProviderLookupParams.refElementId refElementId}

src/data/sparql/sparqlDataProvider.ts

@@ -766,71 +766,71 @@ export class SparqlDataProvider implements DataProvider {
         let outerProjection = '?inst ?class ?label';
         let innerProjection = '?inst';
 
-        let refQueryPart = '';
-        let refQueryTypes = '';
+        let filterByRefElementLink = '';
+        let queryTypes = '';
         if (params.refElementId) {
             outerProjection += ' ?link ?direction';
             innerProjection += ' ?link ?direction';
-            refQueryPart = this.createRefQueryPart({
+            filterByRefElementLink = this.createRefQueryPart({
                 elementId: params.refElementId,
                 linkId: params.refElementLinkId,
                 direction: params.linkDirection,
             });
 
             if (this.settings.linkConfigurations.length > 0) {
                 outerProjection += ' ?classAll';
-                refQueryTypes = this.settings.filterTypePattern.replace(/[?$]class\b/g, '?classAll');
+                queryTypes = this.settings.filterTypePattern.replace(/[?$]class\b/g, '?classAll');
             }
         }
 
-        let elementTypePart = '';
+        let filterByType = '';
         if (params.elementTypeId) {
             const elementTypeIri = escapeIri(params.elementTypeId);
-            elementTypePart = this.settings.filterTypePattern.replace(/[?$]class\b/g, elementTypeIri);
+            filterByType = this.settings.filterTypePattern.replace(/[?$]class\b/g, elementTypeIri);
         }
 
         const {
-            defaultPrefix, dataLabelProperty, filterOnlyLanguages, filterElementInfoPattern, fullTextSearch,
+            defaultPrefix, dataLabelProperty, lookupQuery, filterOnlyLanguages,
+            filterElementInfoPattern, fullTextSearch,
         } = this.settings;
 
-        const elementInfoPart = resolveTemplate(filterElementInfoPattern, {
+        const queryElementInfo = resolveTemplate(filterElementInfoPattern, {
             dataLabelProperty,
             labelLanguageFilter: formatLanguageFilter('?label', filterOnlyLanguages),
         });
 
-        let textSearchPart = '';
+        let filterByText = '';
+        let orderBy = '';
         if (params.text) {
             innerProjection += ' ?score';
             if (this.settings.fullTextSearch.extractLabel) {
-                textSearchPart += sparqlExtractLabel('?inst', '?extractedLabel');
+                filterByText += sparqlExtractLabel('?inst', '?extractedLabel');
+            }
+            filterByText = resolveTemplate(fullTextSearch.queryPattern, {text: params.text, dataLabelProperty});
+            if (filterByText) {
+                orderBy = 'ORDER BY DESC(?score)';
             }
-            textSearchPart = resolveTemplate(fullTextSearch.queryPattern, {text: params.text, dataLabelProperty});
         }
 
         let limitPart = '';
         if (typeof params.limit === 'number') {
             limitPart = `LIMIT ${params.limit}`;
         }
 
-        return `${defaultPrefix}
-            ${fullTextSearch.prefix}
-
-        SELECT ${outerProjection}
-        WHERE {
-            {
-                SELECT DISTINCT ${innerProjection} WHERE {
-                    ${elementTypePart}
-                    ${refQueryPart}
-                    ${textSearchPart}
-                    ${this.settings.filterAdditionalRestriction}
-                }
-                ${textSearchPart ? 'ORDER BY DESC(?score)' : ''}
-                ${limitPart}
-            }
-            ${refQueryTypes}
-            ${elementInfoPart}
-        } ${textSearchPart ? 'ORDER BY DESC(?score)' : ''}
-        `;
+        const completePrefix = defaultPrefix + '\n' + fullTextSearch.prefix + '\n';
+        return completePrefix + resolveTemplate(lookupQuery, {
+            innerProjection,
+            outerProjection,
+            filterInnerPrelude: this.settings.filterInnerPrelude,
+            filterByType,
+            filterByRefElementLink,
+            filterByText,
+            filterAdditionalRestriction: this.settings.filterAdditionalRestriction,
+            orderBy,
+            limit: limitPart,
+            queryTypes,
+            queryElementInfo,
+        });
     }
 
     /**

src/data/sparql/sparqlDataProviderSettings.ts

@@ -189,6 +189,46 @@ export interface SparqlDataProviderSettings {
      */
     linkTypesStatisticsQuery: string;
 
+    /**
+     * SELECT query to lookup entities with {@link DataProvider.lookup()}.
+     *
+     * Parametrized variables:
+     *   - `${outerProjection}`
+     *   - `${innerProjection}`
+     *   - `${filterInnerPrelude}` from {@link filterInnerPrelude}
+     *   - `${filterByType}` from {@link filterTypePattern}
+     *     (when {@link DataProviderLookupParams.elementTypeId} is provided)
+     *   - `${filterByRefElementLink}` from {@link filterRefElementLinkPattern}
+     *     (when {@link DataProviderLookupParams.refElementId} is provided)
+     *   - `${filterByText}` from {@link fullTextSearch}
+     *     (when {@link DataProviderLookupParams.text} is provided)
+     *   - `${filterAdditionalRestriction}` from {@link filterAdditionalRestriction}
+     *   - `${orderBy}` (when {@link DataProviderLookupParams.text} is provided)
+     *   - `${limit}` (when {@link DataProviderLookupParams.limit} is provided)
+     *   - `${queryTypes}` from {@link filterTypePattern}
+     *     (when {@link DataProviderLookupParams.refElementId} is provided and
+     *     {@link linkConfigurations} is non-empty)
+     *   - `${queryElementInfo}` from {@link filterElementInfoPattern}
+     *
+     * Expected bindings:
+     *   - `?inst` element IRI
+     *   - `?class` element type
+     *   - `?label` element label
+     *   - `?link` connected via link type
+     *     (when {@link DataProviderLookupParams.refElementId} is provided)
+     *   - `?direction` connected via link direction (`"in"` or `"out"`)
+     *     (when {@link DataProviderLookupParams.refElementId} is provided)
+     *   - `?score` element lookup score (higher ordered first)
+     *     (for order only; when {@link DataProviderLookupParams.text} is provided)
+     */
+    lookupQuery: string;
+
+    /**
+     * SPARQL query pattern to prepend before inner lookup query
+     * e.g. to specify query evaluation hints.
+     */
+    filterInnerPrelude?: string;
+
     /**
      * SPARQL query pattern to restrict lookup results in case when
      * {@link DataProviderLookupParams.refElementLinkId} is not specified.
@@ -212,6 +252,11 @@ export interface SparqlDataProviderSettings {
      * SPARQL pattern which describes how to fetch elements info similar to `elementInfoQuery`
      * but within the lookup query.
      *
+     * Expected bindings:
+     *   - `?inst` element IRI
+     *   - `?class` element type
+     *   - `?label` element label
+     *
      * Parametrized variables:
      *   - `${dataLabelProperty}` `dataLabelProperty` property from the settings
      *   - `${labelLanguageFilter}` label filter based on `filterOnlyLanguages`
@@ -441,6 +486,22 @@ export const RdfSettings: SparqlDataProviderSettings = {
 
     linkTypesOfQuery: '',
     linkTypesStatisticsQuery: '',
+
+    lookupQuery:
+`SELECT \${outerProjection} WHERE {
+    \${filterInnerPrelude}
+    {
+        SELECT DISTINCT \${innerProjection} WHERE {
+            \${filterByType}
+            \${filterByRefElementLink}
+            \${filterByText}
+            \${filterAdditionalRestriction}
+        } \${orderBy} \${limit}
+    }
+    \${queryTypes}
+    \${queryElementInfo}
+} \${orderBy}`,
+
     filterRefElementLinkPattern: '',
     filterTypePattern: '',
     filterAdditionalRestriction: '',