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 Details

  • 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:

    • 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