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

Class ServiceQuery

java.lang.Object
com.complexible.stardog.plan.eval.service.ServiceQuery
Direct Known Subclasses:
PlanNodeBodyServiceQuery
public abstract class ServiceQuery extends 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.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static interface 
    ServiceQuery.DistinctValuesEstimationFunction
     
    static class 
    ServiceQuery.ServiceQueryBuilder
    Base service query builder class.

  • Field Summary

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

  • Constructor Summary

    Constructors
    Constructor
    Description
    ServiceQuery(IRI theServiceIri)
     

  • Method Summary

    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.
    boolean
    canServiceJoin(com.complexible.stardog.plan.PlanNode arg)
     
    com.complexible.stardog.index.statistics.Cardinality
    distinctValues(int theVar)
    Get an estimate of the distinct values for the variable
    abstract boolean
    equals(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, Set<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, Set<Integer> theArgAssuredVars)
    Evaluate the query silently.
    abstract String
    explain(com.complexible.stardog.plan.PlanVarInfo theVarInfo, com.complexible.stardog.plan.util.QueryTermRenderer theRenderer)
    Returns an explain string for the service invocation
    abstract String
    explainVerbose(com.complexible.stardog.plan.PlanVarInfo theVarInfo, com.complexible.stardog.plan.util.QueryTermRenderer theRenderer)
    Returns an explain string for the service invocation in a parsable verbose format
    com.complexible.stardog.plan.eval.LazyValues
    generatesValues()
    Returns Yes if the service may generate values which may not exist in the data (thus in the mapping dictionary)
    final <T> T
    get(Option<T> theOption)
    Get a configuration option of the ServiceQuery
    abstract com.google.common.collect.ImmutableSet<Integer>
    getAllVars()
     
    abstract com.google.common.collect.ImmutableSet<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<Integer>
    getContextVars()
     
    Iterable<Namespace>
    getNamespaces()
     
    com.google.common.collect.ImmutableSet<Integer>
    getObjectVars()
     
    final Options
    getOptions()
    Return the options associated with this ServiceQuery
    com.google.common.collect.ImmutableSet<Integer>
    getPredicateVars()
     
    Set<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).
    Set<Integer>
    getRequiredUnboundOutputs()
    The set of variables which cannot be bound by the argument of this query.
    com.google.common.collect.ImmutableSet<Integer>
    getSubjectVars()
     
    String
    getUnsatisfiableConstraintsMessage(com.complexible.stardog.plan.PlanVarInfo varInfo)
     
    boolean
    hasDuplicates()
    Returns true if the node can return duplicate solutions
    abstract int
    hashCode()
     
    final 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?
    final 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(Iterable<Namespace> theNamespaces)
     
    final 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 Details

    • DEFAULT_CARDINALITY

      public static final com.complexible.stardog.index.statistics.Cardinality DEFAULT_CARDINALITY

    • mCardinality

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

    • mOptions

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

  • Constructor Details

    • ServiceQuery

      public ServiceQuery(IRI theServiceIri)

  • Method Details

    • 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, Set<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, Set<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 Yes 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<Integer> getAssuredVars()
      What are the vars guaranteed to be bound by this query?

    • getSubjectVars

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

    • getPredicateVars

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

    • getObjectVars

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

    • getContextVars

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

    • getAllVars

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

    • explain

      public abstract String explain(com.complexible.stardog.plan.PlanVarInfo theVarInfo, com.complexible.stardog.plan.util.QueryTermRenderer theRenderer)
      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 String explainVerbose(com.complexible.stardog.plan.PlanVarInfo theVarInfo, com.complexible.stardog.plan.util.QueryTermRenderer theRenderer)
      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 Set<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 Set<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.

    • supportsJoinArgument

      public final boolean supportsJoinArgument()
      Does the query support a join argument to evaluate(ExecutionContext, Operator, PlanVarInfo)?

    • canServiceJoin

      public boolean canServiceJoin(com.complexible.stardog.plan.PlanNode arg)

    • preservesJoinArgumentOrdering

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

    • setNamespaces

      public void setNamespaces(Iterable<Namespace> theNamespaces)

    • getNamespaces

      public 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 Object

    • equals

      public abstract boolean equals(Object obj)
      Overrides:
      equals in class Object

    • toBuilder

      public ServiceQuery.ServiceQueryBuilder toBuilder()

    • getUnsatisfiableConstraintsMessage

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