elasticshell
elasticshell copied to clipboard
A javascript shell for elasticsearch
elasticshell - a shell for elasticsearch
The elasticshell is a javascript shell written in Java. It allows to interact with a running elasticsearch cluster using the Java API.
The elasticshell was a very nice experiment in my early days playing around with elasticsearch. It turned out to be hard to maintain and keep in sync with the elasticsearch codebase though. Also, I got to the conclusion that a shell is not that beneficial to a system that already has extremely user-friendly REST api. Furthermore, the addition of the cat api to elasticsearch filled the gap when it comes to providing text output rather than json. This is why I haven't been maintaining the project for a long time.
Getting Started
Versions
The elasticshell version is tightly coupled with the elasticsearch version since it uses its Java API to connect to it. There currently are three active development branches: one for 0.19.x, one for 0.20.x and one for 0.90.x.
elasticshell | elasticsearch |
master | 0.90.0.RC2 |
0.90.0.RC2 | 0.90.0.RC2 |
0.20.6-RC | 0.20.x |
0.19.12-RC | 0.19.x |
Installation
- Download and unzip the elasticshell distribution
- Run
bin/elasticshell
on unix, orbin/elasticshell.bat
on windows
Help
Use the help() command to have a look at the elasticshell help. Every command is exposed as a javascript function. If you want to get help for a specific command, just type its name without the curly brackets. The help output is currently available only for a few available commands, some more documentation will be added soon.
Auto-suggestions
Have a look at the auto-suggestions through the tab key to see the available commands and variables. JSON is native within the elasticshell, thus auto-suggestions are available within JSON objects too.
Connecting to a cluster
The elasticshell will automatically try to create a new transport client connected to a node running on localhost:9300. That default transport client will be registered with the es variable name, same result as the following command:
var es = transportClient('localhost:9300');
You can manually connect to a running elasticsearch cluster using the following commands:
var es = transportClient('hostname:port')
creates a new transport client. You can provide a list of addresses too.
var es = nodeClient('clusterName')
creates a new node client.
Let's index a document
var jsonDoc = {
"user": "kimchy",
"postDate": "2009-11-15T13:12:00",
"message": "Trying out Elastic Search, so far so good?"
}
es.index('twitter','tweet','1', jsonDoc);
We can also use the available index builder, which allows to use all the options available when indexing a document:
es.indexBuilder().index('twitter').type('tweet').id('1').source(jsonDoc).execute();
Interact with a specific index or type
You can easily execute operations on a specific index or type like this:
es.<index>.<type>.search();
If the elasticshell does not accept the name of the index or type, for instance if the name contains a space or starts with a number, you can use the following alternate syntax:
es['index name'].search();
Let's retrieve a document
es.twitter.tweet.get('1');
The above command retrieves the previously indexed document using the get API.
Let's search
var termQuery = {
"query" : {
"term" : { "user": "kimchy" }
}
}
es.search(termQuery);
We can also use the search builder:
es.searchBuilder().query(termQuery.query).execute();
We can also make use of the elasticsearch query builders like this:
es.searchBuilder().queryBuilder(QueryBuilders.termQuery('user','kimchy')).execute();
Let's add a facet to the previous query
es.searchBuilder()
.query(QueryBuilders.termQuery('user','kimchy'))
.facet(FacetBuilders.termsFacet('user').field('user')).execute();
All the elasticsearch API are exposed through the elasticshell. Remember that the elasticshell is a javascript shell, thus you can have fun with javascript code. On the other hand, the elasticshell has been built on top of the Rhino engine, which means that you can execute Java code too.
Contribute
You can easily fork the project in order to contribute to it and send your pull requests. Due to limitations on all IDEs console, it's recommended to test your changes from a real command line. The project uses in fact the great JLine which needs to execute a bit of native code to provide nice auto-suggestions and so on. You can easily run the elasticshell from the command line through maven using the following command which compiles the project and run its main class:
mvn compile exec:java
The above command has the same result as executing the elasticshell from the normal distribution using the executable provided within the bin folder.
License
This software is licensed under the Apache 2 license, quoted below.
Copyright 2015 Luca Cavanna
Licensed under the Apache License, Version 2.0 (the "License"); you may not
use this file except in compliance with the License. You may obtain a copy of
the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations under
the License.