Dataset Query Capabilities Document Specification

Last modified: 10 June 2004 ($Date: 2005/03/30 05:40:31 $)

Comments to THREDDS mail list


Contents:

Related Resources:


Overview

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.

DQC Elements and Types

queryCapability Element

<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}&amp;maxLon={max}"
min="0.0" max="360.0" units="degree_east" modulo="true" />
<queryCapability>

query Element

<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.

selector Element

<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.

selectList Element

<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.

choice Element

<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.

selectService Element

<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.

selectStation Element

<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.

station Element

<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.

location 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.

location3D Element

<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.

selectFromRange Element

<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}&amp;maxLon={max}&amp;"
min="0.0" max="360.0" units="degree_east" modulo="true" />

the string "minLon=223.0&amp;maxLon=278.0&amp;" 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.

selectFromDateRange Element

<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}&amp;dateEnd={end}&amp;"
end="2004-04-01T00:00" duration="P15D" />

the string "dateStart=2004-04-10T00:00&amp;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}&amp;dateDuration={duration}&amp;"
start="2004-04-01T00:00" end="2004-04-15T12:00" />

the string "dateStart=2004-04-10T00:00&amp;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}&amp;dateDuration={duration}&amp;"
end="present" duration="P5D" />

the string "dateEnd=present&amp;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"
selectType="point"
start="2004-04-01T00:00" end="2004-04-15T12:00" />
the string "datePnt=2004-04-10T00:00" 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.

selectFromGeoRegion Element

<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}&amp;maxLa={maxLat}&amp;minLo={minLon}&amp;maxLo={maxLon}">
<geoBoundingBox>
<upperLeft latitude="45.0" longitude="-110.0" />
<lowerRight latitude="40.0" longitude="-105.0" />
</geoBoundingBox>
</selectFromGeoRegion>

the string "minLa=42.0&amp;maxLa=43.0&amp;minLo=-108.0&amp;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.

geoBoundingBox Element

<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.

userInterface 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.



Example

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>

Notes

How is a Query String Built

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.

Issues for selector Elements that Require Multiple Values

There are several issues that arise with all selector elements that require more than one value to make a valid selection.


Index of elements and types



Ethan Davis