Connect to Elasticsearch

edit

If you are looking for a user interface for Elasticsearch and your data, head on over to Kibana! Not only are there amazing visualization and index management tools, Kibana includes a realistic sample data set to play with so that you can get to know what you could do with your data.

There are two ways to connect directly to your Elasticsearch cluster: Through the RESTful API or through the Java transport client. Both ways use an endpoint URL that includes a port, such as https://ec47fc4d2c53414e1307e85726d4b9bb.us-east-1.aws.found.io:9243.

The simplest way to connect to your cluster:

  1. On the Overview page for your new cluster in the Cloud UI, click the Elasticsearch endpoint URL under Endpoints.
  2. If you get prompted, log in as the elastic user with the password you copied down earlier. Elasticsearch returns a standard message like this:

    {
      "name" : "instance-0000000002",
      "cluster_name" : "811de9be78674138d6b8ba54b830c38d",
      "cluster_uuid" : "KpvANC2ZQb-h5-YVH1qdog",
      "version" : {
        "number" : "5.5.1",
        "build_hash" : "19c13d0",
        "build_date" : "2017-07-18T20:44:24.823Z",
        "build_snapshot" : false,
        "lucene_version" : "6.6.0"
      },
      "tagline" : "You Know, for Search"
    }

RESTful API with JSON

edit

Used with the curl command and most programming languages that aren’t Java, the RESTful API is a very popular way to interact with your Elasticsearch cluster. When you clicked an endpoint URL in the Cloud UI, you were already using the RESTful API.

To interact with your cluster through the API, use your Elasticsearch cluster endpoint information from the Overview page in the Cloud UI. Endpoint URLs look like https://ec47fc4d2c53414e1307e85726d4b9bb.us-east-1.aws.found.io:9243 (AWS) or like https://d8d6bc6fcb4f7ca37640851dadac668a.us-central1.gcp.cloud.es.io:9243 (GCP) and can tell you quite a bit about your cluster. The format is always:

https://CLUSTER_ID.REGION.CLOUD_PLATFORM.DOMAIN:PORT
CLUSTER_ID
The cluster ID that is unique to your cluster. For example: 811de9be78674138d6b8ba54b830c38d.
REGION
The geographic region within your cloud platform. For example: us-east-1 or us-central1.
CLOUD_PLATFORM
The cloud platform, either aws for Amazon Web Services or gcp for Google Cloud Platform.
DOMAIN
The domain name, such as cloud.es.io or found.io. The actual domain name depends on the region you use.
PORT

The port for the RESTful API or the Java transport client. For example: 9243. For the RESTful API, port 9243 is used for HTTPS connections and is strongly recommended (port 443 is also supported for HTTPS). We still allow HTTP connections for the API over port 9200 on some regions, but we recommend against using HTTP and no longer list the HTTP endpoint. For the Java transport client, port 9343 with TLS/SSL is used (port 9300 without encryption is also supported but not recommended).

Port 9200 is not supported on all AWS regions and will not be supported for new regions that we add. Port 9200 is also not supported on the GCP platform. Use port 9243 instead.

If you created a cluster on Elasticsearch 5.0 or later or if you already enabled the security features with an earlier version of Elasticsearch, you must include authentication details with the -u parameter when you interact with your cluster.

If this is your first time using Elasticsearch, you can try out some curl commands to become familiar with the basics of indexing or searching documents. On operating systems like macOS or Linux, you should already have the curl command installed.

If you want to try out examples with your own cluster, remember to include your own endpoint URLs and authentication details. These examples won’t work directly as is.

To index your first document into an index called my_index in Elasticsearch, issue a POST request and include the document in JSON format:

curl -u elastic:password https://CLUSTER_ID.REGION.PLATFORM.found.io:9243/my_index/my_type -XPOST -d '{
"title": "One", "tags": ["ruby"]
}'
{"_index":"my_index","_type":"my_type","_id":"AV3ZeXsOMOVbmlCACuwj","_version":1,"result":"created","_shards":{"total":2,"successful":1,"failed":0},"created":true}

To retrieve all the documents in the same index, issue a GET request:

curl -u elastic:password https://CLUSTER_ID.REGION.PLATFORM.found.io:9243/my_index/my_type/_search?pretty=true
{
  "took" : 0,
  "timed_out" : false,
  "_shards" : {
    "total" : 5,
    "successful" : 5,
    "failed" : 0
  },
  "hits" : {
    "total" : 1,
    "max_score" : 1.0,
    "hits" : [
      {
        "_index" : "my_index",
        "_type" : "my_type",
        "_id" : "AV3ZeXsOMOVbmlCACuwj",
        "_score" : 1.0,
        "_source" : {
          "title" : "One",
          "tags" : [
            "ruby"
          ]
        }
      }
    ]
  }
}

These examples barely scratch the surface of what’s available. Once you experiment with slightly bigger queries, you might also want to try something that is a little more syntax aware. Some popular choices are:

  • Kibana, a great tool for analyzing any type of data stored in Elasticsearch, has grown to include Console, which is useful for interacting with the REST API of Elasticsearch (in versions before 5.0, Console is called Sense).
  • The query editor in Kopf
  • Elastic-hammer, a web front-end for Elasticsearch.

Java transport client

edit

A good choice if your applications are using Java. This lighter-weight transport client forwards requests to a remote cluster over your endpoint URL and port 9343 with TLS/SSL using the native Elasticsearch transport protocol (port 9300 without encryption is also supported but not recommended).