com.bigdata.rdf.sparql.ast

Class StatementPatternNode

java.lang.Object

com.bigdata.bop.CoreBaseBOp

com.bigdata.bop.ModifiableBOpBase

com.bigdata.rdf.sparql.ast.ASTBase

com.bigdata.rdf.sparql.ast.QueryNodeBase

com.bigdata.rdf.sparql.ast.GroupMemberNodeBase<StatementPatternNode>

com.bigdata.rdf.sparql.ast.StatementPatternNode

All Implemented Interfaces:

BOp, IBindingProducerNode, IGroupMemberNode, IJoinNode, IQueryNode, IReorderableNode, IStatementContainer, IVariableBindingRequirements, IPropertySet, Serializable, Cloneable

public class StatementPatternNode
extends GroupMemberNodeBase<StatementPatternNode>
implements IJoinNode, IStatementContainer, IReorderableNode

A node in the AST representing a statement pattern.

Note: The annotations on the class are mostly interpreted by the toPredicate() method in AST2BOpUtility and by the logic in AST2BOpJoins which handles the default and named graph access patterns.

Note: If a variable is bound, then we bind that slot of the predicate. If a variable can take some enumerated set of values, then we use an #INLINE access path to model that "IN" constraint. If the value for a variable must lie within some key range, then we handle that case using RangeBOp. If we have no information about a variable, then we just leave the variable unbound.

See Also:

Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	StatementPatternNode.Annotations

Field Summary

Fields inherited from class com.bigdata.bop.CoreBaseBOp

DEFAULT_INITIAL_CAPACITY

Fields inherited from interface com.bigdata.bop.BOp

NOANNS, NOARGS

Constructor Summary

Constructors

Constructor and Description
StatementPatternNode(BOp[] args, Map<String,Object> anns) Required shallow copy constructor.
StatementPatternNode(StatementPatternNode op) Constructor required for com.bigdata.bop.BOpUtility#deepCopy(FilterNode).
StatementPatternNode(TermNode s, TermNode p, TermNode o) A triple pattern.
StatementPatternNode(TermNode s, TermNode p, TermNode o, TermNode c, org.openrdf.query.algebra.StatementPattern.Scope scope) A quad pattern.

Method Summary

Methods

Modifier and Type	Method and Description
TermNode	c() The variable or constant for the context position (required iff in quads mode).
TermNode	get(int i) Strengthen return type.
List<FilterNode>	getAttachedJoinFilters() Return the FILTER(s) associated with this IJoinNode.
Set<IVariable<?>>	getDesiredBound(StaticAnalysis sa) Get variables that are not required to be bound, but desired in the sense that we want them to be bound when evaluating the construct.
VarNode	getDistinctTermScanVar() Return the variable that will be bound by the DistinctTermAdvancer pattern.
long	getEstimatedCardinality(StaticOptimizer opt) Return the estimated cardinality - either the range count of a statement pattern or some computed estimated cardinality for a join group.
VarNode	getFastRangeCountVar() Return the VarNode associated with the optional StatementPatternNode.Annotations.FAST_RANGE_COUNT_VAR property.
Set<IVariable<?>>	getProducedBindings() Return the variables used by the predicate - i.e.
RangeNode	getRange()
Set<IVariable<?>>	getRequiredBound(StaticAnalysis sa) Return the variables used in the node that *must* be bound prior to evaluating the node.
org.openrdf.query.algebra.StatementPattern.Scope	getScope() The scope for this statement pattern (either named graphs or default graphs).
boolean	isGround() Return true if none of s, p, o, or c is a variable.
boolean	isMinus() Returns false.
boolean	isOptional() Return whether or not this is an join with "optional" semantics.
boolean	isReorderable() The decision about whether to re-order can no longer be made simply by examining the type - individual instances of a particular type may or may not be reorderable.
TermNode	o() The variable or constant for the object position (required).
TermNode	p() The variable or constant for the predicate position (required).
TermNode	s() The variable or constant for the subject position (required).
void	setAttachedJoinFilters(List<FilterNode> filters)
void	setC(TermNode c)
void	setDistinctTermScanVar(VarNode var)
void	setFastRangeCount(VarNode var)
void	setOptional(boolean optional) Mark this StatementPatternNode as one which was lifted out of a "simple optional" group and which therefore has "optional" semantics (we will do an optional join for it).
void	setRange(RangeNode range) Attach a RangeNode that describes a range for the statement pattern's O value.
void	setScope(org.openrdf.query.algebra.StatementPattern.Scope scope)
void	setSid(VarNode sid) Set the SID variable.
VarNode	sid() The statement identifier variable for triples which match this statement pattern (optional).
String	toShortString() General contract is a short (non-recursive) representation of the BOp.
String	toString(int indent) The contract of this method at this level is under-specified.

