To take {es} for a test drive, you can create a hosted deployment on the {ess} or set up a multi-node {es} cluster on your own Linux, macOS, or Windows machine.

When you create a deployment on the {es} Service, the service provisions a three-node {es} cluster along with Kibana and APM.

To create a deployment:

Once you’ve created a deployment, you’re ready to Index some documents.

When you create a deployment on the {ess}, a master node and two data nodes are provisioned automatically. By installing from the tar or zip archive, you can start multiple instances of {es} locally to see how a multi-node cluster behaves.

To run a three-node {es} cluster locally:

Installing {es} from an archive file enables you to easily install and run multiple instances locally so you can try things out. To run a single instance, you can run {es} in a Docker container, install {es} using the DEB or RPM packages on Linux, install using Homebrew on macOS, or install using the MSI package installer on Windows. See [install-elasticsearch] for more information.

Once you have a cluster up and running, you’re ready to index some data. There are a variety of ingest options for {es}, but in the end they all do the same thing: put JSON documents into an {es} index.

You can do this directly with a simple PUT request that specifies the index you want to add the document, a unique document ID, and one or more "field": "value" pairs in the request body:

This request automatically creates the customer index if it doesn’t already exist, adds a new document that has an ID of 1, and stores and indexes the name field.

Since this is a new document, the response shows that the result of the operation was that version 1 of the document was created:

The new document is available immediately from any node in the cluster. You can retrieve it with a GET request that specifies its document ID:

The response indicates that a document with the specified ID was found and shows the original source fields that were indexed.

If you have a lot of documents to index, you can submit them in batches with the {ref}/docs-bulk.html[bulk API]. Using bulk to batch document operations is significantly faster than submitting requests individually as it minimizes network roundtrips.

The optimal batch size depends a number of factors: the document size and complexity, the indexing and search load, and the resources available to your cluster. A good place to start is with batches of 1,000 to 5,000 documents and a total payload between 5MB and 15MB. From there, you can experiment to find the sweet spot.

To get some data into {es} that you can start searching and analyzing:

Once you have ingested some data into an {es} index, you can search it by sending requests to the _search endpoint. To access the full suite of search capabilities, you use the {es} Query DSL to specify the search criteria in the request body. You specify the name of the index you want to search in the request URI.

For example, the following request retrieves all documents in the bank index sorted by account number:

By default, the hits section of the response includes the first 10 documents that match the search criteria:

The response also provides the following information about the search request:

Each search request is self-contained: {es} does not maintain any state information across requests. To page through the search hits, specify the from and size parameters in your request.

For example, the following request gets hits 10 through 19:

Now that you’ve seen how to submit a basic search request, you can start to construct queries that are a bit more interesting than match_all.

To search for specific terms within a field, you can use a match query. For example, the following request searches the address field to find customers whose addresses contain mill or lane:

To perform a phrase search rather than matching individual terms, you use match_phrase instead of match. For example, the following request only matches addresses that contain the phrase mill lane:

To construct more complex queries, you can use a bool query to combine multiple query criteria. You can designate criteria as required (must match), desirable (should match), or undesirable (must not match).

For example, the following request searches the bank index for accounts that belong to customers who are 40 years old, but excludes anyone who lives in Idaho (ID):

Each must, should, and must_not element in a Boolean query is referred to as a query clause. How well a document meets the criteria in each must or should clause contributes to the document’s relevance score. The higher the score, the better the document matches your search criteria. By default, {es} returns documents ranked by these relevance scores.

The criteria in a must_not clause is treated as a filter. It affects whether or not the document is included in the results, but does not contribute to how documents are scored. You can also explicitly specify arbitrary filters to include or exclude documents based on structured data.

For example, the following request uses a range filter to limit the results to accounts with a balance between $20,000 and $30,000 (inclusive).

{es} aggregations enable you to get meta-information about your search results and answer questions like, "How many account holders are in Texas?" or "What’s the average balance of accounts in Tennessee?" You can search documents, filter hits, and use aggregations to analyze the results all in one request.

For example, the following request uses a terms aggregation to group all of the accounts in the bank index by state, and returns the ten states with the most accounts in descending order:

The buckets in the response are the values of the state field. The doc_count shows the number of accounts in each state. For example, you can see that there are 27 accounts in ID (Idaho). Because the request set size=0, the response only contains the aggregation results.

You can combine aggregations to build more complex summaries of your data. For example, the following request nests an avg aggregation within the previous group_by_state aggregation to calculate the average account balances for each state.

Instead of sorting the results by count, you could sort using the result of the nested aggregation by specifying the order within the terms aggregation:

In addition to basic bucketing and metrics aggregations like these, {es} provides specialized aggregations for operating on multiple fields and analyzing particular types of data such as dates, IP addresses, and geo data. You can also feed the results of individual aggregations into pipeline aggregations for further analysis.

The core analysis capabilities provided by aggregations enable advanced features such as using machine learning to detect anomalies.

Now that you’ve set up a cluster, indexed some documents, and run some searches and aggregations, you might want to: