# Class SampleQuery

java.lang.Object
com.codename1.health.SampleQuery

public final class SampleQuery extends Object

Describes a read against `HealthStore`. Fluent setters return `this`.

    SampleQuery q = new SampleQuery()
            .addType(HealthDataType.HEART_RATE)
            .setTimeRange(HealthTimeRange.lastHours(24))
            .setSortDescending(true)
            .setLimit(500);

##### Always set a limit for high-frequency types

A year of continuous heart rate is on the order of half a million samples. The default limit of 10,000 exists so that a naive query cannot exhaust the heap on a phone; raise it deliberately, and prefer paging through `HealthStore.readSamplePage(SampleQuery)` over asking for everything at once.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final int`
  `DEFAULT_LIMIT`
  The limit applied when none is set.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `SampleQuery()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `SampleQuery`
  `addSource(String bundleId)`
  Restricts the query to samples written by one app, identified by its bundle id or package name -- see `HealthSource.getBundleId()`.
  `SampleQuery`
  `addType(HealthDataType type)`
  Adds a type to read.
  `int`
  `getLimit()`
  The sample cap.
  `String`
  `getPageToken()`
  The continuation token, or null to start from the beginning.
  `Duration`
  `getSleepSessionGap()`

  The gap that separates two sleep sessions, as a

  invalid reference

      Duration

  .
  `long`
  `getSleepSessionGapMillis()`
  The sleep-session grouping gap in milliseconds.
  `List<String>`
  `getSources()`
  The source filter, empty when unrestricted.
  `HealthTimeRange`
  `getTimeRange()`
  The span this query reads, or null when unset.
  `List<HealthDataType>`
  `getTypes()`
  The types this query reads.
  `HealthUnit`
  `getUnit()`
  The requested unit, or null for each type's canonical unit.
  `boolean`
  `isFlattenSeries()`
  `true` when series are expanded into individual samples.
  `boolean`
  `isSortDescending()`
  `true` when results come back newest first.
  `SampleQuery`
  `setFlattenSeries(boolean flattenSeries)`
  Whether to expand `SeriesSample` records into individual `QuantitySample` objects.
  `SampleQuery`
  `setLimit(int limit)`
  Caps how many samples come back.
  `SampleQuery`
  `setPageToken(String pageToken)`
  Continues a previous read from `SamplePage.getNextPageToken()`.
  `SampleQuery`
  `setSleepSessionGap(Duration value)`
  The gap that separates two sleep sessions.
  `SampleQuery`
  `setSleepSessionGapMillis(long gapMillis)`
  `SampleQuery`
  `setSortDescending(boolean sortDescending)`
  Returns the newest samples first.
  `SampleQuery`
  `setTimeRange(HealthTimeRange timeRange)`
  The span to read.
  `SampleQuery`
  `setUnit(HealthUnit unit)`
  Returns values in `unit` instead of the type's canonical unit.
  `void`
  `validate()`
  Validates the query and throws if it cannot be run.

  ### Methods inherited from class Object

  `clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Field Details

  - ### DEFAULT_LIMIT

    public static final int DEFAULT_LIMIT
    The limit applied when none is set.
    See Also:
      - Constant Field Values

- ## Constructor Details

  - ### SampleQuery

    public SampleQuery()

- ## Method Details

  - ### addType

    public SampleQuery addType(HealthDataType type)
    Adds a type to read. At least one is required.

  - ### getTypes

    public List<HealthDataType> getTypes()
    The types this query reads.

  - ### addSource

    public SampleQuery addSource(String bundleId)

    Restricts the query to samples written by one app, identified by its bundle id or package name -- see `HealthSource.getBundleId()`. Call more than once to allow several.

    Worth doing when a phone and a watch both record the same activity: see the double-counting warning on `AggregateQuery`.

  - ### getSources

    public List<String> getSources()
    The source filter, empty when unrestricted.

  - ### setTimeRange

    public SampleQuery setTimeRange(HealthTimeRange timeRange)
    The span to read. Required.

  - ### getTimeRange

    public HealthTimeRange getTimeRange()
    The span this query reads, or null when unset.

  - ### setLimit

    public SampleQuery setLimit(int limit)

    Caps how many samples come back. Must be positive.

    On Android the cap is per data type when a query names several. Health Connect pages per record type, so a limit of ten over two types can return twenty. Neither alternative works: dividing the budget cannot find a newest-ten that all lives in one type, and trimming the merged page discards records the per-type continuation tokens have already moved past. Honouring it exactly needs an incremental k-way merge across the types, which is not implemented yet. Query one type at a time where the cap has to be exact -- which is also what iOS does, since `HKSampleQuery` reads one type per query.

  - ### getLimit

    public int getLimit()
    The sample cap.

  - ### setSortDescending

    public SampleQuery setSortDescending(boolean sortDescending)
    Returns the newest samples first. Default is oldest first.

  - ### isSortDescending

    public boolean isSortDescending()
    `true` when results come back newest first.

  - ### setUnit

    public SampleQuery setUnit(HealthUnit unit)

    Returns values in `unit` instead of the type's canonical unit.

    ###### Throws

    The unit is validated when the query runs, not here: a unit that measures the wrong dimension fails with `HealthError.UNIT_MISMATCH` before the platform is touched.

  - ### getUnit

    public HealthUnit getUnit()
    The requested unit, or null for each type's canonical unit.

  - ### setFlattenSeries

    public SampleQuery setFlattenSeries(boolean flattenSeries)

    Whether to expand `SeriesSample` records into individual `QuantitySample` objects. Defaults to `true`.

    Leave it on and both platforms return the same thing, so your code is identical across them. Turn it off when you need a series' record identity -- to delete it, for instance.

    Only Health Connect and the local stores group measurements into records, so only they have anything to withhold. HealthKit stores each measurement separately and the iOS port returns ordinary `QuantitySample` objects whichever way this is set -- not one-point series -- so code that turns flattening off and then casts to `SeriesSample` fails there. Test the type rather than assuming it.

  - ### isFlattenSeries

    public boolean isFlattenSeries()
    `true` when series are expanded into individual samples.

  - ### setSleepSessionGap

    public SampleQuery setSleepSessionGap(Duration value)

    The gap that separates two sleep sessions.

    The

    invalid reference

        Duration

    form of `setSleepSessionGapMillis(long)`, which is the type the rest of

    the framework speaks; the millis form stays for the ports and the wire format.

  - ### getSleepSessionGap

    public Duration getSleepSessionGap()

    The gap that separates two sleep sessions, as a

    invalid reference

        Duration

    .

  - ### setSleepSessionGapMillis

    public SampleQuery setSleepSessionGapMillis(long gapMillis)

  - ### getSleepSessionGapMillis

    public long getSleepSessionGapMillis()
    The sleep-session grouping gap in milliseconds.

  - ### setPageToken

    public SampleQuery setPageToken(String pageToken)
    Continues a previous read from `SamplePage.getNextPageToken()`.

  - ### getPageToken

    public String getPageToken()
    The continuation token, or null to start from the beginning.

  - ### validate

    public void validate() throws HealthException

    Validates the query and throws if it cannot be run.

    Called by `HealthStore` before the platform is touched, so a malformed query fails immediately and locally rather than as an opaque platform error later.

    ###### Throws

    - `HealthException`: with `HealthError.INVALID_ARGUMENT` for a missing type or range or a non-positive limit, and `HealthError.UNIT_MISMATCH` when the requested unit does not match a requested type's dimension.
    Throws:
      `HealthException`