public final class SampleQuery

Object
SampleQuery

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.

Fields

public static final int DEFAULT_LIMIT = 10000 The limit applied when none is set.

Constructors

public SampleQuery()

Methods

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

Inherited methods

From Object

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

Field details

DEFAULT_LIMIT

public static final int DEFAULT_LIMIT = 10000

The limit applied when none is set.

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