@undefineds.co/xpod 0.3.58 → 0.3.62

package/dist/storage/rdf/RdfSearchSourceFilter.d.ts

@@ -0,0 +1,10 @@
+export interface RdfSearchSourceFilter {
+    source?: string;
+    sourcePrefix?: string;
+    localPathPrefix?: string;
+    allowedSources?: string[];
+    deniedSources?: string[];
+    deniedSourcePrefixes?: string[];
+}
+export declare function appendRdfSearchSourceFilters(filter: RdfSearchSourceFilter, conditions: string[], params: unknown[], sourceColumn?: string, localPathColumn?: string): void;
+export declare function appendPgRdfSearchSourceFilters(filter: RdfSearchSourceFilter, conditions: string[], params: unknown[], sourceColumn?: string, localPathColumn?: string): void;

package/dist/storage/rdf/RdfSearchSourceFilter.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.appendRdfSearchSourceFilters = appendRdfSearchSourceFilters;
+exports.appendPgRdfSearchSourceFilters = appendPgRdfSearchSourceFilters;
+function appendRdfSearchSourceFilters(filter, conditions, params, sourceColumn = 'source.source', localPathColumn = 'source.local_path') {
+    if (filter.source) {
+        conditions.push(`${sourceColumn} = ?`);
+        params.push(filter.source);
+    }
+    if (filter.sourcePrefix) {
+        conditions.push(`${sourceColumn} >= ? AND ${sourceColumn} < ?`);
+        params.push(filter.sourcePrefix, `${filter.sourcePrefix}\uffff`);
+    }
+    if (filter.localPathPrefix) {
+        conditions.push(`${localPathColumn} >= ? AND ${localPathColumn} < ?`);
+        params.push(filter.localPathPrefix, `${filter.localPathPrefix}\uffff`);
+    }
+    const allowedSources = uniqueStrings(filter.allowedSources);
+    if (allowedSources) {
+        if (allowedSources.length === 0) {
+            conditions.push('1 = 0');
+        }
+        else {
+            conditions.push(`${sourceColumn} IN (${allowedSources.map(() => '?').join(', ')})`);
+            params.push(...allowedSources);
+        }
+    }
+    const deniedSources = uniqueStrings(filter.deniedSources);
+    if (deniedSources && deniedSources.length > 0) {
+        conditions.push(`${sourceColumn} NOT IN (${deniedSources.map(() => '?').join(', ')})`);
+        params.push(...deniedSources);
+    }
+    const deniedPrefixes = uniqueStrings(filter.deniedSourcePrefixes);
+    for (const prefix of deniedPrefixes ?? []) {
+        conditions.push(`NOT (${sourceColumn} >= ? AND ${sourceColumn} < ?)`);
+        params.push(prefix, `${prefix}\uffff`);
+    }
+}
+function appendPgRdfSearchSourceFilters(filter, conditions, params, sourceColumn = 'source.source', localPathColumn = 'source.local_path') {
+    const placeholder = (value) => {
+        params.push(value);
+        return `$${params.length}`;
+    };
+    if (filter.source) {
+        conditions.push(`${sourceColumn} = ${placeholder(filter.source)}`);
+    }
+    if (filter.sourcePrefix) {
+        appendPgPrefixFilter(conditions, placeholder, sourceColumn, filter.sourcePrefix);
+    }
+    if (filter.localPathPrefix) {
+        appendPgPrefixFilter(conditions, placeholder, localPathColumn, filter.localPathPrefix);
+    }
+    const allowedSources = uniqueStrings(filter.allowedSources);
+    if (allowedSources) {
+        if (allowedSources.length === 0) {
+            conditions.push('1 = 0');
+        }
+        else {
+            conditions.push(`${sourceColumn} = ANY(${placeholder(allowedSources)}::text[])`);
+        }
+    }
+    const deniedSources = uniqueStrings(filter.deniedSources);
+    if (deniedSources && deniedSources.length > 0) {
+        conditions.push(`NOT (${sourceColumn} = ANY(${placeholder(deniedSources)}::text[]))`);
+    }
+    const deniedPrefixes = uniqueStrings(filter.deniedSourcePrefixes);
+    for (const prefix of deniedPrefixes ?? []) {
+        conditions.push(`NOT (${pgPrefixCondition(sourceColumn, placeholder(prefix), placeholder(`${prefix}\uffff`), placeholder(prefix))})`);
+    }
+}
+function appendPgPrefixFilter(conditions, placeholder, column, prefix) {
+    conditions.push(pgPrefixCondition(column, placeholder(prefix), placeholder(`${prefix}\uffff`), placeholder(prefix)));
+}
+function pgPrefixCondition(column, lower, upper, exact) {
+    return `(${column} COLLATE "C") >= (${lower} COLLATE "C") AND (${column} COLLATE "C") < (${upper} COLLATE "C") AND starts_with(${column}, ${exact})`;
+}
+function uniqueStrings(values) {
+    if (!values) {
+        return undefined;
+    }
+    return [...new Set(values.filter((value) => value.length > 0))].sort();
+}
+//# sourceMappingURL=RdfSearchSourceFilter.js.map

