Tech Talk: The Life of a Query

Every time the Particle Health platform gets a request to retrieve clinical records for a set of patient demographics, that’s a separate query. When we receive that query, our platform serves back a response with an indication that we're doing some processing behind the scenes. 

But what exactly is going on under the hood? Let’s take a look at 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 endpoints provided, each subquery makes requests for information about the patient demographics. While each network partner has their own system-specific implementation, the interactions boil down to the same three network calls for each. First, Particle asks if the network partner has knowledge about the given patient. If they do, we will request the metadata associated with any documents they have for that patient. Finally, Particle retrieves all documents from that network partner.
   
   
5. Data Transformation: Subqueries will retrieve data in the C-CDA format by default. But what happens when the initial 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.
   

From start to finish, Particle accurately and efficiently handles requests for clinical data. Our platform brings results from multiple networks back to you. Thanks to our expert engineering team, this is a smooth process for our end users!

‍This article comes from Particle Health’s API documentation.