Registering Elasticsearch with Oracle NoSQL Database

Before you can use Oracle NoSQL Database to create a Text Index in an Elasticsearch cluster, you must register the desired cluster with the Oracle NoSQL Database store, using the plan command named register-es. It is via the register-es plan that you provide the name of the Elasticsearch cluster, the name of one of the hosts in that cluster, and the HTTP port on which that host is listening for connection requests. Specifically, the register-es plan command takes the following form:

plan register-es 
        –clustername <name> 
        -host <host|ip> 
        -port <http port> 
        -secure <true|false> 
        [-wait] 
        [-force]

For example, if your Elasticsearch cluster is named elasticsearch (the default) and includes a node running on your local host, listening on the default HTTP port (9200), then you would execute the following command from the Oracle NoSQL Database administrative command line interface (Admin CLI):

kv-> plan register-es 
        –clustername elasticsearch 
        –host 127.0.0.1 
        –port 9200 
        –secure false 
        -wait

Executed plan 22, waiting for completion...
Plan 22 ended successfully

Note:

When the register-es plan is executed, if the Elasticsearch cluster specified in the command already contains indexes created under a registration between a previous NoSQL store instance and the current Elasticsearch cluster, then the plan will fail and display an error message. Such indexes are referred to as stale indexes, and the plan fails in the face of such stale indexes because the indexes currently maintained in the Elasticsearch cluster's state are associated with the store that previously created them under the original registration. Although those existing indexes are part of the Elasticsearch cluster's state, they are not part of the state of the new store instance. Allowing the new store instance to create a new registration through which new indexes can be created in the cluster can produce inconsistencies and possible conflicts between the state maintained by the store and the state maintained by Elasticsearch; resulting in potential error conditions.

To avoid such error conditions, when the new store instance receives a request for a new registration with the Elasticsearch cluster, and that cluster contains indexes associated with a registration created by a previous store instance, the request is rejected; unless the force flag is specified. If the force flag is specified in the register-es command, then the store will request that Elasticsearch first remove all of its stale indexes; and only after those indexes have been successfully removed, will the registration be created between the new store instance and the Elasticsearch cluster.

During the registration process the store's Admin Service (or simply, the Admin) verifies the existence of (as well as a network path to) the Elasticsearch node specified in the register-es command arguments, and then acquires from that node a complete list of connection information for all the nodes making up that Elasticsearch cluster. This information is stored in the Admin's state, as well as distributed to all the nodes
 of the Oracle NoSQL Database store. If the Elasticsearch cluster's population of nodes changes significantly (due to node or network failure, cluster reconfiguration, and so on), the register-es command can be repeated to update the Oracle NoSQL Database's list of Elasticsearch node connections.

After successfully executing the register-es plan, you can verify that the Oracle NoSQL Database store is indeed registered with the desired Elasticsearch cluster by executing the show parameters command from the Admin CLI in the following way:

show parameters –service <storage node id>

The show parameters command displays a list of properties for the specified storage node that, if the registration was successful, will include the name of the Elasticsearch cluster, along with the host names and/or IP addresses of the nodes making up that cluster. When you execute the show parameters command, the value of the properties named searchClustername and searchClusterMembers will provide that information for you. For example,

kv-> show parameters -service sn1

capacity=1
haHostname=localhost
haPortRange=5005,5007
hostname=localhost
memoryMB=0 
mgmtClass=oracle.kv.impl.mgmt.NoOpAgent 
mgmtPollPort=0
 
mgmtTrapPort=0
 
numCPUs=8
 
registryPort=5000
 
rnHeapMaxMB=0
 
rnHeapPercent=85
 
rootDirPath=./kvroot 
searchClusterMembers=127.0.0.1:9200 
searchClusterName=elasticsearch
serviceLogFileCount=20
serviceLogFileLimit=2000000
storageNodeId=1

systemPercent=10