Query Interface Definition

Author:	vieglais
Revision:	1.3
Date:	2003-05-08

Contents

Overview
- Status
- See Also
Operations
- search
  - Parameters
  - Return
- inventory
  - Parameters
  - Return
- update
  - Parameters
  - Return
- About This Document

Overview

The Query Interface Definition is a WSDL document that defines the operations and data structures of the query operation of the EcoGRID.

Note: should this really be called "Data Access" instead of "Query"?

Status

The wsdl document has been moved to /seek/projects/ecogrid/src/xsd/QueryInterface.wsdl

The interface specification should be considered a preliminary draft and open for comment.

Operations

Three operations are defined in the ecogrid query interface:

search: Returns a subset of content from a specified resource by comparing records against a supplied filter.
inventory: Returns a list of unique values that occur within a data element (column, field) of a resource plus the number of occurrences of each value.
update: Mechanism to permit remote modification of content in a resource. Records may be modified, appended or delete with this operation.

Each operation contains a clientInfo structure that is currently defined to contain a timestamp and a client identifier (e.g. IP address). This data structure is meant as a place holder for more sophisticated content that may for example be used for client authentication.

search

The search operation returns zero or more records from a resource that match a supplied filter.

Parameters

clientInfo: See discussion about clientInfo in the Operations section introduction.
resource: The name of the resource (database) against which the operation is being performed. A single instance of a service supporting the eco-grid query interface may expose more than a single resource.
filter: A filter structure that defines the subset of records that will be returned in a search response.
startRecord: A positive integer that specifies the zero based index of the first record to retrieve from the set of records that match the filter.
numRecords: A positive integer that specifies the number of records to be returned from the set of records that match the filter.
matchCount: A boolean value that indicates if the number of matching records should be available in the response. If false, then the number of matching records may not ne returned in the response (i.e. the value of matchCount in the response is not reliable).

Return

A SearchResponse message is generated in response to a SearchRequest operation. The SearchResponse message contains a clientInfo structure, the number of records that match the filter (value not reliable unless matchCount is TRUE in the SearchRequest), a boolean flag indicating if more records are available than were returned, and a resultset structure that contains an array or records as well as a metadata section that describes the resultset.

inventory

The inventory operation may be considered equivalent to the SQL operation:

SELECT fld, count() AS fldCnt FROM aTable GROUP BY fld ORDER BY fld ASC

Parameters

clientInfo: See discussion about clientInfo in the Operations section introduction.
resource: The name of the resource (database) against which the operation is being performed. A single instance of a service supporting the eco-grid query interface may expose more than a single resource.
elementName: Identifier of the element the operation is being performed on. (Note: change this to elementPath to specify a path within a structure, as in XPath within an XML document).
filter: An optional filter that specifies the subset of records on which the inventory operation is to be performed.

Return

An InventoryResponse message is generated in response to an InventoryRequest message. The InventoryResponse contains a clientInfo section, a recordSet and a boolean flag indicating if the response contains the complete resultset or if the response was truncated (an ecogrid query service may decide to limit the amount of information available in a single request).

The recordSet contains simple records that contain the value of a field and the number of occurrences of that value within that field.

update

The update operation permits editing, deleting and appending records in a resource. Records that are to be updated are included in the request message. There must be sufficient information in each record to uniquely identify the intended target record within the resource (e.g. using a row ID).

Parameters

clientInfo: See discussion about clientInfo in the Operations section introduction.
resource: The name of the resource (database) against which the operation is being performed. A single instance of a service supporting the eco-grid query interface may expose more than a single resource.
updateMethod: An enumerated type that can be one of update, append or delete.
records: The set of records that are to be updated, appended, or deleted. When records are being deleted, only a unique identifier is required to indicate which records are being deleted, otherwise each record should contain the complete content.

Return

An UpdateResponse message is generated in reponse to an UpdateRequest message. The UpdateResponse contains a clientInfo section and an array of status records indicating the success or otherwise of the update operation for each record in the request.

About This Document

This document is formatted as reStructuredText (http://docutils.sourceforge.net/rst.html) which can be processed to html, docbook, pdf, or TeX with various docUtils (http://docutils.sourceforge.net) tools.