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 java.lang.String NO_ID  
      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 Description
      default java.lang.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 java.lang.String explain()
      Return the explanation of this query, which is the plan that will get executed for this query.
      default java.lang.String explain​(boolean theVerbose)
      Deprecated.
      java.lang.String explain​(Options theOptions)
      Explains the query execution by presenting the query execution plan optionally with extra information, such as profiling data.
      java.lang.String getID()
      Return the query ID or NO_ID if not set
      java.lang.String getSchema()
      Returns the schema that will be used by this query or {@code null} if reasoning is not used.
      Query<T> hint​(java.lang.String name, java.lang.String value)
      Add a hint to this query.
      java.util.Map<java.lang.String,​java.lang.String> hints()
      Returns all hints added via the hint(String, String) method.
      Query<T> id​(java.lang.String theID)
      Provide a textual ID for the query.
      boolean isReasoningEnabled()
      Return whether this query is using reasoning
      Query<T> parameter​(java.lang.String theName, boolean theValue)
      Set the parameter to the xsd:boolean value
      Query<T> parameter​(java.lang.String theName, byte theValue)
      Set the parameter to the xsd:byte value
      Query<T> parameter​(java.lang.String theName, double theValue)
      Set the parameter to the xsd:double value
      Query<T> parameter​(java.lang.String theName, float theValue)
      Set the parameter to the xsd:float value
      Query<T> parameter​(java.lang.String theName, int theValue)
      Set the parameter to the xsd:int value
      Query<T> parameter​(java.lang.String theName, long theValue)
      Set the parameter to the xsd:long value
      Query<T> parameter​(java.lang.String theName, short theValue)
      Set the parameter to the xsd:short value
      Query<T> parameter​(java.lang.String theName, Value theValue)
      Set the value of the parameter
      Query<T> parameter​(java.lang.String theName, java.lang.Object theObj)
      Set the parameter to the specified value.
      Query<T> parameter​(java.lang.String theName, java.lang.String theValue)
      Set the parameter to the xsd:string value
      Query<T> parameter​(java.lang.String theName, java.net.URI theURI)
      Set the parameter to the xsd:URI value
      Query<T> parameter​(java.lang.String theName, java.util.Date theValue)
      Set the parameter to the xsd:date value
      Query<T> parameter​(java.lang.String theName, java.util.GregorianCalendar theValue)
      Set the parameter to the xsd:dateTime value
      default java.util.Map<java.lang.String,​Value> parameters()  
      java.lang.String queryString()  
      Query<T> reasoning​(boolean theReasoningFlag)
      Specify whether you would like the query to be executed with reasoning.
      Query<T> schema​(java.lang.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.
      java.lang.String toString()
      Returns the current state of the parameterized SPARQL query for reference where parameters are appended as comments.

    • Method Detail

      • parameter

        Query<T> parameter​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.String theName,
                   java.lang.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​(java.lang.String theName,
                   java.util.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​(java.lang.String theName,
                   java.util.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​(java.lang.String theName,
                   java.net.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​(java.lang.String theName,
                   java.lang.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 java.util.Map<java.lang.String,​Value> parameters()

      • hints

        java.util.Map<java.lang.String,​java.lang.String> hints()
        Returns all hints added via the hint(String, String) method.
        Returns:
        the query hints

      • explain

        @Deprecated
default java.lang.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

        java.lang.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 java.lang.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:
        java.lang.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​(java.lang.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

        java.lang.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

      • id

        Query<T> id​(java.lang.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

        java.lang.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

        java.lang.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 java.lang.Object

      • queryString

        java.lang.String queryString()

      • baseURI

        default java.lang.String baseURI()

      • hint

        @Nonnull
Query<T> hint​(@Nonnull
              java.lang.String name,
              java.lang.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