FHIR © HL7.org  |  Server Home  |  Health Intersections FHIR Server v1.0.329  |  FHIR Version 3.0.2  | User: ANONYMOUS (Unknown)  

Resource "Observation-lastn" Version "1" (OperationDefinition)

Tags:

XML or JSON representation . provenance for this resource

Last N Observations Query

OPERATION: Last N Observations Query

The official URL for this operation definition is:

http://hl7.org/fhir/OperationDefinition/Observation-lastn

The lastn query meets the common need for searching for the most recent or last n=number of observations for a subject. For example, retrieving the last 5 temperatures for a patient to view trends or fetching the most recent laboratory results or vitals signs. To ask a server to return the last n=number of observations, the lastn queryuses the normal search parameters defined for the Observation resource. However, rather than their normal use, they are interpreted as inputs - i.e.. instead of requiring that the resources literally contain the search parameters, they are passed to a server algorithm of some kind that uses them to determine the most appropriate matches.

The response from an lastn query is a set of observations:

  • filtered by additional parameters
  • 'GROUP BY' Observation.code
  • sorted from most recent to the oldest
  • limited to the number of requested responses per group specified by the optional max query parameter
  • If no maximum number is given then only the most recent Observation in each group is returned.

The set of returned observations should represent distinct real world observations and not the same observation with changes in status or versions. If there are no matches, the lastn query SHALL return an empty search set with no error, but may include an operation outcome with further advice.

URL: [base]/Observation/$lastn

Parameters

Use Name Cardinality Type Binding Documentation
IN max 0..1 positiveInt

max is an optional input parameter to the lastn query operation. It is used to specify the maximum number of Observations to return from each group. For example for the query "Fetch the last 3 results for all vitals for a patient" max = 3.

OUT return 1..1 Bundle

The set of most recent N Observations that match the lastn query search criteria.

The key differences between this query operation and simply searching Observation using the combination of _count and _sort parameters are:

  • The lastn query returns only the last N resource grouped by code. Using the _count query method doesn't restrict the total mathches so you may need to page through several "A" Observations before getting to Observation "B".
  • The server is responsible for grouping the observations by codes. This frees the client from needing to determine which codes she should ask for.

This operation cannot be performed on observations that the user is not authorized to see. It is assumed that the server has identified and secured the context appropriately, and can either associate the authorization context with a single patient, or determine whether the context has the rights to the nominated patient, if there is one. If there is no nominated patient (e.g. the operation is invoked at the system level) and the context is not associated with a single patient record, then the server should return an error. Specifying the relationship between the context, a user and patient records is outside the scope of this specification.


