Requesting a pinned data version in a query

The <DataVersionRequested> element is optional, meaning that you can include it into any Conversation Web Service request. (Although, you cannot issue a request that contains both <PinDataVersion> and <DataVersionRequested>). A request with <DataVersionRequested> can also optionally include an outer transaction ID, so that all other queries are processed within this transaction, while using the same data version.

Issuing a query request against a specific data version is useful when, for example, you would like to obtain a large number of records from the Endeca Server (such as, to export them in bulk), or, when the user interface of your front-end application needs to present consistent results to the user. For example, in Studio, various components issue requests to the Endeca Server, and it is desirable for them to represent the same state of the data, even if the data is being updated in real time, while end users continue issuing queries.

Before you request a specific version of the data with <DataVersionRequested>, use PinDataVersion in a previous request, to indicate to the Endeca Server that you would like to hold on to a version for a specified timeout period. The response to the version-pinning request returns the number of the pinned data version (and a current data version number, which may differ from the pinned version number), in the header. You can then use the pinned data version number in any subsequent requests. These requests will be processed against the pinned version, if they are issued within the timeout period.