[hɐəmkɑ] - work

HowTo: The FHIR date Search Parameter – Understanding Prefixes, Intervals, and Combinations

2026-08-12T00:00:00+02:00

Anyone building or querying a FHIR server sooner or later runs into the date search parameter. At first glance it looks simple: ?date=2023-06-15. But as soon as prefixes like ge, sa, or ap come into play, and multiple date parameters get combined, things get confusing fast. This article brings order to the chaos: step by step, with timeline graphics for every case, and a quick-reference table for fast lookups.

Table of Contents¶

Table of Contents
Quick Reference: All Prefixes at a Glance
The Core Principle: FHIR Compares Intervals, Not Points in Time
- No prefix means eq, but precision still matters
The Nine Prefixes at a Glance
Matching Against Period and Range
Open (Incomplete) Periods
Combining Multiple date Parameters
The Full 3×3 Matrix of Range Combinations
Edge Cases: When Combinations Become Redundant or Contradictory
Practical Recommendations

Quick Reference: All Prefixes at a Glance¶

For a fast glance in between. Details and graphics for every row follow in the sections below.

Prefix	Name	Short rule	Example
(none)	implicit `eq`	Precision of the value determines the interval	`date=2023-06-15`
`eq`	equal to	Resource interval fully within the search interval	`date=eq2023-06-15`
`ne`	not equal to	Complement of `eq`	`date=ne2023-06-15`
`gt`	greater than	Extends beyond the end (overlap is sufficient)	`date=gt2023-06-15`
`lt`	less than	Begins before the start (overlap is sufficient)	`date=lt2023-06-15`
`ge`	greater or equal	`gt` or fully contained (`eq`)	`date=ge2023-06-15`
`le`	less or equal	`lt` or fully contained (`eq`)	`date=le2023-06-15`
`sa`	starts after	Entirely after, no overlap	`date=sa2023-06-15`
`eb`	ends before	Entirely before, no overlap	`date=eb2023-06-15`
`ap`	approximately	Overlap + similar order of magnitude	`date=ap2023-06-15`

Missing start/end on a Period: a missing start means -∞, a missing end means +∞. That's why sa can never match when start is missing, and eb can never match when end is missing (details in Section 4).

The Core Principle: FHIR Compares Intervals, Not Points in Time¶

The most important mental reset first: FHIR never treats date values as an exact point in time. It always treats them as an interval. How wide that interval is depends on the precision of the given value:

2023 → the entire year 2023
2023-06 → all of June 2023
2023-06-15 → all of June 15, 2023 (00:00–24:00)
2023-06-15T10:00:00 → (almost) an exact point in time

Every comparison operator then compares two intervals with each other: the search interval from your query parameter, and the resource interval from the resource's field (e.g. Patient.birthDate or Encounter.period).

No prefix means `eq`, but precision still matters¶

If you don't specify a prefix, the server assumes eq. The resource date must then lie fully within your search interval. The coarser the precision, the wider the interval, and the more resource values fit inside it:

FHIR date search parameter WITHOUT a prefix

date=2023-06-15 only matches this single day. date=2023-06, on the other hand, matches every day in June, including the 15th. That's the most common trap for beginners: a "less precise" search query isn't stricter, it's looser.

The Nine Prefixes at a Glance¶

FHIR defines nine prefixes for date in total. Each describes a different relationship between the search interval (red dashed in the graphic) and the matching range (colored/shaded):

All prefixes at a glance

Prefix	Name	Meaning
`eq`	equal to	Resource interval lies fully within the search interval
`ne`	not equal to	Complement of `eq`
`gt`	greater than	Resource interval extends beyond the end of the search interval
`lt`	less than	Resource interval begins before the start of the search interval
`ge`	greater or equal	`gt` or fully contained within the search interval (`eq`)
`le`	less or equal	`lt` or fully contained within the search interval (`eq`)
`sa`	starts after	Begins entirely after the end of the search interval, no overlap
`eb`	ends before	Ends entirely before the start of the search interval, no overlap
`ap`	approximately	Overlap, plus a similar order of magnitude between the intervals

Important, containment vs. overlap: Only eq (and, implicitly, sa/eb) require the resource interval to lie fully within, or fully separated from, the search interval. For gt, lt, ge, and le, an overlap is enough: the resource interval doesn't have to lie completely outside the search range, it just needs to extend past the respective boundary. More on that in the next section.

Matching Against `Period` and `Range`¶

The graphics above show the resource date as a thin red marker. That works for simple date/dateTime fields like Patient.birthDate. As soon as the target field is itself an interval (a Period, e.g. Encounter.period, Condition.onsetPeriod, or a Range), the distinction between containment (fully contained) and overlap (mere overlap) becomes crucial:

