Support for FHIR Search API queries

This issue covers an expansion of the Search API implementation within the Pathling server, and supporting functions within the library API.

The implementation will translate FHIR search parameters into FHIRPath expressions that can be evaluated using the existing FHIRPath engine.

Core concepts

1. Search parameter to FHIRPath translation: Convert any search parameter defined within the FHIR specification into a FHIRPath expression. The FHIR spec already defines FHIRPath expressions for each search parameter, which we can leverage directly. Note that this will require implementation of #2398, #2383, #2522 and verification that the FHIR search expression tests are passing.

2. Search value to FHIRPath literal translation: Convert search parameter values into FHIRPath literals appropriate for the parameter type (token, date, quantity, string, etc.).

3. Prefix to operator mapping: Support the standard FHIR search prefixes and map them to FHIRPath operators.

By combining a search parameter expression with a value expression using the appropriate operator, we produce a boolean FHIRPath expression that filters search results.

In scope

Search parameter types

The following search parameter types will be supported:

• Token
• Date
• Quantity
• String
• Reference
• URI
• Number

These types cover the core use cases for cohort building: coded values (Token), temporal filtering (Date), numeric comparisons (Quantity, Number), text matching (String, URI), resource relationships (Reference), and combined criteria like code-value pairs (Composite).

Prefixes

The following prefixes will be supported:

• eq (equality)
• ne (not equal)
• lt (less than)
• le (less than or equal)
• gt (greater than)
• ge (greater than or equal)

These prefixes enable date range queries (e.g., birthdate=ge1990-01-01&birthdate=lt2000-01-01) and numeric comparisons for lab values (e.g., value-quantity=gt10). The ap (approximately) prefix is excluded as it has limited use cases.

Modifiers

The following modifiers will be supported:

• :not (negation)
• :exact (case-sensitive exact match, string only)

The :not modifier enables exclusion criteria. The :exact modifier supports precise identifier matching. Other modifiers like :missing, :contains, :below, and :above are excluded to limit initial scope.

Boolean logic

The following will be supported:

• AND (repeated parameters)
• OR (comma-separated values)

These operators enable complex cohort definitions combining inclusion and exclusion criteria across multiple conditions.

FHIRPath filter parameter

The existing fhirPath named query (activated via _query=fhirPath) will continue to be supported. When activated, the filter parameter accepts arbitrary FHIRPath expressions. These can be combined with standard search parameters, allowing mixed queries such as:

GET /Patient?_query=fhirPath&filter=name.given.first()='John'&gender=male

If the fhirPath named query is not activated, any filter parameters should be ignored.

Search control parameters

The following search control parameters are already supported via HAPI FHIR:

• _count (pagination)
• _offset (pagination)
• _total (Bundle.total)
• _summary (including _summary=count)
• _elements (element filtering)
• _format (response format)
• _pretty (pretty printing)

Out of scope

• Chained parameters (e.g., subject.name=peter)
• Common parameters (_id, _lastUpdated, _tag, _profile, _security)
• _text / _content (full-text search)
• _list
• _sort
• _include / _revinclude
• _contained / _containedType
• _filter parameter
• Geospatial search (near)
• Reverse chaining (_has)
• Composite search parameters

Library API additions

The following methods will be added to the Java library API and exposed in the Python and R libraries.

Search expression to column

A method that takes a FHIR search expression (URL query string) and returns a Spark column representing the boolean filter condition.

// Java
Column searchToColumn(String resourceType, String searchExpression)

# Python
pc.search_to_column("Patient", "gender=male&birthdate=ge1990-01-01")

# R
pc %>% search_to_column("Patient", "gender=male&birthdate=ge1990-01-01")

FHIRPath expression to column

A method that takes a FHIRPath expression and returns a Spark column. This provides direct access to the FHIRPath engine for use in DataFrame operations.

// Java
Column fhirPathToColumn(String resourceType, String fhirPathExpression)

# Python
pc.fhirpath_to_column("Patient", "name.given.first() = 'John'")

# R
pc %>% fhirpath_to_column("Patient", "name.given.first() = 'John'")

These columns can be used with standard Spark DataFrame operations such as filter(), where(), or select().

Initial use case

The intent is for us to be able to implement the _typeFilter parameter within the server using the Library API exclusively.