Last modified: 10 June 2004 ($Date: 2005/03/30 05:40:31 $)
Comments to THREDDS mail list
A Dataset Query Capabilities (DQC) document is an XML document that describes the set of requests that can be made to one or more THREDDS services. A DQC document is returned when a THREDDS dataset is accessed with serviceType "QueryCapability". The DQC can be thought of as an abstract description of the contents of a THREDDS dataset.
This DQC Document Specification covers the 0.3 version of the query capabilities schema (http://www.unidata.ucar.edu/schemas/thredds/queryCapabilities.0.3.xsd). It explains the meanings of the individual elements that constitutes a DQC document and how a DQC service request is built from the information in a DQC document.
Also see: THREDDS Catalog Primer.
<xsd:element name="queryCapability">
<xsd:complexType>
<xsd:sequence>
<xsd:element ref="query"/>
<!-- Require a selectServiceType, more allowed because of selector elements. -->
<xsd:element ref="selectServiceType"/>
<xsd:element ref="selector" minOccurs="1" maxOccurs="unbounded" />
<xsd:element ref="userInterface" minOccurs="0" maxOccurs="unbounded"/>
</xsd:sequence>
<xsd:attribute name="version" type="xsd:token" default="0.3"/>
<xsd:attribute name="name" type="xsd:token"/>
</xsd:complexType>
</xsd:element>
This is the top level element, containing one query element, followed by one selectServiceType element, followed by one or more selector elements, and 0 or more userInterface elements. For example,
<queryCapability
xmlns="http://www.unidata.ucar.edu/namespaces/thredds/queryCapability/v0.3"
name="My collection of datasets" version="0.3">
<query base="http://my.server/dqcServlet/myCollection" />
<selectServiceType id="serviceType" title="Select service type(s)"
required="false"
template="serviceType={value}" multiple="false">
<serviceType>DODS</serviceType>
<serviceType>HTTP</serviceType>
<selectServiceType>
<selectFromRange title="Longitude" required="false"
template="minLon={min}&maxLon={max}"
min="0.0" max="360.0" units="degree_east" modulo="true" />
<queryCapability>
<xsd:element name="query">
<xsd:complexType>
<xsd:attribute name="base" type="xsd:string" use="required"/>
</xsd:complexType>
</xsd:element>
A query element provides the initial part of the
query string and defines what the query returns.
The base attribute becomes the base of the query URL.
Example:
<query base="http://my.server/dqcServlet/myCollection" />
How the query string is constructed depends on whether the selector elements have template attributes or not. For the details of how to build the query string, see the "How is a Query String Built" section below.
<xsd:element name="selector" type="selectorType" abstract="true"/>
<xsd:complexType name="selectorType">
<xsd:sequence>
<xsd:element name="description" type="cat:documentationType" minOccurs="0" maxOccurs="1"/>
</xsd:sequence>
<xsd:attribute name="id" type="xsd:token" use="required"/>
<xsd:attribute name="title" type="xsd:token" use="required"/>
<xsd:attribute name="template" type="xsd:token" />
<xsd:attribute name="required" type="xsd:boolean" default="true"/>
</xsd:complexType>
Each selector element in a DQC document represents a single selection available to a user. It is the base class for all selectors including selectList,
selectStation, selectFromRange, and
selectGeoRegion.
Thus the following elements and attributes apply to all selectors. The required
attribute (which defaults to "true")
indicates whether the user must make a selection from this selector to obtain
a valid query string. The title attribute is required
and its value is displayed to the user as the title of this selector. The contents
of the optional description element (plain text or
a combination of text and XHTML) may be displayed to the user to further describe
the selector. The id attribute is required and must be unique within the DQC document. The template attribute is optional.
Each selector element for which a selection is made appends a string to the query string. The appended string is built using the template and id attributes. If the optional template attribute is given, the template string (i.e., the value of the template attribute) must contain the replacement string "{value}". The template string becomes the appended string. But first the value of the selection (how that value is determined depends on the type of selector) replaces the replacement string. If no template attribute is given, the value of the id attribute and the value of the selection are used to build the appended string as a name/value pair of the form "<id>=<value>".
More information on how the id and template attributes are used in the building of the query string is available in the "How is a Query String Built" section below.<xsd:element name="selectList" substitutionGroup="selector">
<xsd:complexType>
<xsd:complexContent>
<xsd:extension base="selectorType">
<xsd:sequence>
<xsd:element ref="choice" minOccurs="1" maxOccurs="unbounded"/>
</xsd:sequence>
<xsd:attribute name="multiple" type="xsd:boolean" default="false" />
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
</xsd:element>
A selectList is a kind of selector that defines an enumerated list of choices from which the user can make a selection. Each choice in the enumerated list is defined by a choice element. A selectList element contains an optional description element followed by one or more choice elements. It also allows all of the attributes declared in the selector element: id, title, template, and required. If the multiple attribute is set to "true", the user may select one or more of the available choices. If the multiple attribute is set to "false" (the default value), the user may select only one of the available choices.
The selector's resulting value is the value of the selected choice element's value
attribute. If an optional template
attribute is given, the template string must contain the replacement
string "{value}" and that replacement string is replaced by the
selector's resulting value. The resulting string is then appended to
the query string.For example, if the ".5 reflectivity .54nm res" product is selected from the following:
<selectList id="prod" title="Products:"
template="product={value}" multiple="true" required="true">
<choice name=".5 reflectivity .54nm res" value="N0R">
<description>.5 reflectivity .54nm res 16 levels id 19/r</description>
</choice>
<choice name=".5 storm rel. velocity" value="N0S">
<description>.5 storm rel. velocity .54nm res 16 lvls id 56/srm</description>
</choice>
</selectList>
the string "product=N0R" will be appended to the query string.
If no template attribute is given, the value of the idattribute
becomes a parameter name and the selector's resulting value becomes the
parameter value. The resulting name value pair is appended to the query
string with the form "<id>=<value>". For example, if the
".5 reflectivity .54nm res" product is selected from the following:
<selectList id="prod" title="Products:"
multiple="true" required="true">
<choice name=".5 reflectivity .54nm res" value="N0R">
<description>.5 reflectivity .54nm res 16 levels id 19/r</description>
</choice>
<choice name=".5 storm rel. velocity" value="N0S">
<description>.5 storm rel. velocity .54nm res 16 lvls id 56/srm</description>
</choice>
</selectList>
the string "prod=N0R" will be appended to the query string.
<xsd:element name="choice" type="choiceType"/>
<xsd:complexType name="choiceType">
<xsd:sequence>
<xsd:element name="description" type="cat:documentationType" minOccurs="0" maxOccurs="1"/>
<xsd:element ref="selectList" minOccurs="0" maxOccurs="unbounded"/>
</xsd:sequence>
<xsd:attribute name="name" type="xsd:string" use="required"/>
<xsd:attribute name="value" type="xsd:string" use="required"/>
</xsd:complexType>
A choice element
specifies a single choice that the user can make from a selectList.
The name attribute is displayed to the user, while
the description element is an optional longer description
of the choice. The value attribute of a selected choice
provides the selections resulting value which is used to construct the query.
Here is an example of a selectList element containing several choice elements:
<selectList id="prod" title="Products:"
template="product={value}" multiple="true" required="true">
<choice name=".5 reflectivity .54nm res" value="N0R"/>
<choice name=".5 storm rel. velocity" value="N0S"/>
</selectList>
Each choice element can contain nested selector elements. This allows further refinement of a selection. Here is the above example with nested selectors:
<selectList id="prod" title="Products:"
template="product={value}" multiple="true" required="true">
<choice name=".5 reflectivity .54nm res" value="N0R">
<selectList id="radar" title="Mobile Radar" template="radar={stn}">
<choice name="Mobile Radar 1" value="mr1>
<choice name="Mobile Radar 2" value="mr2>
<choice name="Mobile Radar 3" value="mr3>
</selectList>
</choice>
<choice name=".5 storm rel. velocity" value="N0S">
<selectList id="radar" title="Mobile Radar" template="radar={stn}">
<choice name="Mobile Radar 1" value="mr1>
<choice name="Mobile Radar 3" value="mr3>
</selectList>
</choice>
</selectList>
This allows for cases where there are different choices depending on your first choice.
<xsd:element name="selectService" substitutionGroup="selector">
<xsd:complexType>
<xsd:complexContent>
<xsd:extension base="selectorType">
<xsd:sequence>
<xsd:element name="serviceType" minOccurs="1" maxOccurs="unbounded">
<xsd:complexType>
<xsd:simpleContent>
<xsd:extension base="cat:serviceTypes">
<xsd:attribute name="title" type="xsd:token"/>
</xsd:extension>
</xsd:simpleContent>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
<xsd:attribute name="multiple" type="xsd:boolean" default="false" />
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
</xsd:element>
A selectService element is a type of selector that defines the possible serviceTypes that can be returned from a query on this DQC. It contains an optional description element followed by one or more serviceType elements and also allows all of the attributes declared in the selector element: id, title, template, and required. Each serviceType element specifies a single THREDDS catalog service type (see the THREDDS catalog specification for more information) and allows an optional title attribute to further describe the service type. If the multiple attribute is set to "true", the user may select one or more of the available service types. If the multiple attribute is set to "false" (the default value), the user may select only one of the available service types.
Having a selectService in a
DQC document allows clients to filter the response on the serviceTypes
the client understands. For this reason, a selectService element
is required in all DQC documents.
The selection's resulting value is the value of the selected serviceType element. If an optional template
attribute is given, the template string must contain the replacement
string "{value}" and that replacement string is replaced by the
selection's resulting value. The resulting string is then appended to
the query string. For example, if the "DODS" service type is selected from the following:
<selectService id="serviceType" title="Select service type(s)" required="false"
template="serviceType={value}" multiple="false">
<serviceType>DODS</serviceType>
<serviceType>HTTP</serviceType>
</selectService>
the string "serviceType=DODS" will be appended to the query string.
If no template attribute is given, the value of the id
attribute becomes a parameter name and the selector's resulting value
becomes the parameter value. The resulting name value pair is appended
to the query string with the form "<id>=<value>". For
example, if the "DODS" service type is selected from the following:
<selectService id="service" title="Select service type(s)" required="false"
multiple="false">
<serviceType>DODS</serviceType>
<serviceType>HTTP</serviceType>
</selectService>
the string "service=DODS" will be appended to the query string.
<xsd:element name="selectStation" substitutionGroup="selector">
<xsd:complexType name="selectStationType">
<xsd:complexContent>
<xsd:extension base="selectorType">
<xsd:sequence>
<xsd:element ref="station" minOccurs="1" maxOccurs="unbounded"/>
</xsd:sequence>
<xsd:attribute name="multiple" type="xsd:boolean" default="false" />
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
</xsd:element>
A selectStation element is a kind of selector that allows the user to select from an enumerated list of station elements. It is similar to the selectList element but specialized to handle geographically located stations. Besides the elements and attributes allowed in all selector elements, the selectStation element must contain one or more station elements. Each station element must contain a location element which provides latitude, longitude, and optionally the elevation of the station. If the multiple attribute is set to "true", the user may select one or more of the available stations. If the multiple attribute is set to "false" (the default value), the user may select only one of the available stations.
The selection's resulting value is the value of the selected station element's value attribute. If an optional template attribute is given, the template string must contain the replacement string "{value}" and that replacement string is replaced by the selection's resulting value. The resulting string is then appended to the query string. For example, if the "OKLAHOMA_CITY/Kegelman_Aux_F OK" station is selected from the following:<selectStation id="stn" title="Available Stations" template="station={value}">
<station name="LOS_ANGELES/Orcutt_Oil_Field CA" value="VBX">
<location latitude="34.83" longitude="-120.38"/>
</station>
<station name="OKLAHOMA_CITY/Kegelman_Aux_F OK" value="VNX">
<location latitude="36.73" longitude="-98.12"/>
</station>
</selectStation>
the string "station=VNX" will be appended to the query string.
If no template attribute is given, the value of the id
attribute becomes a parameter name and the selector's resulting value
becomes the parameter value. The resulting name value pair is appended
to the query string with the form "<id>=<value>". For example, if the
"OKLAHOMA_CITY/Kegelman_Aux_F OK" station is selected from the
following:
<selectStation id="stn" title="Available Stations">
<station name="LOS_ANGELES/Orcutt_Oil_Field CA" value="VBX">
<location latitude="34.83" longitude="-120.38"/>
</station>
<station name="OKLAHOMA_CITY/Kegelman_Aux_F OK" value="VNX">
<location latitude="36.73" longitude="-98.12"/>
</station>
</selectStation>
the string "stn=VNX" will be appended to the query string.
<xsd:element name="station" substitutionGroup="choice">
<xsd:complexType name="stationType">
<xsd:complexContent>
<xsd:extension base="choiceType">
<xsd:sequence>
<xsd:element ref="location"/>
</xsd:sequence>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
</xsd:element>
A station element is an
extention of a
choice element that is specific to geographically located stations in
that it specifies a location. It contains exactly one location
element. It inherits the name, description
and value attributes from the choice
type. It is used in conjunction with the selectStation
element.
<xsd:element name="location" type="locationType"/>
<xsd:complexType name="locationType">
<xsd:attribute name="latitude" type="xsd:float" use="required"/>
<xsd:attribute name="longitude" type="xsd:float" use="required"/>
<xsd:attribute name="latitude_units" type="xsd:token" default="degrees_north"/>
<xsd:attribute name="longitude_units" type="xsd:token" default="degrees_east"/>
</xsd:complexType>
A location element has a latitude and longitude, and optionally may contain units for the latitude and longitude. The units default to "degrees_north" and "degrees_east", meaning decimal degrees. The convention for longitude is that 0 is greenwich, with positive going east, and the numbers will be interpreted modulo 360. The default for latittude is 0 is the equator with positive going north, and must be in the range +/- 90.
<xsd:element name="location3D" substitutionGroup="location">
<xsd:complexType>
<xsd:complexContent>
<xsd:extension base="locationType">
<xsd:attribute name="elevation" type="xsd:float" use="required"/>
<xsd:attribute name="elevation_units" type="xsd:token" default="msl"/>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
</xsd:element>
A location3D element extends the location type by adding an elevation attribute to indicate the vertical location. The elevation_units attribute specifies the units of the elevation.
<xsd:element name="selectFromRange" substitutionGroup="selector">
<xsd:complexType>
<xsd:complexContent>
<xsd:extension base="selectorType">
<xsd:attribute name="min" type="xsd:float" use="required" />
<xsd:attribute name="max" type="xsd:float" use="required" />
<xsd:attribute name="units" type="xsd:string" />
<xsd:attribute name="modulo" type="xsd:boolean" default="false" />
<xsd:attribute name="resolution" type="xsd:float" use="required"/>
<xsd:attribute name="selectType" type="rangeSelectTypeEnum" default="subrange" />
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
</xsd:element>
<xsd:simpleType name="rangeSelectTypeEnum">
<xsd:restriction base="xsd:token">
<xsd:enumeration value="point" />
<xsd:enumeration value="subrange" />
</xsd:restriction>
</xsd:simpleType>
A selectFromRange element is a kind of selector that defines a range of numbers from which a user can select a point or a range. The given range is defined by the values of the min and max attributes. The units of the given values and the selected value(s) is given by the value of the units attribute. Defining the modulo attribute to "true" means that the given range is cyclic and the modulo value can be calculated by taking the maximum value and subtracting the minimum value. E.g., longitude from -180.0 to 180.0 has a modulo value of 360.0 as does the longitude range from 0.0 to 360.0. The resolution attribute provides some idea of the density of data points. The selectType attribute indicates whether the user needs to select a single point within the allowed range or needs to select a subrange of the allowed range.
The value of the point or the minimum and maximum value of the subrange (depending on the selectType) are required to build a valid query string from a selectFromRange element. When the value of the selectType
attribute is set to "subrange", a template string must be given and
must contain the replacement strings "{min}" and "{max}". The
replacement strings are replaced by the
values of the minimum and maximum values of the subrange. The
resulting string is then appended to
the query string. For example, if the range 223.0 to 278.0 is selected
from the following:
<selectFromRange id="longRng" title="Longitude" required="false"
selectType="range" template="minLon={min}&maxLon={max}&"
min="0.0" max="360.0" units="degree_east" modulo="true" />
the string "minLon=223.0&maxLon=278.0&" will be appended to the query
string.
When the value of the selectType attribute is set to "point" and a template string is given, the template string must contain the replacement string "{point}" and that replacement string is replaced by the value of the selected point. The resulting string is then appended to the query string. For example, if the value 255.3 is the point selected from the following:
<selectFromRange id="longPnt" title="Longitude" required="false"
selectType="point" template="lonPoint={point}"
min="0.0" max="360.0" units="degree_east" modulo="true" />
the string "lonPoint=255.3" will be appended to the query
string.
When the value of the selectType attribute is set to "point" and no template string is given, the value of the id attribute becomes a parameter name and the value of the selected point becomes the parameter value. The resulting name value pair is appended to the query string with the form "<id>=<value>". For example, if the value 255.3 is the point selected from the following:
<selectFromRange id="longPnt" title="Longitude" required="false"
selectType="point"
min="0.0" max="360.0" units="degree_east" modulo="true" />
the string "longPoint=255.3" will be appended to the query string.
Various issues come up with all selector elements that require multiple values to make a valid selection. See the "Issues for selector Elements that Require Multiple Values" section below for further information.
<xsd:element name="selectFromDateRange" substitutionGroup="selector">
<xsd:complexType name="selectFromDateRangeType">
<xsd:complexContent>
<xsd:extension base="selectorType">
<xsd:attribute name="start" type="cat:dateType" />
<xsd:attribute name="end" type="cat:dateType" />
<xsd:attribute name="duration" type="cat:duration" />
<xsd:attribute name="resolution" type="cat:duration" use="required"/>
<xsd:attribute name="selectType" type="rangeSelectTypeEnum" default="subrange" />
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
</xsd:element>
A selectFromDateRange element is a kind of selector
that defines a date range from which a user may select a point or a range. The
given date range is defined by the values of the start, end, and
duration attributes. Only two of the three attributes can be present
in a given selectFromDateRange. The value of the start and end
attributes must be an ISO8601 encoded date or date/time (e.g.,
2004-03-04T17:30), a valid udunits date string, or the string
"present". The given duration value must be an ISO8601 encoded duration
(e.g., "2Y5M1DT1H3M") or a valid udunits time duration. (See the
THREDDS catalog specification for more information on the dateType and duration types.)
The optional resolution attribute provides some idea of the density of data points. The selectType attribute indicates whether a single point or a range
(start/end, start/duration, or end/duration) is expected.
The value of the point or the subrange (depending on the selectType) are required to build a valid query string from a selectFromDateRange element. When the value of the selectType
attribute is set to "subrange", a template string must be given and
must contain two of these three replacement strings: "{start}", "{end}", and "{duration}". The
replacement strings are replaced by the
values of the corresponding values that define the subrange. The
resulting string is then appended to
the query string. Here is an example that uses the "{start}" and "{end}" replacement strings, if
the range from "2004-04-10T00:00" forward two days ("2004-04-12T00:00")
is selected from the following:
<selectFromDateRange id="datePnt" title="Date"
selectType="subrange" template="dateStart={start}&dateEnd={end}&"
end="2004-04-01T00:00" duration="P15D" />
the string "dateStart=2004-04-10T00:00&dateEnd=2004-04-12T00:00" will be appended to the query string. Here is an example that uses the "{start}" and "{duration}" replacement strings, if the range from "2004-04-10T00:00" forward two days ("P2D") is selected from the following:
<selectFromDateRange id="datePnt" title="Date"
selectType="subrange" template="dateStart={start}&dateDuration={duration}&"
start="2004-04-01T00:00" end="2004-04-15T12:00" />
the string "dateStart=2004-04-10T00:00&dateDuration=P2D" will be appended to the query string. Here is an example that uses the "{end}" and "{duration}" replacement strings, if the two day range ending at the present is selected from the following:
<selectFromDateRange id="datePnt" title="Date"
selectType="subrange" template="dateEnd={end}&dateDuration={duration}&"
end="present" duration="P5D" />
the string "dateEnd=present&dateDuration=P2D" will be appended to the query string.
When the value of the selectType attribute is "point" and a template attribute is given, the template string must contain the replacement
string "{point}" and that replacement string is replaced by the
value of the selected point. The resulting string is then appended to
the query string. For example, if the value "present" is selected from the following:
<selectFromDateRange id="datePnt" title="Date"
selectType="point" template="datePoint={point}"
end="present" duration="P5D" />
the string "datePoint=present" will be appended to the query string.
When the value of the selectType attribute is "point" and no template attribute is given, the value of the idattribute becomes a parameter name and the value of the selected point becomes the parameter value. The resulting name value pair is appended to the query string with the form "<id>=<value>". For example, if the date/time of "2004-04-10T00:00" is selected from the following:
<selectFromDateRange id="datePnt" title="Date"the string "datePnt=2004-04-10T00:00" will be appended to the query string.
selectType="point"
start="2004-04-01T00:00" end="2004-04-15T12:00" />
<xsd:element name="selectFromGeoRegion" substitutionGroup="selector">
<xsd:complexType>
<xsd:complexContent>
<xsd:extension base="selectorType">
<xsd:sequence>
<xsd:element ref="geoBoundingBox"/>
</xsd:sequence>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
</xsd:element>
A selectFromGeoRegion element is a kind of
selector that
defines a geographic region from which a user can select a geographic bounding box. The given geographic region is defined by a geoBoundingBox element. The requested geographic region must be fully located inside the defined geographic region.
Currently, only a geographic bounding box may be selected. Four values are required to define the selected bounding box: the
minimum latitude, maximum latitude, minimum longitude, and
maximum longitude. A template attribute is required and it's value must contain these four replacement strings: "{minLat}", "{minLon}", "{maxLat}", and "{maxLon}". The
replacement strings are replaced by the
values of the corresponding values for the selected geographic bounding box. The
resulting string is then appended to
the query string. For example, if a minimul
latitude of 42.0, a minimum longitude of -108.0, a maximum latitude of
43.0, and a maximum longitude of -106.0 are selected from the following:
<selectFromGeoRegion id="geoCov" title="Geographic Coverage"
template="minLa={minLat}&maxLa={maxLat}&minLo={minLon}&maxLo={maxLon}">
<geoBoundingBox>
<upperLeft latitude="45.0" longitude="-110.0" />
<lowerRight latitude="40.0" longitude="-105.0" />
</geoBoundingBox>
</selectFromGeoRegion>
the string "minLa=42.0&maxLa=43.0&minLo=-108.0&maxLo=-106.0" is appended to the query string.
Various issues come up with all selector elements that require multiple values to make a valid selection. See the "Issues for selector Elements that Require Multiple Values" section below for further information.
<xsd:element name="geoBoundingBox">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="lowerLeft" type="locationType"/>
<xsd:element name="upperRight" type="locationType"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
A geoBoundingBox element defines a lat/lon bounding box using two location elements. The lowerLeft element defines the minimum latitude and minimum longitude of the bounding box. The upperRight element defines the maximum latitude and maximum longitude of the bounding box. The location the lowerLeft element defines must be south-west of the location defined by the upperRight element.
<xsd:element name="userInterface">
<xsd:complexType>
<xsd:sequence>
<xsd:any minOccurs="0" maxOccurs="unbounded" processContents="skip"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
A userInterface element is a container for
zero or more elements that can be anything. The userInterface element
is available for the support of specific applications that need/want
additional information about how to build a user interface from a DQC
document. This requires that the application read a catalog that has
the expected information. This feature was requested early on but has
not been developed.
Here is an example THREDDS dataset that, when accessed, results in a
DQC document (note, the serviceType is "queryCapability"):
<dataset name="NEXRAD data" >
<access serviceType="queryCapability" urlPath="http://www/dqc/radar.xml" />
</dataset>
The resulting DQC document:
<queryCapability>
<query base="http://www/dqc/radar"/>
<selectService id="serviceType" title="Select service type(s)"
required="false" multiple="false">
<serviceType title="Dataset served by OPeNDAP">DODS</serviceType>
<serviceType title="Dataset file available via FTP">FTP</serviceType>
</selectService>
<selectStation id="station" title="Stations:"
multiple="true" required="true">
<station name="ANCHORAGE/Bethel AK" value="ABC">
<location latitude="60.78" longitude="-161.87"/>
</station>
<station name="ABERDEEN/Aberdeen SD" value="ABR">
<location latitude="45.45" longitude="-98.4"/>
</station>
</selectStation>
<selectList id="prod" title="Products:"
multiple="true" required="true">
<choice name=".5 reflectivity .54nm res" value="N0R">
<description>.5 reflectivity .54nm res 16 levels id 19/r</description>
</choice>
<choice name=".5 storm rel. velocity" value="N0S">
<description>.5 storm rel. velocity .54nm res 16 lvls id 56/srm</description>
</choice>
</selectList>
<selectList id="time" title="Times:" required="true">
<choice name="Latest" value="latest"/>
<choice name="Last hour" value="1hour"/>
</selectList>
</queryCapability>
From this DQC document, the client application builds a user interface displaying the choices, for example:
<insert graphic>
The user then selects the "ABC" and "ABR" stations, the "NOS" product, and the "latest" time. With these selections, the application generates this query string:
http://www/dqc/radar?stn=ABC&stn=ABR&product=NOS&time=latest
The result of a query is always a THREDDS catalog, in this case, a coherant collection dataset with collectionType="stations":
<catalog>
<service name="mlode" base="http://www/data/radar" />
<dataset name="Latest NOS NEXRAD product from ABC and ABR" collectionType="stations">
<dataset name="Latest .5 storm relative velocity product from Bethel, AK">
<access serviceName="mlode" urlPath="NOS/ABC/2003121600_NOS.nc" />
</dataset>
<dataset name="Latest .5 storm relative velocity product from Aberdeen, SD">
<access serviceName="mlode" urlPath="NOS/ABR/2003121600_NOS.nc" />
</dataset>
</dataset>
</catalog>
To build a query string from a DQC document, the user makes a
valid selection for each selector
element that is required
and optionally for each selector element
that is not required. Each selector element for which a user makes a selection produces a string. These strings are appended to the value of the query element's base attribute to produce the query string. The order of the selector elements in the DQC document is the order the corresponding strings are appended.
The string produced by a selector element is built using that selector element's template and id attributes. Each selector element is required to have an id attribute and may optionally have a template attribute. If the optional template attribute is given, the template string (i.e., the value of the templateattribute)
must contain one or more replacement strings. What those replacement
strings are (and how many there are) depends on the type of selector.
Once all the replacement strings are replaced with the corresponding
selected values, the template string becomes the string produced by
that selector. The number of selected values and their meaning depends on the type of selector element for which the selection is being made. For example, the selected value for a selectList element is simply the value of the value attribute of the choice element that was selected.
If no template attribute is given, the value of the id attribute becomes a parameter name and the selected value becomes the parameter value. The resulting name value pair is appended to the query string with the form "<id>=<value>". NOTE: Since each selector element only has one id attribute, all selector elements that require more than one value to make a valid selection must include a template attribute.
When the value of the multiple attribute is "true", multiple selections can be made on the selector whether. When multiple selections are made on the same selector, the string produced by that selector is the normal string repeated for each of the multiple selections and expanded for that selection.
There are several issues that arise with all selector elements that require more than one value to make a valid selection.