eq requires containment: the entire resource interval must lie within the search interval.
gt / lt / ge / le only require overlap: it's enough for the resource interval to extend past the respective boundary, even if part of it lies on the "wrong" side.
sa / eb require the opposite of overlap: the resource interval must lie fully, and without any overlap, on the respective side.

For a simple point-in-time field (no Period), this distinction barely shows, since the resource's start and end are (almost) identical. There, gt and sa behave de facto the same. The difference only becomes relevant for actual time spans. That's also why sa/eb are, per the specification, primarily intended for Period/Range values.

Example: An encounter runs from June 10 to June 20. The search date=gt2023-06-15 should find it, even though the encounter started before the 15th. What matters is only that it extends past the 15th (overlap with the range "after the 15th"). With date=sa2023-06-15, the same encounter would not match, because it doesn't lie entirely after the 15th. That's exactly the practical difference between gt and sa.

The following graphic makes this visible for all four "one-sided" prefixes (gt, sa, lt, eb) using the same three example periods: one entirely before, one overlapping the boundary, and one entirely after:

Matching against Period/Range (containment vs. overlap)

You can clearly see: gt and lt (blue shaded area, solid boundary line) let the overlapping Period B through as a match, while sa and eb (dashed boundary line) reject it. Only a period lying entirely on the correct side counts there.

Encounter timeframe	`date=gt2023-06-15`	`date=sa2023-06-15`
June 10–20 (overlaps the boundary)	✅ Match (overlap)	❌ No match (not entirely after)
June 16–20 (entirely after)	✅ Match	✅ Match
June 1–10 (entirely before)	❌ No match	❌ No match

Open (Incomplete) Periods¶

In practice, periods are often not closed, for example an ongoing encounter without an end, or an imported record with an unknown start. The FHIR standard handles this clearly:

A missing lower bound (start) is implicitly treated as less than any real date (i.e. -∞). A missing upper bound (end) is implicitly treated as greater than any real date (i.e. +∞).

This has noticeable consequences, especially for sa and eb:

An ongoing encounter (start set, end missing, so end = +∞) can never match eb (ends before). Its end never lies before any finite date. It will, however, match gt, because its (infinite) end always extends beyond any search boundary.
An encounter with an unknown start (start missing, so start = -∞) can never match sa (starts after). Its beginning never lies after any finite date. It will, however, match lt, because its (infinite) beginning always reaches before any search boundary.
A period with neither start nor end overlaps practically every overlap-based filter (gt, lt, ge, le). By definition, it "extends" past every boundary.

The same four prefixes as in Section 3, now with open instead of closed periods:

Matching against open (incomplete) Period/Range

Practical consequence: If you want to specifically exclude "ongoing" resources (e.g. active encounters, open orders) from a date-range search, eb/sa alone won't do it. You'll additionally need to filter by status, or explicitly by end:missing=true/start:missing=true, depending on what your server supports.

Combining Multiple `date` Parameters¶

In practice, a single prefix is rarely enough. Usually you want to define a range. FHIR servers always combine multiple date parameters in the same query with AND. Four typical patterns:

Combining multiple parameters (AND logic)

Combination	Example	Character
`ge` + `le`	`ge2023-01-01&le2023-12-31`	Closed interval (both bounds inclusive)
`gt` + `lt`	`gt2023-01-01&lt2023-12-31`	Open interval (both bounds exclusive)
`sa` + `eb`	`sa2023-01-01&eb2023-12-31`	Strictly separated range, primarily for Period values
`ge` + `lt`	`ge2023-06-01&lt2023-07-01`	Half-open interval `[start, end)`, the standard pattern for "exactly one month"

If you work with [start, end) in timestamp-heavy ETL pipelines, ge + lt will look familiar: it's exactly the same pattern used for classic time-window queries in SQL.

The Full 3×3 Matrix of Range Combinations¶

The four patterns above are only the most common ones. In fact, any lower bound can be combined with any upper bound:

Lower bounds: ge, gt, sa
Upper bounds: le, lt, eb

That gives 3 × 3 = 9 possible combinations, all spec-compliant:

3x3 matrix of range combinations (lower bound × upper bound)

They differ only in whether the respective boundary is inclusive (solid line) or exclusive (dashed line), and whether it's a simple value comparison (ge/gt/le/lt) or a strict Period comparison (sa/eb). There is no explicit exclusion rule in the FHIR standard. Every cell in this matrix is a valid, functioning query.

Edge Cases: When Combinations Become Redundant or Contradictory¶

Not every syntactically valid combination is practically meaningful. There are three categories you should know about before one of them ends up in a generated query by accident:

Edge cases in parameter combinations

Redundant combinations¶

Don't change the result, but aren't technically an error either: - eq plus a boundary that's already satisfied by the eq interval (eq2023-06-15&ge2020-01-01): the extra condition is superfluous. - Two conditions of the same directional type (ge2020-01-01&ge2023-01-01): only the stricter (later) lower bound actually takes effect.

