Query Parameters

Query Parameters may be set of name/value pairs, a named parameter list with a set of name/value pairs or any combination the previous two options. A Query Transmission contains zero or more Query parameters.

The only query mechanism supported by HL7 v3 is Query-By-Parameter, based on a ParameterItem class for each name-value pair. According to the RIM the ParameterItem represents a valued element structure for the element specified in the query response.

FAQ

Use of nullFlavors in queryParameter classes.

• Does the use of a nullFlavor "UNK" (just to use an example) identify that the value is unknown, and that the receiver should match it with any value it may have, or should "UNK" be interpreted as "known to be unknown" and match only with a nullFlavor as stored at the receivers end ?
  • The Dutch use-case behind this is related to a mandatory birthTime parameter in a query, and the fact that there are persons where both the sender of the query as well as the responding system know that a person has no known birthdate. (i.e. was born in a country where the birthdate was never formally registered, holding a passport that explicitely shows that the birthdate is unknown).
  • If the value of a query parameter is a nullFlavor, the receiving system SHALL not interpret it as a wilcard. The use of nullFlavors in query values needs to be well documented in query conformance statements. (InM Motion, 20070502 Q3, Rene/Mark T, 8-0-0)

Combinatorial logic between Parameters

• I can't find anything in the query domain that describes how to define a query that supports an expression like ( ( parameter1 AND parameter2 ) OR ( parameter3 AND parameter4 ) ). Is there anyone who has used this before or can point me in the direction of some documentation please?

1. The Query By Parameter mechanism in HL7 has no explicit way of conveying combinatorial logic, the logic is implicit. So you'd create a query with 4 parameters, and you'd define (in textual form) that these should be processed/interpreted as "( ( parameter1 AND parameter2 ) OR ( parameter3 AND parameter4 ) )". This "implicit" combinatorial logic is the same as in HL7 v2. In v2.5 this is supported by the QBP segment.
2. The RIM also contains queryBySelection. This allows for logicalExpressions and conjunctions to be explicitely stated within the query. We'd need to create a new query domain to create the appropriate control act wrappers, which we haven't done because nobody has come forward with a use case for it. Note that this option (depending on ones interpretation of these classes, this entire part of the RIM has no description at the moment) puts much more of a burden on the receiver compared to queryByParameter. In v2.5 this is supported by the VTQ segment.

• I am creating query messages and would like to express a message which has several parameter items, some with operators other than "=". I intend to model a QueryByParameter with a ParameterList attached and two parameterItems underneath, one for the parameter value, the other for the parameter operator, e.g. <> (not equals).

1. The standard indicates that parameterItems are key/value pairs. Which suggest an "=" operator.
2. The > and < operators are dealt with at the datatype level, i.e. by defining parameterItem.value to be an IVL<T> datatype. Or even an SET<IVL<T>> if one wants to identify something outside of an interval.
3. The "wildcard based =" operator is dealt with on the data type level (see below).
4. The <> operator is not dealt with at the datatype level, because (parameter1 <> "X") is the equivalent of NOT(parameter1 = "X"). NOT, like AND and OR, is an implicit part of the query interaction.

• This means I would also have to explicitly model every operator choice for each parameter as a different class - which could be a ridiculously large number.

1. HL7 supports a different querying mechanism (see the QueryBySelection classes in the MessageCommunicationsControl Subject Area part of the RIM), which allows for the explicit identification of the paremeter combinatorial logic, has never been fully defined because no use-cases have been brought forward that could not be dealt with by the query by parameter mechanism. Ian gave it a go, see Query recursion. No further proposal related to the development of that area of the RIM has been brought forward. You're very welcome to do so - if you have a use-case for it, I'd encourage you to do so. But the query by parameter querying mechanism does not explicitly convey operators. It was intended to be a simple mechanism.

Conformance

• Can one claim conformance to a query interaction if one doesn't support some of the parameters?

In v3, if you claim support for an interaction, you must support all of the required elements in the message types bound to that interaction. If you don't, you're non-compliant. Queries are treated no differently than other interactions. In effect, committees define their query conformance statements when they construct the interactions.

Thus, if HL7 Canada creates a query that includes required parameters that allow filtering of data, we are making a clear statement "If you're going to claim conformance, you must be able to filter data in response to query parameters as described by this query". This is not a query conformance profile. This is a balloted interaction standard. A query conformance profile would be something created by Canada or some other organization for a balloted query interaction that indicated which optional elements they were supporting and which they weren't.

In general committees should attempt to make things as many things required as they can get consensus on.

SemanticsText

• Does one have to include the semanticstext attribute in parameterItem-derived classes?

All paremeterItem derived classes have to have the semanticsText attribute with a predefined (default) value. The only circumstance where a parameterItem-clone would not have to have semanticsText is a query that has only 1 parameterItem.

The RIM states that parameterItem is a name-value pair. SemanticsText contains the "name" part of the name-value pair. See the ""Link between parameterItem and RIM attributes" section of this page for a discussion on how to define the semantics associated with a parameter.

Note that although widely used by implementers of XML v3 Interactions, the name of the class-clone does not carry any semantic meaning and therefore can't be used (in abstract models, like R-MIMs) to distinguish between one parameterItem clone and another one. Using the className is XML ITS specific.

Fuzzy Parameter Matching

• How does one search with information that is known to be "fuzzy" or incomplete, e.g. because one used wildcards, or a phonetic approximation of someones family name? The issue is wider in scope than just in parameters: it may also apply to updates of a registry, if the name is known to be fuzzy and incorrect.

There are 2 possible approaches to this:

