# Interface QueryMetadata

All Known Implementing Classes:
  `QueryMetadataProxy, SQLTemplateMetadata`

public interface QueryMetadata
Provides a common interface for accessing query metadata.

Since:
  1.2

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final String`
  `CACHE_GROUPS_PROPERTY`
  `static final String`
  `CACHE_STRATEGY_PROPERTY`
  `static final int`
  `FETCH_LIMIT_DEFAULT`
  Defines default query fetch limit, which is zero, meaning that all matching rows should be fetched.
  `static final String`
  `FETCH_LIMIT_PROPERTY`
  Defines the name of the property for the query `fetch limit` .
  `static final int`
  `FETCH_OFFSET_DEFAULT`
  Defines default query fetch start index, which is 0, meaning that matching rows selected starting from the first.
  `static final String`
  `FETCH_OFFSET_PROPERTY`
  Defines the name of the property for the query `fetch offset`.
  `static final boolean`
  `FETCHING_DATA_ROWS_DEFAULT`
  `static final String`
  `FETCHING_DATA_ROWS_PROPERTY`
  `static final int`
  `PAGE_SIZE_DEFAULT`
  Defines default query page size, which is zero for no pagination.
  `static final String`
  `PAGE_SIZE_PROPERTY`
  Defines the name of the property for the query `page size`.
  `static final int`
  `QUERY_TIMEOUT_DEFAULT`
  `static final int`
  `STATEMENT_FETCH_SIZE_DEFAULT`
  Defines default query fetch start index, which is 0, meaning that matching rows selected starting from the first.
  `static final String`
  `STATEMENT_FETCH_SIZE_PROPERTY`
  Defines the name of the property for the query `fetch size`.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `String`
  `getCacheGroup()`
  Returns an optional cache "group".
  `String`
  `getCacheKey()`
  Returns a String that uniquely identifies this query for the purposes of result caching.
  `QueryCacheStrategy`
  `getCacheStrategy()`
  Returns a caching strategy for this query.
  `ClassDescriptor`
  `getClassDescriptor()`
  `DataMap`
  `getDataMap()`
  Returns a DataMap associated with a query or null if no such DataMap exists.
  `DbEntity`
  `getDbEntity()`
  Returns a DbEntity associated with a query or null if no such entity exists.
  `int`
  `getFetchLimit()`
  Returns the limit on the maximum number of records that can be returned by this query.
  `int`
  `getFetchOffset()`
  Specifies a start of a range when fetching a subset of records.
  `ObjEntity`
  `getObjEntity()`
  Returns an ObjEntity associated with a query or null if no such entity exists.
  `Query`
  `getOriginatingQuery()`
  Returns a query that originated this query.
  `int`
  `getPageSize()`
  Returns query page size.
  `Map<String,String>`
  `getPathSplitAliases()`
  Returns a map of aliases vs. expression subpaths that is used to build split joins.
  `PrefetchTreeNode`
  `getPrefetchTree()`
  Returns a root node of prefetch tree used by this query, or null of no prefetches are configured.
  `Procedure`
  `getProcedure()`
  Returns a Procedure associated with a query or null if no such procedure exists.
  `int`
  `getQueryTimeout()`
  `default Function<?,?>`
  `getResultMapper()`
  `List<Object>`
  `getResultSetMapping()`
  Returns an optional list of result set mapping hints.
  `int`
  `getStatementFetchSize()`
  `boolean`
  `isFetchingDataRows()`
  Returns `true` if this query should produce a list of data rows as opposed to Persistent objects, `false` for Persistent objects.
  `default boolean`
  `isReadOnly()`
  Returns true if this is a read-only (selecting) query that does not need to run in its own transaction.
  `boolean`
  `isRefreshingObjects()`
  Returns `true` if the query results should replace any currently cached values, returns `false` otherwise.
  `boolean`
  `isSingleResultSetMapping()`
  `boolean`
  `isSuppressingDistinct()`
  `default void`
  `setResultSetMapping(List<Object> resultSetMapping)`

- ## Field Details

  - ### FETCH_LIMIT_PROPERTY

    static final String FETCH_LIMIT_PROPERTY
    Defines the name of the property for the query `fetch limit` .
    See Also:
      - Constant Field Values

  - ### FETCH_LIMIT_DEFAULT

    static final int FETCH_LIMIT_DEFAULT
    Defines default query fetch limit, which is zero, meaning that all matching rows should be fetched.
    See Also:
      - Constant Field Values

  - ### FETCH_OFFSET_PROPERTY

    static final String FETCH_OFFSET_PROPERTY
    Defines the name of the property for the query `fetch offset`.
    Since:
      3.0
    See Also:
      - Constant Field Values

  - ### FETCH_OFFSET_DEFAULT

    static final int FETCH_OFFSET_DEFAULT
    Defines default query fetch start index, which is 0, meaning that matching rows selected starting from the first.
    Since:
      3.0
    See Also:
      - Constant Field Values

  - ### QUERY_TIMEOUT_DEFAULT

    static final int QUERY_TIMEOUT_DEFAULT
    See Also:
      - Constant Field Values

  - ### PAGE_SIZE_PROPERTY

    static final String PAGE_SIZE_PROPERTY
    Defines the name of the property for the query `page size`.
    See Also:
      - Constant Field Values

  - ### PAGE_SIZE_DEFAULT

    static final int PAGE_SIZE_DEFAULT
    Defines default query page size, which is zero for no pagination.
    See Also:
      - Constant Field Values

  - ### FETCHING_DATA_ROWS_PROPERTY

    static final String FETCHING_DATA_ROWS_PROPERTY
    See Also:
      - Constant Field Values

  - ### FETCHING_DATA_ROWS_DEFAULT

    static final boolean FETCHING_DATA_ROWS_DEFAULT
    See Also:
      - Constant Field Values

  - ### CACHE_STRATEGY_PROPERTY

    static final String CACHE_STRATEGY_PROPERTY
    Since:
      3.0
    See Also:
      - Constant Field Values

  - ### CACHE_GROUPS_PROPERTY

    static final String CACHE_GROUPS_PROPERTY
    Since:
      3.0
    See Also:
      - Constant Field Values

  - ### STATEMENT_FETCH_SIZE_PROPERTY

    static final String STATEMENT_FETCH_SIZE_PROPERTY
    Defines the name of the property for the query `fetch size`.
    Since:
      3.0
    See Also:
      - Constant Field Values

  - ### STATEMENT_FETCH_SIZE_DEFAULT

    static final int STATEMENT_FETCH_SIZE_DEFAULT
    Defines default query fetch start index, which is 0, meaning that matching rows selected starting from the first.
    Since:
      3.0
    See Also:
      - Constant Field Values

- ## Method Details

  - ### getClassDescriptor

    ClassDescriptor getClassDescriptor()
    Since:
      3.0

  - ### getObjEntity

    ObjEntity getObjEntity()
    Returns an ObjEntity associated with a query or null if no such entity exists.

  - ### getDbEntity

    DbEntity getDbEntity()
    Returns a DbEntity associated with a query or null if no such entity exists.

  - ### getProcedure

    Procedure getProcedure()
    Returns a Procedure associated with a query or null if no such procedure exists.

  - ### getDataMap

    DataMap getDataMap()
    Returns a DataMap associated with a query or null if no such DataMap exists.

  - ### getCacheStrategy

    QueryCacheStrategy getCacheStrategy()
    Returns a caching strategy for this query.
    Since:
      3.0

  - ### getCacheKey

    String getCacheKey()
    Returns a String that uniquely identifies this query for the purposes of result caching. If null is returned, no caching is performed.

  - ### getCacheGroup

    String getCacheGroup()
    Returns an optional cache "group". Cache groups allow to invalidate query caches in bulk on different events.
    Since:
      4.0

  - ### isFetchingDataRows

    boolean isFetchingDataRows()
    Returns `true` if this query should produce a list of data rows as opposed to Persistent objects, `false` for Persistent objects. This is a hint to the DataNode executing this query.

  - ### isRefreshingObjects

    boolean isRefreshingObjects()
    Returns `true` if the query results should replace any currently cached values, returns `false` otherwise. If `isFetchingDataRows()` returns `true`, this setting is not applicable and has no effect.

  - ### getPageSize

    int getPageSize()
    Returns query page size. Page size is a hint to Cayenne that query should be performed page by page, instead of retrieving all results at once. If the value returned is less than or equal to zero, no paging should occur.

  - ### getFetchOffset

    int getFetchOffset()
    Specifies a start of a range when fetching a subset of records.
    Since:
      3.0

  - ### getFetchLimit

    int getFetchLimit()
    Returns the limit on the maximum number of records that can be returned by this query. If the actual number of rows in the result exceeds the fetch limit, they will be discarded. One possible use of fetch limit is using it as a safeguard against large result sets that may lead to the application running out of memory, etc. If a fetch limit is greater or equal to zero, all rows will be returned.
    Returns:
      the limit on the maximum number of records that can be returned by this query

  - ### getOriginatingQuery

    Query getOriginatingQuery()
    Returns a query that originated this query. Originating query is a query whose result is needed to obtain the result of the query owning this metadata. Most often than not the returned value is null. One example of non-null originating query is a query for a range of objects in a previously fetched paginated list. The query that fetched the original paginated list is an "originated" query. It may be used to restore a list that got lost due to a cache overflow, etc.
    Since:
      4.0

  - ### getPrefetchTree

    PrefetchTreeNode getPrefetchTree()
    Returns a root node of prefetch tree used by this query, or null of no prefetches are configured.

  - ### getPathSplitAliases

    Map<String,String> getPathSplitAliases()
    Returns a map of aliases vs. expression subpaths that is used to build split joins.
    Since:
      3.0

  - ### getResultSetMapping

    List<Object> getResultSetMapping()
    Returns an optional list of result set mapping hints. Elements in the list can be either `EntityResultSegment` or `ScalarResultSegment`. The returned list can be null.
    Since:
      3.0

  - ### setResultSetMapping

    default void setResultSetMapping(List<Object> resultSetMapping)
    Since:
      4.2

  - ### isSingleResultSetMapping

    boolean isSingleResultSetMapping()
    Returns:
      should the result be mapped to single object (scalar or entity)
    Since:
      4.0
    See Also:
      - `getResultSetMapping()`

  - ### getStatementFetchSize

    int getStatementFetchSize()
    Returns:
      statement's fetch size
    Since:
      3.0

  - ### getQueryTimeout

    int getQueryTimeout()
    Returns:
      query timeout
    Since:
      4.2

  - ### isSuppressingDistinct

    boolean isSuppressingDistinct()
    Since:
      4.0

  - ### getResultMapper

    default Function<?,?> getResultMapper()
    Since:
      4.2

  - ### isReadOnly

    default boolean isReadOnly()
    Returns true if this is a read-only (selecting) query that does not need to run in its own transaction. Defaults to false, so any query not explicitly marked read-only is still wrapped in a transaction.
    Since:
      5.0