<?xml version="1.0" encoding="UTF-8"?>
<OperationDefinition xmlns="http://hl7.org/fhir">
  <id value="Observation-lastn"/>
  <meta>
    <versionId value="1"/>
    <lastUpdated value="2018-09-20T01:09:25.972Z"/>
  </meta>
  <text>
    <status value="generated"/>
    <div xmlns="http://www.w3.org/1999/xhtml">
      <h2>Last N Observations Query</h2>
      <p>OPERATION: Last N Observations Query</p>
      <p>The official URL for this operation definition is: </p>
      <pre>http://hl7.org/fhir/OperationDefinition/Observation-lastn</pre>
      <div>
        <p>The
          <em>lastn query</em>meets the common need for searching for the most recent or last n=number of observations for a subject. For example, retrieving the last 5 temperatures for a patient to view trends or fetching the most recent laboratory results or vitals signs. To ask a server to return the last n=number of observations, the
          <em>lastn</em>queryuses the
          <a href="observation.html#search">normal search parameters</a>defined for the Observation resource. However, rather than their normal use, they are interpreted as inputs - i.e.. instead of requiring that the resources literally contain the search parameters, they are passed to a server algorithm of some kind that uses them to determine the most appropriate matches. </p>
        <p>The response from an lastn query is a set of observations:</p>
        <ul>
          <li>filtered by additional parameters</li>
          <li>'GROUP BY'
            <code>Observation.code</code> </li>
          <li>sorted from most recent to the oldest</li>
          <li>limited to the number of requested responses per group specified by the optional max query parameter</li>
          <li>If no maximum number is given then only the most recent Observation in each group is returned.</li> </ul>
        <p>The set of returned observations should represent distinct real world observations and not the same observation with changes in status or versions. If there are no matches, the
          <em>lastn</em>query SHALL return an empty search set with no error, but may include an operation outcome with further advice. </p> </div>
      <p>URL: [base]/Observation/$lastn</p>
      <p>Parameters</p>
      <table class="grid">
        <tr>
          <td>
            <b>Use</b> </td>
          <td>
            <b>Name</b> </td>
          <td>
            <b>Cardinality</b> </td>
          <td>
            <b>Type</b> </td>
          <td>
            <b>Binding</b> </td>
          <td>
            <b>Documentation</b> </td> </tr>
        <tr>
          <td>IN</td>
          <td>max</td>
          <td>0..1</td>
          <td>positiveInt</td>
          <td/>
          <td>
            <div>
              <p>
                <code>max</code>is an optional input parameter to the
                <em>lastn</em>query operation. It is used to specify the maximum number of Observations to return from each group. For example for the query "Fetch the last 3 results for all vitals for a patient"
                <code>max</code>= 3. </p> </div> </td> </tr>
        <tr>
          <td>OUT</td>
          <td>return</td>
          <td>1..1</td>
          <td>Bundle</td>
          <td/>
          <td>
            <div>
              <p>The set of most recent N Observations that match the
                <em>lastn</em>query search criteria. </p> </div> </td> </tr> </table>
      <div>
        <p>The key differences between this query operation and simply searching Observation using the combination of
          <code>_count</code>and
          <code>_sort</code>parameters are: </p>
        <ul>
          <li>The
            <em>lastn</em>query returns
            <strong>only</strong>the last N resource grouped by code. Using the _count query method doesn't restrict the total mathches so you may need to page through several "A" Observations before getting to Observation "B". </li>
          <li>The server is responsible for grouping the observations by codes. This frees the client from needing to determine which codes she should ask for.</li> </ul>
        <p>This operation cannot be performed on observations that the user is not authorized to see. It is assumed that the server has identified and secured the context appropriately, and can either associate the authorization context with a single patient, or determine whether the context has the rights to the nominated patient, if there is one. If there is no nominated patient (e.g. the operation is invoked at the system level) and the context is not associated with a single patient record, then the server should return an error. Specifying the relationship between the context, a user and patient records is outside the scope of this specification.</p> </div> </div>
  </text>
  <url value="http://hl7.org/fhir/OperationDefinition/Observation-lastn"/>
  <name value="Last N Observations Query"/>
  <status value="draft"/>
  <kind value="operation"/>
  <date value="2017-04-19T07:44:43+10:00"/>
  <publisher value="HL7 (FHIR Project)"/>
  <contact>
    <telecom>
      <system value="url"/>
      <value value="http://hl7.org/fhir"/>
    </telecom>
    <telecom>
      <system value="email"/>
      <value value="fhir@lists.hl7.org"/>
    </telecom>
  </contact>
  <description value="The *lastn query* meets the common need for searching for the most recent or last n=number of observations for a subject. For example, retrieving the last 5 temperatures for a patient to view trends or fetching the most recent laboratory results or vitals signs. To ask a server to return the last n=number of observations, the *lastn* queryuses the [normal search parameters](observation.html#search) defined for the Observation resource. However, rather than their normal use, they are interpreted as inputs - i.e.. instead of requiring that the resources literally contain the search parameters, they are passed to a server algorithm of some kind that uses them to determine the most appropriate matches.&#10;&#10;The response from an lastn query is a set of observations: &#10;&#10;* filtered by additional parameters&#10;* &apos;GROUP BY&apos; `Observation.code`&#10;* sorted from most recent to the oldest&#10;* limited to the number of requested responses per group specified by the optional max query parameter&#10;* If no maximum number is given then only the most recent Observation in each group is returned. &#10;&#10;The set of returned observations should represent distinct real world observations and not the same observation with changes in status or versions. If there are no matches, the *lastn* query SHALL return an empty search set with no error, but may include an operation outcome with further advice."/>
  <code value="lastn"/>
  <comment value="The key differences between this query operation and simply searching Observation using the combination of `_count` and `_sort` parameters are:&#10;&#10;* The *lastn* query returns **only** the last N resource grouped by code. Using the _count query method doesn&apos;t restrict the total mathches so you may need to page through several &quot;A&quot; Observations before getting to Observation &quot;B&quot;.&#10;* The server is responsible for grouping the observations by codes. This frees the client from needing to determine which codes she should ask for.&#10;&#10;This operation cannot be performed on observations that the user is not authorized to see. It is assumed that the server has identified and secured the context appropriately, and can either associate the authorization context with a single patient, or determine whether the context has the rights to the nominated patient, if there is one. If there is no nominated patient (e.g. the operation is invoked at the system level) and the context is not associated with a single patient record, then the server should return an error. Specifying the relationship between the context, a user and patient records is outside the scope of this specification."/>
  <resource value="Observation"/>
  <system value="false"/>
  <type value="true"/>
  <instance value="false"/>
  <parameter>
    <name value="max"/>
    <use value="in"/>
    <min value="0"/>
    <max value="1"/>
    <documentation value="`max` is an optional input parameter to the *lastn* query operation. It is used to specify the maximum number of Observations to return from each group. For example for the query &quot;Fetch the last 3 results for all vitals for a patient&quot; `max` = 3."/>
    <type value="positiveInt"/>
  </parameter>
  <parameter>
    <name value="return"/>
    <use value="out"/>
    <min value="1"/>
    <max value="1"/>
    <documentation value="The set of most recent N Observations that match the *lastn* query search criteria."/>
    <type value="Bundle"/>
  </parameter>
</OperationDefinition>