Observation-operation-lastn - FHIR v6.0.0-ballot2

FHIR CI-Build

This is the Continuous Integration Build of FHIR (will be incorrect/inconsistent at times).
See the Directory of published versions icon

10.1.12.2 Operation $lastn on Observation

Orders and Observations icon

Work Group

Maturity Level: 3

Trial Use

Compartments: N/A

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

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

The canonical URL for this operation definition is

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

Formal Definition (as a OperationDefinition).

URL: [base]/Observation/$lastn

This is an idempotent operation

In Parameters:

Name Scope Cardinality Type Binding Profile Documentation

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

Name Scope Cardinality Type Binding Profile Documentation

return

1..1

Bundle

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

Note: as this is the only out parameter, it is a resource, and it has the name 'return', the result of this operation is returned directly as a resource

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

10.1.12.2.1 Examples

Request: 1): Fetch the last 3 results for all vitals for a patient 2): Fetch the last laboratory results for a patient 3): Fetch the last 3 blood pressures, respiratory rate and heart rates for a patient


1) GET [base]/Observation/$lastn?max=3&patient=Patient/123&category=vital-signs

--------------------------------------------

2) GET [base]/Observation/$lastn?patient=Patient/123&category=laboratory

--------------------------------------------

3) GET [base]/Observation/$lastn?max=3&patient=Patient/123&category=vital-signs&code=9279-1,8867-4,85354-9

Response: 1): A Server returns from an imaginary Last N algorithm the last 3 of 9 different vital signs observations on a patient. e.g. body temperature, body weight, body height... (truncated for readability) 2): A Server returns from an imaginary Last N algorithm the last laboratory observations for a patient. e.g. CBC Panel, UA, Chem Panel, Lipid Panel components and HbA1c, (truncated for readability) 3): A Server returns from an imaginary Last N algorithm the last 3 blood pressures, respiratory rate and heart rates for a patient as specified by code from the request. (truncated for readability)



=========================== Example 1 ============================

HTTP/1.1 200 OK
[other headers]

