Quick start

edit

This guide helps you learn how to:

  • install and run Elasticsearch and Kibana (using Elastic Cloud or Docker),
  • add simple (non-timestamped) dataset to Elasticsearch,
  • run basic searches.

If you’re interested in using Elasticsearch with Python, check out Elastic Search Labs. This is the best place to explore AI-powered search use cases, such as working with embeddings, vector search, and retrieval augmented generation (RAG).

Run Elasticsearch

edit

The simplest way to set up Elasticsearch is to create a managed deployment with Elasticsearch Service on Elastic Cloud. If you prefer to manage your own test environment, install and run Elasticsearch using Docker.

  1. Get a free trial.
  2. Log into Elastic Cloud.
  3. Click Create deployment.
  4. Give your deployment a name.
  5. Click Create deployment and download the password for the elastic user.
  6. Click Continue to open Kibana, the user interface for Elastic Cloud.
  7. Click Explore on my own.

Send requests to Elasticsearch

edit

You send data and other requests to Elasticsearch using REST APIs. This lets you interact with Elasticsearch using any client that sends HTTP requests, such as curl. You can also use Kibana’s Console to send requests to Elasticsearch.

Use Kibana

  1. Open Kibana’s main menu ("" near Elastic logo) and go to Dev Tools > Console.

    Kibana Console
  2. Run the following test API request in Console:

    $response = $client->info();
    response = client.info
    puts response
    res, err := es.Info()
    fmt.Println(res, err)
    const response = await client.info()
    console.log(response)
    GET /

Use curl

To communicate with Elasticsearch using curl or another client, you need your cluster’s endpoint.

  1. Open Kibana’s main menu and click Manage this deployment.
  2. From your deployment menu, go to the Elasticsearch page. Click Copy endpoint.
  3. To submit an example API request, run the following curl command in a new terminal session. Replace <password> with the password for the elastic user. Replace <elasticsearch_endpoint> with your endpoint.

    curl -u elastic:<password> <elasticsearch_endpoint>/

Add data

edit

You add data to Elasticsearch as JSON objects called documents. Elasticsearch stores these documents in searchable indices.

Add a single document

edit

Submit the following indexing request to add a single document to the books index. The request automatically creates the index.

resp = client.index(
    index="books",
    body={
        "name": "Snow Crash",
        "author": "Neal Stephenson",
        "release_date": "1992-06-01",
        "page_count": 470,
    },
)
print(resp)
response = client.index(
  index: 'books',
  body: {
    name: 'Snow Crash',
    author: 'Neal Stephenson',
    release_date: '1992-06-01',
    page_count: 470
  }
)
puts response
const response = await client.index({
  index: 'books',
  document: {
    name: 'Snow Crash',
    author: 'Neal Stephenson',
    release_date: '1992-06-01',
    page_count: 470,
  }
})
console.log(response)
POST books/_doc
{"name": "Snow Crash", "author": "Neal Stephenson", "release_date": "1992-06-01", "page_count": 470}

The response includes metadata that Elasticsearch generates for the document including a unique _id for the document within the index.

Expand to see example response
{
  "_index": "books",
  "_id": "O0lG2IsBaSa7VYx_rEia",
  "_version": 1,
  "result": "created",
  "_shards": {
    "total": 2,
    "successful": 2,
    "failed": 0
  },
  "_seq_no": 0,
  "_primary_term": 1
}

Add multiple documents

edit

Use the _bulk endpoint to add multiple documents in one request. Bulk data must be newline-delimited JSON (NDJSON). Each line must end in a newline character (\n), including the last line.

resp = client.bulk(
    body=[
        {"index": {"_index": "books"}},
        {
            "name": "Revelation Space",
            "author": "Alastair Reynolds",
            "release_date": "2000-03-15",
            "page_count": 585,
        },
        {"index": {"_index": "books"}},
        {
            "name": "1984",
            "author": "George Orwell",
            "release_date": "1985-06-01",
            "page_count": 328,
        },
        {"index": {"_index": "books"}},
        {
            "name": "Fahrenheit 451",
            "author": "Ray Bradbury",
            "release_date": "1953-10-15",
            "page_count": 227,
        },
        {"index": {"_index": "books"}},
        {
            "name": "Brave New World",
            "author": "Aldous Huxley",
            "release_date": "1932-06-01",
            "page_count": 268,
        },
        {"index": {"_index": "books"}},
        {
            "name": "The Handmaids Tale",
            "author": "Margaret Atwood",
            "release_date": "1985-06-01",
            "page_count": 311,
        },
    ],
)
print(resp)
response = client.bulk(
  body: [
    {
      index: {
        _index: 'books'
      }
    },
    {
      name: 'Revelation Space',
      author: 'Alastair Reynolds',
      release_date: '2000-03-15',
      page_count: 585
    },
    {
      index: {
        _index: 'books'
      }
    },
    {
      name: '1984',
      author: 'George Orwell',
      release_date: '1985-06-01',
      page_count: 328
    },
    {
      index: {
        _index: 'books'
      }
    },
    {
      name: 'Fahrenheit 451',
      author: 'Ray Bradbury',
      release_date: '1953-10-15',
      page_count: 227
    },
    {
      index: {
        _index: 'books'
      }
    },
    {
      name: 'Brave New World',
      author: 'Aldous Huxley',
      release_date: '1932-06-01',
      page_count: 268
    },
    {
      index: {
        _index: 'books'
      }
    },
    {
      name: 'The Handmaids Tale',
      author: 'Margaret Atwood',
      release_date: '1985-06-01',
      page_count: 311
    }
  ]
)
puts response
const response = await client.bulk({
  operations: [
    { index: { _index: 'books' } },
    {
      name: 'Revelation Space',
      author: 'Alastair Reynolds',
      release_date: '2000-03-15',
      page_count: 585,
    },
    { index: { _index: 'books' } },
    {
      name: '1984',
      author: 'George Orwell',
      release_date: '1985-06-01',
      page_count: 328,
    },
    { index: { _index: 'books' } },
    {
      name: 'Fahrenheit 451',
      author: 'Ray Bradbury',
      release_date: '1953-10-15',
      page_count: 227,
    },
    { index: { _index: 'books' } },
    {
      name: 'Brave New World',
      author: 'Aldous Huxley',
      release_date: '1932-06-01',
      page_count: 268,
    },
    { index: { _index: 'books' } },
    {
      name: 'The Handmaids Tale',
      author: 'Margaret Atwood',
      release_date: '1985-06-01',
      page_count: 311,
    }
  ]
})
console.log(response)
POST /_bulk
{ "index" : { "_index" : "books" } }
{"name": "Revelation Space", "author": "Alastair Reynolds", "release_date": "2000-03-15", "page_count": 585}
{ "index" : { "_index" : "books" } }
{"name": "1984", "author": "George Orwell", "release_date": "1985-06-01", "page_count": 328}
{ "index" : { "_index" : "books" } }
{"name": "Fahrenheit 451", "author": "Ray Bradbury", "release_date": "1953-10-15", "page_count": 227}
{ "index" : { "_index" : "books" } }
{"name": "Brave New World", "author": "Aldous Huxley", "release_date": "1932-06-01", "page_count": 268}
{ "index" : { "_index" : "books" } }
{"name": "The Handmaids Tale", "author": "Margaret Atwood", "release_date": "1985-06-01", "page_count": 311}

