Changes between Version 36 and Version 37 of Discovery/DiscoveryWebServiceMEDIN


Ignore:
Timestamp:
09/11/09 13:33:30 (10 years ago)
Author:
mpritcha
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • Discovery/DiscoveryWebServiceMEDIN

    v36 v37  
    9393[[Image(doSearchSchema.png, 400px)]] 
    9494 
    95 === Choice of search criteria: <termSearch>, <spatialSearch> and <temporalSearch> ===  
     95==== Choice of search criteria: <termSearch>, <spatialSearch> and <temporalSearch> ==== 
    9696The <searchCriteria> element acts as a container enabling the selection of one or more of <termSearch>, <spatialSearch> and <temporalSearch>. Only one of each of <termSearch>, <spatialSearch> and <temporalSearch> may be included, but at least one of these three types of search must be supplied. If more than one is specified, the resulting search combines the components in "AND" combination (i.e. metadata records should match the term search AND the spatial search AND the temporal search criteria). 
    9797 
    98 ==== termSearch ==== 
     98===== termSearch ===== 
    9999!TermSearch is a full-text search invoked on a specific target field in the discovery database. Child elements <term> and <termTarget> should be populated as follows: 
    100100  * <term> : text term to search for. Whitespace separates component words, which are searched in "OR" combination unless the "+" symbol is used between them, in which case the words joined in this way are searched in "AND" combination. 
     
    146146}}} 
    147147 
    148 === Spatial searching : <spatialOperator> and <boundingBox> === 
     148===== Spatial searching : <spatialOperator> and <boundingBox> ===== 
    149149The search may incorporate a spatial query to restrict results to those metadata records having spatial coverage(s) matching the search criteria defined by the <boundingBox> elements <limitNorth>, <limitSouth>, <limitEast> and <limitWest>. An optional element <spatialReferenceSystem> may be populated with an entry from the [#spatialReferenceSystem spatialReferenceSystem] list to specify an alternative spatial reference system (SRS) of the bounding box coordinates. (*Note : this feature is included for future development e.g. ability to supply spatial search coordinates in British National Grid coordinates. Currently the only supported SRS is EPSG:4326 (WGS84 lat/lon), and this will remain as the default if no SRS is specified. 
    150150 
     
    153153An optional <spatialOperator> may be included, populated with a term from the [#spatialOperatorList spatialOperatorList], defining the comparison to be applied to spatial coverage(s) related to metadata records. The default value is "overlaps". Note that in the discovery index database, metadata records may contain several spatial coverages, so a match can occur if any of the spatial coverages related to the metadata item match the criteria specified in the spatial search.  
    154154 
    155 === Temporal searching : <!DateRange> === 
     155===== Temporal searching : <!DateRange> ===== 
    156156The search may incoporate a temporal query to restrict results to those metadata records having temporal coverage(s) matching the search criteria specified within <DateRange>. One or two <date> elements may be specified, to represent either a single date, or a date range. Each <date> element must contain a <DateValue> element populated in the form YYYY-MM-DD, and optionally a <temporalOperator> element, populated with a value from [#temporalOperatorList temporalOperatorList], defining the semantic meaning of this date criterion in the search. In addition, an optional <dateRangeTarget> element may be included, populated with a value from the [#dateRangeTargetList dateRangeTargetList], to enable searching of dates other than the default of "temporal coverage of data".  
    157157Examples are shown below: 
     
    219219> Looking at these examples we might need to tidy up the capitalisation of elements in the schema & WSDL. 
    220220 
    221 === Paging : <start> and <howMany> ===  
     221==== Paging : <start> and <howMany> ==== 
    222222The optional elements <start> and <howMany> control which records from the result set should be returned (although the total number of hits is always returned as a number to aid with paging in clients). If <start> is omitted, the default value used is 1 (i.e. the first record). If <howMany> is omitted, '''all''' records are returned. 
    223223 
    224224 
    225 === Ordering: <orderBy> and <orderByDirection> === 
     225==== Ordering: <orderBy> and <orderByDirection> ==== 
    226226Ordering of the result set can optionally be requested by providing an <orderBy> element containing one or more <orderByField>s, each with an optional associated <orderByDirection> (default : descending). Available fields for use as an <orderByField> are listed in the [#orderByFieldsList orderByFieldList]. 
    227227 
    228228In addition, the direction of ordering (ascending or descending) can be specified. If omitted, the default direction is descending. 
    229229 
    230 === Scope of search: <scope> === 
     230==== Scope of search: <scope> ==== 
    231231The optional <scope> element can be used to restrict the search to onr or more of the supported NDG Data Provider Groups, defined in NDG controlled vocabulary http://vocab.ndg.nerc.ac.uk/list/N010/0. Currently supported values from this vocabulary are these are given in the the [#scopeList scopeList] list accessible via the getList operation. 
    232232If <scope> is omitted, the search is not restricted in this way. 
    233233 
    234 === Format === 
     234==== Format ==== 
    235235The optional <format> element can be used to restrict the search to records in the discovery index whose original (harvested) representation was in the format specified. The format must be one of the values listed in the [#metadataFormatList metadataFormatList] available from the getList operation. Default behaviour if this element is omitted is not to restrict the search in this way (and return results irrepsective of their harvested format). 
    236236 
    237 === !RecordDetail === 
     237==== !RecordDetail ==== 
    238238The optional <recordDetail> element enables selection of the level of detail included in each result returned in the search result. Values must be one of those available from the [#recordDetailList recordList]. Default is documentId, which simply returns the id of the document corresponding to the result. See [#SearchResults Search Results] section for further explanation of the structures returned in each of these cases. 
    239239 
    240240 
    241 == Search results == 
     241==== Search results ==== 
    242242The doSearchResponse message is defined in the WSDL as shown below (click image for larger version): 
    243243 
     
    319319Request: 
    320320{{{ 
    321 (tbc) 
     321<m:doPresent xmlns:m="urn:DiscoveryServiceAPI"> 
     322    <m:documents> 
     323        <m:document>badc.nerc.ac.uk__DIF__dataent_claus.xml</m:document> 
     324        <m:document>ndg.noc.soton.ac.uk__DIF__NOCSDAT160.xml</m:document> 
     325        <m:document>ndg.noc.soton.ac.uk__DIF__NOCSDAT162.xml</m:document> 
     326        <m:document>ndg.noc.soton.ac.uk__DIF__NOCSDAT163.xml</m:document> 
     327    </m:documents> 
     328    <m:format>DIF_v9.4</m:format> 
     329</m:doPresent> 
    322330}}} 
    323331 
    324332Response: 
    325333{{{ 
    326 (tbc) 
    327 }}} 
     334<doPresentReturn xmlns="urn:DiscoveryServiceAPI"> 
     335    <status>true</status> 
     336    <statusMessage>Success</statusMessage> 
     337    <documents> 
     338        <document>&lt;DIF xmlns="http://gcmd.gsfc.nasa.gov/Aboutus/xml/dif/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">&lt;Entry_ID>badc.nerc.ac.uk:DIF:dataent_claus&lt;/Entry_ID> (...) &lt;/DIF></document> 
     339        <document>&lt;DIF xmlns="http://gcmd.gsfc.nasa.gov/Aboutus/xml/dif/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">&lt;Entry_ID>ndg.noc.soton.ac.uk__DIF__NOCSDAT160&lt;/Entry_ID> (...) &lt;/DIF></document> 
     340        <document>&lt;DIF xmlns="http://gcmd.gsfc.nasa.gov/Aboutus/xml/dif/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">&lt;Entry_ID>ndg.noc.soton.ac.uk__DIF__NOCSDAT162&lt;/Entry_ID> (...) &lt;/DIF></document> 
     341        <document>&lt;DIF xmlns="http://gcmd.gsfc.nasa.gov/Aboutus/xml/dif/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">&lt;Entry_ID>ndg.noc.soton.ac.uk__DIF__NOCSDAT163&lt;/EntryID> (...) &lt;/DIF></document> 
     342    </documents> 
     343</doPresentReturn> 
     344}}} 
     345 
    328346 
    329347 
     
    391409=== spatialOperatorList === 
    392410 overlaps (default):: 
     411   Return metadata records having one or more spatial coverages that spatially overlap the search bounding box.  
    393412 doesNotOverlap:: 
     413   Return metadata records having no spatial coverages that spatially overlap the search bounding box. 
    394414 within:: 
    395  
     415   Return metadata records having one or more spatial coverages that are entirely within the search bounding box. 
     416> Should we restrict this to ("...having '''all''' spatial coverages that entirely within the..." ?) 
    396417 
    397418=== spatialReferenceSystemList === 
    398419 EPSG:4326:: 
     420   WGS84 Lat/Lon, in decimal degrees 
    399421 
    400422=== dateRangeTargetList === 
    401423 temporalCoverage:: 
     424   The temporal coverage of the data described by the metadata record. 
    402425 lastRevisionDate:: 
    403  metadataIngestionDate:: 
     426   The data of last revision to the dataset, recorded in the metadata record. 
     427 discoveryIngestDate:: 
     428   The date that the metadata record was (last) ingested into the discovery index. 
    404429 
    405430=== temporalOperatorList === 
    406431 equals:: 
     432   Target date value is the same as the date specified 
    407433 doesNotEqual:: 
     434   Target date values does not equal the date specified 
    408435 onOrBefore:: 
     436   Target date is equal to or before the date specified 
    409437 onOrAfter:: 
     438   Target date is equal to or after the date specified 
    410439 before:: 
     440   Target date is before the date specified 
    411441 after:: 
     442   Target date is after the date specified 
    412443 
    413444=== metadataFormatList === 
     
    425456=== recordDetailList === 
    426457 id:: 
     458   Return a <documentId> element containing the id of the matching metadata document, in a form that can be used as input to a doPresent request. 
    427459 brief:: 
     460   Return a <documentBrief> element containing a <documentId> element, the title and ordering fields. 
    428461 summary:: 
    429  
     462   Return a <documentSummary> element containing content as per <documentBrief> but additionally abstract, temporal and spatial information. 
     463