Index and search data using Elasticsearch APIs
editIndex and search data using Elasticsearch APIs
editThis quick start guide is a hands-on introduction to the fundamental concepts of Elasticsearch: indices, documents and field type mappings.
You’ll learn how to create an index, add data as documents, work with dynamic and explicit mappings, and perform your first basic searches.
The code examples in this tutorial are in Console syntax by default.
Prerequisites
editBefore you begin, you need to have a running Elasticsearch cluster. The fastest way to get started is with a local development environment. Refer to Run Elasticsearch for other deployment options.
Step 1: Create an index
editCreate a new index named books
:
PUT /books
The following response indicates the index was created successfully.
Step 2: Add data to your index
editThis tutorial uses Elasticsearch APIs, but there are many other ways to add data to Elasticsearch.
You add data to Elasticsearch as JSON objects called documents. Elasticsearch stores these documents in searchable indices.
Add a single document
editSubmit the following indexing request to add a single document to the
books
index.
If the index didn’t already exist, this request would automatically create it.
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.
Example response
{ "_index": "books", "_id": "O0lG2IsBaSa7VYx_rEia", "_version": 1, "result": "created", "_shards": { "total": 2, "successful": 2, "failed": 0 }, "_seq_no": 0, "_primary_term": 1 }
The |
|
The |
|
The |
|
The |
|
The |
|
The |
|
The |
|
The |
|
The |
|
The |
Add multiple documents
editUse the _bulk
endpoint to add multiple documents in one request. Bulk data
must be formatted as newline-delimited JSON (NDJSON).
resp = 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 } ], ) 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.
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 } } ] }
Step 3: Define mappings and data types
editMappings define how data is stored and indexed in Elasticsearch, like a schema in a relational database.
Use dynamic mapping
editWhen using dynamic mapping, Elasticsearch automatically creates mappings for new fields by default. The documents we’ve added so far have used dynamic mapping, because we didn’t specify a mapping when creating the index.
To see how dynamic mapping works, add a new document to the books
index with a field that doesn’t appear in the existing documents.
POST /books/_doc { "name": "The Great Gatsby", "author": "F. Scott Fitzgerald", "release_date": "1925-04-10", "page_count": 180, "language": "EN" }
View the mapping for the books
index with the Get mapping API. The new field new_field
has been added to the mapping with a text
data type.
GET /books/_mapping
Example response
{ "books": { "mappings": { "properties": { "author": { "type": "text", "fields": { "keyword": { "type": "keyword", "ignore_above": 256 } } }, "name": { "type": "text", "fields": { "keyword": { "type": "keyword", "ignore_above": 256 } } }, "new_field": { "type": "text", "fields": { "keyword": { "type": "keyword", "ignore_above": 256 } } }, "page_count": { "type": "long" }, "release_date": { "type": "date" } } } } }
Define explicit mapping
editCreate an index named my-explicit-mappings-books
with explicit mappings.
Pass each field’s properties as a JSON object. This object should contain the field data type and any additional mapping parameters.
PUT /my-explicit-mappings-books { "mappings": { "dynamic": false, "properties": { "name": { "type": "text" }, "author": { "type": "text" }, "release_date": { "type": "date", "format": "yyyy-MM-dd" }, "page_count": { "type": "integer" } } } }
Disables dynamic mapping for the index. Documents containing fields not defined in the mapping will be rejected. |
|
The |
Example response
Combine dynamic and explicit mappings
editExplicit mappings are defined at index creation, and documents must conform to these mappings.
You can also use the Update mapping API.
When an index has the dynamic
flag set to true
, you can add new fields to documents without updating the mapping.
This allows you to combine explicit and dynamic mappings. Learn more about managing and updating mappings.
Step 4: Search your index
editIndexed documents are available for search in near real-time, using the _search
API.
Search all documents
editRun 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
Example response
{ "took": 2, "timed_out": false, "_shards": { "total": 5, "successful": 5, "skipped": 0, "failed": 0 }, "hits": { "total": { "value": 7, "relation": "eq" }, "max_score": 1, "hits": [ { "_index": "books", "_id": "CwICQpIBO6vvGGiC_3Ls", "_score": 1, "_source": { "name": "Brave New World", "author": "Aldous Huxley", "release_date": "1932-06-01", "page_count": 268 } }, ... (truncated) ] } }
The |
|
The |
|
The |
|
The |
|
The |
|
The |
|
The |
|
The |
|
The |
|
The |
match
query
editYou can use the match
query to search for documents that contain a specific value in a specific field.
This is the standard query for full-text searches.
Run the following command to search the books
index for documents containing brave
in the name
field:
resp = client.search( index="books", 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" } } }
Example response
{ "took": 9, "timed_out": false, "_shards": { "total": 5, "successful": 5, "skipped": 0, "failed": 0 }, "hits": { "total": { "value": 1, "relation": "eq" }, "max_score": 0.6931471, "hits": [ { "_index": "books", "_id": "CwICQpIBO6vvGGiC_3Ls", "_score": 0.6931471, "_source": { "name": "Brave New World", "author": "Aldous Huxley", "release_date": "1932-06-01", "page_count": 268 } } ] } }
Step 5: Delete your indices (optional)
editWhen following along with examples, you might want to delete an index to start from scratch. You can delete indices using the Delete index API.
For example, run the following command to delete the indices created in this tutorial:
DELETE /books DELETE /my-explicit-mappings-books
Deleting an index permanently deletes its documents, shards, and metadata.