{
  "resourceType": "Bundle",
  "id": "26419249-18b3-45de-b10e-dca0b2e72b",
  "meta": {
    "lastUpdated": "2017-02-18T03:28:49Z"
  },
  "type": "searchset",
  "total": 27,
  // the patient temperature was being taken several times a day
  "entry": [{
    "fullUrl": "http://server/path/Observation/20170219-06temp",
    "resource": {
      "resourceType": "Observation",
      "id": "20170219temp",
      .. snip ...
  ,{
   "fullUrl": "http://server/path/Observation/20170219-05temp",
       "resource": {
         "resourceType": "Observation",
         "id": "20170218temp",
      .. snip ...
    }
      ,{
       "fullUrl": "http://server/path/Observation/20170219-04temp",
           "resource": {
             "resourceType": "Observation",
             "id": "20170217temp",
          .. snip ...
    },
    // the patient was being weighed daily
    {
    "fullUrl": "http://server/path/Observation/20170219weight",
    "resource": {
      "resourceType": "Observation",
      "id": "20170219weight",
      .. snip ...
  ,{
   "fullUrl": "http://server/path/Observation/20170218weight",
       "resource": {
         "resourceType": "Observation",
         "id": "20170218weight",
      .. snip ...
    }
      ,{
       "fullUrl": "http://server/path/Observation/20170217weight",
           "resource": {
             "resourceType": "Observation",
             "id": "20170217weight",
          .. snip ...
    },
    // height was recorded occasionally over the years
        {
        "fullUrl": "http://server/path/Observation/20170101height",
        "resource": {
          "resourceType": "Observation",
          "id": "20170219height",
          .. snip ...
      ,{
       "fullUrl": "http://server/path/Observation/20160101height",
           "resource": {
             "resourceType": "Observation",
             "id": "20160101height",
          .. snip ...
        }
          ,{
           "fullUrl": "http://server/path/Observation/20131001height",
               "resource": {
                 "resourceType": "Observation",
                 "id": "20131001height",
              .. snip ...
    }
  ]
}

----------------------------------

=========================== Example 2 ============================


HTTP/1.1 200 OK
[other headers]

{
  "resourceType": "Bundle",
  "id": "26419249-18b3-45de-b10e-dca0b2e72b",
  "meta": {
    "lastUpdated": "2017-02-18T03:28:49Z"
  },
  "type": "searchset",
  "total": 45,
  // the patient's last CBC Panel component observations
  "entry": [{
    "fullUrl": "http://server/path/Observation/20170219-CBCPanel-RBCs",
    "resource": {
      "resourceType": "Observation",
      "id": "0170219-CBCPanel-RBCs",
      ... snip ...
      "code" : {
    "coding" : [
      {
        "system" : "http://loinc.org",
        "code" : "789-8",
        "display" : "RBC # Bld Auto"
      }
    ],
    "text" : "RBC # Bld Auto"
  },
  ...snip....
  },
  // the rest of the patient CBC Panel components observations
  { ...snip...
  },
  // the patient's last UA Panel component observations
    {
    "fullUrl": "http://server/path/Observation/20160610-UA-Color",
    "resource": {
      "resourceType": "Observation",
      "id": "20160610-UA-Color",
      .. snip ...
      "code" : {
   "coding" : [
     {
       "system" : "http://loinc.org",
       "code" : "5778-6",
       "display" : "Color of Urine"
     }
   ],
   "text" : "COLOR"
 },
   ...snip....
   },
   // the rest of the patient UA Panel component observations
   { ...snip...
   },
   // the patient's last Metabolic Panel component observations
  {
   "fullUrl": "http://server/path/Observation/20170219MetPanel-Sodium",
       "resource": {
         "resourceType": "Observation",
         "id": "20170219MetPanel-Sodium",
      ... snip ...
        "code" : {
          "coding" : [
          {
            "system" : "http://loinc.org",
            "code" : "2951-2",
            "display" : "Sodium SerPl-sCnc"
            }
          ],
          "text" : "Sodium SerPl-sCnc"
          },
      ...snip....
      },
      // the rest of the patient Metabolic Panel component observations
      { ...snip...
      },
    // the patient Lipase Panel components observations
        {
        "fullUrl": "http://server/path/Observation/20170219LipidPanel-Chol",
        "resource": {
          "resourceType": "Observation",
          "id": "20170219LipidPanel-Chol",
          ... snip ...
          "code": {
                 "coding": [
                   {
                     "system": "http://loinc.org",
                     "code": "14647-2",
                     "display": "Cholesterol [Mass or Moles/volume] in Serum or Plasma"
                   }
                 ],
                 "text": "Cholesterol"
          },
          ...snip....
          },
          // the patient HbA1c observation
          {
          "fullUrl": "http://server/path/Observation/20170219HbA1c",
          "resource": {
            "resourceType": "Observation",
            "id": "20170219HbA1c",
            ... snip ...
            "code": {
                   "coding": [
                     {
                       "system": "http://loinc.org",
                       "code": "4548-4",
                       "display": "Hemoglobin A1c/Hemoglobin.total in Blood"
                     }
                   ],
                   "text": "HbA1c"
            },
            ...snip....
    }
  ]
}

----------------------------------


=========================== Example 3 ============================


HTTP/1.1 200 OK
[other headers]

{
  "resourceType": "Bundle",
  "id": "26419249-18b3-45de-b10e-dca0b2e72b",
  "meta": {
    "lastUpdated": "2017-02-18T03:28:49Z"
  },
  "type": "searchset",
  "total": 9,
  // Returns the patient's last 3 code = 9279-1 Respiratory Rate observations All from 20170219
  "entry": [{
    "fullUrl": "http://server/path/Observation/20170219-06RespRate",
    "resource": {
      "resourceType": "Observation",
      "id": "20170219-06RespRate",
      .. snip ...
     "code": {
       "coding": [
         {
           "system": "http://loinc.org",
           "code": "9279-1",
           "display": "Respiratory rate"
         }
       ],
       "text": "Respiratory rate"
 },
     .. snip ...
  ,{
   "fullUrl": "http://server/path/Observation/20170219-05RespRate",
       "resource": {
         "resourceType": "Observation",
         "id": "20170219-05RespRate",
      .. snip ...
    }
      ,{
       "fullUrl": "http://server/path/Observation/20170219-04RespRate",
           "resource": {
             "resourceType": "Observation",
             "id": "20170217-04RespRate",
          .. snip ...
    },
    // Returns the patient's last 3 code =  8867-4 Heart Rate observations All from 20170219
    // the patient was being weighed daily
    {
    "fullUrl": "http://server/path/Observation/20170219-06HeartRate",
    "resource": {
      "resourceType": "Observation",
      "id": "20170219-06HeartRate",
      .. snip ...
      ],
    "code": {
      "coding": [
        {
          "system": "http://loinc.org",
          "code": "8867-4",
          "display": "Heart rate"
        }
      ],
      "text": "Heart rate"
  ...snip...
  ,{
   "fullUrl": "http://server/path/Observation/20170219-05HeartRate",
       "resource": {
         "resourceType": "Observation",
         "id": "20170219-05HeartRate",
      .. snip ...
    }
      ,{
       "fullUrl": "http://server/path/Observation/20170219-04HeartRate",
           "resource": {
             "resourceType": "Observation",
             "id": "20170219-04HeartRate",
          .. snip ...
    },
    // Returns the patient's last 3 code =  85354-9 Blood pressure systolic and diastolic All from 20170219
        {
        "fullUrl": "http://server/path/Observation/20170219-06BloodPressure",
        "resource": {
          "resourceType": "Observation",
          "id": "20170219-06BloodPressure",
          .. snip ...
          "code": {
           "coding": [
             {
               "system": "http://loinc.org",
               "code": "85354-9",
               "display": "Bood pressure panel with all children optional"
             }
           ],
           "text": "Blood pressure systolic & diastolic"
         },
         ...snip...
                 "component": [
          {
            "code": {
              "coding": [
                {
                  "system": "http://loinc.org",
                  "code": "8480-6",
                  "display": "Systolic blood pressure"
                },
                {
            ...snip...
                        {
              "code": {
                "coding": [
                  {
                    "system": "http://loinc.org",
                    "code": "8462-4",
                    "display": "Diastolic blood pressure"
                  }
                ]
              },
              ...snip....
      ,{
       "fullUrl": "http://server/path/Observation/20170219-05BloodPressure",
           "resource": {
             "resourceType": "Observation",
             "id": "20170219-05BloodPressure",
          .. snip ...
        }
          ,{
           "fullUrl": "http://server/path/Observation/20170219-04BloodPressure",
               "resource": {
                 "resourceType": "Observation",
                 "id": "20170219-04BloodPressure",
              .. snip ...
    }
  ]
}

For more information about operations, including how they are invoked, see Operations.