Query (Stardog-7.7.1 API)

All Known Subinterfaces:

BooleanQuery, GraphQLQuery, GraphQuery, PathQuery, ReadQuery<T>, SelectPlanQuery, SelectQuery, UpdateQuery
```
public interface Query<T>
```
Object for executing a query against a Stardog database.
```
 Usage:

 	SelectQuery q = c.select("select * where ...");

	q.parameter("foo", 12);
	q.parameter("bar", false);
	q.parameter("subj", s);
	q.offset(10);
	q.limit(250);

	// run it
	TupleQueryResult r = q.execute();
	while (r.hasNext()) {
		// do awesome things...
		r.next();
	}

	// always close your query result sets!
 	r.close();
 
```
It is recommended that in order to avoid most types of injection attacks via SPARQL, that any parameterization of queries is handled through the usage of the various parameter methods as opposed to using string concatenation of a query with user input. These methods will safely handle escaping and insertion of the provided value into the query while also providing type safety.

For example the query:
```
   String aName = // some value
String aStr = "select * where { ?s rdf:type foaf:Person. ?s foaf:name \""+aName+"\". }";
 
```
In the best case where the value of aName is valid, you will be fine. But if aName is pulled from user input, it could be the case that the user provided the string:

John Doe". ?s private:ssn ?ssn . ?s private:bankAccountNum ?bn. # }

It would yield the query:

select * where { ?s rdf:type foaf:Person. ?s foaf:name "John Doe". ?s private:ssn ?ssn . ?s private:bankAccountNum ?bn. } #". }

Note here that everything after the # is commented out, thus giving the user the ability to select both the person's SSN and bank account number. If the parameter(String, String) method was instead used by invoking Query.parameter("n", aName), with the original query of select * where { ?s rdf:type foaf:Person. ?s foaf:name ?n. }, and the malicious input, you'd end up with the incorrect, and innocuous query:

select * where { ?s rdf:type foaf:Person. ?s foaf:name """John Doe". ?s private:ssn ?ssn . ?s private:bankAccountNum ?bn. } """^^xsd:string. }
Since:

0.3

Version:

6.0

Author:

Michael Grove

Field Summary

Fields
Modifier and Type Field and Description

static long NO_TIMEOUT
Constant value used to specify that a query has no timeout

Fields
Modifier and Type	Field and Description
`static long`	`NO_TIMEOUT` Constant value used to specify that a query has no timeout

Method Summary

All Methods Instance Methods Abstract Methods Default Methods Deprecated Methods
Modifier and Type	Method and Description
`default String`	`baseURI()`
`default Dataset`	`dataset()`
`Query<T>`	`dataset(Dataset theDataset)` Specify the dataset this query will be executed against.
`T`	`execute()` Execute the query
`default String`	`explain()` Return the explanation of this query, which is the plan that will get executed for this query.
`default String`	`explain(boolean theVerbose)` Deprecated.
`String`	`explain(Options theOptions)` Explains the query execution by presenting the query execution plan optionally with extra information, such as profiling data.
`String`	`getSchema()` Returns the schema that will be used by this query or `{@code null}` if reasoning is not used.
`boolean`	`isReasoningEnabled()` Return whether this query is using reasoning
`Query<T>`	`parameter(String theName, boolean theValue)` Set the parameter to the xsd:boolean value
`Query<T>`	`parameter(String theName, byte theValue)` Set the parameter to the xsd:byte value
`Query<T>`	`parameter(String theName, Date theValue)` Set the parameter to the xsd:date value
`Query<T>`	`parameter(String theName, double theValue)` Set the parameter to the xsd:double value
`Query<T>`	`parameter(String theName, float theValue)` Set the parameter to the xsd:float value
`Query<T>`	`parameter(String theName, GregorianCalendar theValue)` Set the parameter to the xsd:dateTime value
`Query<T>`	`parameter(String theName, int theValue)` Set the parameter to the xsd:int value
`Query<T>`	`parameter(String theName, long theValue)` Set the parameter to the xsd:long value
`Query<T>`	`parameter(String theName, Object theObj)` Set the parameter to the specified value.
`Query<T>`	`parameter(String theName, short theValue)` Set the parameter to the xsd:short value
`Query<T>`	`parameter(String theName, String theValue)` Set the parameter to the xsd:string value
`Query<T>`	`parameter(String theName, URI theURI)` Set the parameter to the xsd:URI value
`Query<T>`	`parameter(String theName, Value theValue)` Set the value of the parameter
`default Map<String,Value>`	`parameters()`
`String`	`queryString()`
`Query<T>`	`reasoning(boolean theReasoningFlag)` Specify whether you would like the query to be executed with reasoning.
`Query<T>`	`schema(String theSchema)` Sets the schema that will be used by this query or `{@code null}` if reasoning will not be used.
`default long`	`timeout()`
`Query<T>`	`timeout(long theTimeout)` Set the timeout for query execution.
`String`	`toString()` Returns the current state of the parameterized SPARQL query for reference where parameters are appended as comments.

