Searching and Pagination

Health Gorilla supports FHIR search operations that allow you to retrieve only the clinical data you need. By applying filters such as patient identity, date, category, or code, you can narrow results to relevant records and reduce system load. When result sets are large, pagination delivers data in manageable chunks to improve performance and reliability.

Search Syntax

FHIR searches use HTTP GET requests with parameters appended to the resource type in the URL. You can include one or more filters in a single search.

Example:

GET /fhir/R4/Observation?patient=12345&category=vital-signs&date=ge2024-01-01

Common Search Parameters

Parameter	Description
`patient`	Specifies the subject of the resource. Required for most clinical resource queries.
`date`	Filters resources by clinically relevant dates. Supports prefixes such as `ge`, `le`, or date ranges.
`category`	Filters by high-level clinical category using coded values such as `vital-signs`.
`code`	Filters by a specific test, condition, or procedure code. Accepts standard code systems such as LOINC or SNOMED CT.
`_lastUpdated`	Filters by the timestamp of the most recent resource modification. Useful for delta queries.
`_count`	Limits the number of results returned per page. Used in pagination.

Combining Filters

Multiple parameters can be combined in a single request using the ampersand (&) delimiter. Depending on the resource, advanced techniques such as chained parameters or reverse includes may also be supported.

Example:

GET /fhir/R4/DocumentReference?patient=12345&category=clinical-note&date=ge2023-01-01

Best Practices for Searching

Always include the patient parameter when querying clinical resources
Use date or _lastUpdated filters to reduce response volume and improve performance
Apply standard category and code values from supported terminologies
Confirm supported parameters per resource
Avoid using unsupported filters or includes that may slow search execution

Pagination

When a FHIR search returns more results than can fit in a single response, Health Gorilla delivers the results in manageable chunks using pagination. Each response contains a Bundle with a limited set of resources and a link array for navigation. Pagination prevents timeouts, reduces payload size, and allows your system to process large datasets incrementally.

When to Use Pagination

Pagination is triggered automatically when a result set exceeds the configured size limit. This commonly occurs with high-volume resources such as Observation, DocumentReference, or Encounter. Instead of one oversized payload, you receive a paginated Bundle with navigation links.

Pagination Structure

A paginated response includes a Bundle.link array with URLs for navigating between pages.

Relation	Description
`self`	URL for the current page
`next`	URL to retrieve the next page of results
`previous`	URL to retrieve the previous page, if supported
`first`	URL for the first page of results, if available
`last`	URL for the final page of results, if available

Follow the next link until no further results remain.

Request Parameters

Several parameters may influence pagination behavior. The most relevant include:

Parameter	Description	R4	STU3
`_count`	Maximum number of resources to return per page	✔	✔
`_include` and `_revinclude`	Include related resources, which can increase result set size and trigger pagination	✔	✔
`_sort`	Optional sort order, if supported for the resource	Partial	Partial
Filters (e.g. `patient`, `date`, `status`)	Influence result size and pagination frequency	✔	✔
`page-token`	Health Gorilla–specific pagination token used in `next` links	✔	—

Note: The page-token parameter is returned by the server and should not be modified. It is not supported in STU3 environments.

Example Flow

Submit a FHIR search request with optional _count and filters.
Review the Bundle.link array for a next relation.
Follow the next link to retrieve the next page.
Continue until no next link is present.

Best Practices for Pagination

Always use the next link exactly as returned in the response
Set a reasonable _count to balance performance and payload size
Avoid concurrent paginated requests for the same query
Log and monitor paging behavior for long-running queries

Pagination behavior is consistent across all supported resource types. Result sets may vary depending on tenant configuration, applied filters, and source data volume.