package/dist/storage/rdf/RdfSearchSourceFilter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RdfSearchSourceFilter.js","sourceRoot":"","sources":["../../../src/storage/rdf/RdfSearchSourceFilter.ts"],"names":[],"mappings":"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","sourcesContent":["export interface RdfSearchSourceFilter {\n  source?: string;\n  sourcePrefix?: string;\n  localPathPrefix?: string;\n  allowedSources?: string[];\n  deniedSources?: string[];\n  deniedSourcePrefixes?: string[];\n}\n\nexport function appendRdfSearchSourceFilters(\n  filter: RdfSearchSourceFilter,\n  conditions: string[],\n  params: unknown[],\n  sourceColumn = 'source.source',\n  localPathColumn = 'source.local_path',\n): void {\n  if (filter.source) {\n    conditions.push(`${sourceColumn} = ?`);\n    params.push(filter.source);\n  }\n  if (filter.sourcePrefix) {\n    conditions.push(`${sourceColumn} >= ? AND ${sourceColumn} < ?`);\n    params.push(filter.sourcePrefix, `${filter.sourcePrefix}\\uffff`);\n  }\n  if (filter.localPathPrefix) {\n    conditions.push(`${localPathColumn} >= ? AND ${localPathColumn} < ?`);\n    params.push(filter.localPathPrefix, `${filter.localPathPrefix}\\uffff`);\n  }\n\n  const allowedSources = uniqueStrings(filter.allowedSources);\n  if (allowedSources) {\n    if (allowedSources.length === 0) {\n      conditions.push('1 = 0');\n    } else {\n      conditions.push(`${sourceColumn} IN (${allowedSources.map(() => '?').join(', ')})`);\n      params.push(...allowedSources);\n    }\n  }\n\n  const deniedSources = uniqueStrings(filter.deniedSources);\n  if (deniedSources && deniedSources.length > 0) {\n    conditions.push(`${sourceColumn} NOT IN (${deniedSources.map(() => '?').join(', ')})`);\n    params.push(...deniedSources);\n  }\n\n  const deniedPrefixes = uniqueStrings(filter.deniedSourcePrefixes);\n  for (const prefix of deniedPrefixes ?? []) {\n    conditions.push(`NOT (${sourceColumn} >= ? AND ${sourceColumn} < ?)`);\n    params.push(prefix, `${prefix}\\uffff`);\n  }\n}\n\nexport function appendPgRdfSearchSourceFilters(\n  filter: RdfSearchSourceFilter,\n  conditions: string[],\n  params: unknown[],\n  sourceColumn = 'source.source',\n  localPathColumn = 'source.local_path',\n): void {\n  const placeholder = (value: unknown): string => {\n    params.push(value);\n    return `$${params.length}`;\n  };\n\n  if (filter.source) {\n    conditions.push(`${sourceColumn} = ${placeholder(filter.source)}`);\n  }\n  if (filter.sourcePrefix) {\n    appendPgPrefixFilter(conditions, placeholder, sourceColumn, filter.sourcePrefix);\n  }\n  if (filter.localPathPrefix) {\n    appendPgPrefixFilter(conditions, placeholder, localPathColumn, filter.localPathPrefix);\n  }\n\n  const allowedSources = uniqueStrings(filter.allowedSources);\n  if (allowedSources) {\n    if (allowedSources.length === 0) {\n      conditions.push('1 = 0');\n    } else {\n      conditions.push(`${sourceColumn} = ANY(${placeholder(allowedSources)}::text[])`);\n    }\n  }\n\n  const deniedSources = uniqueStrings(filter.deniedSources);\n  if (deniedSources && deniedSources.length > 0) {\n    conditions.push(`NOT (${sourceColumn} = ANY(${placeholder(deniedSources)}::text[]))`);\n  }\n\n  const deniedPrefixes = uniqueStrings(filter.deniedSourcePrefixes);\n  for (const prefix of deniedPrefixes ?? []) {\n    conditions.push(`NOT (${pgPrefixCondition(sourceColumn, placeholder(prefix), placeholder(`${prefix}\\uffff`), placeholder(prefix))})`);\n  }\n}\n\nfunction appendPgPrefixFilter(\n  conditions: string[],\n  placeholder: (value: unknown) => string,\n  column: string,\n  prefix: string,\n): void {\n  conditions.push(pgPrefixCondition(\n    column,\n    placeholder(prefix),\n    placeholder(`${prefix}\\uffff`),\n    placeholder(prefix),\n  ));\n}\n\nfunction pgPrefixCondition(column: string, lower: string, upper: string, exact: string): string {\n  return `(${column} COLLATE \"C\") >= (${lower} COLLATE \"C\") AND (${column} COLLATE \"C\") < (${upper} COLLATE \"C\") AND starts_with(${column}, ${exact})`;\n}\n\nfunction uniqueStrings(values: string[] | undefined): string[] | undefined {\n  if (!values) {\n    return undefined;\n  }\n  return [...new Set(values.filter((value) => value.length > 0))].sort();\n}\n"]}

