Export (0) Print
Expand All

Querying data

HealthVault

Retrieving data from HealthVault is done through the GetThings request. The GetThings request performs operations very similar to an SQL select statement:

  • It has formats which allow you to choose what part of the thing data to retrieve, similar to the select statement in SQL.

  • It has filters which allow you to specify the criteria for the things to return, similar to the where clause in SQL.

  • It takes a record ID, which is similar to the from clause in SQL.

In addition, it allows you to specify multiple query groups in one request, which results in a dataset for each group. It also allows datasets to be paged from the server so as not to overwhelm the caller when the dataset is large.

Last updated: September 2012

This topic contains the following sections.

To make a GetThings request, specify the record ID of the health record from which you want to retrieve data. Only one record can be specified in each call, and the user must have already authorized the application with read access to the record. For more inforamtion about the GetThings request, see the Method browser.

The info section of the method request is then defined using a group containing filters and a format section.

The response is a collection of datasets, each containing the results for the groups specified in the request. Each group contains the things that matched the filters for that group. The results within each group are ordered by the thing’s effective date.

The following example request-response XML illustrates how a named group in the request matches a named group in the response:

 
<request>
  <!-- ... -->
  <info>
    <group name="height things">
      <filter>
        <type-id>40750a6a-89b2-455c-bd8d-b420a4cb500b</type-id>
      </filter>
      <format>
        <section>core</section>
        <xml/>
      </format>
    </group>
  </info>
</request>
<response>
  <!-- ... -->
  <info>
    <group name="height things">
      <thing>
        <!-- ... -->
      </thing>
    </group>
  </info>
</response>

In a GetThings request, multiple queries can be specified using groups.

Each group consists of a set of filters and formats that tell HealthVault what data should be returned for that particular group. A group can be named so that it is easy to differentiate the datasets that are returned in the results. The maximum number of things to be returned and the maximum number of full things can also be set on the group. All query results are sorted by effective date, so you get the most recent thing when you specify a maximum of 1.

To query for the most recent instance of height and weight data, with each in a different data set, create two groups. For example, Let's say you call one group height and the other group weight. The group for height will contain a filter specifying only the height thing type, while the weight group will specify only the weight thing type. On each group, you would set the maximum number of returned things to be 1. The result will contain two groups with the names specified in the request. The height group will contain only the most recent instance of height data, and the weight group only the most recent instance of weight data.

 
<info>
  <group name="height" max="1">
    <filter>
      <type-id>40750a6a-89b2-455c-bd8d-b420a4cb500b</type-id>
    </filter>
    <format>
      <section>core</section>
      <xml/>
    </format>
  </group>
  <group name="weight" max="1">
    <filter>
      <type-id>3d34d87e-7fc1-4153-800f-f56592cb0d17</type-id>
    </filter>
    <format>
      <section>core</section>
      <xml/>
    </format>
  </group>
</info>

The format part of the request parameters determines which parts of the thing get returned in each group. The formats you can request include:

  • specified header sections of the thing

  • the type-specific XML

  • the version of the type

  • how to treat binary data attached to the thing

Header sections

You can reduce the amount of data (by a small amount) by requesting only those sections you need for processing in your application.

The header always includes the thing ID, version stamp, and type identifier.

Optional header sections are:

Section

Description

Core

The metadata associated with the thing, including: effective date, state, and flags.

Audits

Information about who created and last updated the thing, and when.

Effective permissions

Information about what access rights the calling application has on the thing instance (Create, Read, Update, or Delete). This information is useful when you want to enable or disable controls for editing or deleting things, based on your application's permissions.

Digital signatures

Digital signature information including the key and cryptographic hash, which can be used to verify that the contents of the thing haven't been changed since the data was signed. Retrieve this section only if you want to validate the cryptographic hash or the signature. For more information, see Digital Signatures

Tags

A set of comma-separated strings defined by the user to tag or categorize things. Not generally useful for applications.

Blobpayload

Metadata about the binary data attached to the thing, sufficient for retrieving the binary data.

Type-specific XML

The type-specific XML is the XML data associated with the thing.

The schema for this data is different for each thing type. This is the personal health data that most applications are interested in. For more information on thing type schemas, see the Thing types and sample data explorer.

Type version

The type version can be specified for types that have been versioned.

Regardless of the type identifier used in the filter or how the data is stored for that particular type, this requests that query results return the data in the specified type version. For more information, see the Blobs section in Thing types.

Binary filter and format specification

The binary filter and format specification can be used to fetch specific binary instances by name and indicate how the data is to be returned.

Each thing instance can have many sets of binary data (blobs) associated with it. Each blob can be named. One instance can remain unnamed and is considered the default instance. The binary filter allows you to specify the names of the blobs to retrieve. If not specified, then all blobs will be returned.

The blob format determines how those blobs are returned. Options include:

Option

Description

Information

Only metadata about the blob is returned: name, content type, and digital signature hash information.

Inline

All binary data for the blob is returned in the XML response using a base64-encoded string.

