merge_sort

General Purpose

This X-Service merges several result sets into one result set from different resources which reside under one group_number.

There is only one set of merged results per group number. Therefore, the calling application has the ability to “remerge” or “merge more” on the same group number. This service also allows the calling application to request the merged list to be sorted by given criteria.

Important Notes:

Merge limit – The merge is limited according to “www_metalib_merge_limit” parameter (in www_server.conf). Default is 300, maximum is 900. If increased, may affect performance and result in timeout.

Remerge – Relevant either when the search is asynchronic or after using the “merge_more_set” action. An action “remerge” will be given so that when doing an asynchronic search on multiple resources, a temporary merged set can be returned to the calling application at any point during the search process, i.e after the first resource fetches results, after some resources fetch some results, and after all the resources fetch the first batch of results. If remerge is requested, the merged set will contain all the records fetched from all the searched resources in the set, at the given time, up to the configuration parameter no_fetched_result per resource (as defined in www_server.conf). In addition, the “remerge” action is also relevant after using the “merge_more_set” action, and will combine all the records fetched from all the searched resources in the set.

Merge – Any merge action can be performed on a group of resources or on a single resource. A request to merge only one resource must be submitted in order to sort the search results from a single resource.

sort_only – Before requesting “sort_only”, ensure that you have already issued a merge request.

Dedup – MetaLib’s dedup functionality may be suppressed by turning off the global parameter enable_dedupe (in www_server.conf). If the value of this parameter is set to ‘N’, dedup will be suppressed both in MetaLib’s user interface (/V) and in the ‘present’ X-Service. If enabled, when using “merge_more_set”, dedup will be done between the newly-fetched records. Only when remerging, will the full dedup be done for all the records in the merged set.

Flow

  • login – Called once by the calling application with valid /X user name and password. The session-id retrieved should be passed to all other API calls
  • find – Performs a search request on a single resource or on a group of resources. Returns the group number.
  • find_group_info (optional) – Reports on the status of the search process for each resource using the group number.
  • merge_sort
  • present – Retrieves a single record or multiple records (documents) from the results set.

Input Parameters

Mandatory
1. SESSION_ID – X(50)
2. GROUP_NUMBER – X(6)
3. ACTION – X(10)
Optional
1. PRIMARY_SORT_KEY
2. SECONDARY_SORT_KEY
3. FETCH_MORE_RECORDS
4. CALLING_APPLICATION – X(100).

Explanation of the mandatory and optional parameters:
  • session_id – The session ID is the unique identifier of the login.
  • group_number – Group identifier of the results set
  • action – The specific merge or sort action required:
    • merge – merge records retrieved up to this point in search process
    • merge_more – retrieve additional records and remerge with existing merged set
    • merge_more_set – retrieve additional records, clear the previous merged set and merge only the new records
    • remerge – delete last merged set and remerge records retrieved up to this point in search process (applies to asyncronic search request or after using the “merge_more_set” action)
    • sort_only – sort existing merged set
  • primary_sort_key –
    Valid values: rank, title, author, year, database
    If not specified, default is by database
  • secondary_sort_key:
    Valid values: rank, title, author, year, database
    If not specified, sort only by primary_sort_key
  • fetch_more_records
    Valid values: 10, 20, 30
    Default is 10. If an invalid value is specified, the default will be used.
    Relevant to the “merge more” and “merge_more_set” actions. If specified on other actions, parameter will be ignored.
    If increased, may affect performance and result in timeout.
  • calling_application – Name of the calling application.
    If not specified, default name is “X-SERVER”, and it will be stored in exact case.

Input XML Format

Example of merge, sorted by rank and title.

<?xml version = "1.0" encoding = "UTF-8"?>
<x_server_request>
<merge_sort_request>
    <group_number>000028</group_number>
    <action>merge</action>
    <primary_sort_key>rank</primary_sort_key>
    <secondary_sort_key>title</secondary_sort_key>
    <session_id>NP8VTHX5AM5RPRPG3LD7P7QA7GVUUGN8M9JVN4LPSY2X3X9V7J</session_id>
</merge_sort_request>
</x_server_request>

Input URL Syntax

