List of operations in the Manage Web Service

The Manage Web Service contains operations for creating new data domains and managing existing ones, in the context of the Endeca Server cluster hosting multiple data domain clusters.

Operation description

The Manage Web Service lets you issue requests to create new or manage existing data domains.

Before you use the Manage Web Service, deploy the Endeca Server nodes in the WebLogic Server container, and use the Cluster Web Service to create data domain profiles.

Each data domain you create with the Manage Web Service has these characteristics:
  • It resides on a subset of Endeca Server nodes that themselves belong to an Endeca Server cluster.
  • It is associated with an existing data domain profile. The domain profiles determine the resources available to each of the data domain clusters once you create them. (You can change the data domain's characteristics after it has been created.)

Request

The input to the Manage Web Service depends on the element in its request. For example:
  • To create a new data domain, use the createDataDomain element, specifying its name and the data domain profile name.
  • To create a new data domain using index files that already exist, use the importDataDomain element, specifying its name, the data domain profile name, and the label for the previously exported index files.

Other operations are discussed in the list of operations in this topic.

Response

Depending on the success of the request, the Manage Web Service returns:
  • If there are no problems and the response was successful, an empty response element is returned (except for listDataDomains and listDataDomainProfiles operations, which return information).
  • A SOAP fault indicating an Endeca Server error, in the instances including the following: a data domain with the specified name already exists, the data domain profile is not defined in the Endeca Server cluster, the Endeca Server cluster has insufficient resources to accommodate the request, or the data domain profile is configured with characteristics that exceed the current hardware resources of the Endeca Server cluster.

List of operations

The Manage Web Service lets you perform the following operations, where operations are represented by elements in the request:
Request element Description
allocateBulkLoadPort Return a host name for the leader node and the port used for Bulk Load Interface, for a data domain with the specified name.

This is a read-write operation — if the current leader is available, it verifies the current Dgraph leader node and reports it along with the port used for Bulk Load; if the current leader node is not available, it appoints a new leader node and a new Bulk Load port and reports them.

createDataDomain Create a new data domain in the Endeca Server cluster, specifying its name, data domain profile name, and (optionally) whether it is enabled. The values are:
  • name is the data domain name.
  • ddProfileName is the name of a data domain profile to use.
  • enabled (Optional). If set to true the data domain is enabled. This is the default. If set to false, the data domain is disabled.
deleteDataDomain Delete a data domain from the system in its entirety removing all associated resources, which include source records, configuration, logs, and index files for this data domain. No backup of any sort is performed. When a data domain is deleted, it cannot be restored.

To delete a data domain, specify its name in this element.

cloneDataDomain Create a new data domain by making a copy of a specified existing data domain.
To clone a data domain, specify:
  • name is the name of the new data domain you will be creating.
  • sourceName is the name of the source data domain from which you will be copying.
  • enabled (Optional). Whether the new data domain should be enabled. If you don't specify the enabled value, the new data domain is enabled by default.
rescaleDataDomain Resize a specified data domain by adding the number of follower nodes to the data domain cluster. To rescale a data domain, specify its name, and numFollowers, which is the desired number of follower Dgraph nodes to handle queries. Ensure that the Endeca Server cluster contains a sufficient number of nodes to accommodate the changed size of the data domain. With this operation, you can only add nodes to the data domain, but not remove them.
Note: When the data domain's profile disallows queries on the leader node (allowQueriesOnLeader is set to false), numFollowers must be greater than one to ensure that at least one follower node is available to handle queries.
exportDataDomain Export the index of the specified data domain by taking a snapshot of the index and copying it into an internally stored file. A snapshot represents a copy of the index files only, and does not capture any other characteristics of the data domain, such as the Dgraph configuration or the data domain profile used when it was created.

On Linux, you can export a data domain that is either enabled or disabled. On Windows, only a disabled data domain can be exported.

When an enabled data domain is exported, it continues to run, but a copy of its index is stored in an offline directory on a shared file system.

To export a data domain, specify:
  • name is the name of the data domain whose index you want to export.
  • nameOfOfflineDataDomain (Optional). The name that will be given to this data domain's index once it is exported. This name must be unique. If not specified, it is assigned automatically, by appending the date to the original data domain name, as in this format: name_MMMMM-dd-yyyy-hh-mm. The request returns the resulting name used for the exported index.
    Important: Keep track of the value of nameOfOfflineDataDomain, because you will need it later for importing this index.
importDataDomain Create a new data domain using previously exported index files. Using this operation assumes that you have previously created a data domain whose index is currently exported; it also assumes that you kept track of the nameOfOfflineDataDomain you used in the exportDataDomain operation, or know the name that was automatically assigned.
To import a data domain, specify:
  • name is the name of the new data domain into which you are importing the index files from a previously exported data domain.
  • nameOfOfflineDataDomain is the name of the previously exported index files.
  • ddProfileName (Optional). The name of the data domain profile that will be used for the new data domain created with imported index files.
  • enabled (Optional). Specifies whether the newly imported data domain should be enabled (if set to true). If the value is not specified, the imported data domain is enabled by default.
enableDataDomain Enable a data domain by specifying its name. This starts the Dgraph nodes (processes) for the data domain.
disableDataDomain Disable a data domain by specifying its name. A disabled data domain exists and is still allocated resources, but its Dgraph nodes are shut down and must be enabled with enableDataDomain before the data domain can handle requests.
getDataDomain Obtain information about a data domain with a specified name. The response returns the data domain name and its status (enabled or disabled).
listDataDomains List all existing data domains and includes additional status information, such as the name, description, whether the data domain is enabled, the number of nodes, the number of query processing threads, and the list of arguments specified for the Dgraph processes (if any are specified).
getDataDomainStats Return runtime statistics about the data domain, if you specify the data domain name. The response includes the following information:
  • The size of the index records on shared storage (in MB).
  • The number of source records in the data domain (this number excludes non-data, or system records).
  • the Dgraph node statistics for each running Dgraph node in the data domain, including the Dgraph startup time, last index creation time, and path. The statistics pages are intended for Oracle Endeca Support.
getDataDomainProfile Obtain information about the data domain profile with the specified name. Returns the name and description of the profile and other data domain profile characteristics, such as the number of nodes, the number of query processing threads, and the list of arguments that are sent to the Dgraph processes.
listDataDomainProfiles Return the set of data domain profiles configured in the Endeca Server cluster. For each data domain profile, returns its name, description, and other characteristics, such as the number of nodes, the number of query processing threads, and the list of arguments sent to the Dgraph processes.
version List the version of the Oracle Endeca Server and the versions of the Dgraph processes powering each of the data domains (if the Dgraph processes for these data domains are currently running).

You do not need to specify the data domain names when using this command.

updateSpellingDictionaries Update the spelling dictionaries in the index for the data domain with the specified name. This operation enables spelling correction and lets you rebuild the dictionaries for spelling correction from the current index while continuing to issue queries and updates to the data domain and without stopping and restarting its Dgraph nodes.

Example

The following examples show the Manage Web Service request and response for creating a data domain:

This abbreviated example shows a Manage Web Service request that creates a data domain myDD based on the data domain profile my_dd_profile. Once created, this data domain will be enabled:
<ns1:createDataDomain xmlns:ns1="http://www.endeca.com/endeca-server/manage/1/0">
      <ns1:name>myDD</ns1:name>
      <ns1:ddProfileName>my_dd_profile</ns1:ddProfileName>
      <ns1:enabled>true</ns1:enabled>
</ns1:createDataDomain>
This example shows an empty createDataDomainResponse from the Manage Web Service. This indicates that the data domain was created successfully:
<ns3:createDataDomainResponse
    xmlns:ns2="http://www.endeca.com/endeca-server/types/1/0"
    xmlns:ns3="http://www.endeca.com/endeca-server/manage/1/0"/>

To verify that the data domain was added, issue a listDataDomains operation.

It is possible that, based on the existing data domain profiles, the Endeca Server cluster cannot create a data domain. This situation can occur if, for example, the data domain profile specifies a greater number of follower nodes in the data domain than the number of deployed Endeca Server nodes. For example, if you have deployed a single Endeca Server node and created a data domain profile with four follower nodes and a dedicated leader node (allowQueriesOnLeader is set to false), you may receive an error similar to the following:
Request for 5 nodes would exceed configured maximum allowable number of oversubscribed nodes

To summarize, if you receive an error when creating a data domain, verify the number and characteristics of your Endeca Server nodes and the configuration of the data domain profile you used. Check that the Endeca Server cluster is configured with a sufficient number of Endeca Server nodes, has enough hardware capacity, and that the data domain profile matches your data domain requirements. For information, see How profiles affect hardware utilization and Deciding which data domain profile to use.

Note: For reference information about the elements and types used in the Manage Web Service, see the Manage Web Service API Reference, in the Oracle Endeca Server API Reference.