Combinations with a guaranteed empty result¶

Structurally impossible to satisfy: - eq + ne on the same value (eq2023-06-15&ne2023-06-15): mutually exclusive conditions. - The lower bound lies after the upper bound in time (ge2023-06-01&le2023-01-01): no date can satisfy both at once.

The server will syntactically accept such queries and simply return an empty result set. Not an error, but not a helpful response either. It's worth validating this client-side before sending the request.

Unusual but valid edge cases¶

Three or more date parameters, e.g. a year range with a single day excluded: ge2023-01-01&le2023-12-31&ne2023-06-15.
ap combined with a boundary, e.g. ap2023-06-15&ge2023-01-01: rarely used, since ap is already fuzzy by nature, and the tolerance calculation remains server-dependent.

Practical Recommendations¶

For simple range filters, ge + lt (half-open interval) is usually the most robust pattern. It avoids rounding issues at precision boundaries (no off-by-one when you mean "through December 31st inclusive").
Use sa/eb deliberately when you need complete separation on Period/Range fields (see Section 3), e.g. "encounter entirely after discharge X". For a simple "from date X onward" filter, you usually mean ge/gt, not sa.
For Period fields with possible open ends (see Section 4), don't forget: sa/eb structurally never match there. Additionally filter by :missing or status if needed.
Before sending a multi-parameter query, it's worth a quick sanity check on the logical consistency between the lower and upper bound, to avoid empty results caused by configuration mistakes in your own pipeline.

With the quick reference above and the six graphics in mind, no prefix, all nine prefixes individually, containment vs. overlap for Period/Range (both open and closed), typical combinations, the full 3×3 matrix, and the edge cases, your next date query in FHIR should no longer be a mystery.

Scientific workflow with BOOX Note Air 3 C

2024-01-26T00:00:00+01:00

Recently I bought an ONYX BOOX Note Air 3 C to support my scientific workflow. In the end of last year I realized why I wasn't moving forward in my scientifc career. To be honest I was very well aware of one main reason, which was that I hadn't enough self-discipline to read the sources needed for my research, but I didn't know the reason for it until last year. It turned out that the main reason was that most of the sources were in digital form and I couldn't bring myself to read them on the computer monitor. A tablet or smartphone weren't viable alternatives either, as the displays simply tire me out too quickly.

An e-book reader was a potential solution. But a colleague has been working with a Remarkable 2 for some time, which I also found very interesting. However, the reader experience with this device was not good. After some research, I decided on a Boox Note Air 3 C, which seemed the most promising in terms of reader and note-taking functionality. Nevertheless, I wasn't quite sure whether I could establish a meaningful workflow for scientific work in my everyday working life with the device.

After a few weeks of use, I can now say that the Note Air 3 C fully meets my expectations. My main usage scenarios so far have been reading textbooks, including annotating directly in the PDF and general note-taking. In the first few days of use, I naturally tried to get to grips with the device's on-board features. I tried to create a usable workflow with the help of the BOOX cloud and the BOOXDrop function. However, this turned out to be quite incomprehensible. Mainly because my primary operating system is a Linux system and the synchronization tools are only available for Windows and Mac OS.

And even though there are tools like Marcin Juszkiewicz's onyx-send2boox, I didn't really like the idea of sending all my data through the manufacturer's cloud storage right from the start. I still have the cloud and the backup to it activated. However, my daily workflow no longer uses it.

Instead, I have now established a workflow that relies mostly on self-hosted services and open source applications.

Web browsing¶

I have been using Firefox as my web browser on all my computers for ages. And I also had Firefox as the default browser on my Android smartphone. I recently switched to an iPhone, but there is also a mobile Firefox for iOS (unfortunately without add-on support).

It was therefore obvious to install Firefox on the Note Air 3 C as well. Especially to be able to install add-ons. Above all uBlock Origin to block unnecessary and in the worst case (for the battery of an e-ink device) animated advertising on websites. Using Firefox on all devices allows me to move tabs between devices at will (as long as the installation is linked to my Mozilla account). Of course, I also use a cloud service here, but the Mozilla cloud, which has been mature for years, seems far more trustworthy to me than the cloud of a Chinese hardware manufacturer. And the added convenience of synchronizing not only tabs, but also bookmarks and history is simply too great not to use it.

Bookmarking (read-it-later)¶

I have always used bookmarks in the classic sense, i.e. the bookmarks in the web browser, only as links to frequently visited websites. I have never managed short-term bookmarks in the browser bookmarks. For me, this has always been the task of read-it-later apps and services.

Even though a read-it-later service has been integrated into Firefox for some time with Pocket, I have never used it. Instead, I have been running my own Wallabag instance for some time now. I don't have much to say about this. It just works.