1. Add a "match type" attribute to ParameterItem. Then we could say things like "exactMatch", "specialization", "exactOrSpecialization", "wildcard", "regex", or other things. This option has two disadvantages:
   1. It does not solve the use-case related to fuzzy names in registries, it only solves the query parameter use-case
   2. It would increase the complexity of the interpretation of queries, and it may encourage bad behaviour like searching for "a phonetic root OID", "a regexp for a code starting with a certain chacter" - at the same time we're telling people that OIDs and codes are meaningless numbers.
2. The matching behaviour will be implicit and documented in the query conformance statement which is specific to the system responding to the query.
   • This is the current way of dealing with this. Wilcard characters within the data may be used to specify that one desires fuzzy matching, it is up to the conformance statement to specify what (and if) such wildcards are supported.
3. Define a use-code for those data types where there are known use-cases for (a) fuzzy searches, or (b) fuzzy data storage requirements (like registering a person using a name that is known to be phonetic). *IF* there is a use case for it, it should be determined on a datatype-by-datatype basis how we deal with search/wildcard/phonetic values.
   • This is not a valid option: SRCH and PHON are NOT intended for searches. A name of use-type SRCH is a name 'provided for the purpose of searching' (could be an old name, a known misspelled version which has been used before, etc.). Therefore datatype use codes are NOT suitable to specify the matching methodology.

Interpretation of omitted data type parts

When sending a query and one of the parameters has the Person Name datatype and if the sender includes only the LastName part of that Person Name datatype with a value such as "Daoust", should the sender expect to get back: (1) all people whose last names are Daoust, or (2) all people with a last name of Daoust and no recorded value for first name and no recorded value for first name? I believe the correct answer is (1).

(Rene) That is what I would expect as well. The formal answer to your question is however: it depends on how you, as a comittee, define the behaviour to be. As a comittee you are free to define what the non-presence of an attribute means, this could/may differ on a query by query basis.

This is the same issue as the AND/ OR logic between parameterItem classes: in principle it's entirely up to you as a comitte to define the behaviour, the most INM can do is define a rule akin to "unless defined otherwise by the interaction walkthrough, the non-presence of values for parts of datatypes does not indicate a search for a nullflavor value".

Link between parameterItem and RIM attributes

1. Could a committee design a query where the parameter is "name" (having datatype Person name), and "name" means return all persons who have a matching value in either the RIM Person.name or the RIM Patient.name? I believe the correct answer is "No", a query parameter value should map to a single RIM attribute, not two or more.
2. Should a parameter always map to 1 single attribute?
3. How does one value semantcsText in case of multiple matching attributes?

From the RIM:

• ParameterItem.value :: ANY (0..1) - Definition:Provides the value for the valued element structure (name-value pair) for the element specified in the query response.
• ParameterItem.semanticsText :: ST (0..1) - Definition:Provides a unique identification (the name of the name-value pair) to an element within a specified query response structure.

The QUQI D-MIM walkthrough states: Query definitions in the application domains state how the value and semanticsText attributes are to be populated. The following is the description and use of the attributes for this class.

• id: can assist in tracing problems with implementing the query-by-parameter mechanism
• value: represents a valued element structure for the element specified in the query response
• semanticsText: provides a unique identification to an element within a specified query response structure

Question 1: Yes, you can define a "name" parameter, as long as you define clearly in the query interaction what the intended behaviour of the receiver should be. For example, that there is a fall-back mechanism to try and match it with Patient.name, and if that attribute is empty (not valued, not a nullflavor), match it with person.name.

Question 2: There is no requirement that a parameter matches a single attribute as contained in the static model of the response. It may be true for most use-cases, but there is no such requirement. A parameter does NOT have to match 1 individual D-MIM attribute, as long as the relationship can be defined in a computational manner.

• an example from PA: mothersMaidenName. This is a parameter in one of PA's queries, although (as a concept) is it pretty difficult (but not impossible) to state where its value is located in v3 models, and it is actually not contained in the response to the query where the parameter is used.
• another example from PA, based on Patient Registries: the static model contains a LivingSubject entity, the Patient role played by the living subject, and other roles played by the LivingSubject (the OtherIDs class). A parameter could be created that maps to the set of {Patient.id, OtherIDs.id} which is a computable an exhaustive set, and both of which are Role.IDs.

Question 3: Although it is a well established best practice to use the attribute name a parameter is linked to as a value for semanticsText, there is no requirement to do so. Any string which identifies this particular type of parameterItem class is a valid one. Each ParemeterItem class contains a key/value pair, whereby the key is semanticsText. (and not as some assume: the name of the class).

SELECT x,y,z use-case

• How does a committee indicate, for example, that the query itself contains two parameter values (e.g. Person.name and Person.birthDate), but that the query response should include Person.name, Person.birthDate, Person.address, Person.genderCode?

The RIM states for Parameter: "The Parameter class is an implementation class that represents the structure of parameters that may be specified with the Query-by-parameter mechanisms of the V3 query framework.", and for ParameterItem: "Represents a valued element structure (name-value pair) for the element specified in the query response."

If we regard a query as the equivalent of a "SELECT x,y,z FROM database WHERE a=1 and b=2" then all parameterItems are the equivalent of the WHERE clause. See Nature of ParameterItem for a discussion paper on this topic - The INM committee has adopted a motion which clarifies that the parameterItem class can't be use to specify a SELECT clause (Canadian and UK projects use parameterItem - but that's not a valid usage of the class).

See Harmonization: add QuerySpec.responseTemplateId attribute for the proposed solution of this use-case.