FHIR GraphQL Connection API

[msdrigg]

FHIR GraphQL Connection API

The connection api for graphql is outlined here: https://hl7.org/fhir/graphql.html#searching

It is an alternative api to query lists of resources that provides some additional metadata about the resource list.

Specifically, it allows querying for ResourceConnections of the form

{ 
   ConditionConnection (clinical_status: active, patient: example) { 
     count offset pagesize
     edges {
       mode, score, resource { id, active }
     }
     first previous next last
   } 
}

The equivalent query with the ResourceList api would look like this

{ 
   ConditionList(clinical_status: relapse, patient: example) { 
      id, active
   } 
}

Simple queries are more difficult to express with the Connection api, but it offers metadata about the query that could not be expressed in the List api.

My specific use case is wanting to know how many items are in the list without having to query for every item (there may be very many items). I don't see a way to do this with the existing api.

Challenges with implementing this new feature

• Implementing the cursor parameter in a reasonable way
  • Fhir spec doesn't specify how to implement cursors
  • I could see cursors being implemented as a combination of an offset and a count for ease of implementation
  • Cursors could be a reference to the last datatype int the list, but I don't know of an easy api to query postgres for next x items matching these filters after this item
• Ongoing maintenance
  • Fhir spec doesn't specify how to deal with this either :(

Alternatives Considered

• Just query for every resource
  • This is likely what I will do in the meantime because my queries are currently not too large
• Perform the query with the fhir api instead of the graphql api
  • The standard api doesn't offer the query nesting that the graphql api does offer

[reshmakh]

Tagging #1274 here fore reference

[msdrigg]

Also wanted to mention that there is a https://github.com/supabase/pg_graphql extension that provides a graphql api for postgres. I took a look at how they handle cursors because I figured Medplum could use a similar approach.

They create cursors by base64 encoding the list of all of the values used in the ORDER BY clause as well as the primary key. For example, for a query like

{ 
   ConditionConnection (clinical_status: active, patient: example, _sort: "-code") { 
     count offset pagesize
     edges {
       mode, score, resource { id, active }
     }
     first previous next last
   } 
}

The cursor for each returned result would be of the form base64Encode(["Condition.code", "Condition.id"])

This cursor provides enough information to recreate the query and filter out all values either before or after any specific Condition

There is still some work to actually implement the mapping from GraphQL Query + Resource -> Cursor and GraphQL Query + Cursor -> SQL Query, but there are others who have shown that it can be solved without storing any extra information on the server.

[codyebberson]

Hi @msdrigg thanks for the suggestion.

A rough implementation of this should fit pretty nicely into the existing GraphQL implementation with 3 steps:

1. Define the Connection response type
2. Create ${resourceType}Connection fields within each resource type, similar to how we do ${resourceType}List: https://github.com/medplum/medplum/blob/main/packages/server/src/fhir/operations/graphql.ts#L192-L197
3. Create a resolver that returns the Connection response rather than a normal list of resources, similar to the existing resolveBySearch: https://github.com/medplum/medplum/blob/main/packages/server/src/fhir/operations/graphql.ts#L389-L412

We do not have any values for mode or score at the moment, but everything else should be straightforward.

Regarding cursors... We have looked at using Postgres cursor techniques, but thus far have been ok with using simple LIMIT and OFFSET, which should be fine up until searches span millions+ of resources in the same search. If you are running into search performance limitations, then we can revisit that assessment.

[msdrigg]

So you're saying that the first, next, and last cursor parameters would just be the offset values?

I mentioned cursors not because of performance issues, but because of the fact that paging through data with offsets could miss data if a resource has been created or updated since the paging started. Even with small resource counts.

Have you run into this issue in practice?

[codyebberson]

Oh, I see. Yes, I meant first, next, and last could be the URL's that we generate for Bundle.link entries in search results.

because of the fact that paging through data with offsets could miss data if a resource has been created or updated since the paging started

First, this depends on if we're using the word "cursor" to refer to a Postgres Cursor or "keyset pagination", which people sometimes refer to as "cursor".

For a proper Postgres Cursor... In my experience, this creates a lot of awkward complexity in the server to figure out when you can discard the cursor reference. Postgres Cursors are resource intensive, and have scale issues. This StackOverflow answer provides a nice summary of the challenges of using Postgres Cursors: https://stackoverflow.com/a/13149184/2051724

For keyset pagination... This has the outward appearance of a cursor, because the search URL has an opaque "cursor" query string parameter. But behind the scenes, it's just a representation of the last row in token form. In my experience, keyset pagination is a good thing, and it has been our intent to eventually use it.

Keyset pagination can prevent one type of data misses, but not all. Consider:

1. Resources "a, b, c, d, e", which have meta.lastUpdated values ascending in that order
2. You do a search for resources using _lastUpdated ascending with page size of 3
3. The first page returns "a, b, c"
4. Someone else updates "b", so the last updated order becomes: "a, c, d, e, b"
5. You do a search for the 2nd page

What happens?

• Using LIMIT and OFFSET, page 2 returns "e, b" which is incorrect.
• Using keyset pagination, page 2 returns "d, e, b" which is more correct, but still has the risk of duplicate data.
• Using Postgres cursors would correctly return "d, e", but has the performance risk of the user never actually requesting page two.

Have you run into this issue in practice?

Unfortunately, yes, we have run into variants of this problem.

The best best option is to setup an ETL to a data warehouse, where you can have a more reliable query environment.

Outside of that, there is usually a business logic / operational component, where you can make certain assumptions about data updates during certain times of day, or about data in certain statuses, etc.

[codyebberson]

If you need an extra layer of guarantees, then you can request overlapping pages, to ensure that the boundary items are what you expected. For example, request 1-10, 10-20, 20-30, etc.

[msdrigg]

First, this depends on if we're using the word "cursor" to refer to a Postgres Cursor or "keyset pagination", which people sometimes refer to as "cursor".

Ahh I see the confusion—I was meaning “keyset pagination cursor” not “postgres cursors”

• Using keyset pagination, page 2 returns "d, e, b" which is more correct, but still has the risk of duplicate data.

True—I wasn’t considering this situation but there could easily be data misses/duplicates even with keyset pagination

[codyebberson]

Cool, we're on the same page. We're tracking keyset pagination (#1281). No ETA :(

[codyebberson]

Implemented in #1934

Released in 2.0.18: https://github.com/medplum/medplum/releases/tag/v2.0.18