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">
      <p class="res-header-id">
        <b> Generated Narrative: OperationDefinition Observation-lastn</b> 
      </p> 
      <a name="Observation-lastn"> </a> 
      <a name="hcObservation-lastn"> </a> 
      

      <p> URL: [base]/Observation/$lastn</p> 
      <h3> Parameters</h3> 
      <table class="grid">
        <tr> 
          <td> 
            <b> Use</b> 
          </td> 
          <td> 
            <b> Name</b> 
          </td> 
          <td> 
            <b> Scope</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/>  
          <td> 0..1</td> 
          <td> 
            <a href="datatypes.html#positiveInt">positiveInt</a> 
          </td> 
          <td/>  
          <td> 
            <div> 
              <p> 
                 is  an optional input parameter to the 
                 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>  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/>  
          <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 
             the last N resource grouped by code.  Using the _count query method doesn't restrict

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

             before getting to Observation &quot;B&quot;.

          </li> 
          The server is responsible for grouping the observations by codes.  This frees the

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

           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> 
  <extension url="http://hl7.org/fhir/StructureDefinition/structuredefinition-wg">
    <valueCode value="oo"/> 
  </extension> 
  <url value="http://hl7.org/fhir/OperationDefinition/Observation-lastn"/> 
  <version value="6.0.0-ballot3"/> 
  <name value="Lastn"/> 
  <title value="Last N Observations Query"/> 
  <status value="draft"/> 
  <kind value="operation"/> 
  <experimental value="false"/> 
  

  <date value="2025-11-09T02:03:16+00:00"/> 
  <publisher value="HL7 International / Orders and Observations"/> 
  <contact> 
    <telecom> 
      <system value="url"/> 
      <value value="http://hl7.org/fhir"/> 
    </telecom> 
    <telecom> 
      <system value="email"/> 
      <value value="fhir@lists.hl7.org"/> 
    </telecom> 
  </contact> 
  <contact> 
    <telecom> 
      <system value="url"/> 
      <value value="http://www.hl7.org/Special/committees/orders"/> 
    </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.

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

* 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

* Filtered by additional parameters

   * If not explicitly filtered by status then will include statuses of 'entered-in-error'
* 'GROUP BY' `Observation.code`

* Ordered first by “equivalent” `Observation.code` value

   * 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:

   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']|

  |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 effective time to the oldest effective time. For further
   guidance, refer here on [sorting](https://www.hl7.org/fhir/search.html#_sort).

* The ordering of the “equivalent” code groups is not specified.
* Ordered secondly (within each code group) from most recent effective time to
   the oldest effective time. For further guidance, refer here on [sorting](https://www.hl7.org/
  fhir/search.html#_sort).

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

  * In case of a tie—when the effective times for more than one Observation in
   the same code group—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.
Note that the individual Observation.code values used for grouping might not be
   explicit in the request, for example if a category of Observations is requested,
   or if a code is specified with the `:below` modifier.

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."/> 
  <jurisdiction> 
    <coding> 
      <system value="http://unstats.un.org/unsd/methods/m49/m49.htm"/> 
      <code value="001"/> 
      <display value="World"/> 
    </coding> 
  </jurisdiction> 
  <affectsState value="false"/> 
  <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

   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

   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,

   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"/> 
    `max` is  an optional input parameter to the *lastn* query operation.  It is used

    <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

>