Methods inherited from class com.bigdata.rdf.sparql.ast.GroupMemberNodeBase

getContext, getParent, getParentGraphPatternGroup, getParentJoinGroup, setParent

Methods inherited from class com.bigdata.rdf.sparql.ast.QueryNodeBase

getQueryHints, toString

Methods inherited from class com.bigdata.rdf.sparql.ast.ASTBase

addExplainHint, getExplainHints, getQueryHint, getQueryHint, getQueryHintAsBoolean, getQueryHintAsBoolean, getQueryHintAsInteger, replaceAllWith, setQueryHint, setQueryHints

Methods inherited from class com.bigdata.bop.ModifiableBOpBase

addArg, addArg, addArgIfAbsent, annotations, annotationsEqual, argIterator, args, arity, clearProperty, copyAll, getProperty, indexOf, removeArg, replaceWith, setArg, setArgs, setId, setProperty, setUnboundProperty, toArray, toArray

Methods inherited from class com.bigdata.bop.CoreBaseBOp

annotationsEqual, annotationsToString, annotationsToString, annotationValueToString, checkArgs, clone, equals, getEvaluationContext, getId, getProperty, getRequiredProperty, hashCode, indent, isController, mutation, shortenName

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface com.bigdata.rdf.sparql.ast.IGroupMemberNode

getContext, getParent, getParentGraphPatternGroup, getParentJoinGroup, setParent

Methods inherited from interface com.bigdata.bop.BOp

annotations, argIterator, args, arity, clone, getEvaluationContext, getId, getProperty, getRequiredProperty, isController, setProperty, toArray, toArray, toString

Methods inherited from interface cutthecrap.utils.striterators.IPropertySet

getProperty

Constructor Detail

StatementPatternNode

public StatementPatternNode(StatementPatternNode op)

Constructor required for com.bigdata.bop.BOpUtility#deepCopy(FilterNode).

StatementPatternNode

public StatementPatternNode(BOp[] args,
                    Map<String,Object> anns)

Required shallow copy constructor.

StatementPatternNode

public StatementPatternNode(TermNode s,
                    TermNode p,
                    TermNode o)

A triple pattern. The StatementPattern.Scope will be StatementPattern.Scope.DEFAULT_CONTEXTS, the context will be null.

Parameters:

s -

p -

o -

See Also:

StatementPatternNode#StatementPatternNode(TermNode, TermNode, TermNode, TermNode, Scope)

StatementPatternNode

public StatementPatternNode(TermNode s,
                    TermNode p,
                    TermNode o,
                    TermNode c,
                    org.openrdf.query.algebra.StatementPattern.Scope scope)

A quad pattern.

Note: When a StatementPatternNode appears in a WHERE clause, the StatementPattern.Scope should be marked as StatementPattern.Scope.DEFAULT_CONTEXTS if it is NOT embedded within a GRAPH clause and otherwise as StatementPattern.Scope.NAMED_CONTEXTS.

The context position of the statement should be null unless it is embedded within a GRAPH clause, in which case the context is the context specified for the parent GRAPH clause.

The SPARQL UPDATE WITH uri is a syntactic sugar for GRAPH uri {...}. Therefore, when present, any StatementPatternNode outside of an explicit GRAPH group is also marked as StatementPattern.Scope.NAMED_CONTEXTS and the context position will be bound to the uri specified in the WITH clause.

