Changes between Version 63 and Version 64 of Taskforces/FCS/FCS-Specification-Draft


Ignore:
Timestamp:
06/13/17 13:54:53 (7 years ago)
Author:
Leif-Jöran
Comment:

Adding operation=searchRetrieve 2.0 example

Legend:

Unmodified
Added
Removed
Modified

  • Taskforces/FCS/FCS-Specification-Draft

    v63 v64  
    749749
    750750== Operation ''explain'' #explain
    751 {{{
    752 #!div style="border: 1px solid #000000; font-size: 75%"
    753 TODO: adjust for advanced stuff!
    754 }}}
    755751The ''explain'' operation of the SRU protocol serves to announce server capabilities and to allow clients to configure themselves automatically. This operation is used similarly.
    756752
    … …  
    841837}}}
    842838
    843 And a SRU 2.0 example request and response to an ''explain'' request with added extra request parameter `x-fcs-endpoint-description`:
     839And a SRU 2.0 example request and response to an ''explain'' request also with the extra request parameter `x-fcs-endpoint-description`:
    844840* HTTP GET request: Client → Endpoint:
    845841{{{#!sh
    … …  
    921917          <ed:Language>swe</ed:Language>
    922918        </ed:Languages>
    923         <ed:AvailableDataViews ref="hits"/>
    924         <ed:AvailableLayers ref="word"/>
     919        <ed:AvailableDataViews ref="hits adv"/>
     920        <ed:AvailableLayers ref="word lemma pos"/>
    925921      </ed:Resource>
    926922    </ed:Resources>
    … …  
    931927
    932928== Operation ''scan'' #scan
    933 The ''scan'' operation of the SRU protocol is currently not used in the ''Basic Search'' or ''Advanced Search'' capability of CLARIN-FCS. Future capabilities may use this operation, therefore it is `NOT RECOMMENDED` for Endpoints to define custom extensions that use this operation.
     929The ''scan'' operation of the SRU protocol is currently neither used in the ''Basic Search'' nor ''Advanced Search'' capability of CLARIN-FCS. Future capabilities may use this operation, therefore it is `NOT RECOMMENDED` for Endpoints to define custom extensions that use this operation.
    934930
    935931== Operation ''searchRetrieve'' #searchRetrieve
    … …  
    993989}}}
    994990
    995 In general, the Endpoint is `REQUIRED` to accept an ''unrestricted search'' and `SHOULD` perform the search operation on ''all'' Resources that are available at the Endpoint. If that is for some reason not feasible, e.g. performing an unrestricted search would allocate too many resources, the Endpoint `MAY` independently restrict the search to a scope that it can handle. If it does so, it `MUST` issue a non-fatal diagnostics `http://clarin.eu/fcs/diagnostic/2` ("Resource set too large. Query context automatically adjusted."). The details field of diagnostics `MUST` contain the persistent identifier of the resources to which the query scope was limited to. If the Endpoint limits the query scope to more than one resource, it `MUST` generate a ''separate'' non-fatal diagnostic `http://clarin.eu/fcs/diagnostic/2` for each of the resources.
     991Moving to a SRU 2.0 example which shows a request and response to a ''searchRetrieve'' request with a ''queryType=fcs'' query for ''[word = "användning"]'':
     992* HTTP GET request: Client → Endpoint:
     993{{{#!sh
     994http://localhost:8080/korp-endpoint/sru?operation=searchRetrieve&queryType=fcs&query=%5bword%3d%22anv%C3%A4ndning%22%5d&x-cmd-resource-info=true
     995}}}
     996* HTTP Response: Endpoint → Client:
     997{{{#!xml
     998<?xml version='1.0' encoding='utf-8'?>
     999<sruResponse:searchRetrieveResponse>
     1000  <sruResponse:version>2.0</sruResponse:version>
     1001  <sruResponse:numberOfRecords>33260</sruResponse:numberOfRecords>
     1002  <sruResponse:records>
     1003    <sruResponse:record>
     1004      <sruResponse:recordSchema>http://clarin.eu/fcs/resource</sruResponse:recordSchema>
     1005      <sruResponse:recordXMLEscaping>xml</sruResponse:recordXMLEscaping>
     1006      <sruResponse:recordData>
     1007        <fcs:Resource pid="ABOUNDERRATTELSER2012-32245">
     1008          <fcs:ResourceFragment>
     1009            <fcs:DataView type="application/x-clarin-fcs-hits+xml">
     1010              <hits:Result>Youtube-videon har väckt debatt om polisernas <hits:Hit>användning</hits:Hit> av våld .</hits:Result>
     1011            </fcs:DataView>
     1012            <fcs:DataView type="application/x-clarin-fcs-adv+xml">
     1013              <adv:Advanced unit="item">
     1014                <adv:Segments>
     1015                  <adv:Segment id="s1" start="1" end="15"/>
     1016                  <adv:Segment id="s2" start="16" end="19"/>
     1017                  <adv:Segment id="s3" start="20" end="25"/>
     1018                  <adv:Segment id="s4" start="26" end="32"/>
     1019                  <adv:Segment id="s5" start="33" end="35"/>
     1020                  <adv:Segment id="s6" start="36" end="46"/>
     1021                  <adv:Segment id="s7" start="47" end="57"/>
     1022                  <adv:Segment id="s8" start="58" end="60"/>
     1023                  <adv:Segment id="s9" start="61" end="65"/>
     1024                  <adv:Segment id="sa" start="66" end="67"/>
     1025                </adv:Segments>
     1026                <adv:Layers>
     1027                  <adv:Layer id="http://spraakbanken.gu.se/ns/fcs/layer/lemma">
     1028                    <adv:Span ref="s1">|</adv:Span>
     1029                    <adv:Span ref="s2">|ha|</adv:Span>
     1030                    <adv:Span ref="s3">|väcka|</adv:Span>
     1031                    <adv:Span ref="s4">|debatt|</adv:Span>
     1032                    <adv:Span ref="s5">|om|</adv:Span>
     1033                    <adv:Span ref="s6">|polis|</adv:Span>
     1034                    <adv:Span ref="s7" highlight="h1">|användning|</adv:Span>
     1035                    <adv:Span ref="s8">|av|</adv:Span>
     1036                    <adv:Span ref="s9">|våld|</adv:Span>
     1037                    <adv:Span ref="sa">|</adv:Span>
     1038                  </adv:Layer>
     1039                  <adv:Layer id="http://spraakbanken.gu.se/ns/fcs/layer/word">
     1040                    <adv:Span ref="s1">Youtube-videon</adv:Span>
     1041                    <adv:Span ref="s2">har</adv:Span>
     1042                    <adv:Span ref="s3">väckt</adv:Span>
     1043                    <adv:Span ref="s4">debatt</adv:Span>
     1044                    <adv:Span ref="s5">om</adv:Span>
     1045                    <adv:Span ref="s6">polisernas</adv:Span>
     1046                    <adv:Span ref="s7" highlight="h1">användning</adv:Span>
     1047                    <adv:Span ref="s8">av</adv:Span>
     1048                    <adv:Span ref="s9">våld</adv:Span>
     1049                    <adv:Span ref="sa">.</adv:Span>
     1050                  </adv:Layer>
     1051                  <adv:Layer id="http://spraakbanken.gu.se/ns/fcs/layer/pos">
     1052                    <adv:Span ref="s1">PROPN</adv:Span>
     1053                    <adv:Span ref="s2">VERB</adv:Span>
     1054                    <adv:Span ref="s3">VERB</adv:Span>
     1055                    <adv:Span ref="s4">NOUN</adv:Span>
     1056                    <adv:Span ref="s5">ADP</adv:Span>
     1057                    <adv:Span ref="s6">NOUN</adv:Span>
     1058                    <adv:Span ref="s7" highlight="h1">NOUN</adv:Span>
     1059                    <adv:Span ref="s8">ADP</adv:Span>
     1060                    <adv:Span ref="s9">NOUN</adv:Span>
     1061                    <adv:Span ref="sa">PUNCT</adv:Span>
     1062                  </adv:Layer>
     1063                </adv:Layers>
     1064              </adv:Advanced>
     1065            </fcs:DataView>
     1066          </fcs:ResourceFragment>
     1067        </fcs:Resource>
     1068      </sruResponse:recordData>
     1069      <sruResponse:recordPosition>1</sruResponse:recordPosition>
     1070    </sruResponse:record>
     1071    <!-- 249 records not shown -->
     1072  </sruResponse:records>
     1073  <sruResponse:nextRecordPosition>251</sruResponse:nextRecordPosition>
     1074  <sruResponse:echoedSearchRetrieveRequest>
     1075  <sruResponse:version>2.0</sruResponse:version>
     1076  <sruResponse:startRecord>1</sruResponse:startRecord>
     1077</sruResponse:echoedSearchRetrieveRequest>
     1078<sruResponse:resultCountPrecision>info:srw/vocabulary/resultCountPrecision/1/exact</sruResponse:resultCountPrecision></sruResponse:searchRetrieveResponse>
     1079}}}
     1080
     1081In general, as you can se from both the SRU 1.2 and SRU 2.0 examples above, the Endpoint is `REQUIRED` to accept an ''unrestricted search'' and `SHOULD` perform the search operation on ''all'' Resources that are available at the Endpoint. If that is for some reason not feasible, e.g. performing an unrestricted search would allocate too many resources, the Endpoint `MAY` independently restrict the search to a scope that it can handle. If it does so, it `MUST` issue a non-fatal diagnostics `http://clarin.eu/fcs/diagnostic/2` ("Resource set too large. Query context automatically adjusted."). The details field of diagnostics `MUST` contain the persistent identifier of the resources to which the query scope was limited to. If the Endpoint limits the query scope to more than one resource, it `MUST` generate a ''separate'' non-fatal diagnostic `http://clarin.eu/fcs/diagnostic/2` for each of the resources.
    9961082
    9971083The Client can request the Endpoint to ''restrict the search'' to a sub-resource of these Resources. In this case, the Client `MUST` pass a comma-separated list of persistent identifiers in the `x-fcs-context` extra request parameter of the ''searchRetrieve'' request. The Endpoint `MUST` then restrict the search to those Resources, which are identified by the persistent identifiers passed by the Client. If a Client requests too many resources for the Endpoint to handle with `x-fcs-context`, the Endpoint `MAY` issue a fatal diagnostic `http://clarin.eu/fcs/diagnostic/3` ("Resource set too large. Cannot perform Query.") and terminate processing. Alternatively, the Endpoint `MAY` also automatically adjust the scope and issue a non-fatal diagnostic `http://clarin.eu/fcs/diagnostic/2` (see above). And Endpoint `MUST NOT` issue a `http://clarin.eu/fcs/diagnostic/3` diagnostic in response to a request, if a Client performed the request ''without'' the `x-fcs-context` extra request parameter.