The wallbag app runs smoothly on the Note Air 3 C and allows me to call up my read-it-later bookmarks on this device at any time. Adding entries to the app is done via the Android sharing function and therefore also allows bookmarks to be added directly from the web browser.

wallabag app on BOOX Note Air 3 C

Literature management¶

Since I personally and we in our scientific working group operate a shared library via Zotero, it was only natural that I should use it on the Note Air 3 C as well. Unfortunately, there is no Zotero app in the Play Store that works on the device. But that's only half the story.

On the one hand, there is now an official Zotero app in the beta phase that works on the device and, on the other hand, the currently much better app Zoo for Zotero also works. With the caveat that the latter cannot be installed from the Play Store. But a direct installation via APK (which can be obtained from relevant sources) is possible and has run without any problems for me so far. In addition, the last update of the app is from August 2021, so the lack of an automatic update by the Play Store is also a minor risk. Nevertheless, you should of course keep an eye on the development of direct APK installations and carry out a manual update if necessary.

Zoo for Zotero app on BOOX Note Air 3 C

The Zotero libraries (both my personal and the group library) contain not only scientific publications relevant to the respective research, but also other specialized literature such as textbooks and links to relevant websites and blog posts.

As a result, Zotero has now become the standard synchronization method for e-books for me. I simply create an entry in Zotero for a new e-book using the ISBN and then attach the file to the entry. On the Note Air 3 C, I can sync the e-book (or any academic paper) directly from the Zoo for Zotero app. PDFs and also EPUBs are opened directly in the BOOX Neo Reader app, so that annotations are possible out of the box.

The only drawback is that the annotated files are of course not synchronized directly back into Zotero. On the other hand, with regard to the group library, this is perhaps not such a bad thing. After all, not all of my colleagues want to have my annotations in their library.

Occasionally I also need a quick way to simply transfer the clipboard from my computer to the Note Air 3 C or vice versa. Since I run Linux desktop systems on all my computers, as mentioned above, the best option in my opinion is KDE Connect. This not only offers clipboard sharing, but also functions such as sharing notifications or remote input.

Even though it is called KDE Connect, it is also compatible with GNOME desktops thanks to the GSConnect extension.

AI assistance¶

Even if it doesn't look particularly good on the e-ink display due to the heavily animated live output, the official ChatGPT app can be used. But I only use it when I really don't have any other device to hand, which is never the case as I always have at least one smartphone nearby. And despite the smaller display, the usability is far better here.

ChatGPT app on BOOX Note Air 3 C

Collaboration¶

Since we use Jira and Confluence as collaboration tools in our working group, I also use the official apps for Jira Data Center and Confluence Data Center. But here, too, I have to say that I only use the apps when I don't have another device to hand. So I can only say that they work and are easy to use, but I haven't done any in-depth usage analysis.

E-mail¶

As you may have guessed from the previous paragraphs, I don't really use the Note Air 3 C as a tablet in the classic sense. Nevertheless, I occasionally need to open an email on the tablet. I think that any standard email client should work on the device, but for the sake of completeness I'll also mention that Marcel Bokhost's brilliant open source email client FairEmail works wonderfully on the device.

Calendar (and contacts)¶

Calendar access (and synchronization) is another functionality that I don't need all the time. But every now and then it is useful to be able to view my calendar on the Note Air 3 C. Since I synchronize my calendar (also on other devices) via CalDav (and my contacts via CardDav), I simply use DAVx⁵ on the device to synchronize calendar and contacts.

As the device does not come with a calendar or contacts app as standard, these have to be installed later. I've been a big fan of the Simple Calendar and Simple Contacts apps for years. However, I must mention that I always use the Pro versions. So it may be that the free version lacks features or has other disadvantages.

Public libraries¶

As I live in Germany, I was particularly interested in whether and how well the Onleihe app for german public libraries works on the BOOX Note Air 3 C. What can I say? What can I say, it works, but the app looks very restless on the E-Ink display due to the many color representations. Although you can also change the color scheme to a dark standard theme, the green areas (visible in the screenshot below) still look very uneven, as the black used then does not form a uniform color area. Therefore, it doesn't really invite you to browse, but it's enough to quickly borrow an e-book or an e-magazine.

Onleihe on BOOX Note Air 3 C

Also reading electronic newspaper via the Onleihe App works quite well. Of course, you need to zoom quite a lot to compensate for the number of columns in a daily newspaper.

Reading newspaper via Onleihe app on BOOX Note Air 3 C

Alternative app store¶

F-Droid can be installed on the Note Air 3 C not only to have an alternative to the Play Store, but also to be able to install open source apps that may not have been released for the device in the Play Store. This also allows the installation of free builds for some apps, which offer the full range of functions that would otherwise only be available via a Pro upgrade.