package/dist/storage/rdf/RdfSparqlAdapter.d.ts

@@ -48,13 +48,38 @@ export interface RdfSparqlUpdateDelta {
 export interface RdfSparqlUpdateCompileOptions {
     defaultGraph?: string | NamedNode;
 }
+export interface UnsupportedSparqlQueryErrorOptions {
+    code?: string;
+    capability?: string;
+    hint?: string;
+    correction?: SparqlCorrection;
+}
+export type SparqlCorrectionAction = 'rewrite_query' | 'constrain_graph_scope' | 'materialize_intermediate' | 'route_external_executor' | 'use_write_api';
+export type SparqlCorrectionTarget = 'embedded_rdf_engine' | 'trusted_client_or_federated_engine' | 'pod_write_api';
+export interface SparqlCorrection {
+    capability: string;
+    primaryAction: SparqlCorrectionAction;
+    availableActions: SparqlCorrectionAction[];
+    target: SparqlCorrectionTarget;
+    message: string;
+}
 export declare class UnsupportedSparqlQueryError extends Error {
-    constructor(message: string);
+    readonly code: string;
+    readonly capability: string;
+    readonly hint: string;
+    readonly correction: SparqlCorrection;
+    constructor(message: string, options?: UnsupportedSparqlQueryErrorOptions);
 }
 export declare class DisabledSparqlFeatureError extends Error {
     constructor(message: string);
 }
+export declare class NativeSparqlExecutionError extends Error {
+    readonly code = "rdf.sparql.native_execution_error";
+    constructor(message: string);
+}
+export declare function sparqlCorrectionForCapability(capability: string): SparqlCorrection;
 export declare class RdfSparqlAdapter {
+    assertServerOwnedNativeQuery(query: string, basePath: string): void;
     compile(query: string | SparqlQuery, basePath: string): RdfSparqlCompileResult;
     compileUpdateDelta(query: string | SparqlQuery, basePath: string, options?: RdfSparqlUpdateCompileOptions): RdfSparqlUpdateDelta;
     private compileDeleteWhere;
@@ -135,6 +160,7 @@ export declare class RdfSparqlAdapter {
     private addSolutionBind;
     private compileOrderExpression;
     private compileFilter;
+    private compileDisjunctiveFilterBranches;
     private compileOrFilter;
     private flattenOrExpressions;
     private filterValueKey;

package/dist/storage/rdf/RdfSparqlAdapter.js

@@ -1,15 +1,39 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RdfSparqlAdapter = exports.DisabledSparqlFeatureError = exports.UnsupportedSparqlQueryError = void 0;
+exports.RdfSparqlAdapter = exports.NativeSparqlExecutionError = exports.DisabledSparqlFeatureError = exports.UnsupportedSparqlQueryError = void 0;
+exports.sparqlCorrectionForCapability = sparqlCorrectionForCapability;
 const n3_1 = require("n3");
 const sparqljs_1 = require("sparqljs");
 const RdfQueryExecutor_1 = require("./RdfQueryExecutor");
 const PATH_JOIN_VARIABLE_PREFIX = '__rdf_path';
 const XPATH_FUNCTION_NS = 'http://www.w3.org/2005/xpath-functions#';
+function assertNoExternalService(value) {
+    if (Array.isArray(value)) {
+        for (const item of value) {
+            assertNoExternalService(item);
+        }
+        return;
+    }
+    if (value === null || typeof value !== 'object') {
+        return;
+    }
+    const record = value;
+    if (record.type === 'service') {
+        throw new DisabledSparqlFeatureError('SPARQL SERVICE federation is disabled for server-owned Pod queries');
+    }
+    for (const child of Object.values(record)) {
+        assertNoExternalService(child);
+    }
+}
 class UnsupportedSparqlQueryError extends Error {
-    constructor(message) {
-        super(message);
+    constructor(message, options = {}) {
+        const normalizedMessage = normalizeUnsupportedSparqlMessage(message);
+        super(normalizedMessage);
         this.name = 'UnsupportedSparqlQueryError';
+        this.code = options.code ?? 'rdf.sparql.unsupported_query_shape';
+        this.capability = options.capability ?? inferUnsupportedSparqlCapability(normalizedMessage);
+        this.hint = options.hint ?? unsupportedSparqlHint(this.capability);
+        this.correction = options.correction ?? sparqlCorrectionForCapability(this.capability);
     }
 }
 exports.UnsupportedSparqlQueryError = UnsupportedSparqlQueryError;
@@ -20,7 +44,213 @@ class DisabledSparqlFeatureError extends Error {
     }
 }
 exports.DisabledSparqlFeatureError = DisabledSparqlFeatureError;
+class NativeSparqlExecutionError extends Error {
+    constructor(message) {
+        super(message.startsWith('Native SPARQL engine failed:') ? message : `Native SPARQL engine failed: ${message}`);
+        this.code = 'rdf.sparql.native_execution_error';
+        this.name = 'NativeSparqlExecutionError';
+    }
+}
+exports.NativeSparqlExecutionError = NativeSparqlExecutionError;
+function normalizeUnsupportedSparqlMessage(message) {
+    const noFallbackMatch = /^No compatibility SPARQL fallback configured for ([^:]+):\s*(.+)$/i.exec(message);
+    if (noFallbackMatch) {
+        return `Embedded SPARQL engine cannot execute ${noFallbackMatch[1]}: ${normalizeEmbeddedUnsupportedReason(noFallbackMatch[2])}`;
+    }
+    return normalizeEmbeddedUnsupportedReason(message);
+}
+function normalizeEmbeddedUnsupportedReason(reason) {
+    let normalized = reason
+        .replace(/\s+fallback to compatibility engine\b/gi, ' is not supported by the embedded RDF engine')
+        .replace(/\bis handled by the compatibility engine\b/gi, 'is not supported by the embedded RDF engine')
+        .replace(/\bcompatibility fallback\b/gi, 'embedded RDF engine');
+    if (/^unsupported shape$/i.test(normalized.trim())) {
+        normalized = 'Query shape is not supported by the embedded RDF engine';
+    }
+    return normalized;
+}
+function inferUnsupportedSparqlCapability(message) {
+    const normalized = message.toLowerCase();
+    if (normalized.includes('subquer')) {
+        return 'sparql.query.subquery';
+    }
+    if (normalized.includes('rdf-star')) {
+        return 'sparql.query.rdf_star';
+    }
+    if (normalized.includes('property path')) {
+        return 'sparql.query.property_path';
+    }
+    if (normalized.includes('default graph')) {
+        return 'sparql.graph.default';
+    }
+    if (normalized.includes('graph variable')) {
+        return 'sparql.graph.variable';
+    }
+    if (normalized.includes('graph outside') || normalized.includes('dataset scope')) {
+        return 'sparql.graph.scope';
+    }
+    if (normalized.includes('update')) {
+        return 'sparql.update.embedded_delta';
+    }
+    if (normalized.includes('construct')) {
+        return 'sparql.query.construct';
+    }
+    if (normalized.includes('describe')) {
+        return 'sparql.query.describe';
+    }
+    if (normalized.includes('wildcard')) {
+        return 'sparql.query.wildcard_projection';
+    }
+    if (normalized.includes('having')) {
+        return 'sparql.query.having';
+    }
+    if (normalized.includes('group by') || normalized.includes('grouped')) {
+        return 'sparql.query.group';
+    }
+    if (normalized.includes('aggregate')) {
+        return 'sparql.query.aggregate';
+    }
+    if (normalized.includes('values')) {
+        return 'sparql.query.values';
+    }
+    if (/\bbind\b/.test(normalized)) {
+        return 'sparql.query.bind';
+    }
+    if (normalized.includes('minus')) {
+        return 'sparql.query.minus';
+    }
+    if (normalized.includes('exists')) {
+        return 'sparql.query.exists';
+    }
+    if (normalized.includes('optional')) {
+        return 'sparql.query.optional';
+    }
+    if (normalized.includes('union')) {
+        return 'sparql.query.union';
+    }
+    if (normalized.includes('filter')) {
+        return 'sparql.query.filter';
+    }
+    if (normalized.includes('function')) {
+        return 'sparql.query.function';
+    }
+    return 'sparql.query.shape';
+}
+function unsupportedSparqlHint(capability) {
+    switch (capability) {
+        case 'sparql.query.subquery':
+            return 'Flatten the subquery into required graph patterns, materialize the intermediate result, or route it through a trusted external SPARQL executor for this access scope.';
+        case 'sparql.query.property_path':
+            return 'Rewrite property paths as explicit predicate patterns before sending the query to the embedded RDF engine.';
+        case 'sparql.graph.default':
+            return 'Use explicit named GRAPH clauses inside the Pod base path instead of relying on default graph semantics.';
+        case 'sparql.graph.variable':
+            return 'Constrain graph variables with finite named graph filters before executing the query.';
+        case 'sparql.graph.scope':
+            return 'Limit GRAPH/FROM/USING targets to explicit graph documents inside the current Pod base path.';
+        case 'sparql.update.embedded_delta':
+            return 'Use embedded SPARQL UPDATE shapes that resolve to explicit local graph documents, or apply the change through a higher-level write API.';
+        case 'sparql.query.construct':
+            return 'Use CONSTRUCT templates made of ordinary triples with IRI or variable predicates, and keep the WHERE shape within the embedded query subset.';
+        case 'sparql.query.describe':
+            return 'Describe explicit IRIs or variables bound by required graph patterns; avoid DESCRIBE shapes that depend on optional-only bindings.';
+        case 'sparql.query.wildcard_projection':
+            return 'Project explicit variables for grouped or expression SELECT queries instead of mixing wildcard and computed projections.';
+        case 'sparql.query.having':
+            return 'Keep HAVING as simple comparisons between supported aggregate aliases and RDF terms.';
+        case 'sparql.query.group':
+            return 'Group only variables bound by required graph patterns or local BINDs, and project grouped variables or aggregate aliases.';
+        case 'sparql.query.aggregate':
+            return 'Use supported grouped aggregate shapes with variables bound by required graph patterns.';
+        case 'sparql.query.values':
+            return 'Bind VALUES variables from required graph patterns first, and avoid VALUES rows that introduce only standalone bindings.';
+        case 'sparql.query.bind':
+            return 'Order BIND expressions after the required graph patterns that bind every variable they reference.';
+        case 'sparql.query.minus':
+            return 'Make MINUS share at least one variable with the required query shape, and avoid nested dependent groups.';
+        case 'sparql.query.exists':
+            return 'Make FILTER EXISTS/NOT EXISTS share variables with required graph patterns, and avoid nested dependent groups.';
+        case 'sparql.query.optional':
+            return 'Keep OPTIONAL branches tied to variables already bound by required graph patterns.';
+        case 'sparql.query.union':
+            return 'Keep UNION branches as required graph-pattern branches with compatible projected variables.';
+        case 'sparql.query.filter':
+            return 'Use simple FILTER expressions over variables bound by required graph patterns.';
+        case 'sparql.query.function':
+            return 'Use the embedded engine supported XPath string functions, or precompute unsupported function results with BIND/materialized data.';
+        case 'sparql.query.rdf_star':
+            return 'Materialize RDF-star annotations as ordinary RDF resources or reification before querying this embedded engine.';
+        default:
+            return 'Rewrite the query to an embedded RDF engine supported shape, or route it through a trusted external SPARQL executor for this access scope.';
+    }
+}
+function sparqlCorrectionForCapability(capability) {
+    if (capability === 'sparql.geosparql') {
+        return {
+            capability,
+            primaryAction: 'route_external_executor',
+            availableActions: ['route_external_executor', 'materialize_intermediate'],
+            target: 'trusted_client_or_federated_engine',
+            message: 'Route GeoSPARQL queries to a trusted external executor until a concrete Xpod product workload justifies native embedded support.',
+        };
+    }
+    if (capability === 'sparql.federation.service') {
+        return {
+            capability,
+            primaryAction: 'route_external_executor',
+            availableActions: ['route_external_executor'],
+            target: 'trusted_client_or_federated_engine',
+            message: 'Execute SERVICE federation from a trusted client-side or federated query layer instead of the server-owned Pod embedded engine.',
+        };
+    }
+    if (capability === 'sparql.update.embedded_delta') {
+        return {
+            capability,
+            primaryAction: 'use_write_api',
+            availableActions: ['use_write_api', 'rewrite_query'],
+            target: 'pod_write_api',
+            message: 'Apply the write through a higher-level Pod write API, or rewrite the update so it targets explicit local graph documents.',
+        };
+    }
+    if (capability.startsWith('sparql.graph.')) {
+        return {
+            capability,
+            primaryAction: 'constrain_graph_scope',
+            availableActions: ['constrain_graph_scope', 'rewrite_query'],
+            target: 'embedded_rdf_engine',
+            message: 'Constrain graph scope to explicit named graph documents inside the current Pod base path before retrying.',
+        };
+    }
+    if (capability === 'sparql.query.subquery'
+        || capability === 'sparql.query.aggregate'
+        || capability === 'sparql.query.group'
+        || capability === 'sparql.query.having'
+        || capability === 'sparql.query.function'
+        || capability === 'sparql.query.rdf_star') {
+        return {
+            capability,
+            primaryAction: 'materialize_intermediate',
+            availableActions: ['materialize_intermediate', 'rewrite_query', 'route_external_executor'],
+            target: 'embedded_rdf_engine',
+            message: 'Materialize the unsupported intermediate result or rewrite the query into the embedded RDF subset before retrying.',
+        };
+    }
+    return {
+        capability,
+        primaryAction: 'rewrite_query',
+        availableActions: ['rewrite_query', 'route_external_executor'],
+        target: 'embedded_rdf_engine',
+        message: 'Rewrite the query into the embedded RDF engine supported subset before retrying, or route it through a trusted external executor.',
+    };
+}
 class RdfSparqlAdapter {
+    assertServerOwnedNativeQuery(query, basePath) {
+        const parsed = new sparqljs_1.Parser({ baseIRI: basePath }).parse(query);
+        assertNoExternalService(parsed);
+        if (parsed.type !== 'update') {
+            this.compileQueryDatasetScope(this.queryFromClause(parsed), basePath);
+        }
+    }
     compile(query, basePath) {
         const parsed = typeof query === 'string'
             ? new sparqljs_1.Parser({ baseIRI: basePath }).parse(query)
@@ -625,9 +855,19 @@ class RdfSparqlAdapter {
                         break;
                     }
                     if (optional) {
+                        const disjunction = this.compileDisjunctiveFilterBranches(expression);
+                        if (disjunction) {
+                            state.addOptionalUnion(disjunction);
+                            break;
+                        }
                         state.addOptionalFilters(this.compileFilter(expression));
                         break;
                     }
+                    const disjunction = this.compileDisjunctiveFilterBranches(expression);
+                    if (disjunction) {
+                        state.addUnion(disjunction);
+                        break;
+                    }
                     state.query.filters?.push(...this.compileFilter(expression));
                     break;
                 }
@@ -1546,6 +1786,25 @@ class RdfSparqlAdapter {
         }
         throw new UnsupportedSparqlQueryError(`FILTER ${operator} fallback to compatibility engine`);
     }
+    compileDisjunctiveFilterBranches(expression) {
+        const normalized = this.normalizeFunctionCallExpression(expression);
+        if (!normalized || !isOperationExpression(normalized) || normalized.operator.toLowerCase() !== '||') {
+            return undefined;
+        }
+        try {
+            this.compileOrFilter(normalized);
+            return undefined;
+        }
+        catch (error) {
+            if (!(error instanceof UnsupportedSparqlQueryError)) {
+                throw error;
+            }
+        }
+        return this.flattenOrExpressions(normalized).map((branch) => ({
+            patterns: [],
+            filters: this.compileFilter(branch),
+        }));
+    }
     compileOrFilter(expression) {
         const branches = this.flattenOrExpressions(expression);
         let variable;
@@ -2642,8 +2901,11 @@ function variablesInBindExpression(expression) {
             return [expression.variable];
         case 'lowerCase':
         case 'upperCase':
+        case 'numericValue':
             return variablesInBindExpression(expression.expression);
         case 'coalesce':
+        case 'add':
+        case 'multiply':
             return unique(expression.expressions.flatMap((item) => variablesInBindExpression(item)));
         case 'if':
             return unique([