What's the difference between a string and a token search parameter?

String parameters support partial, case-insensitive text matching, useful for names or descriptions, while token parameters typically require an exact match on a coded value or identifier, often scoped to a specific coding system.

How do I search for observations linked to a specific patient?

Use the patient or subject reference parameter with that patient's specific resource id, which filters results to only Observations whose reference points to that exact Patient resource rather than any other patient.

Can I combine multiple search parameters in one query?

Yes, most FHIR searches combine multiple parameters simultaneously, such as searching for observations matching both a patient reference and a date range together, narrowing results to exactly what your specific query needs.

What does chaining actually let me do that a simple search parameter can't?

Chaining lets you search one resource type based on criteria that live on a resource it references, such as finding Observations based on properties of the Patient they reference, rather than properties of the Observation itself.

Why would I use _include instead of making a separate API call?

_include retrieves related resources in the same response as your original search, reducing the number of round-trip API calls needed and often improving performance compared to fetching referenced resources with separate follow-up requests.

Is there a maximum number of results a single FHIR search can return?

Yes, servers typically enforce a maximum page size regardless of what _count value you request, so plan for pagination through Bundle links rather than assuming a single request will return an unlimited result set.

FHIR Search Parameters Guide: Queries That Work

TL;DR

FHIR search parameters come in a handful of types — string (partial, case-insensitive text match), token (exact match on codes/identifiers), reference (search by a linked resource), and date/quantity (with comparison prefixes like gt, lt, ge, le). Chaining lets you search one resource by properties of a resource it references; _include and _revinclude pull related resources into the same response in either direction; composite parameters search combined conditions together. Results paginate via Bundle next/previous links, with _count controlling page size (servers cap the max regardless of what you request) and _sort controlling order.

Quick answer

FHIR search parameters are what turn a FHIR server from a simple lookup-by-id API into a genuinely queryable data store, letting you find resources matching specific criteria rather than needing to know every resource's exact identifier in advance. Each resource type defines its own set of supported search parameters, and understanding the different parameter types, how to chain searches across related resources, and how pagination actually works separates queries that return exactly what you need from ones that silently miss data or return more than expected.

Below is how the core parameter types work, how chaining and includes let you search across related resources, and how pagination and sorting behave in practice. If you're building complex FHIR queries, our free Mirth Health Check can review your specific search logic directly — part of the Mirth Connect support work we do for US healthcare teams.

Understanding the Core FHIR Search Parameter Types

FHIR defines several distinct parameter types, each suited to a different kind of data, and knowing which type applies to a given field determines exactly how you need to structure your search query.

String Parameters for Partial Text Matching

String parameters, like a patient's name, support partial and case-insensitive matching by default, meaning a search for a partial name fragment can return results even without an exact, complete match to the stored value.

Token Parameters for Coded and Identifier Values

Token parameters handle coded values and identifiers, like a specific LOINC code or a patient's medical record number, typically requiring an exact match on the code or identifier value, optionally scoped to a specific coding system.

Reference Parameters for Linked Resources

Reference parameters let you search based on a resource's relationship to another, such as finding all Observations where the patient reference points to a specific Patient resource's id.

Date and Quantity Parameters With Comparison Prefixes

Date and quantity parameters support comparison prefixes like gt, lt, ge, and le, letting you search for observations after a specific date or lab values above a certain numeric threshold rather than only exact matches.

Chaining and Includes for Searching Across Resources

Real queries often need to search based on criteria that live on a different, related resource, and FHIR provides specific mechanisms for exactly this kind of cross-resource searching.

Chained Parameters Search Through References

Chained parameters let you search one resource type based on properties of a resource it references, such as finding all Observations where the referenced Patient's name matches a specific value, using dot notation to chain the search.

_include Pulls Related Resources Into the Response

The _include parameter lets you retrieve a resource along with resources it references in a single response, such as fetching Observations along with their referenced Patient resources, avoiding a separate follow-up request.

_revinclude Pulls in Resources That Reference the Result

_revinclude works in the opposite direction from _include, retrieving resources that reference your search results, such as finding a Patient along with every Observation that references that specific patient.

Composite Parameters Search Combined Conditions

Composite search parameters let you search on a combination of two related values simultaneously, such as finding observations matching both a specific code and a specific value together, rather than searching each independently.

How Pagination and Sorting Actually Work

Large result sets need to be paginated and often sorted in a specific order, and FHIR defines standard mechanisms for both that behave consistently across compliant servers.

_count Controls Page Size for Large Result Sets

The _count parameter specifies how many results to return per page, and servers typically enforce a maximum page size regardless of what you request, so don't assume an arbitrarily large _count value will always be honored.

Bundle Links Provide Pagination Navigation

Search results return as a Bundle containing next and previous links, letting your application navigate through additional pages of results without needing to manually calculate offset values yourself.

_sort Orders Results by a Specific Parameter

The _sort parameter lets you order results by a specific field, such as sorting observations by date, with a minus prefix indicating descending order rather than the default ascending sort.

Total Result Counts May Not Always Be Included

Depending on server configuration, the total count of matching results may or may not be included in the Bundle, so don't assume every FHIR server will tell you the full result count upfront by default.

When to call for help

If a query is silently missing data or returning more than expected, the cause is usually a mismatch between the parameter type you're using and what the field actually needs. Our free Mirth Connect health check reviews your search logic as part of the standard diagnostic.

Book a Free Health Check →

Troubleshooting something specific? Send us the log, or check pricing for our support plans.

FHIR Search Parameters Guide: Building Queries That Actually Work