Execute a Query and Get Its Results

The service queries the data mart using the query definition and generates output based on the result option. Each query request and its results will be recorded under the given user id and project id.
The server will read the value <result_waittime_ms> from the <request_header> and if the query did not complete before the wait time specified in the request, it will send a response to the client with a "PENDING" status. The client can later send a query instance request to see if the query has completed and retrieve the query result information.
The query definition option:

Element Name	Description
query_name	Name of the query
query_description	Description of the query
query_timing	The values of the query timing are the same as the values of the <panel_timing> option in the panel definition. The panel timing will override the query timing value if both have values specified.
Value	Description
ANY	The query result doesn't depend on the patient's encounter / visit value
SAME SAMEVISIT	The patients selected within the panel will have the same Encounter / Visit.
SAMEINSTANCENUM	The patients selected across the panels will have the same Encounter / Visit, CONCEPT_CD, START_DATE, PROVIDER_ID, and INSTANCE_NUM value in the fact table.

|

specificity_scale	Not implemented
panel	The panel option is defined in the previous section called Panel Definition Details.

The service supports the following result options.

PATIENTSET
PATIENT_ENCOUNTER_SET
PATIENT_COUNT_XML
PATIENT_GENDER_COUNT_XML
PATIENT_AGE_COUNT_XML
PATIENT_VITALSTATUS_COUNT_XML
PATIENT_RACE_COUNT_XML

Note
If the result option (<result_output_list>) is not specified in the request, then the default result option is "PATIENTSET".

CRC_ENABLE_UNITCD_CONVERSION=ON|OFF
(https://i2b2.atlassian.net/wiki/display/DevForum/Metadata+XML+for+Medication+Modifiers)
To use LARGETEXT constraint in the query, the minimum user role of DATA_DEID is required.
Notes:

The CRC will take advantage of simple query by not using the temp table. As a default it is advisable to set the flag <query_mode> optimize_without_temp_table</query_mode> in the <psmheader>.
To speed up the query, the CRC selects which panel SQL to run first. The selection of panel will be based on the individual item / concept's toal_num value specified on the Ontology's Metadata table. It is not necessary to populate total_num for each of the Metadata's concepts, but just populating some of the commonly used concepts like the '\Demographics\Gender\Male' would help. Please refer to the Ontology cell if you would like to automatically populate the total_num column for all the Ontology's metadata concept.
If the concepts numerical facts value is not stored in normalized unit_cde, then the user can enable the unit conversion in the query before applying the value constraint by setting the PM project param (CRC_ENABLE_UNITCD_CONVERSION=ON|OFF). The fact's nval_num column will be converted based on the metadata xml (<ConvertingUnits/>, <MultiplyingFactor/> exists in the Ontology cell before applying the query's value constraint. For better query performance do not enable this option, make sure numerical fact values are in the normalized units.
To enable the process timing information in the <query_instance> section of the response set the PM project param (PM_ENABLE_PROCESS_TIMING=INFO|DEBUG).

Result Output Name	Description	Output Value
PATIENTSET	The patient set from the query will be persisted in the database	Not applicable
PATIENT_ENCOUNTER_SET	The set of patients and the corresponding encounter will be persisted in the database.	Not applicable
PATIENT_COUNT_XML	Returns the patient count in the i2b2 result xml format. The i2b2 result format is similar to the name-value pair. (i2b2_result_msg.xsd)	<i2b2_result_envelope xmlns:ns10="http://www.i2b2.org/xsd/hive/msg/result/1.1/"> <body> <result name="PATIENT_COUNT_XML"> <data type="int" column="patient_count">1000</data> </result> </body> </i2b2_result_envelope>
PATIENT_GENDER_COUNT_XML	Returns the patient gender count in the i2b2 result xml format. Refer to i2b2_result_msg.xsd for the i2b2 result format.	<i2b2_result_envelope xmlns:ns10="http://www.i2b2.org/xsd/hive/msg/result/1.1/"> <body> <result name="PATIENT_GENDER_COUNT_XML"> <data type="int" column="Female">100</data> <data type="int" column="Male">200</data> <data type="int" column="Unknown">9</data> </result> </body> </i2b2_result_envelope>
PATIENT_AGE_COUNT_XML	Returns the patient age count in the i2b2 result xml format. Refer to i2b2_result_msg.xsd for the i2b2 result format.	<i2b2_result_envelope xmlns:ns10="http://www.i2b2.org/xsd/hive/msg/result/1.1/"> <body> <result name="PATIENT_AGE_COUNT_XML"> <data type="int" column=">= 65 years old">83</data> <data type="int" column=">= 85 years old">6</data> <data type="int" column="0-9 years old">1</data> <data type="int" column="10-17 years old">0</data> <data type="int" column="18-34 years old">16</data> <data type="int" column="35-44 years old">31</data> <data type="int" column="45-54 years old">32</data> <data type="int" column="55-64 years old">44</data> <data type="int" column="65-74 years old">42</data> <data type="int" column="75-84 years old">35</data> <data type="int" column="zz not recorded">0</data> </result> </body> </i2b2_result_envelope>
PATIENT_VITALSTATUS_COUNT_XML	Returns the patient vital status count in the i2b2 result xml format. Refer to i2b2_result_msg.xsd for the i2b2 result format.	<i2b2_result_envelope xmlns:ns10="http://www.i2b2.org/xsd/hive/msg/result/1.1/"> <body> <result name="PATIENT_VITALSTATUS_COUNT_XML"> <data type="int" Column="Deceased">0</data> <data type="int" column="Deferred">0</data> <data type="int" column="Living">123</data> <data type="int" column="Not recorded">0</data> </result> </body> </i2b2_result_envelope>
PATIENT_RACE_COUNT_XML	Returns the patient race count in the i2b2 result xml format. Refer to i2b2_result_msg.xsd for the i2b2 result format.	<i2b2_result_envelope xmlns:ns10="http://www.i2b2.org/xsd/hive/msg/result/1.1/"> <body> <result name="PATIENT_RACE_COUNT_XML"> <data type="int" column="American Indian">30</data> <data type="int" column="Asian">40</data> <data type="int" column="Black">18</data> <data type="int" column="Hispanic">19</data> <data type="int" column="Indian">2</data> <data type="int" column="Not recorded">1866</data> <data type="int" column="White">100</data> </result> </body> </i2b2_result_envelope>

Patient Set Query Use Case Scenarios