# 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.
  `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`
  `setSleepSessionGapMillis(long gapMillis)`
  The gap that separates two sleep sessions, for the iOS port's session reassembly.
  `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.

  - ### 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 -- and accept that iOS, which has no such grouping, returns series of size 1.

  - ### isFlattenSeries

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

  - ### setSleepSessionGapMillis

    public SampleQuery setSleepSessionGapMillis(long gapMillis)

    The gap that separates two sleep sessions, for the iOS port's session reassembly. Defaults to 15 minutes.

    HealthKit stores sleep as a run of category samples with no session object, so the port groups samples separated by less than this gap into one `SleepSample`. Raise it if your users nap; lower it if you would rather see brief wakings split the night. Ignored on Android, where sessions are stored natively.

  - ### 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`