Response size is limited and can be as low as 4MB, so not all blobs can be returned this way. The size limitation is for the entire response, so multiple blobs that combine to be more than the response limit will cause an error.

Streamed

This is the preferred method for retrieving blobs. The streaming mechanism doesn’t have the same size limitations that retrieving blobs inline does.

Metadata sufficient for retrieving the blob via an HTTP GET is returned. The metadata includes a URL directly to the blob, as well as the content encoding of that blob (if any).

For more information on retrieving blobs through streaming, see the Blobs section in Thing types.

The filter part of the request determines which things are returned in the response.

Each group can consist of any numbers of filters. Filters are logically ANDed together with the other filters in the group. For example, if you specify two filters in one group, with the first filter having the type identifier for weight things and the other filter having the type identifier for height, you would get no results because there are no things that are of both types. However, if you specified one of the filters having the type identifier for weight and the other with a created date minimum, then you’d get all weight things that were created after the specified date.

Within each filter there are a number of options. Each option is logically ANDed with the other options in the filter. However, some of the options are actually sets. Within these sets the value is logically ORed. For example, filters allow multiple type identifiers to be specified, such as weight and exercise. This request will return both weight and exercise items when specified in the same filter. The type identifiers are still ANDed with the other filter criteria. So if you add a minimum created date to the same filter, you’d get weight and exercise items that were created after the date specified. Other filter parameters that are treated as sets are: thing identifier, version stamp, client thing identifier, and thing state.

Filter fields include:

Filter field

Description

Created application identifier

Only things that were created by the specified application are returned.

Note: In the case of master/child and SODA applications, applications created based on the same master are not considered equivalent for this query. The child application identifier must be specified.

Created date maximum

Only things that were created before the specified date are returned.

Created date minimum

Only things that were created after the specified date are returned.

Created person identifier

Only things that were created by the specified person are returned.

Effective date maximum

Only things with an effective date before the one specified are returned.

Effective date minimum

Only things with an effective date after the one specified are returned.

The eff-date element contains the effective date.

Thing state

Although available as a filter field, the only allowed state for applications to specify is Active, which is also the default.

Type identifier

Only things of the specified types are returned.

Updated application identifier

Only things that were last updated by the specified application are returned.

Note: In the case of master-child and SODA applications, applications created based on the same master are not considered equivalent for this query. The child application identifier must be specified.

Updated date maximum

Only things that were last updated before the specified date are returned.

Updated date minimum

Only things that were last updated after the specified date are returned.

Updated end date maximum

Only things with an updated end date before the one specified are returned.

Updated end date minimum

Only things with an updated end date after the one specified are returned.

Updated person identifier

Only things that were last updated by the specified person are returned.

XPath

A Boolean condition expressed in XPath into the data XML portion of the thing. Only items matching that expression are returned.

This filter field is discussed in more detail below.

XPath

HealthVault supports querying for things based on XPath predicates. The predicates define search criteria into the thing data.

All XPaths must start with /thing/data-xml. HealthVault supports querying on any child element or attribute under data-xml.

Single predicate queries are optimized in HealthVault. Optimized queries include:

Predicate type

Description

String

String predicates encode the search value in quotes.

Numeric

Numeric predicates do not encode the search value in quotes.

Compound queries and predicates other than those described above are not optimized. Non-optimized queries are served by loading the entire set of thing data and searching with brute force. A non-optimized query executed against a record with a large number of things risks taking a long time. The predicates described above are a good way to search for data quickly.

/thing/data-xml/medication/name/text[. = "Aspirin"]
/thing/data-xml/medication/name/text[@myattribute = "value"]
/thing/data-xml/weight/value/kg[. =  150]
/thing/data-xml/weight/value/kg[. >  150]
/thing/data-xml/weight/value/kg[. <  150]

In order to conserve network bandwidth and HealthVault server resources, queries that return large datasets don’t return all the data in the first response. The first response includes a configured number (defined by the maxFullThingResultsPerGroup configuration item) of full things and the rest of the results as partial things. Full things consist of all the data requested in the format section. The partial things contain only the thing identifier, type identifier, and effective date of the thing.

After the first set of full things and partial things are returned, you can create another request asking for the next set of partial things, using the thing identifier. This set should not exceed the number of full things returned in the first request. Now you have two "pages" of data. You can continue this process until all data has been retrieved. For more information, see Thing types.

The HealthVault configuration values related to full and partial things are:

  • maxGetThingsQueryGroups – The maximum number of filter groups that can be provided for the query.

  • maxFullThingResultsPerGroup – The maximum number of full things returned per filter group.

  • maxPartialThingResultsPerGroup – The maximum number of partial things returned per filter group.

The GetServiceDefinition request returns information about Microsoft HealthVault and its related features, including values for various configuration items. For more information, see the Service definition detail section on the Method browser page.

The HealthVault .Net SDK provides classes for reading and writing data. For querying and writing data, use the HealthRecordAccessor class. For advanced querying, use the HealthRecordSearcher class.

Show:
© 2014 Microsoft