- Field Detail
  - NO_TIMEOUT
```
static final long NO_TIMEOUT
```
    Constant value used to specify that a query has no timeout
    
    See Also:
    
    Constant Field Values
- Method Detail
  - execute
```
T execute()
   throws StardogException
```
    Execute the query
    
    Returns:
    
    the query result
    
    Throws:
    
    StardogException - if there is an error executing the query
  - parameter
```
Query<T> parameter(String theName,
                   Value theValue)
```
    Set the value of the parameter
    
    Parameters:
    
    theName - the parameter to set
    
    theValue - the value of the parameter
    
    Returns:
    
    this query
  - parameter
```
Query<T> parameter(String theName,
                   int theValue)
```
    Set the parameter to the xsd:int value
    
    Parameters:
    
    theName - the parameter to set
    
    theValue - the value of the parameter
    
    Returns:
    
    this query
  - parameter
```
Query<T> parameter(String theName,
                   long theValue)
```
    Set the parameter to the xsd:long value
    
    Parameters:
    
    theName - the parameter to set
    
    theValue - the value of the parameter
    
    Returns:
    
    this query
  - parameter
```
Query<T> parameter(String theName,
                   float theValue)
```
    Set the parameter to the xsd:float value
    
    Parameters:
    
    theName - the parameter to set
    
    theValue - the value of the parameter
    
    Returns:
    
    this query
  - parameter
```
Query<T> parameter(String theName,
                   double theValue)
```
    Set the parameter to the xsd:double value
    
    Parameters:
    
    theName - the parameter to set
    
    theValue - the value of the parameter
    
    Returns:
    
    this query
  - parameter
```
Query<T> parameter(String theName,
                   short theValue)
```
    Set the parameter to the xsd:short value
    
    Parameters:
    
    theName - the parameter to set
    
    theValue - the value of the parameter
    
    Returns:
    
    this query
  - parameter
```
Query<T> parameter(String theName,
                   boolean theValue)
```
    Set the parameter to the xsd:boolean value
    
    Parameters:
    
    theName - the parameter to set
    
    theValue - the value of the parameter
    
    Returns:
    
    this query
  - parameter
```
Query<T> parameter(String theName,
                   byte theValue)
```
    Set the parameter to the xsd:byte value
    
    Parameters:
    
    theName - the parameter to set
    
    theValue - the value of the parameter
    
    Returns:
    
    this query
  - parameter
```
Query<T> parameter(String theName,
                   String theValue)
```
    Set the parameter to the xsd:string value
    
    Parameters:
    
    theName - the parameter to set
    
    theValue - the value of the parameter
    
    Returns:
    
    this query
  - parameter
```
Query<T> parameter(String theName,
                   Date theValue)
```
    Set the parameter to the xsd:date value
    
    Parameters:
    
    theName - the parameter to set
    
    theValue - the value of the parameter
    
    Returns:
    
    this query
  - parameter
```
Query<T> parameter(String theName,
                   GregorianCalendar theValue)
```
    Set the parameter to the xsd:dateTime value
    
    Parameters:
    
    theName - the parameter to set
    
    theValue - the value of the parameter
    
    Returns:
    
    this query
  - parameter
```
Query<T> parameter(String theName,
                   URI theURI)
```
    Set the parameter to the xsd:URI value
    
    Parameters:
    
    theName - the parameter to set
    
    theURI - the value of the parameter
    
    Returns:
    
    this query
  - parameter
```
Query<T> parameter(String theName,
                   Object theObj)
```
    Set the parameter to the specified value. Convenience method which will delegate to one of the other parameter(...) methods
    
    Parameters:
    
    theName - the parameter name
    
    theObj - the param value
    
    Returns:
    
    this query
  - parameters
