Package com.complexible.stardog.plan.eval.service

Class ServiceQuery

  • Direct Known Subclasses:
    PlanNodeBodyServiceQuery
    public abstract class ServiceQuery
extends java.lang.Object
    An immutable instance of a query on a given service. The query allows maintaining state about the query as well as evaluating it. Features of different types of ServiceQueries can be set using its options with ServiceQueryOptions. This is the preferred approach instead of extending the API with additional functions.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected com.complexible.stardog.index.statistics.Cardinality mCardinality  
      protected com.complexible.stardog.plan.eval.service.ServiceQueryOptions mOptions  

    • Constructor Summary

      Constructors 
      Constructor Description
      ServiceQuery​(IRI theServiceIri)  

    • Method Summary

      All Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      com.complexible.stardog.index.statistics.Cardinality alternativeDistinctValues​(int theVar)
      If applicable, get an alternative estimate of the distinct values for the variable.
      com.complexible.stardog.index.statistics.Cardinality distinctValues​(int theVar)
      Get an estimate of the distinct values for the variable
      abstract boolean equals​(java.lang.Object obj)  
      com.complexible.stardog.index.statistics.Cardinality estimateCardinality​(com.complexible.stardog.db.ConnectableConnection theConn, Options theOption)
      Estimate cardinality of the service query.
      com.complexible.stardog.index.statistics.Cardinality estimateJoinCardinality​(com.complexible.stardog.db.ConnectableConnection conn, Options options, com.complexible.stardog.plan.PlanNode joined)
      Estimate cardinality of the service query.
      abstract com.complexible.stardog.plan.eval.operator.SolutionIterator<?> evaluate​(com.complexible.stardog.plan.eval.ExecutionContext theContext, com.complexible.stardog.plan.eval.operator.Operator theArg, com.complexible.stardog.plan.PlanVarInfo theVarInfo)
      Evaluate the query
      com.complexible.stardog.plan.eval.operator.SolutionIterator<?> evaluate​(com.complexible.stardog.plan.eval.ExecutionContext theContext, com.complexible.stardog.plan.eval.operator.Operator theArg, com.complexible.stardog.plan.PlanVarInfo theVarInfo, java.util.Set<java.lang.Integer> theArgAssuredVars)
      Evaluate the query.
      com.complexible.stardog.plan.eval.operator.SolutionIterator<?> evaluateSilent​(com.complexible.stardog.plan.eval.ExecutionContext theContext, com.complexible.stardog.plan.eval.operator.Operator theArg, com.complexible.stardog.plan.PlanVarInfo theVarInfo)
      Evaluate the query silently.
      com.complexible.stardog.plan.eval.operator.SolutionIterator<?> evaluateSilent​(com.complexible.stardog.plan.eval.ExecutionContext theContext, com.complexible.stardog.plan.eval.operator.Operator theArg, com.complexible.stardog.plan.PlanVarInfo theVarInfo, java.util.Set<java.lang.Integer> theArgAssuredVars)
      Evaluate the query silently.
      abstract java.lang.String explain​(com.complexible.stardog.plan.PlanVarInfo theVarInfo)
      Returns an explain string for the service invocation
      abstract java.lang.String explainVerbose​(com.complexible.stardog.plan.PlanVarInfo theVarInfo)
      Returns an explain string for the service invocation in a parsable verbose format
      com.complexible.stardog.plan.eval.LazyValues generatesValues()
      Returns true if the service may generate values which may not exist in the data (thus in the mapping dictionary)
      <T> T get​(Option<T> theOption)
      Get a configuration option of the ServiceQuery
      abstract com.google.common.collect.ImmutableSet<java.lang.Integer> getAllVars()  
      abstract com.google.common.collect.ImmutableSet<java.lang.Integer> getAssuredVars()
      What are the vars guaranteed to be bound by this query?
      com.complexible.stardog.index.statistics.Cardinality getCardinality()  
      com.google.common.collect.ImmutableSet<java.lang.Integer> getContextVars()  
      java.lang.Iterable<Namespace> getNamespaces()  
      com.google.common.collect.ImmutableSet<java.lang.Integer> getObjectVars()  
      Options getOptions()
      Return the options associated with this ServiceQuery
      com.google.common.collect.ImmutableSet<java.lang.Integer> getPredicateVars()  
      java.util.Set<java.lang.Integer> getRequiredInputBindings()
      The set of variables which should be bound by the argument of this query (if they are to be bound at all, membership in this set does not imply they are assured vars).
      java.util.Set<java.lang.Integer> getRequiredUnboundOutputs()
      The set of variables which cannot be bound by the argument of this query.
      com.google.common.collect.ImmutableSet<java.lang.Integer> getSubjectVars()  
      java.lang.String getUnsatisfiableConstraintsMessage​(com.complexible.stardog.plan.PlanVarInfo varInfo)  
      boolean hasDuplicates()
      Returns true if the node can return duplicate solutions
      abstract int hashCode()  
      boolean isBodySparqlQuery()
      Is the query body a SPARQL query? If so, we can apply some of our SPARQL transformations/optimizations.
      boolean isClosed()
      Is the service query "closed"? or can we still use it?
      boolean preservesJoinArgumentOrdering()
      If the query supportsJoinArgument(), are solutions returned in the same order as the join argument?
      com.complexible.stardog.plan.QueryTerm serviceTerm()
      Service term (var or IRI) of this query.
      ServiceQuery setCardinality​(com.complexible.stardog.index.statistics.Cardinality theCardinality)  
      void setNamespaces​(java.lang.Iterable<Namespace> theNamespaces)  
      boolean supportsJoinArgument()
      Does the query support a join argument to evaluate(ExecutionContext, Operator, PlanVarInfo)?
      ServiceQuery.ServiceQueryBuilder toBuilder()  

      • Methods inherited from class java.lang.Object

        clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

    • Field Detail

      • mCardinality

        protected com.complexible.stardog.index.statistics.Cardinality mCardinality

      • mOptions

        protected final com.complexible.stardog.plan.eval.service.ServiceQueryOptions mOptions

    • Constructor Detail

      • ServiceQuery

        public ServiceQuery​(IRI theServiceIri)

    • Method Detail

      • hasDuplicates

        public boolean hasDuplicates()
        Returns true if the node can return duplicate solutions
        Returns:
        true, if duplicates are possible

      • evaluate

        public abstract com.complexible.stardog.plan.eval.operator.SolutionIterator<?> evaluate​(com.complexible.stardog.plan.eval.ExecutionContext theContext,
                                                                                        com.complexible.stardog.plan.eval.operator.Operator theArg,
                                                                                        com.complexible.stardog.plan.PlanVarInfo theVarInfo)
                                                                                 throws com.complexible.stardog.plan.eval.operator.OperatorException
        Evaluate the query
        Parameters:
        theArg - a SIP join argument, null if not present. Solutions from the argument which satisfy the join must retain all bindings, including those which are not used in the join. Note that variables in the argument may be unassured.
        Throws:
        com.complexible.stardog.plan.eval.operator.OperatorException

      • evaluate

        public com.complexible.stardog.plan.eval.operator.SolutionIterator<?> evaluate​(com.complexible.stardog.plan.eval.ExecutionContext theContext,
                                                                               com.complexible.stardog.plan.eval.operator.Operator theArg,
                                                                               com.complexible.stardog.plan.PlanVarInfo theVarInfo,
                                                                               java.util.Set<java.lang.Integer> theArgAssuredVars)
                                                                        throws com.complexible.stardog.plan.eval.operator.OperatorException
        Evaluate the query. Allows for providing the assured variables of the argument. If not overwritten, defaults to evaluate(com.complexible.stardog.plan.eval.ExecutionContext, com.complexible.stardog.plan.eval.operator.Operator, com.complexible.stardog.plan.PlanVarInfo)
        Parameters:
        theArg - a SIP join argument, null if not present. Solutions from the argument which satisfy the join must retain all bindings, including * those which are not used in the join. Note that variables in the argument may be unassured.
        theArgAssuredVars - the set of assured variables in the argument
        Throws:
        com.complexible.stardog.plan.eval.operator.OperatorException

      • evaluateSilent

        public com.complexible.stardog.plan.eval.operator.SolutionIterator<?> evaluateSilent​(com.complexible.stardog.plan.eval.ExecutionContext theContext,
                                                                                     com.complexible.stardog.plan.eval.operator.Operator theArg,
                                                                                     com.complexible.stardog.plan.PlanVarInfo theVarInfo)
                                                                              throws com.complexible.stardog.plan.eval.operator.OperatorException
        Evaluate the query silently. We return a single empty solution if the service call fails
        Throws:
        com.complexible.stardog.plan.eval.operator.OperatorException

      • evaluateSilent

        public com.complexible.stardog.plan.eval.operator.SolutionIterator<?> evaluateSilent​(com.complexible.stardog.plan.eval.ExecutionContext theContext,
                                                                                     com.complexible.stardog.plan.eval.operator.Operator theArg,
                                                                                     com.complexible.stardog.plan.PlanVarInfo theVarInfo,
                                                                                     java.util.Set<java.lang.Integer> theArgAssuredVars)
                                                                              throws com.complexible.stardog.plan.eval.operator.OperatorException
        Evaluate the query silently. We return a single empty solution if the service call fails. Allows for providing the assured variables of the argument. If not overwritten, defaults to evaluateSilent(com.complexible.stardog.plan.eval.ExecutionContext, com.complexible.stardog.plan.eval.operator.Operator, com.complexible.stardog.plan.PlanVarInfo)
        Throws:
        com.complexible.stardog.plan.eval.operator.OperatorException

      • generatesValues

        public com.complexible.stardog.plan.eval.LazyValues generatesValues()
        Returns true if the service may generate values which may not exist in the data (thus in the mapping dictionary)

      • getAssuredVars

        public abstract com.google.common.collect.ImmutableSet<java.lang.Integer> getAssuredVars()
        What are the vars guaranteed to be bound by this query?

      • getSubjectVars

        public com.google.common.collect.ImmutableSet<java.lang.Integer> getSubjectVars()

      • getPredicateVars

        public com.google.common.collect.ImmutableSet<java.lang.Integer> getPredicateVars()

      • getObjectVars

        public com.google.common.collect.ImmutableSet<java.lang.Integer> getObjectVars()

      • getContextVars

        public com.google.common.collect.ImmutableSet<java.lang.Integer> getContextVars()

      • getAllVars

        public abstract com.google.common.collect.ImmutableSet<java.lang.Integer> getAllVars()

      • explain

        public abstract java.lang.String explain​(com.complexible.stardog.plan.PlanVarInfo theVarInfo)
        Returns an explain string for the service invocation
        Returns:
        an explain string for the service invocation or null if there is no custom explanation

      • explainVerbose

        public abstract java.lang.String explainVerbose​(com.complexible.stardog.plan.PlanVarInfo theVarInfo)
        Returns an explain string for the service invocation in a parsable verbose format
        Returns:
        an explain string in verbose format

      • serviceTerm

        public com.complexible.stardog.plan.QueryTerm serviceTerm()
        Service term (var or IRI) of this query.

      • getRequiredInputBindings

        public java.util.Set<java.lang.Integer> getRequiredInputBindings()
        The set of variables which should be bound by the argument of this query (if they are to be bound at all, membership in this set does not imply they are assured vars). A service may compute some binding based on "input" data. If this data is not available, the service will not create bindings for it and the result will be incorrect. A non-empty set returned here implies the query supports a join arg.

      • getRequiredUnboundOutputs

        public java.util.Set<java.lang.Integer> getRequiredUnboundOutputs()
        The set of variables which cannot be bound by the argument of this query. A service may bind "output" of a computation to this set of vars. Bindings cannot exist as they would be overwritten. Join must be done externally.

      • estimateCardinality

        public com.complexible.stardog.index.statistics.Cardinality estimateCardinality​(com.complexible.stardog.db.ConnectableConnection theConn,
                                                                                Options theOption)
        Estimate cardinality of the service query.

      • getCardinality

        public com.complexible.stardog.index.statistics.Cardinality getCardinality()

      • setCardinality

        public ServiceQuery setCardinality​(com.complexible.stardog.index.statistics.Cardinality theCardinality)

      • distinctValues

        public com.complexible.stardog.index.statistics.Cardinality distinctValues​(int theVar)
        Get an estimate of the distinct values for the variable
        Parameters:
        theVar - the variable
        Returns:
        an estimation of the number of distinct values for the variable in the ServiceQuery

      • alternativeDistinctValues

        public com.complexible.stardog.index.statistics.Cardinality alternativeDistinctValues​(int theVar)
        If applicable, get an alternative estimate of the distinct values for the variable. The alternative estimation function is used for the impact analysis. Changing the distinct values estimations can impact the join cardinality with the service query. For example, an alternative distinct values estimations could take the position of the variable in the service query pattern into account.
        Parameters:
        theVar - the variable
        Returns:
        the estimate

      • estimateJoinCardinality

        public com.complexible.stardog.index.statistics.Cardinality estimateJoinCardinality​(com.complexible.stardog.db.ConnectableConnection conn,
                                                                                    Options options,
                                                                                    com.complexible.stardog.plan.PlanNode joined)
        Estimate cardinality of the service query. todo: this method should return Selectivity instead of Cardinality, change this in Stardog 9

      • isClosed

        public boolean isClosed()
        Is the service query "closed"? or can we still use it?

      • isBodySparqlQuery

        public final boolean isBodySparqlQuery()
        Is the query body a SPARQL query? If so, we can apply some of our SPARQL transformations/optimizations.

      • preservesJoinArgumentOrdering

        public final boolean preservesJoinArgumentOrdering()
        If the query supportsJoinArgument(), are solutions returned in the same order as the join argument?

      • setNamespaces

        public void setNamespaces​(java.lang.Iterable<Namespace> theNamespaces)

      • getNamespaces

        public java.lang.Iterable<Namespace> getNamespaces()

      • getOptions

        public final Options getOptions()
        Return the options associated with this ServiceQuery
        Returns:
        the options

      • get

        public final <T> T get​(Option<T> theOption)
        Get a configuration option of the ServiceQuery
        Type Parameters:
        T - the type of the value of the option
        Parameters:
        theOption - the option
        Returns:
        the value of the option, or null if it's not set and there is no default

      • hashCode

        public abstract int hashCode()
        Overrides:
        hashCode in class java.lang.Object

      • equals

        public abstract boolean equals​(java.lang.Object obj)
        Overrides:
        equals in class java.lang.Object

      • getUnsatisfiableConstraintsMessage

        public java.lang.String getUnsatisfiableConstraintsMessage​(com.complexible.stardog.plan.PlanVarInfo varInfo)