Package com.complexible.stardog.api

# Interface Query<T>

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:
  8.2
Author:
  Michael Grove

- ## Field Summary

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

- ## Method Summary

  Modifier and Type
  Method
  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`
  `getID()`
  Return the query ID or `NO_ID` if not set
  `String`
  `getSchema()`
  Returns the schema that will be used by this query or ``null`` if reasoning is not used.
  `Query<T>`
  `hint(String name, String value)`
  Add a hint to this query.
  `Map<String,String>`
  `hints()`
  Returns all hints added via the `hint(String, String)` method.
  `Query<T>`
  `id(String theID)`
  Provide a textual ID for the query.
  `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, 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, 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, short theValue)`
  Set the parameter to the xsd:short value
  `Query<T>`
  `parameter(String theName, Value theValue)`
  Set the value of the parameter
  `Query<T>`
  `parameter(String theName, Object theObj)`
  Set the parameter to the specified 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, Date theValue)`
  Set the parameter to the xsd:date value
  `Query<T>`
  `parameter(String theName, GregorianCalendar theValue)`
  Set the parameter to the xsd:dateTime value
  `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 ``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 Details

  - ### NO_ID

    static final String NO_ID
    See Also:
      - `QueryManager.NO_ID`
      - Constant Field Values

  - ### NO_TIMEOUT

    static final long NO_TIMEOUT
    Constant value used to specify that a query has no timeout
    See Also:
      - Constant Field Values

- ## Method Details

  - ### 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()

  - ### hints

    Map<String,String> hints()
    Returns all hints added via the `hint(String, String)` method.
    Returns:
      the query hints

  - ### 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 ``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 ``null`` if reasoning is not used.
    Returns:
      the name of the reasoning schema

  - ### id

    Query<T> id(String theID)
    Provide a textual ID for the query. This is optional since the server will auto-assign an ID to the query when it receives it. However, an externally set ID allows the client to use it to `terminate` the query without an additional request to the `QueryManager` to obtain the list of running queries and having to find this query in that list. Note: the client is responsible for uniqueness of IDs they provide. If the client attempts to set an ID which clashes with the ID of another currently running query, the query will be rejected before execution. One recommended way is to use `UUID.randomUUID()`.
    Parameters:
      `theID` - the provided ID.
    Returns:
      this query

  - ### getID

    String getID()
    Return the query ID or `NO_ID` if not set
    Returns:
      the query's ID

  - ### 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()

  - ### hint

    @Nonnull Query<T> hint(@Nonnull String name, String value)
    Add a hint to this query. This is equivalent to adding `#pragma <name> <value>` to the beginning of the query string.
    Parameters:
      `name` - name of the hint
      `value` - value of the hint
    Returns:
      this query