Holding on to a data version

The Endeca Server lets you hold on to (or pin) a specific version of the data in memory. Holding on to a version is useful, for example, when the front-end application (such as Studio), needs to return consistent page results. It is also useful to hold on to a specific version if you want to export a large number of records from the Endeca Server.

You can issue a Conversation Web Service request to hold a version in memory, so that a subsequent request can ask for this version when performing query processing. The following statements describe the behavior of the Endeca Server:
  • When you issue a request to hold a data version, a data version is kept in memory (or is "pinned") for a period of time you specify.
  • In the request, you can optionally specify the value for the timeout. Timeout is the time after which the version is dismissed by the Endeca Server. It is counted from the time of the most recent request that uses this data version. If you do not specify a timeout, the default timeout from EndecaServer.properties file is used.
  • If you specify a timeout value that is less than the minimum, or greater than the maximum values, the request returns an error.
  • If you continue issuing requests against the pinned version, the timeout is renewed.
  • The pinned version expires after a timeout, and is removed by the Endeca Server if you stop issuing queries against this version.
  • If you issue multiple requests in succession to hold on to a data version, each time specifying a different timeout value within the minimum and maximum boundaries, the greater of the timeout values is used. Consider this example, where you have already pinned a version by specifying a timeout of 10 minutes, and your maximum timeout value is 20 minutes:
    • If you issue a new request with the 15 minutes timeout, the Endeca Server increases the timeout to this value, because it is greater than the existing timeout of 10 minutes. it also checks the new value is less than the maximum of 20 minutes in EndecaServer.properties.
    • If you issue a new request with the 7 minutes timeout, the Endeca Server checks how much time is left in the existing timeout. If, for example, 7 minutes are left in the existing timeout of 10 minutes, this timeout is not reset. Similarly, if 8 minutes are left, the current timeout is not reset because 8 > 7. However, if 5 minutes are left, the timeout is increased to 7 minutes.
  • A version is pinned by the Endeca Server on a specific Dgraph in the data domain. To guarantee this, Endeca Server lets you pin a data version only if your data domain uses session affinity. Session affinity guarantees that a request is routed to the same Dgraph in the data domain, if the Dgraph is available. (If you use a default data domain profile, session affinity is enabled by default.) For details on configuring session affinity, see the Endeca Server Administrator's Guide.

To pin a data version:

  1. Check that the data domain profile uses session affinity. Issue the following commands in succession: 
    endeca-cmd get-dd <data_domain_name>
endeca-cmd get-dd-profile <data_domain_profile_name>

    The get-dd command returns the details of your data domain, including its profile. The get-dd-profile command returns the characteristics of the data domain profile.

    The following lines in the profile indicate that session affinity is specified for the data domain: 
    session-id-type: header
session-id-key: X-Endeca-Session-ID
    In this example, session affinity uses header (other methods are possible for session affinity. See the Endeca Server Cluster Guide).
  2. On the host and port of your Endeca Server deployment, issue a Conversation Web Service request that specifies a timeout, as in this abbreviated example: 
    ...
<ns:Request>
 <!--Optional:-->
  <ns:PinDataVersion>optional_pin_timeout</ns:PinDataVersion>
<ns:State>
  ....
</ns:State>

    where optional_pin_timeout can be any integer value in milliseconds that is within the boundaries of the minimum and maximum timeout values specified in the EndecaServer.properties file in $DOMAIN_HOME/config. In that file, the defaults are as follows: the minimum timeout is 60000 milliseconds (1 minute), and the maximum timeout is 300000 ms (5 minutes). The default listed in the file is 120000 ms (2 minutes). If the timeout is not specified in the request, it uses the default from the file.

If successful, the Endeca Server returns an empty Conversation Web Service response, similar to the following: 
<cs:Results xmlns:cs="http://www.endeca.com/MDEX/conversation/3/0" 
            xmlns:mdex="http://www.endeca.com/MDEX/XQuery/2009/09">
    <cs:State/>
</cs:Results>
The header of the response includes:
  • The X-Endeca-Served-Data-Version — this is the version that you pinned.
  • The X-Endeca-Data-Version — this is latest data version.
The latest data version may or may not differ from the pinned data version. Here is an example of a header, in which the served data version (the one you pinned), and the latest data version are the same, which is a typical case: 
X-Endeca-Served-Data-Version 61
X-Endeca-Data-Version 61

Once you obtain the pinned data version, you can then use it in subsequent requests issued within the specified timeout. To use the pinned version, include DataVersionRequested element in subsequent requests, while staying within the timeout.