In order to merge/sort, the session_id, group_number and action must be embedded within the URL syntax:

MetalibPath:port/X?op=merge_sort_request&group_number=group number&session_id=Login session&action=action&primary_sort_key=primary sort key&secondary_sort_key=secondary sort key&fetch_more_records=n

Example URL Syntax

http://10.1.235.47:8334/X?op=source_locate_request&source_locate_filter=&requester_ip=10.1.235.47&institute=METALIB&user_group=GUEST&locate_command=WIN=(METALIB)&source_full_info_flag=N&session_id=L9UUHVLPA7LUTEQYM7YJX8GLH6FDR2V77GRG6TIQ21UIXQEXH2

Output XML Format

Explanation of Output Values
  • new_set_number – Sequence number for the new merge set
  • group_number – Group identifier of the merged results set
  • no_of_documents – Number of documents in the new merge set
Example:
<?xml version = "1.0" encoding = "UTF-8"?>
<x_server_response metalib_version="4.00 (20)">
        <merge_sort_response>
                <new_set_number>000095</new_set_number>
                <group_number>000028</group_number>
                <no_of_documents>000000060</no_of_documents>
                <session_id new_session="N">NP8VTHX5AM5RPRPG3LD7P7QA7GVUUGN8M9JVN4LPSY2X3X9V7J</session_id>
        </merge_sort_response>
</x_server_response>

Possible Error Codes

1. If the session_id, provided as an input parameter, is not valid, the following error message appears in the XML output:

<error_code>0151</error_code>
<error_text>You are not authorized to use this function</error_text>

This can be caused by not using the session_id returned from the Login X-Service.

2. If this X-Service was activated after the session had timed out:

<error_code>2050</error_code> 
<error_text>Session timeout</error_text>

3. If a mandatory parameter is missing:

<error_code>2038</error_code>
<error_text>Missing element from XML request - '$1'</error_text>

4. If the group_number parameter is invalid:

<error_code>0135</error_code>
<error_text>Invalid group number</error_text>

5. If an invalid action is requested:

<error_code>6037</error_code>
<error_text>Invalid action parameter</error_text>

6. If an invalid sort key is specified:

<error_code>6038</error_code>
<error_text>Invalid sort parameter - '$1'</error_text>

7. If the same values are given for the primary and secondary sort keys:

<error_code>6039</error_code>
<error_text>Primary and secondary sort keys are identical. The secondary sort key is ignored.</error_text>

8. If only a secondary sort key is specified, and no primary key is given:

<error_code>0136</error_code>
<error_text>You must specify primary sort key</error_text>

9. If a resource returns an error:

<error_code>6032</error_code>
<error_text>Resource/s returned an error</error_text>

10. If only “Search & Link” resources return results:

<error_code>6033</error_code>
<error_text>Results have been retrieved only from "Search & Link resources</error_text>

11. If only “Link to” resources return results:

<error_code>6034</error_code>
<error_text>Results have been retrieved only from "Link to" resources</error_text>

12. If all the resources cannot fetch results:

<error_code>6035</error_code>
<error_text>Search suspended</error_text>

13. If all the resources have no results:

<error_code>0132</error_code>
<error_text>There are no results</error_text>

14. If sort_only is requested before a merge action:

<error_code>6036</error_code>
<error_text>You must request 'merge' before the 'sort_only' action</error_text>

15. If an invalid fetch more parameter is specified:

<error_code>6040</error_code>
<error_text>Fetch more is limited to 10, 20 or 30</error_text>

16.If no records can be retieved from the target, or no merged set exists:

<error_code>6041</error_code>
<error_text>MetaLib cannot retrieve records from target, or merged set does not exist</error_text>

17. If the number of records in the merge set is higher than the limit and a further merge more is requested:

<error_code>0133</error_code>
<error_text>Cannot merge more. You have already exceeded the merge limit</error_text>

18. If a merge is requested, and there are too many records to be merged:

<error_code>0134</error_code>
<error_text>The merged set has more records than the merge limit</error_text>

19. If all available records have been merged:

<error_code>137</error_code>
<error_text>You have already merged all records available</error_text>