Configuring session affinity for data domains

When receiving client requests, the Endeca Server cluster routes them to the arbitrary Endeca Server nodes hosting the appropriate data domains. Optionally, you can configure your data domain profile to utilize session affinity for request routing.

Configuring session affinity in the Endeca Server guarantees that queries with the same session ID are routed to the same Dgraph nodes in the data domain. This improves query processing performance by efficiently utilizing the Dgraph process cache, and improves performance of caching entities (known in Studio as views).

When configuring the data domain profile with endeca-cmd, you can specify:

endeca-cmd parameter Description
endeca-cmd put-dd-profile --session-id-type method The method that will be used for establishing session affinity.

The available options are: HEADER for HTTP headers, PARAMETER for URL parameters, or COOKIE.

The default method is HEADER. The values are not case-sensitive.

endeca-cmd put-dd-profile --session-id-key name The name of the object that will be checked by the specified method. The default name is X-Endeca-Session-ID.

When you create a new data domain using this profile, the Endeca Server utilizes the values you have specified.

For all three methods (HTTP header, URL parameter, or cookie), the Endeca Server attempts to locate the session ID based on the method and name you specified. If the Endeca Server does not locate a specific session ID in the request, it arbitrarily selects an ID and attempts to route the request to the appropriate Endeca Server node using round-robin distribution.

The Endeca Server expects that the front-end client application that will be issuing requests to the hosted data domains will explicitly set the HTTP headers, the URL parameters, and cookies for its requests.

Note: The Endeca Server returns a cookie with any query-type request to a data domain using the cookie method which does not have the cookie set. Therefore, if you select the cookie method, the cookie returned by the Endeca Server in the previous request should be used for routing the subsequent request.
To configure the data domain for using a particular method of session affinity:
  1. Use a command-line window (for example, open a Command Prompt in Windows) and navigate to the endeca-cmd directory.
  2. When configuring a data domain profile, use the command as in the following example: 
    endeca-cmd put-dd-profile MyProfile --session-id-type header --session-id-key x-endeca-session-id

    Alternatively, you can use the following syntax in the Cluster Web Service request (this example is abbreviated as it lists only the parameters specific to session affinity configuration, and omits other data domain parameters): 

    <ns1:putDataDomainProfile xmlns:ns1="http://www.endeca.com/endeca-server/cluster/2/0">
  <ns1:dataDomainProfile>
  ...
  <ns10:sessionIdType xmlns:ns10="http://www.endeca.com/endeca-server/types/2/0">header</ns10:sessionIdType>
  <ns11:sessionIdKey xmlns:ns11="http://www.endeca.com/endeca-server/types/2/0">X-Endeca-Session-ID</ns11:sessionIdKey>
  </ns1:dataDomainProfile>
</ns1:putDataDomainProfile>