AbstractPrequeryGenerator.scala

/*
 * Copyright © 2015-2019 the contributors (see Contributors.md).
 *
 * This file is part of Knora.
 *
 * Knora is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Affero General Public License as published
 * by the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * Knora is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Affero General Public License for more details.
 *
 * You should have received a copy of the GNU Affero General Public
 * License along with Knora.  If not, see <http://www.gnu.org/licenses/>.
 */

package org.knora.webapi.responders.v2.search.gravsearch.prequery

import org.knora.webapi._
import org.knora.webapi.messages.v2.responder.valuemessages.DateValueContentV2
import org.knora.webapi.responders.v2.search._
import org.knora.webapi.responders.v2.search.gravsearch.GravsearchQueryChecker
import org.knora.webapi.responders.v2.search.gravsearch.types._
import org.knora.webapi.util.ApacheLuceneSupport.LuceneQueryString
import org.knora.webapi.util.IriConversions._
import org.knora.webapi.util.{SmartIri, StringFormatter}

import scala.collection.mutable

object AbstractPrequeryGenerator {
    // separator used by GroupConcat
    val groupConcatSeparator: Char = StringFormatter.INFORMATION_SEPARATOR_ONE
}

/**
 * An abstract base class for [[WhereTransformer]] instances that generate SPARQL prequeries from Gravsearch input.
 *
 * @param typeInspectionResult the result of running type inspection on the Gravsearch input.
 * @param querySchema          the ontology schema used in the input Gravsearch query.
 */
