diff --git a/engine/src/main/java/com/google/android/fhir/search/Search.kt b/engine/src/main/java/com/google/android/fhir/search/Search.kt index 4d9586b275..f30623bff4 100644 --- a/engine/src/main/java/com/google/android/fhir/search/Search.kt +++ b/engine/src/main/java/com/google/android/fhir/search/Search.kt @@ -34,6 +34,25 @@ import org.hl7.fhir.r4.model.ResourceType * }) * } * ``` + * ### Performance Tip: + * Avoid requesting all resources at once — especially if they number in the thousands — as it can + * significantly impact performance due to memory use and JSON deserialization overhead. + * + * ### Recommended Usage: + * Always paginate queries using `.count()` and `.from()` in [Search] to fetch only the number of + * results needed for the UI. + * + * Example (Paginated Search): + * ``` + * val results = fhirEngine.search { + * count = 20 // Limit to 20 results + * from = 0 // Offset for pagination + * } + * ``` + * + * For technical context, see: + * - Issue: https://github.com/google/android-fhir/issues/2684 + * - PR with performance metrics: https://github.com/google/android-fhir/pull/2669 * * @param init The lambda expression used to configure the [Search] object. * @return A list of [SearchResult] objects containing the matching resources and any included