Spec-Zone.ru › Elasticsearch 8
›Руководство по Elasticsearch [8.17] ›Быстрые запуски

Индексирование и поиск данных с помощью API Elasticsearch

Это руководство по быстрому запуску — практическое введение в основные понятия Elasticsearch: индексы, документы и схемы типов полей.

Вы узнаете, как создавать индекс, добавлять данные в виде документов, работать с динамическими и явными схемами и выполнять первые базовые поиски.

Примеры кода в этом учебнике по умолчанию используют синтаксис консоли. Вы можете преобразовать их в другие языки программирования в пользовательском интерфейсе консоли.

Требования

Вам потребуется запущенный кластер Elasticsearch вместе с Kibana для использования API-консоли Dev Tools. Выполните следующую команду в своей консоли, чтобы настроить локальный кластер с одним узлом в Docker:

curl -fsSL https://elastic.co/start-local | sh

Шаг 1: Создание индекса

Создайте новый индекс с именем books:

resp = client.indices.create(
    index="books",
)
print(resp)
const response = await client.indices.create({
  index: "books",
});
console.log(response);
PUT /books

Следующий ответ указывает, что индекс был успешно создан.

Пример ответа 
{
  "acknowledged": true,
  "shards_acknowledged": true,
  "index": "books"
}

Шаг 2: Добавление данных в индекс

В этом руководстве используются API Elasticsearch, но есть и другие способы добавления данных в Elasticsearch.

Вы добавляете данные в Elasticsearch в виде JSON-объектов, называемых документами. Elasticsearch хранит эти документы в индексах, которые можно искать.

Добавление одного документа

Отправьте следующий запрос индексирования, чтобы добавить один документ в индекс books.

Если индекс еще не существовал, этот запрос автоматически создаст его.

resp = client.index(
    index="books",
    document={
        "name": "Snow Crash",
        "author": "Neal Stephenson",
        "release_date": "1992-06-01",
        "page_count": 470
    },
)
print(resp)
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
}

Ответ включает метаданные, сгенерированные Elasticsearch для документа, включая уникальный _id для документа в индексе.

Пример ответа 
{
  "_index": "books", 
  "_id": "O0lG2IsBaSa7VYx_rEia", 
  "_version": 1, 
  "result": "created", 
  "_shards": { 
    "total": 2, 
    "successful": 2, 
    "failed": 0 
  },
  "_seq_no": 0, 
  "_primary_term": 1 
}

Поле _index указывает индекс, в который был добавлен документ.

Поле _id является уникальным идентификатором документа.

Поле _version указывает версию документа.

Поле result указывает результат операции индексирования.

Поле _shards содержит информацию о количестве фрагментов, на которых была выполнена операция индексирования, и количестве успешных операций.

Поле total указывает общее количество фрагментов для индекса.

Поле successful указывает количество фрагментов, на которых была выполнена операция индексирования.

Поле failed указывает количество фрагментов, которые завершились ошибкой во время операции индексирования. 0 указывает отсутствие ошибок.

Поле _seq_no содержит монотонно возрастающее число, увеличивающееся при каждой операции индексирования на фрагменте.

Поле _primary_term — это монотонно возрастающее число, увеличивающееся каждый раз, когда первичный фрагмент назначается другому узлу.

Добавление нескольких документов

Используйте _bulk конечную точку, чтобы добавить несколько документов в одном запросе. Данные для массовой обработки должны быть отформатированы как 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}

Вы должны получить ответ, указывающий, что ошибок не было.

Пример ответа 
{
  "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
      }
    }
  ]
}

Шаг 3: Определение схем и типов данных

Схемы определяют, как данные хранятся и индексируются в Elasticsearch, как схема в реляционной базе данных.

Использование динамической схемы

При использовании динамической схемы Elasticsearch по умолчанию автоматически создает схемы для новых полей. Документы, которые мы добавили до сих пор, использовали динамическую схему, потому что мы не указывали схему при создании индекса.

Чтобы увидеть, как работает динамическая схема, добавьте новый документ в индекс books с полем, которое не отображается в существующих документах.

resp = client.index(
    index="books",
    document={
        "name": "The Great Gatsby",
        "author": "F. Scott Fitzgerald",
        "release_date": "1925-04-10",
        "page_count": 180,
        "language": "EN"
    },
)
print(resp)
const response = await client.index({
  index: "books",
  document: {
    name: "The Great Gatsby",
    author: "F. Scott Fitzgerald",
    release_date: "1925-04-10",
    page_count: 180,
    language: "EN",
  },
});
console.log(response);
POST /books/_doc
{
  "name": "The Great Gatsby",
  "author": "F. Scott Fitzgerald",
  "release_date": "1925-04-10",
  "page_count": 180,
  "language": "EN" 
}

Новое поле.