abstract class AbstractPrequeryGenerator(constructClause: ConstructClause,
                                         typeInspectionResult: GravsearchTypeInspectionResult,
                                         querySchema: ApiV2Schema) extends WhereTransformer {
    protected implicit val stringFormatter: StringFormatter = StringFormatter.getGeneralInstance

    // a Set containing all `TypeableEntity` (keys of `typeInspectionResult`) that have already been processed
    // in order to prevent duplicates
    private val processedTypeInformationKeysWhereClause = mutable.Set.empty[TypeableEntity]

    // suffix appended to variables that are returned by a SPARQL aggregation function.
    protected val groupConcatVariableSuffix = "__Concat"

    // A set of types that can be treated as dates by the knora-api:toSimpleDate function.
    private val dateTypes: Set[IRI] = Set(OntologyConstants.KnoraApiV2Complex.DateValue, OntologyConstants.KnoraApiV2Complex.StandoffTag)

    /**
     * A container for a generated variable representing a value literal.
     *
     * @param variable     the generated variable.
     * @param useInOrderBy if `true`, the generated variable can be used in ORDER BY.
     */
    private case class GeneratedQueryVariable(variable: QueryVariable, useInOrderBy: Boolean)

    // variables that are created when processing filter statements or for a value object var used as a sort criterion
    // they represent the value of a literal pointed to by a value object
    private val valueVariablesAutomaticallyGenerated = mutable.Map.empty[QueryVariable, Set[GeneratedQueryVariable]]

    // variables the represent resource metadata
    private val resourceMetadataVariables = mutable.Set.empty[QueryVariable]

    /**
     * Saves a generated variable representing a value literal, if it hasn't been saved already.
     *
     * @param valueVar     the variable representing the value.
     * @param generatedVar the generated variable representing the value literal.
     * @param useInOrderBy if `true`, the generated variable can be used in ORDER BY.
     * @return `true` if the generated variable was saved, `false` if it had already been saved.
     */
    private def addGeneratedVariableForValueLiteral(valueVar: QueryVariable, generatedVar: QueryVariable, useInOrderBy: Boolean = true): Boolean = {
        val currentGeneratedVars = valueVariablesAutomaticallyGenerated.getOrElse(valueVar, Set.empty[GeneratedQueryVariable])

        if (!currentGeneratedVars.exists(currentGeneratedVar => currentGeneratedVar.variable == generatedVar)) {
            valueVariablesAutomaticallyGenerated.put(valueVar, currentGeneratedVars + GeneratedQueryVariable(generatedVar, useInOrderBy))
            true
        } else {
            false
        }
    }

    /**
     * Gets a saved generated variable representing a value literal, for use in ORDER BY.
     *
     * @param valueVar the variable representing the value.
     * @return a generated variable that represents a value literal and can be used in ORDER BY, or `None` if no such variable has been saved.
     */
    protected def getGeneratedVariableForValueLiteralInOrderBy(valueVar: QueryVariable): Option[QueryVariable] = {
        valueVariablesAutomaticallyGenerated.get(valueVar) match {
            case Some(generatedVars: Set[GeneratedQueryVariable]) =>
                val generatedVarsForOrderBy: Set[QueryVariable] = generatedVars.filter(_.useInOrderBy).map(_.variable)

                if (generatedVarsForOrderBy.size > 1) {
                    throw AssertionException(s"More than one variable was generated for the literal values of ${valueVar.toSparql} and marked for use in ORDER BY: ${generatedVarsForOrderBy.map(_.toSparql).mkString(", ")}")
                }

                generatedVarsForOrderBy.headOption

            case None => None
        }
    }

    // Generated statements for date literals, so we don't generate the same statements twice.
    private val generatedDateStatements = mutable.Set.empty[StatementPattern]

    // Variables generated to represent marked-up text in standoff, so we don't generate the same variables twice.
    private val standoffMarkedUpVariables = mutable.Set.empty[QueryVariable]

    /**
     * The variable in the CONSTRUCT clause that represents the main resource.
     */
    val mainResourceVariable: QueryVariable = {
        val mainResourceQueryVariables = constructClause.statements.foldLeft(Set.empty[QueryVariable]) {
            case (acc: Set[QueryVariable], statementPattern) =>
                statementPattern.pred match {
                    case IriRef(iri, _) =>

                        val iriStr = iri.toString

                        if (iriStr == OntologyConstants.KnoraApiV2Simple.IsMainResource || iriStr == OntologyConstants.KnoraApiV2Complex.IsMainResource) {
                            statementPattern.obj match {
                                case XsdLiteral(value, SmartIri(OntologyConstants.Xsd.Boolean)) if value.toBoolean =>
                                    statementPattern.subj match {
                                        case queryVariable: QueryVariable => acc + queryVariable
                                        case _ => throw GravsearchException(s"The subject of knora-api:isMainResource must be a variable")
                                    }

                                case _ => acc
                            }
                        } else {
                            acc
                        }

                    case _ => acc
                }
        }

        if (mainResourceQueryVariables.isEmpty) {
            throw GravsearchException("CONSTRUCT clause contains no knora-api:isMainResource")
        }

        if (mainResourceQueryVariables.size > 1) {
            throw GravsearchException("CONSTRUCT clause contains more than one knora-api:isMainResource")
        }

        mainResourceQueryVariables.head
    }

    /**
     * Creates additional statements for a non property type (e.g., a resource).
     *
     * @param nonPropertyTypeInfo type information about non property type.
     * @param inputEntity         the [[Entity]] to make the statements about.
     * @return a sequence of [[QueryPattern]] representing the additional statements.
     */
    private def createAdditionalStatementsForNonPropertyType(nonPropertyTypeInfo: NonPropertyTypeInfo, inputEntity: Entity): Seq[QueryPattern] = {
        if (nonPropertyTypeInfo.isResourceType) {

            // inputEntity is either source or target of a linking property
            // create additional statements in order to query permissions and other information for a resource

            Seq(
                StatementPattern.makeInferred(subj = inputEntity, pred = IriRef(OntologyConstants.Rdf.Type.toSmartIri), obj = IriRef(OntologyConstants.KnoraBase.Resource.toSmartIri)),
                StatementPattern.makeExplicit(subj = inputEntity, pred = IriRef(OntologyConstants.KnoraBase.IsDeleted.toSmartIri), obj = XsdLiteral(value = "false", datatype = OntologyConstants.Xsd.Boolean.toSmartIri))
            )
        } else {
            // inputEntity is target of a value property
            // properties are handled by `convertStatementForPropertyType`, no processing needed here

            Seq.empty[QueryPattern]
        }
    }

    /**
     * Generates statements matching a `knora-base:LinkValue`.
     *
     * @param linkSource the resource that is the source of the link.
     * @param linkPred   the link predicate.
     * @param linkTarget the resource that is the target of the link.
     * @return statements matching the `knora-base:LinkValue` that describes the link.
     */
    private def generateStatementsForLinkValue(linkSource: Entity, linkPred: Entity, linkTarget: Entity): Seq[StatementPattern] = {
        // Generate a variable name representing the link value
        val linkValueObjVar: QueryVariable = SparqlTransformer.createUniqueVariableFromStatementForLinkValue(
            baseStatement = StatementPattern(
                subj = linkSource,
                pred = linkPred,
                obj = linkTarget
            )
        )

        // create an Entity that connects the subject of the linking property with the link value object
        val linkValueProp: Entity = linkPred match {
            case linkingPropQueryVar: QueryVariable =>
                // Generate a variable name representing the link value property
                // in case FILTER patterns are given restricting the linking property's possible IRIs, the same variable will recreated when processing FILTER patterns
                createLinkValuePropertyVariableFromLinkingPropertyVariable(linkingPropQueryVar)

            case propIri: IriRef =>
                // convert the given linking property IRI to the corresponding link value property IRI
                // only matches the linking property's link value
                IriRef(propIri.iri.toOntologySchema(InternalSchema).fromLinkPropToLinkValueProp)

            case literal: XsdLiteral => throw GravsearchException(s"literal ${literal.toSparql} cannot be used as a predicate")

            case other => throw GravsearchException(s"${other.toSparql} cannot be used as a predicate")
        }

        // Add statements that represent the link value's properties for the given linking property
        // do not check for the predicate because inference would not work
        // instead, linkValueProp restricts the link value objects to be returned
        Seq(
            StatementPattern.makeInferred(subj = linkSource, pred = linkValueProp, obj = linkValueObjVar),
            StatementPattern.makeExplicit(subj = linkValueObjVar, pred = IriRef(OntologyConstants.Rdf.Type.toSmartIri), obj = IriRef(OntologyConstants.KnoraBase.LinkValue.toSmartIri)),
            StatementPattern.makeExplicit(subj = linkValueObjVar, pred = IriRef(OntologyConstants.KnoraBase.IsDeleted.toSmartIri), obj = XsdLiteral(value = "false", datatype = OntologyConstants.Xsd.Boolean.toSmartIri)),
            StatementPattern.makeExplicit(subj = linkValueObjVar, pred = IriRef(OntologyConstants.Rdf.Subject.toSmartIri), obj = linkSource),
            StatementPattern.makeExplicit(subj = linkValueObjVar, pred = IriRef(OntologyConstants.Rdf.Object.toSmartIri), obj = linkTarget)
        )
    }

    private def convertStatementForPropertyType(inputOrderBy: Seq[OrderCriterion])(propertyTypeInfo: PropertyTypeInfo, statementPattern: StatementPattern, typeInspectionResult: GravsearchTypeInspectionResult): Seq[QueryPattern] = {
        /**
         * Ensures that if the object of a statement is a variable, and is used in the ORDER BY clause of the input query, the subject of the statement
         * is the main resource. Throws an exception otherwise.
         *
         * @param objectVar the variable that is the object of the statement.
         */
        def checkSubjectInOrderBy(objectVar: QueryVariable): Unit = {
            statementPattern.subj match {
                case subjectVar: QueryVariable =>
                    if (mainResourceVariable != subjectVar && inputOrderBy.exists(criterion => criterion.queryVariable == objectVar)) {
                        throw GravsearchException(s"Variable ${objectVar.toSparql} is used in ORDER BY, but does not represent a value of the main resource")
                    }

                case _ => ()
            }
        }

        /**
         * Transforms a statement pointing to a list node so it matches also any of its subnodes.
         *
         * @return transformed statements.
         */
        def handleListNode(): Seq[StatementPattern] = {

            if (querySchema == ApiV2Simple) {
                throw GravsearchException("the method 'handleListNode' only works for the complex schema")
            }

            // the list node to match for provided in the input query
            val listNode: Entity = statementPattern.obj

            // variable representing the list node to match for
            val listNodeVar: QueryVariable = SparqlTransformer.createUniqueVariableFromStatement(
                baseStatement = statementPattern,
                suffix = "listNodeVar"
            )

            // transforms the statement given in the input query so the list node and any of its subnodes are matched
            Seq(
                statementPatternToInternalSchema(statementPattern, typeInspectionResult).copy(obj = listNodeVar),
                StatementPattern.makeExplicit(
                    subj = listNode,
                    pred = IriRef(iri = OntologyConstants.KnoraBase.HasSubListNode.toSmartIri, propertyPathOperator = Some('*')),
                    obj = listNodeVar
                )
            )

        }

        val maybeSubjectTypeIri: Option[SmartIri] = typeInspectionResult.getTypeOfEntity(statementPattern.subj) match {
            case Some(NonPropertyTypeInfo(subjectTypeIri)) => Some(subjectTypeIri)
            case _ => None
        }

        val subjectIsResource: Boolean = maybeSubjectTypeIri.exists(iri => OntologyConstants.KnoraApi.isKnoraApiV2Resource(iri))

        // Is the subject of the statement a resource?
        if (subjectIsResource) {
            // Yes. Is the object of the statement also a resource?
            if (propertyTypeInfo.objectIsResourceType) {
                // Yes. This is a link property. Make sure that the object is either an IRI or a variable (cannot be a literal).
                statementPattern.obj match {
                    case _: IriRef => ()
                    case objectVar: QueryVariable => checkSubjectInOrderBy(objectVar)
                    case other => throw GravsearchException(s"Object of a linking statement must be an IRI or a variable, but ${other.toSparql} given.")
                }

                // Generate statement patterns to match the link value.
                val linkValueStatements = generateStatementsForLinkValue(
                    linkSource = statementPattern.subj,
                    linkPred = statementPattern.pred,
                    linkTarget = statementPattern.obj
                )

                // Add the input statement, which uses the link property, to the generated statements about the link value.
                statementPatternToInternalSchema(statementPattern, typeInspectionResult) +: linkValueStatements

            } else {
                // The subject is a resource, but the object isn't, so this isn't a link property.
                // Is the property a resource metadata property?
                statementPattern.pred match {
                    case iriRef: IriRef if OntologyConstants.ResourceMetadataPropertyAxioms.contains(iriRef.iri.toString) =>
                        // Yes. Store the variable if provided.
                        val maybeObjectVar: Option[QueryVariable] = statementPattern.obj match {
                            case queryVar: QueryVariable =>
                                checkSubjectInOrderBy(queryVar)
                                Some(queryVar)

                            case _ => None
                        }

                        resourceMetadataVariables ++= maybeObjectVar

                        // Just convert the statement pattern to the internal schema
                        Seq(statementPatternToInternalSchema(statementPattern, typeInspectionResult))

                    case _ =>
                        //  The property is not a resource metadata property. Make sure the object is a variable.
                        val objectVar: QueryVariable = statementPattern.obj match {
                            case queryVar: QueryVariable =>
                                checkSubjectInOrderBy(queryVar)
                                queryVar

                            case other => throw GravsearchException(s"Object of a value property statement must be a QueryVariable, but ${other.toSparql} given.")
                        }

                        // Does the variable refer to a Knora value object? We assume it does if the query just uses the
                        // simple schema. If the query uses the complex schema, check whether the property's object type is a
                        // Knora API v2 value class.

                        val objectVarIsValueObject = querySchema == ApiV2Simple ||
                            OntologyConstants.KnoraApiV2Complex.ValueClasses.contains(propertyTypeInfo.objectTypeIri.toString)

                        if (objectVarIsValueObject) {
                            // The variable refers to a value object.

                            // Convert the statement to the internal schema, and add a statement to check that the value object is not marked as deleted.
                            val valueObjectIsNotDeleted = StatementPattern.makeExplicit(subj = statementPattern.obj, pred = IriRef(OntologyConstants.KnoraBase.IsDeleted.toSmartIri), obj = XsdLiteral(value = "false", datatype = OntologyConstants.Xsd.Boolean.toSmartIri))

                            // check if the object var is used as a sort criterion
                            val objectVarAsSortCriterionMaybe = inputOrderBy.find(criterion => criterion.queryVariable == objectVar)

                            val orderByStatement: Option[QueryPattern] = if (objectVarAsSortCriterionMaybe.nonEmpty) {
                                // it is used as a sort criterion, create an additional statement to get the literal value

                                val criterion = objectVarAsSortCriterionMaybe.get

                                val propertyIri: SmartIri = typeInspectionResult.getTypeOfEntity(criterion.queryVariable) match {
                                    case Some(nonPropertyTypeInfo: NonPropertyTypeInfo) =>
                                        valueTypesToValuePredsForOrderBy.getOrElse(nonPropertyTypeInfo.typeIri.toString, throw GravsearchException(s"${criterion.queryVariable.toSparql} cannot be used in ORDER BY")).toSmartIri

                                    case Some(_) => throw GravsearchException(s"Variable ${criterion.queryVariable.toSparql} represents a property, and therefore cannot be used in ORDER BY")

                                    case None => throw GravsearchException(s"No type information found for ${criterion.queryVariable.toSparql}")
                                }

                                // Generate the variable name.
                                val variableForLiteral: QueryVariable = SparqlTransformer.createUniqueVariableNameFromEntityAndProperty(criterion.queryVariable, propertyIri.toString)

                                // put the generated variable into a collection so it can be reused in `NonTriplestoreSpecificGravsearchToPrequeryGenerator.getOrderBy`
                                // set to true when the variable already exists
                                val variableForLiteralExists = !addGeneratedVariableForValueLiteral(criterion.queryVariable, variableForLiteral)

                                if (!variableForLiteralExists) {
                                    // Generate a statement to get the literal value
                                    val statementPatternForSortCriterion = StatementPattern.makeExplicit(subj = criterion.queryVariable, pred = IriRef(propertyIri), obj = variableForLiteral)
                                    Some(statementPatternForSortCriterion)
                                } else {
                                    // statement has already been created
                                    None
                                }
                            } else {
                                // it is not a sort criterion
                                None
                            }

                            Seq(statementPatternToInternalSchema(statementPattern, typeInspectionResult), valueObjectIsNotDeleted) ++ orderByStatement
                        } else {
                            // The variable doesn't refer to a value object. Just convert the statement pattern to the internal schema.
                            Seq(statementPatternToInternalSchema(statementPattern, typeInspectionResult))
                        }
                }
            }
        } else {
            // The subject isn't a resource, so it must be a value object or standoff node. Is the query in the complex schema?
            if (querySchema == ApiV2Complex) {
                // Yes. If the subject is a standoff tag and the object is a resource, that's an error, because the client
                // has to use the knora-api:standoffLink function instead.
                if (maybeSubjectTypeIri.contains(OntologyConstants.KnoraApiV2Complex.StandoffTag.toSmartIri) && propertyTypeInfo.objectIsResourceType) {
                    throw GravsearchException(s"Invalid statement pattern (use the knora-api:standoffLink function instead): ${statementPattern.toSparql.trim}")
                } else {
                    // Is the object of the statement a list node?
                    propertyTypeInfo.objectTypeIri match {
                        case SmartIri(OntologyConstants.KnoraApiV2Complex.ListNode) =>
                            // Yes, transform statement so it also matches any of the subnodes of the given node
                            handleListNode()
                        case _ =>
                            // No, just convert the statement pattern to the internal schema.
                            Seq(statementPatternToInternalSchema(statementPattern, typeInspectionResult))
                    }

                }
            } else {
                // The query is in the simple schema, so the statement is invalid.
                throw GravsearchException(s"Invalid statement pattern: ${statementPattern.toSparql.trim}")
            }
        }
    }

    protected def processStatementPatternFromWhereClause(statementPattern: StatementPattern, inputOrderBy: Seq[OrderCriterion]): Seq[QueryPattern] = {

        // look at the statement's subject, predicate, and object and generate additional statements if needed based on the given type information.
        // transform the originally given statement if necessary when processing the predicate

        // check if there exists type information for the given statement's subject
        val additionalStatementsForSubj: Seq[QueryPattern] = checkForNonPropertyTypeInfoForEntity(
            entity = statementPattern.subj,
            typeInspectionResult = typeInspectionResult,
            processedTypeInfo = processedTypeInformationKeysWhereClause,
            conversionFuncForNonPropertyType = createAdditionalStatementsForNonPropertyType
        )

        // check if there exists type information for the given statement's object
        val additionalStatementsForObj: Seq[QueryPattern] = checkForNonPropertyTypeInfoForEntity(
            entity = statementPattern.obj,
            typeInspectionResult = typeInspectionResult,
            processedTypeInfo = processedTypeInformationKeysWhereClause,
            conversionFuncForNonPropertyType = createAdditionalStatementsForNonPropertyType
        )

        // Add additional statements based on the whole input statement, e.g. to deal with the value object or the link value, and transform the original statement.
        val additionalStatementsForWholeStatement: Seq[QueryPattern] = checkForPropertyTypeInfoForStatement(
            statementPattern = statementPattern,
            typeInspectionResult = typeInspectionResult,
            conversionFuncForPropertyType = convertStatementForPropertyType(inputOrderBy)
        )

        additionalStatementsForSubj ++ additionalStatementsForWholeStatement ++ additionalStatementsForObj

    }

    /**
     * Creates additional statements for a given [[Entity]] based on type information using `conversionFuncForNonPropertyType`
     * for a non property type (e.g., a resource).
     *
     * @param entity                           the entity to be taken into consideration (a statement's subject or object).
     * @param typeInspectionResult             type information.
     * @param processedTypeInfo                the keys of type information that have already been looked at.
     * @param conversionFuncForNonPropertyType the function to use to create additional statements.
     * @return a sequence of [[QueryPattern]] representing the additional statements.
     */
    private def checkForNonPropertyTypeInfoForEntity(entity: Entity, typeInspectionResult: GravsearchTypeInspectionResult, processedTypeInfo: mutable.Set[TypeableEntity], conversionFuncForNonPropertyType: (NonPropertyTypeInfo, Entity) => Seq[QueryPattern]): Seq[QueryPattern] = {
        val typesNotYetProcessed = typeInspectionResult.copy(entities = typeInspectionResult.entities -- processedTypeInfo)

        typesNotYetProcessed.getTypeOfEntity(entity) match {
            case Some(nonPropInfo: NonPropertyTypeInfo) =>
                // add a TypeableEntity for subject to prevent duplicates
                processedTypeInfo += GravsearchTypeInspectionUtil.toTypeableEntity(entity)
                conversionFuncForNonPropertyType(nonPropInfo, entity)

            case Some(other) => throw AssertionException(s"NonPropertyTypeInfo expected for $entity, got $other")

            case None => Seq.empty[QueryPattern]
        }
    }

    /**
     * Converts the given statement based on the given type information using `conversionFuncForPropertyType`.
     *
     * @param statementPattern              the statement to be converted.
     * @param typeInspectionResult          type information.
     * @param conversionFuncForPropertyType the function to use for the conversion.
     * @return a sequence of [[QueryPattern]] representing the converted statement.
     */
    private def checkForPropertyTypeInfoForStatement(statementPattern: StatementPattern, typeInspectionResult: GravsearchTypeInspectionResult, conversionFuncForPropertyType: (PropertyTypeInfo, StatementPattern, GravsearchTypeInspectionResult) => Seq[QueryPattern]): Seq[QueryPattern] = {
        typeInspectionResult.getTypeOfEntity(statementPattern.pred) match {
            case Some(propInfo: PropertyTypeInfo) =>
                // process type information for the predicate into additional statements
                conversionFuncForPropertyType(propInfo, statementPattern, typeInspectionResult)

            case Some(other) => throw AssertionException(s"PropertyTypeInfo expected for ${statementPattern.pred}, got $other")

            case None =>
                // no type information given and thus no further processing needed, just return the originally given statement (e.g., rdf:type), converted to the internal schema.
                Seq(statementPatternToInternalSchema(statementPattern, typeInspectionResult))
        }
    }

    // A Map of knora-api value types (both complex and simple) to the corresponding knora-base value predicates
    // that point to literals. This is used only for generating additional statements for ORDER BY clauses, so it only needs to include
    // types that have a meaningful order.
    private val valueTypesToValuePredsForOrderBy: Map[IRI, IRI] = Map(
        OntologyConstants.Xsd.Integer -> OntologyConstants.KnoraBase.ValueHasInteger,
        OntologyConstants.Xsd.Decimal -> OntologyConstants.KnoraBase.ValueHasDecimal,
        OntologyConstants.Xsd.Boolean -> OntologyConstants.KnoraBase.ValueHasBoolean,
        OntologyConstants.Xsd.String -> OntologyConstants.KnoraBase.ValueHasString,
        OntologyConstants.KnoraApiV2Simple.Date -> OntologyConstants.KnoraBase.ValueHasStartJDN,
        OntologyConstants.KnoraApiV2Simple.Color -> OntologyConstants.KnoraBase.ValueHasColor,
        OntologyConstants.KnoraApiV2Simple.Geoname -> OntologyConstants.KnoraBase.ValueHasGeonameCode,
        OntologyConstants.KnoraApiV2Complex.TextValue -> OntologyConstants.KnoraBase.ValueHasString,
        OntologyConstants.KnoraApiV2Complex.IntValue -> OntologyConstants.KnoraBase.ValueHasInteger,
        OntologyConstants.KnoraApiV2Complex.DecimalValue -> OntologyConstants.KnoraBase.ValueHasDecimal,
        OntologyConstants.KnoraApiV2Complex.TimeValue -> OntologyConstants.KnoraBase.ValueHasTimeStamp,
        OntologyConstants.KnoraApiV2Complex.BooleanValue -> OntologyConstants.KnoraBase.ValueHasBoolean,
        OntologyConstants.KnoraApiV2Complex.DateValue -> OntologyConstants.KnoraBase.ValueHasStartJDN,
        OntologyConstants.KnoraApiV2Complex.ColorValue -> OntologyConstants.KnoraBase.ValueHasColor,
        OntologyConstants.KnoraApiV2Complex.GeonameValue -> OntologyConstants.KnoraBase.ValueHasGeonameCode
    )

    /**
     * Calls [[GravsearchQueryChecker.checkStatement]], then converts the specified statement pattern to the internal schema.
     *
     * @param statementPattern     the statement pattern to be converted.
     * @param typeInspectionResult the type inspection result.
     * @return the converted statement pattern.
     */
    private def statementPatternToInternalSchema(statementPattern: StatementPattern, typeInspectionResult: GravsearchTypeInspectionResult): StatementPattern = {
        GravsearchQueryChecker.checkStatement(
            statementPattern = statementPattern,
            querySchema = querySchema,
            typeInspectionResult = typeInspectionResult
        )

        statementPattern.toOntologySchema(InternalSchema)
    }

    /**
     * Given a variable representing a linking property, creates a variable representing the corresponding link value property.
     *
     * @param linkingPropertyQueryVariable variable representing a linking property.
     * @return variable representing the corresponding link value property.
     */
    private def createLinkValuePropertyVariableFromLinkingPropertyVariable(linkingPropertyQueryVariable: QueryVariable): QueryVariable = {
        SparqlTransformer.createUniqueVariableNameFromEntityAndProperty(
            base = linkingPropertyQueryVariable,
            propertyIri = OntologyConstants.KnoraBase.HasLinkToValue
        )
    }

    /**
     * Represents a transformed Filter expression and additional statement patterns that possibly had to be created during transformation.
     *
     * @param expression         the transformed FILTER expression. In some cases, a given FILTER expression is replaced by additional statements, but
     *                           only if it is the top-level expression in the FILTER.
     * @param additionalPatterns additionally created query patterns.
     */
    protected case class TransformedFilterPattern(expression: Option[Expression], additionalPatterns: Seq[QueryPattern] = Seq.empty[QueryPattern])

    /**
     * Handles query variables that represent properties in a [[FilterPattern]].
     *
     * @param queryVar           the query variable to be handled.
     * @param comparisonOperator the comparison operator used in the filter pattern.
     * @param iriRef             the IRI the property query variable is restricted to.
     * @param propInfo           information about the query variable's type.
     * @return a [[TransformedFilterPattern]].
     */
    private def handlePropertyIriQueryVar(queryVar: QueryVariable, comparisonOperator: CompareExpressionOperator.Value, iriRef: IriRef, propInfo: PropertyTypeInfo): TransformedFilterPattern = {

        iriRef.iri.checkApiV2Schema(querySchema, throw GravsearchException(s"Invalid schema for IRI: ${iriRef.toSparql}"))

        val internalIriRef = iriRef.toOntologySchema(InternalSchema)

        // make sure that the comparison operator is a CompareExpressionOperator.EQUALS
        if (comparisonOperator != CompareExpressionOperator.EQUALS)
            throw GravsearchException(s"Comparison operator in a CompareExpression for a property type must be ${CompareExpressionOperator.EQUALS}, but '$comparisonOperator' given (for negations use 'FILTER NOT EXISTS')")

        val userProvidedRestriction = CompareExpression(queryVar, comparisonOperator, internalIriRef)

        // check if the objectTypeIri of propInfo is knora-api:Resource
        // if so, it is a linking property and its link value property must be restricted too
        if (OntologyConstants.KnoraApi.isKnoraApiV2Resource(propInfo.objectTypeIri)) {
            // it is a linking property, restrict the link value property
            val restrictionForLinkValueProp = CompareExpression(
                leftArg = createLinkValuePropertyVariableFromLinkingPropertyVariable(queryVar), // the same variable was created during statement processing in WHERE clause in `convertStatementForPropertyType`
                operator = comparisonOperator,
                rightArg = IriRef(internalIriRef.iri.fromLinkPropToLinkValueProp)) // create link value property from linking property

            TransformedFilterPattern(
                Some(
                    AndExpression(
                        leftArg = userProvidedRestriction,
                        rightArg = restrictionForLinkValueProp)
                )
            )
        } else {
            // not a linking property, just return the provided restriction
            TransformedFilterPattern(Some(userProvidedRestriction))
        }
    }

    /**
     * Handles query variables that represent a list node label in a [[FilterPattern]].
     *
     * @param queryVar               the query variable to be handled.
     * @param comparisonOperator     the comparison operator used in the filter pattern.
     * @param literalValueExpression the label to match against.
     */
    private def handleListQueryVar(queryVar: QueryVariable, comparisonOperator: CompareExpressionOperator.Value, literalValueExpression: Expression): TransformedFilterPattern = {

        // make sure that the expression is a literal of the expected type
        val nodeLabel: String = literalValueExpression match {
            case xsdLiteral: XsdLiteral if xsdLiteral.datatype.toString == OntologyConstants.KnoraApiV2Simple.ListNode => xsdLiteral.value

            case other => throw GravsearchException(s"Invalid type for literal ${OntologyConstants.KnoraApiV2Simple.ListNode}")
        }

        val validComparisonOperators = Set(CompareExpressionOperator.EQUALS)

        // check if comparison operator is supported
        if (!validComparisonOperators.contains(comparisonOperator))
            throw GravsearchException(s"Invalid operator '$comparisonOperator' in expression (allowed operators in this context are ${validComparisonOperators.map(op => "'" + op + "'").mkString(", ")})")

        // Generate a variable name representing the list node pointed to by the list value object
        val listNodeVar: QueryVariable = SparqlTransformer.createUniqueVariableNameFromEntityAndProperty(
            base = queryVar,
            propertyIri = OntologyConstants.KnoraBase.ValueHasListNode
        )

        // Generate variable name representing the label of the list node pointed to
        val listNodeLabel: QueryVariable = SparqlTransformer.createUniqueVariableNameFromEntityAndProperty(
            base = queryVar,
            propertyIri = OntologyConstants.Rdfs.Label
        )

        TransformedFilterPattern(
            // use the SPARQL-STR function because the list node label has a language tag
            Some(CompareExpression(StrFunction(listNodeLabel), comparisonOperator, XsdLiteral(nodeLabel, OntologyConstants.Xsd.String.toSmartIri))), // compares the provided literal to the value object's literal value
            Seq(
                // connects the query variable with the list node label
                StatementPattern.makeExplicit(subj = queryVar, pred = IriRef(OntologyConstants.KnoraBase.ValueHasListNode.toSmartIri), listNodeVar),
                StatementPattern.makeExplicit(subj = listNodeVar, pred = IriRef(OntologyConstants.Rdfs.Label.toSmartIri), obj = listNodeLabel)

            )
        )
    }

    /**
     * Handles query variables that represent literals in a [[FilterPattern]].
     *
     * @param queryVar                 the query variable to be handled.
     * @param comparisonOperator       the comparison operator used in the filter pattern.
     * @param literalValueExpression   the literal provided in the [[FilterPattern]] as an [[Expression]].
     * @param xsdType                  valid xsd types of the literal.
     * @param valueHasProperty         the property of the value object pointing to the literal (in the internal schema).
     * @param validComparisonOperators a set of valid comparison operators, if to be restricted.
     * @return a [[TransformedFilterPattern]].
     */
    private def handleLiteralQueryVar(queryVar: QueryVariable, comparisonOperator: CompareExpressionOperator.Value, literalValueExpression: Expression, xsdType: Set[IRI], valueHasProperty: IRI, validComparisonOperators: Set[CompareExpressionOperator.Value] = Set.empty[CompareExpressionOperator.Value]): TransformedFilterPattern = {

        // make sure that the expression is a literal of the expected type
        val literal: XsdLiteral = literalValueExpression match {
            case xsdLiteral: XsdLiteral if xsdType(xsdLiteral.datatype.toString) => xsdLiteral

            case other => throw GravsearchException(s"Invalid right argument ${other.toSparql} in comparison (allowed types in this context are ${xsdType.map(_.toSmartIri.toSparql).mkString(", ")})")
        }

        // check if comparison operator is supported for given type
        if (validComparisonOperators.nonEmpty && !validComparisonOperators(comparisonOperator))
            throw GravsearchException(s"Invalid operator '$comparisonOperator' in expression (allowed operators in this context are ${validComparisonOperators.map(op => "'" + op + "'").mkString(", ")})")

        // Does the variable refer to resource metadata?
        if (resourceMetadataVariables.contains(queryVar)) {
            // Yes. Leave the expression as is.
            TransformedFilterPattern(
                Some(CompareExpression(queryVar, comparisonOperator, literal)),
                Seq.empty
            )
        } else {
            // The variable does not refer to resource metadata.
            // Generate a variable name representing the literal attached to the value object.
            val valueObjectLiteralVar: QueryVariable = SparqlTransformer.createUniqueVariableNameFromEntityAndProperty(
                base = queryVar,
                propertyIri = valueHasProperty
            )

            // Add a statement to assign the literal to a variable, which we'll use in the transformed FILTER expression,
            // if that statement hasn't been added already.

            val statementToAddForValueHas: Seq[StatementPattern] = if (addGeneratedVariableForValueLiteral(queryVar, valueObjectLiteralVar)) {
                Seq(
                    // connects the query variable with the value object (internal structure: values are represented as objects)
                    StatementPattern.makeExplicit(subj = queryVar, pred = IriRef(valueHasProperty.toSmartIri), valueObjectLiteralVar)
                )
            } else {
                Seq.empty[StatementPattern]
            }

            TransformedFilterPattern(
                Some(CompareExpression(valueObjectLiteralVar, comparisonOperator, literal)), // compares the provided literal to the value object's literal value
                statementToAddForValueHas
            )
        }
    }

    /**
     * Handles query variables that represent a date in a [[FilterPattern]].
     *
     * @param queryVar            the query variable to be handled.
     * @param comparisonOperator  the comparison operator used in the filter pattern.
     * @param dateValueExpression the date literal provided in the [[FilterPattern]] as an [[Expression]].
     * @return a [[TransformedFilterPattern]].
     */
    private def handleDateQueryVar(queryVar: QueryVariable, comparisonOperator: CompareExpressionOperator.Value, dateValueExpression: Expression): TransformedFilterPattern = {

        // make sure that the right argument is a string literal (dates are represented as knora date strings in knora-api simple)
        val dateStringLiteral: XsdLiteral = dateValueExpression match {
            case dateStrLiteral: XsdLiteral if dateStrLiteral.datatype.toString == OntologyConstants.KnoraApiV2Simple.Date => dateStrLiteral

            case other => throw GravsearchException(s"Invalid right argument ${other.toSparql} in date comparison")
        }

        // validate Knora date string
        val dateStr: String = stringFormatter.validateDate(dateStringLiteral.value, throw BadRequestException(s"${dateStringLiteral.value} is not a valid date string"))

        // Convert it to Julian Day Numbers.
        val dateValueContent = DateValueContentV2.parse(dateStr)

        // Generate a variable name representing the period's start
        val dateValueHasStartVar = SparqlTransformer.createUniqueVariableNameFromEntityAndProperty(base = queryVar, propertyIri = OntologyConstants.KnoraBase.ValueHasStartJDN)

        // sort dates by their period's start (in the prequery)
        // is set to `true` if the date value object var is a sort criterion and has been handled already
        val dateValVarExists: Boolean = !addGeneratedVariableForValueLiteral(queryVar, dateValueHasStartVar)

        // Generate a variable name representing the period's end
        val dateValueHasEndVar = SparqlTransformer.createUniqueVariableNameFromEntityAndProperty(base = queryVar, propertyIri = OntologyConstants.KnoraBase.ValueHasEndJDN)

        // connects the value object with the periods start variable
        // only generate a new statement if it has not already been created when handling the sort criteria
        val dateValStartStatementOption: Option[StatementPattern] = if (!dateValVarExists) {
            Some(StatementPattern.makeExplicit(subj = queryVar, pred = IriRef(OntologyConstants.KnoraBase.ValueHasStartJDN.toSmartIri), obj = dateValueHasStartVar))
        } else {
            None
        }

        // connects the value object with the periods end variable
        val dateValEndStatement = StatementPattern.makeExplicit(subj = queryVar, pred = IriRef(OntologyConstants.KnoraBase.ValueHasEndJDN.toSmartIri), obj = dateValueHasEndVar)

        // process filter expression based on given comparison operator
        comparisonOperator match {

            case CompareExpressionOperator.EQUALS =>

                // any overlap in considered as equality
                val leftArgFilter = CompareExpression(XsdLiteral(dateValueContent.valueHasStartJDN.toString, OntologyConstants.Xsd.Integer.toSmartIri), CompareExpressionOperator.LESS_THAN_OR_EQUAL_TO, dateValueHasEndVar)

                val rightArgFilter = CompareExpression(XsdLiteral(dateValueContent.valueHasEndJDN.toString, OntologyConstants.Xsd.Integer.toSmartIri), CompareExpressionOperator.GREATER_THAN_OR_EQUAL_TO, dateValueHasStartVar)

                val filter = AndExpression(leftArgFilter, rightArgFilter)

                val statementsToAdd = (dateValStartStatementOption.toSeq :+ dateValEndStatement).filterNot(statement => generatedDateStatements.contains(statement))
                generatedDateStatements ++= statementsToAdd

                TransformedFilterPattern(
                    Some(filter),
                    statementsToAdd
                )

            case CompareExpressionOperator.NOT_EQUALS =>

                // no overlap in considered as inequality (negation of equality)
                val leftArgFilter = CompareExpression(XsdLiteral(dateValueContent.valueHasStartJDN.toString, OntologyConstants.Xsd.Integer.toSmartIri), CompareExpressionOperator.GREATER_THAN, dateValueHasEndVar)

                val rightArgFilter = CompareExpression(XsdLiteral(dateValueContent.valueHasEndJDN.toString, OntologyConstants.Xsd.Integer.toSmartIri), CompareExpressionOperator.LESS_THAN, dateValueHasStartVar)

                val filter = OrExpression(leftArgFilter, rightArgFilter)

                val statementsToAdd = (dateValStartStatementOption.toSeq :+ dateValEndStatement).filterNot(statement => generatedDateStatements.contains(statement))
                generatedDateStatements ++= statementsToAdd

                TransformedFilterPattern(
                    Some(filter),
                    statementsToAdd
                )

            case CompareExpressionOperator.LESS_THAN =>

                // period ends before indicated period
                val filter = CompareExpression(dateValueHasEndVar, CompareExpressionOperator.LESS_THAN, XsdLiteral(dateValueContent.valueHasStartJDN.toString, OntologyConstants.Xsd.Integer.toSmartIri))

                val statementsToAdd = (dateValStartStatementOption.toSeq :+ dateValEndStatement).filterNot(statement => generatedDateStatements.contains(statement)) // dateValStartStatement may be used as ORDER BY statement
                generatedDateStatements ++= statementsToAdd

                TransformedFilterPattern(
                    Some(filter),
                    statementsToAdd
                )

            case CompareExpressionOperator.LESS_THAN_OR_EQUAL_TO =>

                // period ends before indicated period or equals it (any overlap)
                val filter = CompareExpression(dateValueHasStartVar, CompareExpressionOperator.LESS_THAN_OR_EQUAL_TO, XsdLiteral(dateValueContent.valueHasEndJDN.toString, OntologyConstants.Xsd.Integer.toSmartIri))

                val statementToAdd = if (dateValStartStatementOption.nonEmpty && !generatedDateStatements.contains(dateValStartStatementOption.get)) {
                    generatedDateStatements += dateValStartStatementOption.get
                    Seq(dateValStartStatementOption.get)
                } else {
                    Seq.empty[StatementPattern]
                }

                TransformedFilterPattern(
                    Some(filter),
                    statementToAdd
                )

            case CompareExpressionOperator.GREATER_THAN =>

                // period starts after end of indicated period
                val filter = CompareExpression(dateValueHasStartVar, CompareExpressionOperator.GREATER_THAN, XsdLiteral(dateValueContent.valueHasEndJDN.toString, OntologyConstants.Xsd.Integer.toSmartIri))

                val statementToAdd = if (dateValStartStatementOption.nonEmpty && !generatedDateStatements.contains(dateValStartStatementOption.get)) {
                    generatedDateStatements += dateValStartStatementOption.get
                    Seq(dateValStartStatementOption.get)
                } else {
                    Seq.empty[StatementPattern]
                }

                TransformedFilterPattern(
                    Some(filter),
                    statementToAdd
                )

            case CompareExpressionOperator.GREATER_THAN_OR_EQUAL_TO =>

                // period starts after indicated period or equals it (any overlap)
                val filter = CompareExpression(dateValueHasEndVar, CompareExpressionOperator.GREATER_THAN_OR_EQUAL_TO, XsdLiteral(dateValueContent.valueHasStartJDN.toString, OntologyConstants.Xsd.Integer.toSmartIri))

                val statementsToAdd = (dateValStartStatementOption.toSeq :+ dateValEndStatement).filterNot(statement => generatedDateStatements.contains(statement)) // dateValStartStatement may be used as ORDER BY statement
                generatedDateStatements ++= statementsToAdd

                TransformedFilterPattern(
                    Some(filter),
                    statementsToAdd
                )

            case other => throw GravsearchException(s"Invalid operator '$other' in date comparison")

        }

    }

    /**
     * Handles a [[FilterPattern]] containing a query variable.
     *
     * @param queryVar             the query variable.
     * @param compareExpression    the filter pattern's compare expression.
     * @param typeInspectionResult the type inspection results.
     * @return a [[TransformedFilterPattern]].
     */
    private def handleQueryVar(queryVar: QueryVariable, compareExpression: CompareExpression, typeInspectionResult: GravsearchTypeInspectionResult): TransformedFilterPattern = {

        typeInspectionResult.getTypeOfEntity(queryVar) match {
            case Some(typeInfo) =>
                // check if queryVar represents a property or a value
                typeInfo match {

                    case propInfo: PropertyTypeInfo =>

                        // left arg queryVar is a variable representing a property
                        // therefore the right argument must be an IRI restricting the property variable to a certain property
                        compareExpression.rightArg match {
                            case iriRef: IriRef =>

                                handlePropertyIriQueryVar(
                                    queryVar = queryVar,
                                    comparisonOperator = compareExpression.operator,
                                    iriRef = iriRef,
                                    propInfo = propInfo
                                )

                            case other => throw GravsearchException(s"Invalid right argument ${other.toSparql} in comparison (expected a property IRI)")
                        }

                    case nonPropInfo: NonPropertyTypeInfo =>

                        // Is the query using the API v2 simple schema?
                        if (querySchema == ApiV2Simple) {
                            // Yes. Depending on the value type, transform the given Filter pattern.
                            // Add an extra level by getting the value literal from the value object.
                            // If queryVar refers to a value object as a literal, for the value literal an extra variable has to be created, taking its type into account.
                            nonPropInfo.typeIri.toString match {

                                case OntologyConstants.Xsd.Integer =>

                                    handleLiteralQueryVar(
                                        queryVar = queryVar,
                                        comparisonOperator = compareExpression.operator,
                                        literalValueExpression = compareExpression.rightArg,
                                        xsdType = Set(OntologyConstants.Xsd.Integer),
                                        valueHasProperty = OntologyConstants.KnoraBase.ValueHasInteger
                                    )

                                case OntologyConstants.Xsd.Decimal =>

                                    handleLiteralQueryVar(
                                        queryVar = queryVar,
                                        comparisonOperator = compareExpression.operator,
                                        literalValueExpression = compareExpression.rightArg,
                                        xsdType = Set(OntologyConstants.Xsd.Decimal, OntologyConstants.Xsd.Integer), // an integer literal is also valid
                                        valueHasProperty = OntologyConstants.KnoraBase.ValueHasDecimal
                                    )

                                case OntologyConstants.Xsd.DateTimeStamp =>

                                    handleLiteralQueryVar(
                                        queryVar = queryVar,
                                        comparisonOperator = compareExpression.operator,
                                        literalValueExpression = compareExpression.rightArg,
                                        xsdType = Set(OntologyConstants.Xsd.DateTimeStamp),
                                        valueHasProperty = OntologyConstants.KnoraBase.ValueHasTimeStamp
                                    )

                                case OntologyConstants.Xsd.Boolean =>

                                    handleLiteralQueryVar(
                                        queryVar = queryVar,
                                        comparisonOperator = compareExpression.operator,
                                        literalValueExpression = compareExpression.rightArg,
                                        xsdType = Set(OntologyConstants.Xsd.Boolean),
                                        valueHasProperty = OntologyConstants.KnoraBase.ValueHasBoolean,
                                        validComparisonOperators = Set(CompareExpressionOperator.EQUALS, CompareExpressionOperator.NOT_EQUALS)
                                    )

                                case OntologyConstants.Xsd.String =>

                                    handleLiteralQueryVar(
                                        queryVar = queryVar,
                                        comparisonOperator = compareExpression.operator,
                                        literalValueExpression = compareExpression.rightArg,
                                        xsdType = Set(OntologyConstants.Xsd.String),
                                        valueHasProperty = OntologyConstants.KnoraBase.ValueHasString,
                                        validComparisonOperators = Set(CompareExpressionOperator.EQUALS, CompareExpressionOperator.NOT_EQUALS)
                                    )

                                case OntologyConstants.Xsd.Uri =>

                                    handleLiteralQueryVar(
                                        queryVar = queryVar,
                                        comparisonOperator = compareExpression.operator,
                                        literalValueExpression = compareExpression.rightArg,
                                        xsdType = Set(OntologyConstants.Xsd.Uri),
                                        valueHasProperty = OntologyConstants.KnoraBase.ValueHasUri,
                                        validComparisonOperators = Set(CompareExpressionOperator.EQUALS, CompareExpressionOperator.NOT_EQUALS)
                                    )

                                case OntologyConstants.KnoraApiV2Simple.Date =>

                                    handleDateQueryVar(queryVar = queryVar, comparisonOperator = compareExpression.operator, dateValueExpression = compareExpression.rightArg)

                                case OntologyConstants.KnoraApiV2Simple.ListNode =>

                                    handleListQueryVar(queryVar = queryVar, comparisonOperator = compareExpression.operator, literalValueExpression = compareExpression.rightArg)

                                case other => throw NotImplementedException(s"Value type $other not supported in FilterExpression")

                            }

                        } else {
                            // The query is using the complex schema. Keep the expression as it is.
                            TransformedFilterPattern(Some(compareExpression))
                        }

                }

            case None =>
                throw GravsearchException(s"No type information found about ${queryVar.toSparql}")
        }
    }

    /**
     *
     * Handles the use of the SPARQL lang function in a [[FilterPattern]].
     *
     * @param langFunctionCall     the lang function call to be handled.
     * @param compareExpression    the filter pattern's compare expression.
     * @param typeInspectionResult the type inspection results.
     * @return a [[TransformedFilterPattern]].
     */
    private def handleLangFunctionCall(langFunctionCall: LangFunction, compareExpression: CompareExpression, typeInspectionResult: GravsearchTypeInspectionResult): TransformedFilterPattern = {

        if (querySchema == ApiV2Complex) {
            throw GravsearchException(s"The lang function is not allowed in a Gravsearch query that uses the API v2 complex schema")
        }

        // make sure that the query variable represents a text value
        typeInspectionResult.getTypeOfEntity(langFunctionCall.textValueVar) match {
            case Some(typeInfo) =>
                typeInfo match {

                    case nonPropInfo: NonPropertyTypeInfo =>

                        nonPropInfo.typeIri.toString match {

                            case OntologyConstants.Xsd.String => () // xsd:string is expected

                            case _ => throw GravsearchException(s"${langFunctionCall.textValueVar.toSparql} must be an xsd:string")
                        }

                    case _ => throw GravsearchException(s"${langFunctionCall.textValueVar.toSparql} must be an xsd:string")
                }

            case None =>
                throw GravsearchException(s"No type information found about ${langFunctionCall.textValueVar.toSparql}")
        }

        // comparison operator must be '=' or '!='
        if (!Set(CompareExpressionOperator.EQUALS, CompareExpressionOperator.NOT_EQUALS).contains(compareExpression.operator)) throw GravsearchException(s"Comparison operator must be '=' or '!=' for use with a 'lang' function call")

        val langLiteral: XsdLiteral = compareExpression.rightArg match {
            case strLiteral: XsdLiteral if strLiteral.datatype == OntologyConstants.Xsd.String.toSmartIri => strLiteral

            case other => throw GravsearchException(s"Right argument of comparison statement must be a string literal for use with 'lang' function call")
        }

        // Generate a variable name representing the language of the text value
        val textValHasLanguage: QueryVariable = SparqlTransformer.createUniqueVariableNameFromEntityAndProperty(langFunctionCall.textValueVar, OntologyConstants.KnoraBase.ValueHasLanguage)

        // Add a statement to assign the literal to a variable, which we'll use in the transformed FILTER expression,
        // if that statement hasn't been added already.
        val statementToAddForValueHasLanguage = if (addGeneratedVariableForValueLiteral(valueVar = langFunctionCall.textValueVar, generatedVar = textValHasLanguage, useInOrderBy = false)) {
            Seq(
                // connects the value object with the value language code
                StatementPattern.makeExplicit(subj = langFunctionCall.textValueVar, pred = IriRef(OntologyConstants.KnoraBase.ValueHasLanguage.toSmartIri), textValHasLanguage)
            )
        } else {
            Seq.empty[StatementPattern]
        }

        TransformedFilterPattern(
            Some(CompareExpression(textValHasLanguage, compareExpression.operator, langLiteral)),
            statementToAddForValueHasLanguage
        )

    }

    /**
     * Handles the use of the SPARQL regex function in a [[FilterPattern]].
     *
     * @param regexFunctionCall    the regex function call to be handled.
     * @param typeInspectionResult the type inspection results.
     * @return a [[TransformedFilterPattern]].
     */
    private def handleRegexFunctionCall(regexFunctionCall: RegexFunction, typeInspectionResult: GravsearchTypeInspectionResult): TransformedFilterPattern = {

        // If the query uses the API v2 complex schema, leave the function call as it is.
        if (querySchema == ApiV2Complex) {
            TransformedFilterPattern(Some(regexFunctionCall))
        } else {
            // If the query uses only the simple schema, transform the function call.

            // Make sure that the first argument of the regex function is a query variable.
            val regexQueryVar: QueryVariable = regexFunctionCall.textExpr match {
                case queryVar: QueryVariable => queryVar
                case _ => throw GravsearchException(s"First argument of regex function must be a variable")
            }

            // make sure that the query variable (first argument of regex function) represents string literal
            typeInspectionResult.getTypeOfEntity(regexQueryVar) match {
                case Some(typeInfo) =>
                    typeInfo match {

                        case nonPropInfo: NonPropertyTypeInfo =>

                            nonPropInfo.typeIri.toString match {

                                case OntologyConstants.Xsd.String => () // xsd:string is expected, TODO: should also xsd:anyUri be allowed?

                                case _ => throw GravsearchException(s"${regexQueryVar.toSparql} must be of type xsd:string")
                            }

                        case _ => throw GravsearchException(s"${regexQueryVar.toSparql} must be of type NonPropertyTypeInfo")
                    }

                case None =>
                    throw GravsearchException(s"No type information found about ${regexQueryVar.toSparql}")
            }

            // Does the variable refer to resource metadata?
            if (resourceMetadataVariables.contains(regexQueryVar)) {
                // Yes. Leave the expression as is.
                TransformedFilterPattern(
                    Some(RegexFunction(regexQueryVar, regexFunctionCall.pattern, regexFunctionCall.modifier)),
                    Seq.empty
                )
            } else {
                // No, it refers to a TextValue. Generate a variable name representing the string literal.
                val textValHasString: QueryVariable = SparqlTransformer.createUniqueVariableNameFromEntityAndProperty(base = regexQueryVar, propertyIri = OntologyConstants.KnoraBase.ValueHasString)

                // Add a statement to assign the literal to a variable, which we'll use in the transformed FILTER expression,
                // if that statement hasn't been added already.
                val statementToAddForValueHasString: Seq[StatementPattern] = if (addGeneratedVariableForValueLiteral(regexQueryVar, textValHasString)) {
                    Seq(
                        // connects the value object with the value literal
                        StatementPattern.makeExplicit(subj = regexQueryVar, pred = IriRef(OntologyConstants.KnoraBase.ValueHasString.toSmartIri), textValHasString)
                    )
                } else {
                    Seq.empty[StatementPattern]
                }

                TransformedFilterPattern(
                    Some(RegexFunction(textValHasString, regexFunctionCall.pattern, regexFunctionCall.modifier)),
                    statementToAddForValueHasString
                )

            }
        }
    }

    /**
     * Handles the deprecated function `knora-api:match` in the simple schema.
     *
     * @param functionCallExpression the function call to be handled.
     * @param typeInspectionResult   the type inspection results.
     * @param isTopLevel             if `true`, this is the top-level expression in the `FILTER`.
     * @return a [[TransformedFilterPattern]].
     */
    private def handleMatchFunctionInSimpleSchema(functionCallExpression: FunctionCallExpression, typeInspectionResult: GravsearchTypeInspectionResult, isTopLevel: Boolean): TransformedFilterPattern = {
        val functionIri: SmartIri = functionCallExpression.functionIri.iri

        if (querySchema == ApiV2Complex) {
            throw GravsearchException(s"Function ${functionIri.toSparql} cannot be used in a Gravsearch query written in the complex schema; use ${OntologyConstants.KnoraApiV2Complex.MatchFunction.toSmartIri.toSparql} instead")
        }

        // The match function must be the top-level expression, otherwise boolean logic won't work properly.
        if (!isTopLevel) {
            throw GravsearchException(s"Function ${functionIri.toSparql} must be the top-level expression in a FILTER")
        }

        // two arguments are expected: the first must be a variable representing a string value,
        // the second must be a string literal

        if (functionCallExpression.args.size != 2) throw GravsearchException(s"Two arguments are expected for ${functionIri.toSparql}")

        // a QueryVariable expected to represent a text value
        val textValueVar: QueryVariable = functionCallExpression.getArgAsQueryVar(pos = 0)

        typeInspectionResult.getTypeOfEntity(textValueVar) match {
            case Some(nonPropInfo: NonPropertyTypeInfo) =>

                nonPropInfo.typeIri.toString match {

                    case OntologyConstants.Xsd.String => () // xsd:string is expected, TODO: should also xsd:anyUri be allowed?

                    case _ => throw GravsearchException(s"${textValueVar.toSparql} must be an xsd:string")
                }

            case _ => throw GravsearchException(s"${textValueVar.toSparql} must be an xsd:string")
        }

        val textValHasString: QueryVariable = SparqlTransformer.createUniqueVariableNameFromEntityAndProperty(base = textValueVar, propertyIri = OntologyConstants.KnoraBase.ValueHasString)

        // Add a statement to assign the literal to a variable, which we'll use in the transformed FILTER expression,
        // if that statement hasn't been added already.
        val valueHasStringStatement = if (addGeneratedVariableForValueLiteral(textValueVar, textValHasString)) {
            Seq(StatementPattern.makeExplicit(subj = textValueVar, pred = IriRef(OntologyConstants.KnoraBase.ValueHasString.toSmartIri), textValHasString))
        } else {
            Seq.empty[StatementPattern]
        }

        val searchTerm: XsdLiteral = functionCallExpression.getArgAsLiteral(1, xsdDatatype = OntologyConstants.Xsd.String.toSmartIri)

        val searchTerms: LuceneQueryString = LuceneQueryString(searchTerm.value)

        // Replace the filter with a statement using the deprecated knora-base:matchesTextIndex property.
        TransformedFilterPattern(
            None, // FILTER has been replaced by statements
            valueHasStringStatement ++ Seq(
                StatementPattern.makeExplicit(
                    subj = textValHasString,
                    pred = IriRef(OntologyConstants.KnoraBase.MatchesTextIndex.toSmartIri),
                    obj = XsdLiteral(searchTerms.getQueryString, OntologyConstants.Xsd.String.toSmartIri)
                )
            )
        )
    }

    /**
     * Handles the function `knora-api:matchText` in the simple schema.
     *
     * @param functionCallExpression the function call to be handled.
     * @param typeInspectionResult   the type inspection results.
     * @param isTopLevel             if `true`, this is the top-level expression in the `FILTER`.
     * @return a [[TransformedFilterPattern]].
     */
    private def handleMatchTextFunctionInSimpleSchema(functionCallExpression: FunctionCallExpression, typeInspectionResult: GravsearchTypeInspectionResult, isTopLevel: Boolean): TransformedFilterPattern = {
        val functionIri: SmartIri = functionCallExpression.functionIri.iri

        if (querySchema == ApiV2Complex) {
            throw GravsearchException(s"Function ${functionIri.toSparql} cannot be used in a Gravsearch query written in the complex schema; use ${OntologyConstants.KnoraApiV2Complex.MatchTextFunction.toSmartIri.toSparql} instead")
        }

        // The match function must be the top-level expression, otherwise boolean logic won't work properly.
        if (!isTopLevel) {
            throw GravsearchException(s"Function ${functionIri.toSparql} must be the top-level expression in a FILTER")
        }

        // two arguments are expected: the first must be a variable representing a string value,
        // the second must be a string literal

        if (functionCallExpression.args.size != 2) throw GravsearchException(s"Two arguments are expected for ${functionIri.toSparql}")

        // a QueryVariable expected to represent a text value
        val textValueVar: QueryVariable = functionCallExpression.getArgAsQueryVar(pos = 0)

        typeInspectionResult.getTypeOfEntity(textValueVar) match {
            case Some(nonPropInfo: NonPropertyTypeInfo) =>

                nonPropInfo.typeIri.toString match {

                    case OntologyConstants.Xsd.String => () // xsd:string is expected, TODO: should also xsd:anyUri be allowed?

                    case _ => throw GravsearchException(s"${textValueVar.toSparql} must be an xsd:string")
                }

            case _ => throw GravsearchException(s"${textValueVar.toSparql} must be an xsd:string")
        }

        val textValHasString: QueryVariable = SparqlTransformer.createUniqueVariableNameFromEntityAndProperty(base = textValueVar, propertyIri = OntologyConstants.KnoraBase.ValueHasString)

        // Add a statement to assign the literal to a variable, which we'll use in the transformed FILTER expression,
        // if that statement hasn't been added already.
        val valueHasStringStatement = if (addGeneratedVariableForValueLiteral(textValueVar, textValHasString)) {
            Seq(StatementPattern.makeExplicit(subj = textValueVar, pred = IriRef(OntologyConstants.KnoraBase.ValueHasString.toSmartIri), textValHasString))
        } else {
            Seq.empty[StatementPattern]
        }

        val searchTerm: XsdLiteral = functionCallExpression.getArgAsLiteral(1, xsdDatatype = OntologyConstants.Xsd.String.toSmartIri)

        val searchTerms: LuceneQueryString = LuceneQueryString(searchTerm.value)

        // Replace the filter with a LuceneQueryPattern.
        TransformedFilterPattern(
            None, // FILTER has been replaced by statements
            valueHasStringStatement :+ LuceneQueryPattern(
                subj = textValueVar,
                obj = textValHasString,
                queryString = searchTerms
            )
        )
    }

    /**
     * Handles the deprecated function `knora-api:match` in the complex schema.
     *
     * @param functionCallExpression the function call to be handled.
     * @param typeInspectionResult   the type inspection results.
     * @param isTopLevel             if `true`, this is the top-level expression in the `FILTER`.
     * @return a [[TransformedFilterPattern]].
     */
    private def handleMatchFunctionInComplexSchema(functionCallExpression: FunctionCallExpression, typeInspectionResult: GravsearchTypeInspectionResult, isTopLevel: Boolean): TransformedFilterPattern = {
        val functionIri: SmartIri = functionCallExpression.functionIri.iri

        if (querySchema == ApiV2Simple) {
            throw GravsearchException(s"Function ${functionIri.toSparql} cannot be used in a Gravsearch query written in the simple schema; use ${OntologyConstants.KnoraApiV2Simple.MatchFunction.toSmartIri.toSparql} instead")
        }

        // The match function must be the top-level expression, otherwise boolean logic won't work properly.
        if (!isTopLevel) {
            throw GravsearchException(s"Function ${functionIri.toSparql} must be the top-level expression in a FILTER")
        }

        // two arguments are expected: the first must be a variable representing a string value,
        // the second must be a string literal

        if (functionCallExpression.args.size != 2) throw GravsearchException(s"Two arguments are expected for ${functionIri.toSparql}")

        // a QueryVariable expected to represent a string
        val stringVar: QueryVariable = functionCallExpression.getArgAsQueryVar(pos = 0)

        val searchTermStr: XsdLiteral = functionCallExpression.getArgAsLiteral(1, xsdDatatype = OntologyConstants.Xsd.String.toSmartIri)

        val searchTerms: LuceneQueryString = LuceneQueryString(searchTermStr.value)

        // Replace the filter with a statement using the deprecated knora-base:matchesTextIndex property.
        TransformedFilterPattern(
            None, // FILTER has been replaced by statements
            Seq(
                StatementPattern.makeExplicit(
                    subj = stringVar,
                    pred = IriRef(OntologyConstants.KnoraBase.MatchesTextIndex.toSmartIri),
                    XsdLiteral(searchTerms.getQueryString, OntologyConstants.Xsd.String.toSmartIri)
                )
            )
        )
    }

    /**
     * Handles the function `knora-api:matchText` in the complex schema.
     *
     * @param functionCallExpression the function call to be handled.
     * @param typeInspectionResult   the type inspection results.
     * @param isTopLevel             if `true`, this is the top-level expression in the `FILTER`.
     * @return a [[TransformedFilterPattern]].
     */
    private def handleMatchTextFunctionInComplexSchema(functionCallExpression: FunctionCallExpression, typeInspectionResult: GravsearchTypeInspectionResult, isTopLevel: Boolean): TransformedFilterPattern = {
        val functionIri: SmartIri = functionCallExpression.functionIri.iri

        if (querySchema == ApiV2Simple) {
            throw GravsearchException(s"Function ${functionIri.toSparql} cannot be used in a Gravsearch query written in the simple schema; use ${OntologyConstants.KnoraApiV2Simple.MatchTextFunction.toSmartIri.toSparql} instead")
        }

        // The match function must be the top-level expression, otherwise boolean logic won't work properly.
        if (!isTopLevel) {
            throw GravsearchException(s"Function ${functionIri.toSparql} must be the top-level expression in a FILTER")
        }

        // two arguments are expected: the first must be a variable representing a text value,
        // the second must be a string literal

        if (functionCallExpression.args.size != 2) throw GravsearchException(s"Two arguments are expected for ${functionIri.toSparql}")

        // a QueryVariable expected to represent a text value
        val textValueVar: QueryVariable = functionCallExpression.getArgAsQueryVar(pos = 0)

        typeInspectionResult.getTypeOfEntity(textValueVar) match {
            case Some(nonPropInfo: NonPropertyTypeInfo) =>

                nonPropInfo.typeIri.toString match {

                    case OntologyConstants.KnoraApiV2Complex.TextValue => ()

                    case _ => throw GravsearchException(s"${textValueVar.toSparql} must be a knora-api:TextValue")
                }

            case _ => throw GravsearchException(s"${textValueVar.toSparql} must be a knora-api:TextValue")
        }

        val textValHasString: QueryVariable = SparqlTransformer.createUniqueVariableNameFromEntityAndProperty(base = textValueVar, propertyIri = OntologyConstants.KnoraBase.ValueHasString)

        // Add a statement to assign the literal to a variable, which we'll use in the transformed FILTER expression,
        // if that statement hasn't been added already.
        val valueHasStringStatement = if (addGeneratedVariableForValueLiteral(textValueVar, textValHasString)) {
            Seq(StatementPattern.makeExplicit(subj = textValueVar, pred = IriRef(OntologyConstants.KnoraBase.ValueHasString.toSmartIri), textValHasString))
        } else {
            Seq.empty[StatementPattern]
        }

        val searchTerm: XsdLiteral = functionCallExpression.getArgAsLiteral(1, xsdDatatype = OntologyConstants.Xsd.String.toSmartIri)

        val searchTerms: LuceneQueryString = LuceneQueryString(searchTerm.value)

        // Replace the filter with a LuceneQueryPattern.
        TransformedFilterPattern(
            None, // FILTER has been replaced by statements
            valueHasStringStatement :+ LuceneQueryPattern(
                subj = textValueVar,
                obj = textValHasString,
                queryString = searchTerms
            )
        )
    }

    /**
     * Handles the deprecated function `knora-api:matchInStandoff`.
     *
     * @param functionCallExpression the function call to be handled.
     * @param typeInspectionResult   the type inspection results.
     * @param isTopLevel             if `true`, this is the top-level expression in the `FILTER`.
     * @return a [[TransformedFilterPattern]].
     */
    private def handleMatchInStandoffFunction(functionCallExpression: FunctionCallExpression, typeInspectionResult: GravsearchTypeInspectionResult, isTopLevel: Boolean): TransformedFilterPattern = {
        val functionIri: SmartIri = functionCallExpression.functionIri.iri

        if (querySchema == ApiV2Simple) {
            throw GravsearchException(s"Function ${functionIri.toSparql} cannot be used in a Gravsearch query written in the simple schema")
        }

        if (!isTopLevel) {
            throw GravsearchException(s"Function ${functionIri.toSparql} must be the top-level expression in a FILTER")
        }

        // Three arguments are expected:
        // 1. a variable representing the string literal value of the text value
        // 2. a variable representing the standoff tag
        // 3. a string literal containing space-separated search terms

        if (functionCallExpression.args.size != 3) throw GravsearchException(s"Three arguments are expected for ${functionIri.toSparql}")

        // A variable representing the object of the text value's valueHasString.
        val textValueStringLiteralVar: QueryVariable = functionCallExpression.getArgAsQueryVar(pos = 0)

        // A variable representing the standoff tag.
        val standoffTagVar: QueryVariable = functionCallExpression.getArgAsQueryVar(pos = 1)

        // A string literal representing the search terms.
        val searchTermStr: XsdLiteral = functionCallExpression.getArgAsLiteral(pos = 2, xsdDatatype = OntologyConstants.Xsd.String.toSmartIri)

        val searchTerms: LuceneQueryString = LuceneQueryString(searchTermStr.value)

        // Generate a statement to search the full-text search index, using the deprecated virtual predicate
        // knora-base:matchesTextIndex, to assert that text value contains the search terms.
        val fullTextSearchStatement: Seq[StatementPattern] = Seq(
            StatementPattern.makeInferred(
                subj = textValueStringLiteralVar,
                pred = IriRef(OntologyConstants.KnoraBase.MatchesTextIndex.toSmartIri),
                XsdLiteral(searchTerms.getQueryString, OntologyConstants.Xsd.String.toSmartIri)
            )
        )

        // Generate query patterns to assign the text in the standoff tag to a variable, if we
        // haven't done so already.

        val startVariable = QueryVariable(standoffTagVar.variableName + "__start")
        val endVariable = QueryVariable(standoffTagVar.variableName + "__end")

        val markedUpPatternsToAdd: Seq[QueryPattern] = if (!standoffMarkedUpVariables.contains(startVariable)) {
            standoffMarkedUpVariables += startVariable

            Seq(
                // ?standoffTag knora-base:standoffTagHasStart ?standoffTag__start .
                StatementPattern.makeExplicit(standoffTagVar, IriRef(OntologyConstants.KnoraBase.StandoffTagHasStart.toSmartIri), startVariable),
                // ?standoffTag knora-base:standoffTagHasEnd ?standoffTag__end .
                StatementPattern.makeExplicit(standoffTagVar, IriRef(OntologyConstants.KnoraBase.StandoffTagHasEnd.toSmartIri), endVariable)
            )
        } else {
            Seq.empty[QueryPattern]
        }

        // Generate a FILTER pattern for each search term, using the regex function to assert that the text in the
        // standoff tag contains the term:
        // FILTER REGEX(SUBSTR(?textValueStr, ?standoffTag__start + 1, ?standoffTag__end - ?standoffTag__start), 'term', "i")
        // TODO: handle the differences between regex syntax and Lucene syntax.
        val regexFilters: Seq[FilterPattern] = searchTerms.getSingleTerms.map {
            term: String =>
                FilterPattern(
                    expression = RegexFunction(
                        textExpr = SubStrFunction(
                            textLiteralVar = textValueStringLiteralVar,
                            startExpression = ArithmeticExpression(
                                leftArg = startVariable,
                                operator = PlusOperator,
                                rightArg = IntegerLiteral(1)
                            ),
                            lengthExpression = ArithmeticExpression(
                                leftArg = endVariable,
                                operator = MinusOperator,
                                rightArg = startVariable
                            )
                        ),
                        pattern = term, // TODO: Ignore Lucene operators
                        modifier = Some("i")
                    )
                )
        }

        TransformedFilterPattern(
            expression = None, // The expression has been replaced by additional patterns.
            additionalPatterns = fullTextSearchStatement ++ markedUpPatternsToAdd ++ regexFilters
        )
    }

    /**
     * Handles the function `knora-api:matchTextInStandoff`.
     *
     * @param functionCallExpression the function call to be handled.
     * @param typeInspectionResult   the type inspection results.
     * @param isTopLevel             if `true`, this is the top-level expression in the `FILTER`.
     * @return a [[TransformedFilterPattern]].
     */
    private def handleMatchTextInStandoffFunction(functionCallExpression: FunctionCallExpression, typeInspectionResult: GravsearchTypeInspectionResult, isTopLevel: Boolean): TransformedFilterPattern = {
        val functionIri: SmartIri = functionCallExpression.functionIri.iri

        if (querySchema == ApiV2Simple) {
            throw GravsearchException(s"Function ${functionIri.toSparql} cannot be used in a Gravsearch query written in the simple schema")
        }

        if (!isTopLevel) {
            throw GravsearchException(s"Function ${functionIri.toSparql} must be the top-level expression in a FILTER")
        }

        // Three arguments are expected:
        // 1. a variable representing the text value
        // 2. a variable representing the standoff tag
        // 3. a string literal containing space-separated search terms

        if (functionCallExpression.args.size != 3) throw GravsearchException(s"Three arguments are expected for ${functionIri.toSparql}")

        // a QueryVariable expected to represent a text value
        val textValueVar: QueryVariable = functionCallExpression.getArgAsQueryVar(pos = 0)

        typeInspectionResult.getTypeOfEntity(textValueVar) match {
            case Some(nonPropInfo: NonPropertyTypeInfo) =>

                nonPropInfo.typeIri.toString match {

                    case OntologyConstants.KnoraApiV2Complex.TextValue => ()

                    case _ => throw GravsearchException(s"${textValueVar.toSparql} must be a knora-api:TextValue")
                }

            case _ => throw GravsearchException(s"${textValueVar.toSparql} must be a knora-api:TextValue")
        }

        val textValHasString: QueryVariable = SparqlTransformer.createUniqueVariableNameFromEntityAndProperty(base = textValueVar, propertyIri = OntologyConstants.KnoraBase.ValueHasString)

        // Add a statement to assign the literal to a variable, which we'll use in the transformed FILTER expression,
        // if that statement hasn't been added already.
        val valueHasStringStatement = if (addGeneratedVariableForValueLiteral(textValueVar, textValHasString)) {
            Seq(StatementPattern.makeExplicit(subj = textValueVar, pred = IriRef(OntologyConstants.KnoraBase.ValueHasString.toSmartIri), textValHasString))
        } else {
            Seq.empty[StatementPattern]
        }

        // A string literal representing the search terms.
        val searchTermStr: XsdLiteral = functionCallExpression.getArgAsLiteral(pos = 2, xsdDatatype = OntologyConstants.Xsd.String.toSmartIri)

        val searchTerms: LuceneQueryString = LuceneQueryString(searchTermStr.value)

        // Generate a LuceneQueryPattern to search the full-text search index, to assert that text value contains
        // the search terms.
        val luceneQueryPattern: LuceneQueryPattern = LuceneQueryPattern(
            subj = textValueVar,
            obj = textValHasString,
            queryString = searchTerms
        )

        // Generate query patterns to assign the text in the standoff tag to a variable, if we
        // haven't done so already.

        // A variable representing the standoff tag.
        val standoffTagVar: QueryVariable = functionCallExpression.getArgAsQueryVar(pos = 1)

        val startVariable = QueryVariable(standoffTagVar.variableName + "__start")
        val endVariable = QueryVariable(standoffTagVar.variableName + "__end")

        val markedUpPatternsToAdd: Seq[QueryPattern] = if (!standoffMarkedUpVariables.contains(startVariable)) {
            standoffMarkedUpVariables += startVariable

            Seq(
                // ?standoffTag knora-base:standoffTagHasStart ?standoffTag__start .
                StatementPattern.makeExplicit(standoffTagVar, IriRef(OntologyConstants.KnoraBase.StandoffTagHasStart.toSmartIri), startVariable),
                // ?standoffTag knora-base:standoffTagHasEnd ?standoffTag__end .
                StatementPattern.makeExplicit(standoffTagVar, IriRef(OntologyConstants.KnoraBase.StandoffTagHasEnd.toSmartIri), endVariable)
            )
        } else {
            Seq.empty[QueryPattern]
        }

        // Generate a FILTER pattern for each search term, using the regex function to assert that the text in the
        // standoff tag contains the term:
        // FILTER REGEX(SUBSTR(?textValueStr, ?standoffTag__start + 1, ?standoffTag__end - ?standoffTag__start), 'term', "i")
        // TODO: handle the differences between regex syntax and Lucene syntax.
        val regexFilters: Seq[FilterPattern] = searchTerms.getSingleTerms.map {
            term: String =>
                FilterPattern(
                    expression = RegexFunction(
                        textExpr = SubStrFunction(
                            textLiteralVar = textValHasString,
                            startExpression = ArithmeticExpression(
                                leftArg = startVariable,
                                operator = PlusOperator,
                                rightArg = IntegerLiteral(1)
                            ),
                            lengthExpression = ArithmeticExpression(
                                leftArg = endVariable,
                                operator = MinusOperator,
                                rightArg = startVariable
                            )
                        ),
                        pattern = term, // TODO: Ignore Lucene operators
                        modifier = Some("i")
                    )
                )
        }

        TransformedFilterPattern(
            expression = None, // The expression has been replaced by additional patterns.
            additionalPatterns = (valueHasStringStatement :+ luceneQueryPattern) ++ markedUpPatternsToAdd ++ regexFilters
        )
    }


    /**
     * Checks that the query is in the simple schema, then calls `handleMatchLabelFunction`.
     *
     * @param functionCallExpression the function call to be handled.
     * @param typeInspectionResult   the type inspection results.
     * @param isTopLevel             if `true`, this is the top-level expression in the `FILTER`.
     * @return a [[TransformedFilterPattern]].
     */
    private def handleMatchLabelFunctionInSimpleSchema(functionCallExpression: FunctionCallExpression, typeInspectionResult: GravsearchTypeInspectionResult, isTopLevel: Boolean): TransformedFilterPattern = {
        val functionIri: SmartIri = functionCallExpression.functionIri.iri

        if (querySchema == ApiV2Complex) {
            throw GravsearchException(s"Function ${functionIri.toSparql} cannot be used in a Gravsearch query written in the complex schema; use ${OntologyConstants.KnoraApiV2Complex.MatchLabelFunction.toSmartIri.toSparql} instead")
        }

        handleMatchLabelFunction(
            functionCallExpression = functionCallExpression,
            typeInspectionResult = typeInspectionResult,
            isTopLevel = isTopLevel
        )
    }

    /**
     * Checks that the query is in the complex schema, then calls `handleMatchLabelFunction`.
     *
     * @param functionCallExpression the function call to be handled.
     * @param typeInspectionResult   the type inspection results.
     * @param isTopLevel             if `true`, this is the top-level expression in the `FILTER`.
     * @return a [[TransformedFilterPattern]].
     */
    private def handleMatchLabelFunctionInComplexSchema(functionCallExpression: FunctionCallExpression, typeInspectionResult: GravsearchTypeInspectionResult, isTopLevel: Boolean): TransformedFilterPattern = {
        val functionIri: SmartIri = functionCallExpression.functionIri.iri

        if (querySchema == ApiV2Simple) {
            throw GravsearchException(s"Function ${functionIri.toSparql} cannot be used in a Gravsearch query written in the simple schema; use ${OntologyConstants.KnoraApiV2Simple.MatchLabelFunction.toSmartIri.toSparql} instead")
        }

        handleMatchLabelFunction(
            functionCallExpression = functionCallExpression,
            typeInspectionResult = typeInspectionResult,
            isTopLevel = isTopLevel
        )
    }

    /**
     * Handles the function `knora-api:matchLabel` in either schema.
     *
     * @param functionCallExpression the function call to be handled.
     * @param typeInspectionResult   the type inspection results.
     * @param isTopLevel             if `true`, this is the top-level expression in the `FILTER`.
     * @return a [[TransformedFilterPattern]].
     */
    private def handleMatchLabelFunction(functionCallExpression: FunctionCallExpression, typeInspectionResult: GravsearchTypeInspectionResult, isTopLevel: Boolean): TransformedFilterPattern = {
        val functionIri: SmartIri = functionCallExpression.functionIri.iri

        // The matchLabel function must be the top-level expression, otherwise boolean logic won't work properly.
        if (!isTopLevel) {
            throw GravsearchException(s"Function ${functionIri.toSparql} must be the top-level expression in a FILTER")
        }

        // Two arguments are expected:
        // 1. a variable representing a resource
        // 2. a string literal

        if (functionCallExpression.args.size != 2) throw GravsearchException(s"Two arguments are expected for ${functionIri.toSparql}")

        // A QueryVariable expected to represent a resource.
        val resourceVar: QueryVariable = functionCallExpression.getArgAsQueryVar(pos = 0)

        typeInspectionResult.getTypeOfEntity(resourceVar) match {
            case Some(nonPropInfo: NonPropertyTypeInfo) if OntologyConstants.KnoraApi.isKnoraApiV2Resource(nonPropInfo.typeIri) => ()
            case _ => throw GravsearchException(s"${resourceVar.toSparql} must be a knora-api:Resource")
        }

        // Add a statement to assign the literal to a variable, which we'll use in the transformed FILTER expression,
        // if that statement hasn't been added already.

        val rdfsLabelVar: QueryVariable = SparqlTransformer.createUniqueVariableNameFromEntityAndProperty(base = resourceVar, propertyIri = OntologyConstants.Rdfs.Label)

        val rdfsLabelStatement = if (addGeneratedVariableForValueLiteral(resourceVar, rdfsLabelVar)) {
            Seq(StatementPattern.makeExplicit(subj = resourceVar, pred = IriRef(OntologyConstants.Rdfs.Label.toSmartIri), rdfsLabelVar))
        } else {
            Seq.empty[StatementPattern]
        }

        val searchTerm: XsdLiteral = functionCallExpression.getArgAsLiteral(1, xsdDatatype = OntologyConstants.Xsd.String.toSmartIri)
        val luceneQueryString: LuceneQueryString = LuceneQueryString(searchTerm.value)

        // Replace the filter with a LuceneQueryPattern.
        TransformedFilterPattern(
            None, // The FILTER has been replaced by statements.
            rdfsLabelStatement :+ LuceneQueryPattern(
                subj = resourceVar,
                obj = rdfsLabelVar,
                queryString = luceneQueryString
            )
        )
    }

    /**
     * Handles the function `knora-api:StandoffLink`.
     *
     * @param functionCallExpression the function call to be handled.
     * @param typeInspectionResult   the type inspection results.
     * @param isTopLevel             if `true`, this is the top-level expression in the `FILTER`.
     * @return a [[TransformedFilterPattern]].
     */
    private def handleStandoffLinkFunction(functionCallExpression: FunctionCallExpression, typeInspectionResult: GravsearchTypeInspectionResult, isTopLevel: Boolean): TransformedFilterPattern = {
        val functionIri: SmartIri = functionCallExpression.functionIri.iri

        if (querySchema == ApiV2Simple) {
            throw GravsearchException(s"Function ${functionIri.toSparql} cannot be used in a Gravsearch query written in the simple schema")
        }

        if (!isTopLevel) {
            throw GravsearchException(s"Function ${functionIri.toSparql} must be the top-level expression in a FILTER")
        }

        // Three arguments are expected:
        // 1. a variable or IRI representing the resource that is the source of the link
        // 2. a variable representing the standoff link tag
        // 3. a variable or IRI representing the resource that is the target of the link

        if (functionCallExpression.args.size != 3) throw GravsearchException(s"Three arguments are expected for ${functionIri.toSparql}")

        // A variable or IRI representing the resource that is the source of the link.
        val linkSourceEntity = functionCallExpression.args.head match {
            case queryVar: QueryVariable => queryVar
            case iriRef: IriRef => iriRef
            case _ => throw GravsearchException(s"The first argument of ${functionIri.toSparql} must be a variable or IRI")
        }

        typeInspectionResult.getTypeOfEntity(linkSourceEntity) match {
            case Some(nonPropertyTypeInfo: NonPropertyTypeInfo) if nonPropertyTypeInfo.isResourceType => ()
            case _ => throw GravsearchException(s"The first argument of ${functionIri.toSparql} must represent a knora-api:Resource")
        }

        // A variable representing the standoff link tag.
        val standoffTagVar = functionCallExpression.getArgAsQueryVar(pos = 1)

        typeInspectionResult.getTypeOfEntity(standoffTagVar) match {
            case Some(NonPropertyTypeInfo(typeIri)) if typeIri.toString == OntologyConstants.KnoraApiV2Complex.StandoffTag => ()
            case _ => throw GravsearchException(s"The second argument of ${functionIri.toSparql} must represent a knora-api:StandoffTag")
        }

        val linkTargetEntity = functionCallExpression.args(2) match {
            case queryVar: QueryVariable => queryVar
            case iriRef: IriRef => iriRef
            case _ => throw GravsearchException(s"The third argument of ${functionIri.toSparql} must be a variable or IRI")
        }

        val statementsForTargetResource: Seq[QueryPattern] = typeInspectionResult.getTypeOfEntity(linkTargetEntity) match {
            case Some(nonPropertyTpeInfo: NonPropertyTypeInfo) if nonPropertyTpeInfo.isResourceType =>

                // process the entity representing the target of the link
                createAdditionalStatementsForNonPropertyType(nonPropertyTpeInfo, linkTargetEntity)

            case _ => throw GravsearchException(s"The third argument of ${functionIri.toSparql} must represent a knora-api:Resource")
        }

        val hasStandoffLinkToIriRef = IriRef(OntologyConstants.KnoraBase.HasStandoffLinkTo.toSmartIri)

        // Generate statements linking the source resource and the standoff tag to the target resource.
        val linkStatements = Seq(
            StatementPattern.makeExplicit(subj = linkSourceEntity, pred = hasStandoffLinkToIriRef, obj = linkTargetEntity),
            StatementPattern.makeInferred(subj = standoffTagVar, pred = IriRef(OntologyConstants.KnoraBase.StandoffTagHasLink.toSmartIri), obj = linkTargetEntity)
        )

        // Generate statements matching the link value that describes the standoff link between the source and target resources.
        val statementsForLinkValue: Seq[StatementPattern] = generateStatementsForLinkValue(
            linkSource = linkSourceEntity,
            linkPred = hasStandoffLinkToIriRef,
            linkTarget = linkTargetEntity
        )

        TransformedFilterPattern(
            None, // FILTER has been replaced with statements
            linkStatements ++ statementsForLinkValue ++ statementsForTargetResource
        )
    }

    /**
     *
     * Handles a Gravsearch-specific function call in a [[FilterPattern]].
     *
     * @param functionCallExpression the function call to be handled.
     * @param typeInspectionResult   the type inspection results.
     * @param isTopLevel             if `true`, this is the top-level expression in the `FILTER`.
     * @return a [[TransformedFilterPattern]].
     */
    private def handleKnoraFunctionCall(functionCallExpression: FunctionCallExpression, typeInspectionResult: GravsearchTypeInspectionResult, isTopLevel: Boolean): TransformedFilterPattern = {
        val functionIri: SmartIri = functionCallExpression.functionIri.iri

        // Get a Scala function that implements the Gravsearch function.
        val functionFunction: (FunctionCallExpression, GravsearchTypeInspectionResult, Boolean) => TransformedFilterPattern = functionIri.toString match {
            case OntologyConstants.KnoraApiV2Simple.MatchFunction => handleMatchFunctionInSimpleSchema // deprecated
            case OntologyConstants.KnoraApiV2Complex.MatchFunction => handleMatchFunctionInComplexSchema // deprecated
            case OntologyConstants.KnoraApiV2Complex.MatchInStandoffFunction => handleMatchInStandoffFunction // deprecated
            case OntologyConstants.KnoraApiV2Simple.MatchTextFunction => handleMatchTextFunctionInSimpleSchema
            case OntologyConstants.KnoraApiV2Complex.MatchTextFunction => handleMatchTextFunctionInComplexSchema
            case OntologyConstants.KnoraApiV2Simple.MatchLabelFunction => handleMatchLabelFunctionInSimpleSchema
            case OntologyConstants.KnoraApiV2Complex.MatchLabelFunction => handleMatchLabelFunctionInComplexSchema
            case OntologyConstants.KnoraApiV2Complex.MatchTextInStandoffFunction => handleMatchTextInStandoffFunction
            case OntologyConstants.KnoraApiV2Complex.StandoffLinkFunction => handleStandoffLinkFunction
            case OntologyConstants.KnoraApiV2Complex.ToSimpleDateFunction =>
                throw GravsearchException(s"Function ${functionIri.toSparql} must be used in a comparison expression")

            case _ => throw NotImplementedException(s"Function ${functionCallExpression.functionIri} not found")
        }

        // Call the Scala function.
        functionFunction(
            functionCallExpression,
            typeInspectionResult,
            isTopLevel
        )
    }

    /**
     * Handles the `knora-api:toSimpleDate` function in a comparison.
     *
     * @param filterCompare        the comparison expression.
     * @param functionCallExpr     the function call expression.
     * @param typeInspectionResult the type inspection result.
     * @return a [[TransformedFilterPattern]].
     */
    private def handleToSimpleDateFunction(filterCompare: CompareExpression, functionCallExpr: FunctionCallExpression, typeInspectionResult: GravsearchTypeInspectionResult): TransformedFilterPattern = {
        if (querySchema == ApiV2Simple) {
            throw GravsearchException(s"Function ${functionCallExpr.functionIri.toSparql} cannot be used in a query written in the simple schema")
        }

        if (functionCallExpr.args.size != 1) throw GravsearchException(s"One argument is expected for ${functionCallExpr.functionIri.toSparql}")

        // One argument is expected: a QueryVariable representing something that belongs to a subclass of knora-api:DateBase.
        val dateBaseVar: QueryVariable = functionCallExpr.getArgAsQueryVar(pos = 0)

        typeInspectionResult.getTypeOfEntity(dateBaseVar) match {
            case Some(nonPropInfo: NonPropertyTypeInfo) =>
                if (!dateTypes.contains(nonPropInfo.typeIri.toString)) {
                    throw GravsearchException(s"${dateBaseVar.toSparql} must represent a knora-api:DateValue or a knora-api:StandoffDateTag")
                }

            case _ => throw GravsearchException(s"${dateBaseVar.toSparql} must represent a knora-api:DateValue or a knora-api:StandoffDateTag")
        }

        handleDateQueryVar(queryVar = dateBaseVar, comparisonOperator = filterCompare.operator, dateValueExpression = filterCompare.rightArg)
    }

    /**
     * Transforms a Filter expression provided in the input query (knora-api simple) into a knora-base compliant Filter expression.
     *
     * @param filterExpression     the `FILTER` expression to be transformed.
     * @param typeInspectionResult the results of type inspection.
     * @return a [[TransformedFilterPattern]].
     */
    protected def transformFilterPattern(filterExpression: Expression, typeInspectionResult: GravsearchTypeInspectionResult, isTopLevel: Boolean): TransformedFilterPattern = {

        filterExpression match {

            case filterCompare: CompareExpression =>

                // left argument of a CompareExpression must be a QueryVariable or a function call
                filterCompare.leftArg match {

                    case queryVar: QueryVariable =>
                        handleQueryVar(queryVar = queryVar, compareExpression = filterCompare, typeInspectionResult = typeInspectionResult)

                    case functionCallExpr: FunctionCallExpression if functionCallExpr.functionIri.iri.toString == OntologyConstants.KnoraApiV2Complex.ToSimpleDateFunction =>
                        handleToSimpleDateFunction(
                            filterCompare = filterCompare,
                            functionCallExpr = functionCallExpr,
                            typeInspectionResult = typeInspectionResult
                        )

                    case lang: LangFunction =>
                        handleLangFunctionCall(langFunctionCall = lang, compareExpression = filterCompare, typeInspectionResult = typeInspectionResult)

                    case other => throw GravsearchException(s"Invalid left argument ${other.toSparql} in comparison")
                }


            case filterOr: OrExpression =>
                // recursively call this method for both arguments
                val filterExpressionLeft: TransformedFilterPattern = transformFilterPattern(filterOr.leftArg, typeInspectionResult, isTopLevel = false)
                val filterExpressionRight: TransformedFilterPattern = transformFilterPattern(filterOr.rightArg, typeInspectionResult, isTopLevel = false)

                // recreate Or expression and include additional statements
                TransformedFilterPattern(
                    Some(OrExpression(filterExpressionLeft.expression.getOrElse(throw DataConversionException("Expression was expected from previous FILTER conversion, but None given")), filterExpressionRight.expression.getOrElse(throw DataConversionException("Expression was expected from previous FILTER conversion, but None given")))),
                    filterExpressionLeft.additionalPatterns ++ filterExpressionRight.additionalPatterns
                )


            case filterAnd: AndExpression =>
                // recursively call this method for both arguments
                val filterExpressionLeft: TransformedFilterPattern = transformFilterPattern(filterAnd.leftArg, typeInspectionResult, isTopLevel = false)
                val filterExpressionRight: TransformedFilterPattern = transformFilterPattern(filterAnd.rightArg, typeInspectionResult, isTopLevel = false)

                // recreate And expression and include additional statements
                TransformedFilterPattern(
                    Some(AndExpression(filterExpressionLeft.expression.getOrElse(throw DataConversionException("Expression was expected from previous FILTER conversion, but None given")), filterExpressionRight.expression.getOrElse(throw DataConversionException("Expression was expected from previous FILTER conversion, but None given")))),
                    filterExpressionLeft.additionalPatterns ++ filterExpressionRight.additionalPatterns
                )

            case regexFunction: RegexFunction =>

                handleRegexFunctionCall(regexFunctionCall = regexFunction, typeInspectionResult = typeInspectionResult)

            case functionCall: FunctionCallExpression =>

                handleKnoraFunctionCall(functionCallExpression = functionCall, typeInspectionResult, isTopLevel = isTopLevel)

            case other => throw NotImplementedException(s"$other not supported as FilterExpression")
        }

    }

}