```
default Map<String,Value> parameters()
```
  - explain
```
@Deprecated
default String explain(boolean theVerbose)
                            throws StardogException
```
    Deprecated.
    
    Return the explanation of this query, which is the plan that will get executed for this query. This is for information purposes only.
    
    Parameters:
    
    theVerbose - the verbose flag
    
    Returns:
    
    the query explanation
    
    Throws:
    
    StardogException - if there is an error explaining the query
  - explain
```
String explain(Options theOptions)
        throws StardogException
```
    Explains the query execution by presenting the query execution plan optionally with extra information, such as profiling data.
    
    Parameters:
    
    theOptions - the explain options
    
    Returns:
    
    the query explanation
    
    Throws:
    
    StardogException - if there is an error explaining the query
  - explain
```
default String explain()
                throws StardogException
```
    Return the explanation of this query, which is the plan that will get executed for this query. This is for information purposes only.
    
    Returns:
    
    the query explanation
    
    Throws:
    
    StardogException - if there is an error explaining the query
  - dataset
```
Query<T> dataset(Dataset theDataset)
```
    Specify the dataset this query will be executed against. This defines the active graph for the query and will override anything specified within the query. Use Datasets.NO_DATASET remove the dataset.
    
    Parameters:
    
    theDataset - the active graph dataset
    
    Returns:
    
    this query
    
    See Also:
    
    Datasets
  - dataset
```
default Dataset dataset()
```
  - reasoning
```
Query<T> reasoning(boolean theReasoningFlag)
```
    Specify whether you would like the query to be executed with reasoning. For update queries, the reasoning flag only affects the evaluation of WHERE clauses in DELETE/INSERT queries.
    
    You can only modify the reasoning flag of a query outside of a transaction. If querying within a transaction you can only use the reasoning flag associated with the connection.
    
    If the reasoning schema is explicitly set via the schema(String) function beforehand then calling reasoning(true) will have no effect. If the schema is not set then calling reasoning(true) is equivalent to setting the schema to the default schema. Calling reasoning(false) is always equivalent to setting the schema to the null schema.
    
    Parameters:
    
    theReasoningFlag - the reasoning flag
    
    Returns:
    
    this query
    
    Throws:
    
    IllegalStateException - if attempting to change the reasoning flag of the query inside of a transaction
  - isReasoningEnabled
```
boolean isReasoningEnabled()
```
    Return whether this query is using reasoning
    
    Returns:
    
    the reasoning flag
  - schema
```
Query<T> schema(String theSchema)
```
    Sets the schema that will be used by this query or {@code null} if reasoning will not be used. If the schema is set with this function reasoning(boolean) function is not needed to be called.
    
    Parameters:
    
    theSchema - the name of the schema
    
    Returns:
    
    this query
  - getSchema
```
String getSchema()
```
    Returns the schema that will be used by this query or {@code null} if reasoning is not used.
    
    Returns:
    
    the name of the reasoning schema
  - timeout
```
default long timeout()
```
  - timeout
```
Query<T> timeout(long theTimeout)
```
    Set the timeout for query execution.
    
    Parameters:
    
    theTimeout - the timeout in ms. A zero or negative value will be interpreted as no timeout
    
    Returns:
    
    this query
  - toString
```
String toString()
```
    Returns the current state of the parameterized SPARQL query for reference where parameters are appended as comments. The returned string is not used to execute or transmit the query and should only be used for information purposes. If the original query has not been parameterized with one of the ReadQuery.limit(long), ReadQuery.offset(long), or parameter(String, Value) functions then the result will be the original query string. If the original query has been modified with one of these functions then the parameters will be appended at the end of the query string as comments using an appropriate SPARQL keyword (LIMIT, OFFSET, or VALUES).
    
    Overrides:
    
    toString in class Object
  - queryString
```
String queryString()
```
  - baseURI
```
default String baseURI()
```

Interface Query<T>

Field Summary

Method Summary

Field Detail

NO_TIMEOUT

Method Detail

execute

parameter

parameter

parameter

parameter

parameter

parameter

parameter

parameter

parameter

parameter

parameter

parameter

parameter

parameters

explain

explain

explain

dataset

dataset

reasoning

isReasoningEnabled

schema

getSchema

timeout

timeout

toString

queryString

baseURI