Query Profile Reference

This is a reference to the full format of Query Profile and Query Profile Type configuration files. For an introduction to query profiles, please see query profiles.

Query Profiles

A query profile defines a named set of search request parameters with values - structure:

<query-profile id="[id]" [optional attributes]>

    <description></description> ?

    <dimensions></dimensions> ?

    <field name="[name]" [optional attributes]>[value]</field> *

    <query-profile for="[dimension values] [optional attributes]>
        <field name="[name]">[value]</field> *
    </query-profile> *

</query-profile>

where ? means optional and * means repeatable tag. These items are described in the following sections.

id

The id has the format:

id        ::= name(:major(.minor(.micro(.qualifier)?)?)?)?
name      ::= identifier
major     ::= integer
minor     ::= integer
micro     ::= integer
qualifier ::= identifier

Any omitted numeric version component missing is taken to mean 0, while a missing qualifier is taken to mean the empty string. If the name is exactly default, this profile will be the default. If there are multiple profiles named default, the newest version is the default.

Optional query-profile attributes

Description

A textual description of the purpose of this. Used for documentation.

Query profile field

A field in a query profile defines a key-value pair.

If the value is a primitive (string, number), then this key value will be available from the Query exactly as if it was submitted with the search request as a parameter (if it is set both ways, the search request takes priority).

If the value is a reference to another query profile, the key-values of the referenced profile will be available from the Query exactly as if they were submitted with the search request as a parameter, with the key of this value and a dot prepended to each key in the nested profile, i.e keyNameInReferringProfile.keyNameInReferencedProfile=value.

field name

The name of the field, must be a valid identifier.

Optional field attributes

field value

This value of the field, may be either:

• a primitive, encoded as any (XML escaped) string, or
• a reference to another query profile encoded as <ref>[query-profile-id]</ref>

If this field is defined in the query profile type referenced by this query profile, then the value must be the valid value type defined by that query type field definition.

Dimensions

A comma-separated list of dimensions over which variants of this profile may be created as nested query profiles. The names of the dimensions are the names of request parameters which, when received in the request, will trigger the matching profile variants.

Query profile (nested)

A nested query profile defines variants of values returned from the enclosing query profile, which are returned for variable requests where this variant is the most specific match to the request properties named by the dimensions as defined by its for attribute. No other attributes may be set in nested query profiles.

Query profile (nested) for attribute

This attribute defines the values of the dimensions of the enclosing profile for which this nested profile defined alternative values, as a comma-separated list. The values are defined in the same order as the dimensions are defined. Dimensions for which this should match any value may be denoted by a "*". One or more trailing "*" may be omitted - example:

for="a,b,*,c,*,*"
for="a,b,*,c"      // equivalent to the above

Query Profile Types

A query profile type defines a set of valid, typed values for a query profile - structure:

<query-profile-type id="[id]" [optional attributes]>

    <description></description> ?

    <match path="true"/> ?

    <strict/> ?

    <field name="[name]" type="[type]" [optional attributes]/> *

</query-profile-type>

where ? means optional tag and * means repeatable tag. These items are described in the following sections.

Optional query-profile-type attributes

match

If <match path="true"> is added to the query profile type, the name of the profile will be understood as a slash separated path name during matching of a query profile name to an actual profile. If the query profile name is a path component prefix of the query profile name reference, the profile matches the reference. The profile having the most specific match is used as the target of the reference.

If match is not specified in the profile type, exact name matching is used. The syntax is as specified for future extensions.

The match setting is inherited from supertypes to subtypes.

strict

If this element is added to a query profile type, then that profile can only contain values explicitly defined in the profile, whether that value is provided by a query profile, the search request or programmatically.

It is possible to add strict sub-profiles to a non-strict profile and vice-versa, making it possible to create respectively "structs in maps" and "maps in structs".

A profile which inherits a strict profile will also be strict, i.e strict is inherited.

Some rules to note when using a top-level profile type which is declared as strict:

• If the top-level profile is of a strict type, that type should usually inherit the native type to allow the built-in parameters to be passed in. This profile type and the subtypes it references are always available - refer to the Query API reference.
• Non-primitive model objects are permitted to be added to the query profiles even if the top level profile is strict, but primitives (strings, numbers, booleans) are not permitted but must either be declared in the strict profile type, or wrapped in a proper model object
• Feature specific properties like select are not automatically permitted, the parameters of the features which should be exposed must be declared explicitly in a strict top level type.

Query profile type field

This defines the name and type of a field of query profiles of this type.

field type

This defines the type of this field. The type is one of:

Optional field definition attributes

Identifiers

An identifier is a string matches the pattern [a-zA-Z_/][a-zA-Z0-9_/]*.