Operation-observation-lastn.xml

Operation Definition

<?xml version="1.0" encoding="UTF-8"?>

<OperationDefinition xmlns="http://hl7.org/fhir">
  <id value="Observation-lastn"/> 
  <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>  query uses 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 request for a lastn query SHALL include:</p> 

        <ul> 

          <li> A 
            <code> $lastn</code>  operation parameter
          </li> 

          <li> A subject using either the 
            <code> patient</code>  or 
            <code> subject</code>   search parameter
          </li> 

          <li> A 
            <code> category</code>  parameter and/or a search parameter that contains a code element in its FHIRpath expression.
              ( e.g., 
            <code> code</code>  or 
            <code> code-value-concept</code> )
          </li> 

        </ul> 

        <p> The request for a lastn query MAY include:</p> 

        <ul> 

          <li> Other Observation search parameters and modifiers</li> 

        </ul> 

        <p> The response from a lastn query is a set of observations:</p> 

        <ul> 

          <li> Filtered by additional parameters

            <ul> 

              <li> If not explicitly filtered by status then will include statuses of 'entered-in-error'</li> 

            </ul> 

          </li> 

          <li> 'GROUP BY' 
            <code> Observation.code</code> 

            <ul> 

              <li> Codes SHALL be considered equivalent if the 
                <code> coding.value</code>  
                <em> and</em>  
                <code> coding.system</code>  are the same.
              </li> 

              <li> Text only codes SHALL be treated and grouped based on the text.</li> 

              <li> For codes with translations (multiple codings), the code translations are assumed to be
                 equal and the grouping by code SHALL follow the transitive property of equality.</li> 

            </ul> 

          </li> 

        </ul> 

        <p> for example:</p> 

        <table class="grid">

          <thead> 

            <tr> 
              <th> Observation.code for observation a</th> 
              <th> Observation.code for observation b</th> 
              <th> Observation.code for observation c</th> 
              <th> number of groups [codes/text in each group]</th> 
            </tr> 

          </thead> 

          <tbody> 

            <tr> 
              <td> a</td> 
              <td> b</td> 
              <td> c</td> 
              <td> 3 [a],[b],[c]</td> 
            </tr> 

            <tr> 
              <td> a</td> 
              <td> b</td> 
              <td> a,c</td> 
              <td> 2 [a.c],[b]</td> 
            </tr> 

            <tr> 
              <td> a</td> 
              <td> b</td> 
              <td> a,b</td> 
              <td> 1 [a,b]</td> 
            </tr> 

            <tr> 
              <td> 'textM'</td> 
              <td> 'Text'</td> 
              <td> 't e x t'</td> 
              <td> 3 ['text'],['Text'],['t e x t']</td> 
            </tr> 

          </tbody> 

        </table> 

        <ul> 

          <li> Sorted from most recent to the oldest</li> 

          <li> Limited to the number of requested responses per group specified by the optional 
            <em> max</em>  query parameter

            <ul> 

              <li> In case of a tie - when the effective times for &gt;1 Observations are equal - both will
                 be returned.  Therefore, more Observations may be returned than is specified in 
                <em> max</em> .  For example, 4 Observations instead of 3 if the 3rd and 4th most recent observation
                 had the same effective time.
              </li> 

            </ul> 

          </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> 
            <a href="datatypes.html#positiveInt">positiveInt</a> 
          </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 &quot;Fetch the last 3 results for all vitals
                 for a patient&quot; 
                <code> max</code>  = 3.
              </p> 

            </div> 
          </td> 
        </tr> 
        <tr> 
          <td> OUT</td> 
          <td> return</td> 
          <td> 1..1</td> 
          <td> 
            <a href="bundle.html">Bundle</a> 
          </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 matches so you may need to page through several &quot;A&quot; Observations 
             before getting to Observation &quot;B&quot;.
          </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> 
  <extension url="http://hl7.org/fhir/StructureDefinition/structuredefinition-fmm">
    <valueInteger value="3"/> 
  </extension> 
  <extension url="http://hl7.org/fhir/StructureDefinition/structuredefinition-standards-status">
    <valueCode value="trial-use"/> 
  </extension> 
  <url value="http://hl7.org/fhir/OperationDefinition/Observation-lastn"/> 
  <version value="4.2.0"/> 
  <name value="Last N Observations Query"/> 
  <status value="draft"/> 
  <kind value="operation"/> 
  <date value="2019-12-31T21:03:40+11: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* query uses 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.

The request for a lastn query SHALL include:

* A `$lastn` operation parameter
*  A subject using either the `patient` or `subject`  search parameter
*  A `category` parameter and/or a search parameter that contains a code element in its
   FHIRpath expression.  ( e.g., `code` or `code-value-concept`)

The request for a lastn query MAY include:

* Other Observation search parameters and modifiers

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

*  Filtered by additional parameters
   * If not explicitly filtered by status then will include statuses of 'entered-in-error'
* 'GROUP BY' `Observation.code`
   * Codes SHALL be considered equivalent if the `coding.value` *and* `coding.system`
   are the same.
   * Text only codes SHALL be treated and grouped based on the text.
   * For codes with translations (multiple codings), the code translations are assumed
   to be equal and the grouping by code SHALL follow the transitive property of equality.

for example:

|Observation.code for observation a|Observation.code for observation b|Observation.code
   for observation c|number of groups [codes/text in each group]|    
|---|---|---|---|     
|a|b|c | 3 [a],[b],[c]|    
|a|b|a,c | 2 [a.c],[b]|     
|a|b|a,b | 1 [a,b]|    
|'textM'|'Text'|'t e x t'|3 ['text'],['Text'],['t e x t']|

* Sorted from most recent to the oldest
* Limited to the number of requested responses per group specified by the optional *max*
   query parameter
  * In case of a tie - when the effective times for &gt;1 Observations are equal - both
   will be returned.  Therefore, more Observations may be returned than is specified in *max*.
    For example, 4 Observations instead of 3 if the 3rd and 4th most recent observation had
   the same effective time.
* 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."/> 
  <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:

* The *lastn* query returns **only** the last N resource grouped by code.  Using the _count
   query method doesn't restrict the total matches so you may need to page through several
   &quot;A&quot; Observations  before getting to Observation &quot;B&quot;.
* 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."/> 
  <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>