The Life of a Query

When the Particle Health platform gets a request to retrieve clinical records for a set of patient demographics, we serve back a response with an indication that we're doing some processing behind the scenes. But what exactly is going on under the hood? We've outlined the life of a query below so that you can better understand how the platform works.

  1. Update the Master Patient Index: The first step each query takes is updating Particle's Master Patient Index so we can ensure we always have the latest demographics being represented for a given patient.

  2. Record Locator: Next, we'll use the geographic information provided in the patient's demographics, as well as any location hints provided, to feed our proprietary Record Locator algorithm to determine all of the network partners that may have data for this request.

  3. Subquery Split: Using this list of network partners, we split the query into a multitude of subqueries, each representing the patient demographics and a unique partner endpoint to request data from. Queries are typically split into hundreds of subqueries during this process.

  4. Query Networks: Using the partner endpoint provided, each subquery makes requests for information about the patient demographics. While each network partner has its own process that happens behind the scenes, it always boils down to the same three network calls for each. They first identify if they have data for the patient based on the demographics provided, then they identify if they have any associated documents, and finally, they will return all documents.

  5. Data Transformation: Subqueries are responsible for retrieving data in C-CDA format. But what happens when the query is made for FHIR data instead? Well, every document retrieved from the network goes through a data transformation pipeline that converts the underlying C-CDA documents into FHIR R4 and stores this data in Particle's FHIR Storage. Read more in C-CDA vs. FHIR and Cooking with FHIR.

  6. Data Aggregation: With hundreds of subqueries all making requests in parallel, it's a tricky process to ensure we've got all of the data back before wrapping up processing. Every time a subquery completes, we run checks to determine the number of subqueries still outstanding. When that number hits zero, we take all of the resulting C-CDA files and bundle them into a single ZIP file for retrieval. The query is then marked complete. At this point, the query will read COMPLETE (if using the C-CDA API) or respond with a 200 (if using the FHIR API).

  7. Data Made Available: Once the query is complete, the data can be retrieved based on the API that was used to initiate the process. C-CDA queries can retrieve the C-CDA files or bundled ZIP file from the /Files/ endpoint, while FHIR queries can retrieve FHIR R4 JSON data using the /R4/ endpoint.

Did this page help you?