Просмотрите схему индекса books с помощью API получения схемы. Новое поле language было добавлено в схему с типом данных text.

resp = client.indices.get_mapping(
    index="books",
)
print(resp)
const response = await client.indices.getMapping({
  index: "books",
});
console.log(response);
GET /books/_mapping
Пример ответа 
{
  "books": {
    "mappings": {
      "properties": {
        "author": {
          "type": "text",
          "fields": {
            "keyword": {
              "type": "keyword",
              "ignore_above": 256
            }
          }
        },
        "name": {
          "type": "text",
          "fields": {
            "keyword": {
              "type": "keyword",
              "ignore_above": 256
            }
          }
        },
        "language": {
          "type": "text",
          "fields": {
            "keyword": {
              "type": "keyword",
              "ignore_above": 256
            }
          }
        },
        "page_count": {
          "type": "long"
        },
        "release_date": {
          "type": "date"
        }
      }
    }
  }
}

Определение явной схемы

Создайте индекс с именем my-explicit-mappings-books с явной схемой. Передайте свойства каждого поля в виде JSON-объекта. Этот объект должен содержать тип данных поля и любые дополнительные параметры схемы.

resp = client.indices.create(
    index="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"
            }
        }
    },
)
print(resp)
const response = await client.indices.create({
  index: "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",
      },
    },
  },
});
console.log(response);
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" }
    }
  }
}

Отключает динамическую схему для индекса. Документы, содержащие поля, не определенные в схеме, будут отклонены.

Объект properties определяет поля и их типы данных для документов в этом индексе.
Пример ответа 
{
  "acknowledged": true,
  "shards_acknowledged": true,
  "index": "my-explicit-mappings-books"
}

Комбинирование динамической и явной схем

Явные схемы определяются при создании индекса, и документы должны соответствовать этим схемам. Вы также можете использовать API обновления схемы. Когда для индекса установлен флаг dynamic со значением true, вы можете добавлять новые поля в документы без обновления схемы.

Это позволяет объединить явную и динамическую схемы. Узнайте больше о управлении и обновлении схемами.

Шаг 4: Поиск в индексе

Индексированные документы доступны для поиска в режиме реального времени с использованием _search API.

Поиск всех документов

Выполните следующую команду, чтобы выполнить поиск во всех документах индекса books:

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
Пример ответа 
{
  "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)
    ]
  }
}

Поле took указывает время в миллисекундах, затраченное Elasticsearch на выполнение поиска.

Поле timed_out указывает, произошла ли ошибка таймаута поиска.

Поле _shards содержит информацию о количестве фрагментов, на которых был выполнен поиск, и количестве успешных фрагментов.

Объект hits содержит результаты поиска.

Объект total предоставляет информацию о общем количестве совпадающих документов.

Поле max_score указывает наибольший релевантный балл среди всех совпадающих документов.

Поле _index указывает индекс, которому принадлежит документ.

Поле _id — уникальный идентификатор документа.

Поле _score указывает релевантный балл документа.

Поле _source содержит исходный JSON-объект, переданный во время индексирования.

match запрос

Вы можете использовать match запрос, чтобы искать документы, содержащие определённое значение в определённом поле. Это стандартный запрос для полнотекстовых поисков.

Выполните следующую команду, чтобы найти документы в индексе books, содержащие brave в поле name:

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"
    }
  }
}
Пример ответа 
{
  "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
        }
      }
    ]
  }
}

max_score — это рейтинг самого высокорейтингового документа в результатах. В данном случае, есть только один соответствующий документ, поэтому max_score — это рейтинг этого документа.

Шаг 5: Удаление индексов (необязательно)

При работе с примерами, возможно, вам потребуется удалить индекс, чтобы начать с нуля. Вы можете удалить индексы с помощью API удаления индекса.

Например, выполните следующую команду, чтобы удалить индексы, созданные в этом руководстве:

resp = client.indices.delete(
    index="books",
)
print(resp)

resp1 = client.indices.delete(
    index="my-explicit-mappings-books",
)
print(resp1)
const response = await client.indices.delete({
  index: "books",
});
console.log(response);

const response1 = await client.indices.delete({
  index: "my-explicit-mappings-books",
});
console.log(response1);
DELETE /books
DELETE /my-explicit-mappings-books

Удаление индекса навсегда удаляет его документы, фрагменты и метаданные.

© 2023-2025 Elasticsearch
As of September 2024, Elasticsearch is available under a choice of three licenses: the Server Side Public License (SSPL), the Elastic License, or the AGPLv3 (OSI approved).
Elasticsearch and the Elasticsearch logo are trademarks of Elasticsearch B.V., registered in the U.S. and in other countries.
https://www.elastic.co/guide/en/elasticsearch/reference/8.17/getting-started.html

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API