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)