==========================
Query Interface Definition
==========================

:Author: $Author: vieglais $
:Revision: $Revision: 1.4 $
:Date: $Date: 2003-05-10 22:35:14 $


.. contents::

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

See Also
========

QueryInterface.wsdl
 http://cvs.ecoinformatics.org/cvs/cvsweb.cgi/~checkout~/seek/projects/ecogrid/src/xsd/QueryInterface.wsdl?content-type=text/plain

query.xsd
  http://cvs.ecoinformatics.org/cvs/cvsweb.cgi/~checkout~/seek/projects/ecogrid/src/xsd/query.xsd?content-type=text/plain or a `html rendering of query.xsd <query.htm>`_.

resultset.xsd
  http://cvs.ecoinformatics.org/cvs/cvsweb.cgi/~checkout~/seek/projects/ecogrid/src/xsd/resultset.xsd?content-type=text/plain or a `html rendering of resultset.xsd <resultset.htm>`_.

Generic SOAP client built from WSDL
  http://www.soapclient.com/soapclient?template=%2Fclientform.html&fn=soapform&SoapTemplate=%2FSoapResult.html&SoapWSDL=http%3A%2F%2Fcvs.ecoinformatics.org%2Fcvs%2Fcvsweb.cgi%2F%7Echeckout%7E%2Fseek%2Fprojects%2Fecogrid%2Fsrc%2Fxsd%2FQueryInterface.wsdl%3Fcontent-type%3Dtext%2Fplain&_ArraySize=2&CacheWSDL=0


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