Query (Apache Geode 1.10.0)
Date: 2019-09-19

org.apache.geode.cache.query

## Interface Query

-     public interface Query

  Interface for query objects. Supports execution of queries with optional parameters.
  Since:
    GemFire 4.0

- - ### Method Summary

    All Methods Instance Methods Abstract Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `compile()` Deprecated. as of 6.5
    `Object` | `execute()` Executes this query and returns an object that represent its result.
    `Object` | `execute(Object... params)` Executes this query with the given parameters and returns an object that represent its result.
    `Object` | `execute(RegionFunctionContext context)` Executes this query on the partitioned data-store associated with the given RegionFunctionContext and returns an object that represents its result.
    `Object` | `execute(RegionFunctionContext context, Object[] params)` Executes this query on the partitioned data-store associated with the given RegionFunctionContext and parameters and returns an object that represents its result.
    `String` | `getQueryString()` Return the original query string that was specified in the constructor.
    `QueryStatistics` | `getStatistics()` Get statistics information for this query.
    `boolean` | `isCompiled()` Deprecated. as of 6.5

- - ### Method Detail

    - #### getQueryString

          String getQueryString()

      Return the original query string that was specified in the constructor.
      Returns:
        the original query string

    - #### execute

          Object execute()
                  throws FunctionDomainException,
                         TypeMismatchException,
                         NameResolutionException,
                         QueryInvocationTargetException

      Executes this query and returns an object that represent its result. If the query resolves to a primitive type, an instance of the corresponding wrapper type (`Integer`, etc.) is returned. If the query resolves to more than one object, a `SelectResults` is returned. Query execution can potentially take a long time depending on data size and query complexity. The system property "gemfire.Cache.MAX_QUERY_EXECUTION_TIME" can be set to define the maximum time allowed for a query to complete its execution. If query execution time exceeds "gemfire.Cache.MAX_QUERY_EXECUTION_TIME", then the query is canceled and QueryExecutionTimeoutException is thrown back to the caller, if the execution is local to the VM. If the canceled query was initiated by a GemFire client, then a QueryException is thrown on the client with its cause set to QueryExecutionTimeoutException. This timeout does not account for the time taken to construct the results after execution completes and the results returned to the caller.
      Returns:
        The object that represents the result of the query. Note that if a query is just a select statement then it will return a result that is an instance of `SelectResults`. However, since a query is not necessarily just a select statement, the return type of this method is `Object`. For example, the query `(select distinct * from /rgn).size` returns an instance of `java.lang.Integer`.
      Throws:
        `FunctionDomainException` - A function was applied to a parameter that is improper for that function. For example, the ELEMENT function was applied to a collection of more than one element
        `TypeMismatchException` - If a bound parameter is not of the expected type.
        `NameResolutionException` - If a name in the query cannot be resolved.
        `IllegalArgumentException` - The number of bound parameters does not match the number of placeholders
        `IllegalStateException` - If the query is not permitted on this type of region
        `QueryExecutionTimeoutException` - If the query gets canceled due to setting system variable "gemfire.Cache.MAX_QUERY_EXECUTION_TIME". This is a thrown when query is executed on the local regions (embedded mode).
        `QueryInvocationTargetException` - If the data referenced in from clause is not available for querying.
        `QueryExecutionLowMemoryException` - If the query gets canceled due to low memory conditions and the resource manager critical heap percentage has been set
        `PartitionOfflineException` - If persistent data recovery is not complete for a partitioned region referred to in the query.

    - #### execute

          Object execute(Object... params)
                  throws FunctionDomainException,
                         TypeMismatchException,
                         NameResolutionException,
                         QueryInvocationTargetException

      Executes this query with the given parameters and returns an object that represent its result. If the query resolves to a primitive type, an instance of the corresponding wrapper type (`Integer`, etc.) is returned. If the query resolves to more than one object, a `SelectResults` is returned. Query execution can potentially take a long time depending on data size and query complexity. The system property "gemfire.Cache.MAX_QUERY_EXECUTION_TIME" can be set to define the maximum time allowed for a query to complete its execution. If query execution time exceeds "gemfire.Cache.MAX_QUERY_EXECUTION_TIME", then the query is canceled and QueryExecutionTimeoutException is thrown back to the caller, if the execution is local to the VM. If the canceled query was initiated by a GemFire client, then a QueryException is thrown on the client with its cause set to QueryExecutionTimeoutException. This timeout does not account for the time taken to construct the results after execution completes and the results returned to the caller.
      Parameters:
        `params` - Values that are bound to parameters (such as `$1`) in this query.
      Returns:
        The object that represents the result of the query. Note that if a query is just a select statement then it will return a result that is an instance of `SelectResults`. However, since a query is not necessarily just a select statement, the return type of this method is `Object`. For example, the query `(select distinct * from /rgn).size` returns an instance of `java.lang.Integer`.
      Throws:
        `FunctionDomainException` - A function was applied to a parameter that is improper for that function. For example, the ELEMENT function was applied to a collection of more than one element
        `TypeMismatchException` - If a bound parameter is not of the expected type.
        `NameResolutionException` - If a name in the query cannot be resolved.
        `IllegalArgumentException` - The number of bound parameters does not match the number of placeholders
        `IllegalStateException` - If the query is not permitted on this type of region
        `QueryExecutionTimeoutException` - If the query gets canceled due to setting system variable "gemfire.Cache.MAX_QUERY_EXECUTION_TIME". This is a thrown when query is executed on the local regions (embedded mode).
        `QueryInvocationTargetException` - If the data referenced in from clause is not available for querying.
        `QueryExecutionLowMemoryException` - If the query gets canceled due to low memory conditions and the resource manager critical heap percentage has been set
        `PartitionOfflineException` - If persistent data recovery is not complete for a partitioned region referred to in the query.

    - #### execute

          Object execute(RegionFunctionContext context)
                  throws FunctionDomainException,
                         TypeMismatchException,
                         NameResolutionException,
                         QueryInvocationTargetException

      Executes this query on the partitioned data-store associated with the given RegionFunctionContext and returns an object that represents its result. An Exception is thrown when data-set associated with the `RegionFunctionContext` gets moved or destroyed from the local node. The RegionFunctionContext defines the execution context of a data dependent `Function`. And is obtained when the function is executed using `FunctionService.onRegion(Region)`, the `FunctionContext` E.g.: // Function service execute() method: public void execute(FunctionContext context) { RegionFunctionContext regionContext = (RegionFunctionContext)context; Query query = cache.getQueryService().newQuery("Select * from /MyRegion"); SelectResults results = (SelectResults)query.execute(regionContext); } Using this method a join query query can be executed between two co-located PartitionRegion data-set referenced through `RegionFunctionContext`. This method should NOT be used for multiple partitioned regions based join queries. We support equi-join queries only on co-located PartitionedRegions if the the co-located columns ACTUALLY EXIST IN WHERE CLAUSE and in case of multi-column partitioning , should have "AND" clause. E.g.: // Equi-join query: Select * from /partitionRegion1 p1, /PartitionRegion2 p2 where p1.field = p2.field [AND .....]
      Parameters:
        `context` - RegionFunctionContext which will target the query on subset of data if executed on PartitionedRegion.
      Returns:
        The object that represents the result of the query. Note that if a query is just a select statement then it will return a result that is an instance of `SelectResults`. However, since a query is not necessarily just a select statement, the return type of this method is `Object`. For example, the query `(select distinct * from /rgn).size` returns an instance of `java.lang.Integer`.
      Throws:
        `FunctionDomainException` - A function was applied to a parameter that is improper for that function. For example, the ELEMENT function was applied to a collection of more than one element
        `TypeMismatchException` - If a bound parameter is not of the expected type.
        `NameResolutionException` - If a name in the query cannot be resolved.
        `IllegalArgumentException` - The number of bound parameters does not match the number of place holders
        `IllegalStateException` - If the query is not permitted on this type of region
        `QueryExecutionTimeoutException` - If the query gets canceled due to setting system variable "gemfire.Cache.MAX_QUERY_EXECUTION_TIME". This is a thrown when query is executed on the local regions (embedded mode).
        `QueryInvocationTargetException` - If the data referenced in from clause is not available for querying.
        `QueryExecutionLowMemoryException` - If the query gets canceled due to low memory conditions and the resource manager critical heap percentage has been set
        `PartitionOfflineException` - If persistent data recovery is not complete for a partitioned region referred to in the query.
      Since:
        GemFire 6.2.2

    - #### execute

          Object execute(RegionFunctionContext context,
                         Object[] params)
                  throws FunctionDomainException,
                         TypeMismatchException,
                         NameResolutionException,
                         QueryInvocationTargetException

      Executes this query on the partitioned data-store associated with the given RegionFunctionContext and parameters and returns an object that represents its result. An Exception is thrown if data moving across nodes (Like, partitioned data-store rebalancing) coincides with data to be queried. The RegionFunctionContext defines the execution context of a data dependent `Function`. And is obtained when the function is executed using `FunctionService.onRegion(Region)`, the `FunctionContext` E.g.: // Function service execute() method: public void execute(FunctionContext context) { RegionFunctionContext regionContext = (RegionFunctionContext)context; Query query = cache.getQueryService().newQuery("Select * from /MyRegion"); SelectResults results = (SelectResults)query.execute(regionContext); } Using this method a join query query can be executed between two co-located PartitionRegion data-set referenced through `RegionFunctionContext`. This method should NOT be used for multiple partitioned regions based join queries. We support equi-join queries only on co-located PartitionedRegions if the the co-located columns ACTUALLY EXIST IN WHERE CLAUSE and in case of multi-column partitioning , should have "AND" clause. E.g.: // Equi-join query: Select * from /partitionRegion1 p1, /PartitionRegion2 p2 where p1.field = p2.field [AND .....]
      Parameters:
        `context` - RegionFunctionContext which will target the query on subset of data if executed on PartitionedRegion.
        `params` - Values that are bound to parameters (such as `$1`) in this query.
      Returns:
        The object that represents the result of the query. Note that if a query is just a select statement then it will return a result that is an instance of `SelectResults`. However, since a query is not necessarily just a select statement, the return type of this method is `Object`. For example, the query `(select distinct * from /rgn).size` returns an instance of `java.lang.Integer`.
      Throws:
        `FunctionDomainException` - A function was applied to a parameter that is improper for that function. For example, the ELEMENT function was applied to a collection of more than one element
        `TypeMismatchException` - If a bound parameter is not of the expected type.
        `NameResolutionException` - If a name in the query cannot be resolved.
        `IllegalArgumentException` - The number of bound parameters does not match the number of place holders
        `IllegalStateException` - If the query is not permitted on this type of region
        `QueryExecutionTimeoutException` - If the query gets canceled due to setting system variable "gemfire.Cache.MAX_QUERY_EXECUTION_TIME". This is a thrown when query is executed on the local regions (embedded mode).
        `QueryInvocationTargetException` - If the data referenced in from clause is not available for querying.
        `QueryExecutionLowMemoryException` - If the query gets canceled due to low memory conditions and the resource manager critical heap percentage has been set
        `PartitionOfflineException` - If persistent data recovery is not complete for a partitioned region referred to in the query.
      Since:
        GemFire 6.2.2

    - #### compile

          @Deprecated
          void compile()
                            throws TypeMismatchException,
                                   NameResolutionException

      Deprecated. as of 6.5
      Compiles this `Query` to achieve higher performance execution.
      Throws:
        `TypeMismatchException` - If the compile-time type of a name, parameter, or expression is not the expected type
        `QueryInvalidException` - The syntax of the query string is not correct
        `NameResolutionException`

    - #### isCompiled

          @Deprecated
          boolean isCompiled()

      Deprecated. as of 6.5
      Return whether this query has been compiled into VM bytecodes.
      Returns:
        `true` if this query has been compiled into bytecodes

    - #### getStatistics

          QueryStatistics getStatistics()

      Get statistics information for this query.