You should receive a response indicating there were no errors.

Expand to see example response
{
  "errors": false,
  "took": 29,
  "items": [
    {
      "index": {
        "_index": "books",
        "_id": "QklI2IsBaSa7VYx_Qkh-",
        "_version": 1,
        "result": "created",
        "_shards": {
          "total": 2,
          "successful": 2,
          "failed": 0
        },
        "_seq_no": 1,
        "_primary_term": 1,
        "status": 201
      }
    },
    {
      "index": {
        "_index": "books",
        "_id": "Q0lI2IsBaSa7VYx_Qkh-",
        "_version": 1,
        "result": "created",
        "_shards": {
          "total": 2,
          "successful": 2,
          "failed": 0
        },
        "_seq_no": 2,
        "_primary_term": 1,
        "status": 201
      }
    },
    {
      "index": {
        "_index": "books",
        "_id": "RElI2IsBaSa7VYx_Qkh-",
        "_version": 1,
        "result": "created",
        "_shards": {
          "total": 2,
          "successful": 2,
          "failed": 0
        },
        "_seq_no": 3,
        "_primary_term": 1,
        "status": 201
      }
    },
    {
      "index": {
        "_index": "books",
        "_id": "RUlI2IsBaSa7VYx_Qkh-",
        "_version": 1,
        "result": "created",
        "_shards": {
          "total": 2,
          "successful": 2,
          "failed": 0
        },
        "_seq_no": 4,
        "_primary_term": 1,
        "status": 201
      }
    },
    {
      "index": {
        "_index": "books",
        "_id": "RklI2IsBaSa7VYx_Qkh-",
        "_version": 1,
        "result": "created",
        "_shards": {
          "total": 2,
          "successful": 2,
          "failed": 0
        },
        "_seq_no": 5,
        "_primary_term": 1,
        "status": 201
      }
    }
  ]
}

Search data

edit

Indexed documents are available for search in near real-time.

Search all documents

edit

Run the following command to search the books index for all documents:

resp = client.search(
    index="books",
)
print(resp)
response = client.search(
  index: 'books'
)
puts response
const response = await client.search({
  index: 'books'
})
console.log(response)
GET books/_search

The _source of each hit contains the original JSON object submitted during indexing.

match query

edit

You can use the match query to search for documents that contain a specific value in a specific field. This is the standard query for performing full-text search, including fuzzy matching and phrase searches.

Run the following command to search the books index for documents containing brave in the name field:

resp = client.search(
    index="books",
    body={"query": {"match": {"name": "brave"}}},
)
print(resp)
response = client.search(
  index: 'books',
  body: {
    query: {
      match: {
        name: 'brave'
      }
    }
  }
)
puts response
const response = await client.search({
  index: 'books',
  query: {
    match: {
      name: 'brave'
    }
  }
})
console.log(response)
GET books/_search
{
  "query": {
    "match": {
      "name": "brave"
    }
  }
}

Next steps

edit

Now that Elasticsearch is up and running and you’ve learned the basics, you’ll probably want to test out larger datasets, or index your own data.

Learn more about search queries

edit

Add more data

edit
  • Learn how to install sample data using Kibana. This is a quick way to test out Elasticsearch on larger workloads.
  • Learn how to use the upload data UI in Kibana to add your own CSV, TSV, or JSON files.
  • Use the bulk API to ingest your own datasets to Elasticsearch.

Elasticsearch programming language clients

edit
  • Check out our client library to work with your Elasticsearch instance in your preferred programming language.
  • If you’re using Python, check out Elastic Search Labs for a range of examples that use the Elasticsearch Python client. This is the best place to explore AI-powered search use cases, such as working with embeddings, vector search, and retrieval augmented generation (RAG).