A null context in StatementPattern.Scope.DEFAULT_CONTEXTS is interpreted as the RDF merge of the graphs in the defaultGraph (as specified by the DatasetNode). When non-null (it can be bound by the SPARQL UPDATE WITH clause), the defaultGraph declared by the DatasetNode is ignored and the context is bound to the constant specified in that WITH clause.

Absent any other constraints on the query, an unbound variable context in StatementPattern.Scope.NAMED_CONTEXTS may be bound to any named graph specified by the DatasetNode.

Parameters:

s - The subject (variable or constant; required).

p - The subject (variable or constant; required).

o - The subject (variable or constant; required).

c - The context (variable or constant; optional).

scope - Either StatementPattern.Scope.DEFAULT_CONTEXTS or StatementPattern.Scope.NAMED_CONTEXTS (required).

Throws:

IllegalArgumentException - if s, p, or o is null.

IllegalArgumentException - if scope is null.

IllegalArgumentException - if scope is StatementPattern.Scope.NAMED_CONTEXTS and c is null.

Method Detail

s

public final TermNode s()

The variable or constant for the subject position (required).

p

public final TermNode p()

The variable or constant for the predicate position (required).

o

public final TermNode o()

The variable or constant for the object position (required).

c

public final TermNode c()

The variable or constant for the context position (required iff in quads mode).

get

public TermNode get(int i)

Strengthen return type.

Specified by:

get in interface BOp

Overrides:

get in class ModifiableBOpBase

Parameters:

i - The argument index in [0:BOp.arity()-1].

Returns:

The argument.

setC

public final void setC(TermNode c)

sid

public final VarNode sid()

The statement identifier variable for triples which match this statement pattern (optional). The statement identifier is the composition of the (subject, predicate, and object) positions of the matched statements.

See Also:

StatementPatternNode.Annotations.SID

setSid

public final void setSid(VarNode sid)

Set the SID variable.

getScope

public final org.openrdf.query.algebra.StatementPattern.Scope getScope()

The scope for this statement pattern (either named graphs or default graphs).

See Also:

StatementPatternNode.Annotations.SCOPE, StatementPattern.Scope

setScope

public final void setScope(org.openrdf.query.algebra.StatementPattern.Scope scope)

getFastRangeCountVar

public final VarNode getFastRangeCountVar()

Return the VarNode associated with the optional StatementPatternNode.Annotations.FAST_RANGE_COUNT_VAR property.

Returns:

The VarNode -or- null if this triple pattern is not associated with that annotation.

setFastRangeCount

public final void setFastRangeCount(VarNode var)

getDistinctTermScanVar

public final VarNode getDistinctTermScanVar()

Return the variable that will be bound by the DistinctTermAdvancer pattern.

Returns:

The distinct term scan variable -or- null if the access path will not use a distinct term scan.

See Also:

StatementPatternNode.Annotations.DISTINCT_TERM_SCAN_VAR

setDistinctTermScanVar

public final void setDistinctTermScanVar(VarNode var)

isOptional

public final boolean isOptional()

Return whether or not this is an join with "optional" semantics. Optional joins may or may not produce variable bindings, but will not reduce the incoming solutions based on whether or not they bind.

This returns true iff the StatementPatternNode was lifted out of an optional JoinGroupNode such that it has OPTIONAL semantics.

Specified by:

isOptional in interface IJoinNode

See Also:

ASTSimpleOptionalOptimizer

isMinus

public final boolean isMinus()

Returns false.

Specified by:

isMinus in interface IJoinNode

setOptional

public final void setOptional(boolean optional)

Mark this StatementPatternNode as one which was lifted out of a "simple optional" group and which therefore has "optional" semantics (we will do an optional join for it).

Note: The need to maintain the correct semantics for the simple optional group (statement pattern plus filter(s)) is also the reason why the lifted FILTER(s) MUST NOT require the materialization of any variables which would not have been bound before that JOIN. Since variables bound by the JOIN for the optional statement pattern will not be materialized, filters attached to that JOIN can not require materialization of variables bound by the JOIN (though they can depend on variables already bound by the required joins in the parent group).

See Also:

ASTSimpleOptionalOptimizer

setRange

public final void setRange(RangeNode range)

Attach a RangeNode that describes a range for the statement pattern's O value.

Parameters:

range -

getRange

public final RangeNode getRange()

getAttachedJoinFilters

public final List<FilterNode> getAttachedJoinFilters()

Description copied from interface: IJoinNode

Return the FILTER(s) associated with this IJoinNode. Such filters will be run with the JOIN for this statement pattern. As such, they MUST NOT rely on materialization of variables which would not have been bound before that JOIN.

Specified by:

getAttachedJoinFilters in interface IJoinNode

Returns:

The attached join filters and never null (it may return an empty list)(.

See Also:

ASTSimpleOptionalOptimizer, ASTAttachJoinFiltersOptimizer

setAttachedJoinFilters

public final void setAttachedJoinFilters(List<FilterNode> filters)

Specified by:

setAttachedJoinFilters in interface IJoinNode

isGround

public boolean isGround()

Return true if none of s, p, o, or c is a variable.

getProducedBindings

public Set<IVariable<?>> getProducedBindings()

Return the variables used by the predicate - i.e. what this node will attempt to bind when run.

toString

public String toString(int indent)

Description copied from class: CoreBaseBOp

The contract of this method at this level is under-specified. Sub-classes may choose between: - return a string representation of the object, similar to the use of CoreBaseBOp.toString() Or: - return a pretty-print representation of the object with indent Note that the former contract may or may not include recursive descent through a tree-like object, whereas the latter almost certainly does.

Specified by:

toString in interface BOp

Specified by:

toString in interface IQueryNode

Overrides:

toString in class CoreBaseBOp

Returns:

toShortString

public String toShortString()

Description copied from class: CoreBaseBOp

General contract is a short (non-recursive) representation of the BOp.

Specified by:

toShortString in interface BOp

Overrides:

toShortString in class CoreBaseBOp

isReorderable

public boolean isReorderable()

Description copied from interface: IReorderableNode

The decision about whether to re-order can no longer be made simply by examining the type - individual instances of a particular type may or may not be reorderable.

Specified by:

isReorderable in interface IReorderableNode

getEstimatedCardinality

public long getEstimatedCardinality(StaticOptimizer opt)

Description copied from interface: IReorderableNode

Return the estimated cardinality - either the range count of a statement pattern or some computed estimated cardinality for a join group.

Specified by:

getEstimatedCardinality in interface IReorderableNode

Parameters:

opt - This optimizer can be used to help work out the estimate

getRequiredBound

public Set<IVariable<?>> getRequiredBound(StaticAnalysis sa)

Description copied from interface: IVariableBindingRequirements

Return the variables used in the node that *must* be bound prior to evaluating the node. For instance, when evaluation a SPARQL 1.1 service and the endpoint is specified through a variable, then this variable must be bound in order to identify the endpoint to which the query is to be sent. By *must* be bound we mean that, if it is possible to bring the variables in a join group in order such that they are bound when executing the construct (e.g., think of a FILTER), then we *must* consider that. However, when the IVariableBindingRequirements#getRequiredBound() interface cannot be satisified, the query may still be valid and return results (for the SPARQL 1.1 service example mentioned above, it may not, for the FILTER it may). The set of these variables must be disjoint from IVariableBindingRequirements#getRequiredUnound().

Specified by:

getRequiredBound in interface IVariableBindingRequirements

Returns:

the set of variables that must be bound prior to evaluation

getDesiredBound

public Set<IVariable<?>> getDesiredBound(StaticAnalysis sa)

Description copied from interface: IVariableBindingRequirements

Get variables that are not required to be bound, but desired in the sense that we want them to be bound when evaluating the construct. In general, the more variables are bound, the better, but this might differ for certain constructs. Should only report variables that are *not* reported through method IVariableBindingRequirements.getRequiredBound(StaticAnalysis).

Specified by:

getDesiredBound in interface IVariableBindingRequirements

Returns:

the set of variables that are desires to be bound, but not required