Spec-Zone.ru › Elasticsearch 7
›Руководство по Elasticsearch [7.17] ›REST API ›API поиска

API поиска векторных тайлов

Ищет геопространственные значения в векторном тайле. Возвращает результаты в виде двоичного векторного тайла Mapbox.

GET my-index/_mvt/my-geo-field/15/5271/12710

Запрос

GET <target>/_mvt/<field>/<zoom>/<x>/<y>

POST <target>/_mvt/<field>/<zoom>/<x>/<y>

Предварительные условия

  • Перед использованием этого API необходимо ознакомиться со спецификацией векторных тайлов Mapbox.
  • Если в Elasticsearch включены функции безопасности, у вас должна быть read право доступа к индексу для целевого потока данных, индекса или псевдонима. Для межкластерного поиска см. Межкластерный поиск и безопасность.

Параметры пути

<target>

(Обязательно, строка) Список потоков данных, индексов или псевдонимов, которые нужно искать, разделенных запятыми. Поддерживаются подстановки (*). Для поиска во всех потоках данных и индексах опустите этот параметр или используйте * или _all.

Для поиска в удаленном кластере используйте синтаксис <cluster>:<target>. См. Поиск по нескольким кластерам.

<field>

(Обязательно, строка) Поле, содержащее геопространственные значения для возврата. Должно быть полем типа geo_point или geo_shape. Поле должно иметь включенные doc values. Не может быть вложенным полем.

Векторные тайлы не поддерживают наборы геометрий. Для значений geometrycollection в поле geo_shape API возвращает черту слоя hits для каждого элемента набора. Это поведение может быть изменено в будущих выпусках.

<zoom>
(Обязательно, целое число) Уровень масштабирования векторного тайла для поиска. Принимает значения от 0 до 29.
<x>
(Обязательно, целое число) Координата X для поиска в векторном тайле.
<y>
(Обязательно, целое число) Координата Y для поиска в векторном тайле.

Описание

Внутренне API поиска векторных тайлов преобразует запрос в запрос поиска, содержащий:

  • Запрос geo_bounding_box по полю <field>. Запрос использует тайл <zoom>/<x>/<y> в качестве прямоугольника.
  • Агрегацию geotile_grid по полю <field>. Агрегация использует тайл <zoom>/<x>/<y> в качестве прямоугольника.
  • Дополнительно, агрегацию geo_bounds по полю <field>. Поиск включает эту агрегацию, только если параметр exact_bounds имеет значение true.

Например, запрос API поиска векторных тайлов с аргументом exact_bounds со значением true может быть преобразован в следующий запрос:

GET my-index/_search
{
  "size": 10000,
  "query": {
    "geo_bounding_box": {
      "my-geo-field": {
        "top_left": {
          "lat": -40.979898069620134,
          "lon": -45
        },
        "bottom_right": {
          "lat": -66.51326044311186,
          "lon": 0
        }
      }
    }
  },
  "aggregations": {
    "grid": {
      "geotile_grid": {
        "field": "my-geo-field",
        "precision": 11,
        "size": 65536,
        "bounds": {
          "top_left": {
            "lat": -40.979898069620134,
            "lon": -45
          },
          "bottom_right": {
            "lat": -66.51326044311186,
            "lon": 0
          }
        }
      }
    },
    "bounds": {
      "geo_bounds": {
        "field": "my-geo-field",
        "wrap_longitude": false
      }
    }
  }
}

API возвращает результаты в виде двоичного векторного тайла Mapbox. Векторные тайлы Mapbox закодированы с использованием Google Protobufs (PBF). По умолчанию тайл содержит три слоя:

  • Слой hits, содержащий черту для каждого значения <field>, соответствующего запросу geo_bounding_box.
  • Слой aggs, содержащий черту для каждой ячейки сетки geotile_grid. Эти ячейки могут использоваться как тайлы для уровней меньшего масштабирования. Слой содержит черты только для ячеек с соответствующими данными.

  • Слой meta, содержащий:

    • Черту, содержащую прямоугольник. По умолчанию это прямоугольник тайла.
    • Диапазоны значений для любых вложенных агрегаций по полю geotile_grid.
    • Метаданные для поиска.

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

API возвращает ошибки в формате UTF-8 закодированного JSON.

Параметры запроса

Несколько параметров API можно указать в качестве параметров запроса или тела запроса. Если оба параметра указаны, приоритет имеет параметр запроса.

exact_bounds

(Необязательно, булево) Если false, черта слоя meta представляет собой прямоугольник тайла. По умолчанию false.

Если true, черта слоя meta представляет собой прямоугольник, полученный из агрегации geo_bounds. Агрегация выполняется на значениях <field>, которые пересекают тайл <zoom>/<x>/<y> с wrap_longitude установленным в false. Результирующий прямоугольник может быть больше, чем векторный тайл.

extent
(Необязательно, целое число) Размер стороны тайла в пикселях. Векторные тайлы являются квадратными с равными сторонами. По умолчанию 4096.
grid_precision

(Необязательно, целое число) Дополнительные уровни масштабирования, доступные через слой aggs. Например, если <zoom> равно 7, и grid_precision равно 8, можно увеличить масштаб до уровня 15. Принимает значения от 0 до 8. По умолчанию 8. Если 0, результаты не включают слой aggs.

Это значение определяет размер сетки для слоя geotile_grid следующим образом:

(2^grid_precision) x (2^grid_precision)

Например, значение 8 разделяет тайл на сетку 256x256 ячеек. Слой aggs содержит черты только для ячеек с соответствующими данными.

grid_type

(Необязательно, строка) Определяет тип геометрии для черт в слое aggs. В слое aggs каждая черта представляет собой geotile_grid ячейку. Принимает значения:

grid (По умолчанию)
Каждая черта представляет собой Polygon прямоугольника ячейки.
point
Каждая черта представляет собой Point, являющуюся центром ячейки.
centroid
Каждая черта представляет собой Point, являющуюся центром данных в ячейке. Для сложных геометрий фактический центр может находиться вне ячейки. В таких случаях черта устанавливается на ближайшую точку к центру внутри ячейки.
size
(Необязательно, целое число) Максимальное количество черт, возвращаемых в слое hits. Принимает значения от 0 до 10000. По умолчанию 10000. Если 0, результаты не включают слой hits.
track_total_hits

(Необязательно, целое число или булево) Количество совпадений запроса для точного подсчёта. По умолчанию 10000.

Если true, точное количество совпадений возвращается с некоторым снижением производительности. Если false, ответ не содержит общего количества совпадений по запросу.

Тело запроса

aggs

(Необязательно, объект агрегации) Под-агрегации для geotile_grid. Поддерживает следующие типы агрегаций:

  • avg
  • boxplot
  • cardinality
  • extended stats
  • max
  • median absolute deviation
  • min
  • percentile
  • percentile-rank
  • stats
  • sum

  • value count

    Имена агрегаций не могут начинаться с _mvt_. Префикс _mvt_ зарезервирован для внутренних агрегаций.

exact_bounds

(Необязательно, Булево) Если false, то признак слоя meta представляет собой ограничивающую рамку тайла. По умолчанию false.

Если true, то признак слоя meta представляет собой ограничивающую рамку, полученную из агрегации geo_bounds. Агрегация выполняется над значениями <field>, которые пересекают тайл <zoom>/<x>/<y> с wrap_longitude, установленным в false. Результирующая ограничивающая рамка может быть больше, чем векторный тайл.

extent
(Необязательно, целое число) Размер стороны тайла в пикселях. Векторные тайлы квадратные с равными сторонами. По умолчанию 4096.
fields

(Необязательно, массив строк и объектов) Поля, которые нужно вернуть в слое hits. Поддерживает подстановку значений (*).

Этот параметр не поддерживает поля со значениями типа массивов. Поля со значениями типа массив могут возвращать несогласованные результаты.

Вы можете указать поля в массиве как строку или объект.

Свойства объектов fields
field
(Обязательно, строка) Поле для возврата. Поддерживает подстановку значений (*).
format

(Необязательно, строка) Формат для полей дат и геопространственных данных. Другие типы данных полей не поддерживают этот параметр.

date и date_nanos поля принимают формат даты. geo_point и geo_shape поля принимают:

geojson (по умолчанию)
GeoJSON
wkt
Well Known Text
mvt(<zoom>/<x>/<y>@<extent>) или mvt(<zoom>/<x>/<y>)

Бинарный векторный тайл Mapbox. API возвращает тайл в формате base64.

Параметры mvt
<zoom>
(Обязательно, целое число) Уровень масштабирования тайла. Принимает значения от 0 до 29.
<x>
(Обязательно, целое число) Координата X тайла.
<y>
(Обязательно, целое число) Координата Y тайла.
<extent>
(Необязательно, целое число) Размер стороны тайла в пикселях. Векторные тайлы квадратные с равными сторонами. По умолчанию 4096.
grid_precision

(Необязательно, целое число) Дополнительные уровни масштабирования, доступные через слой aggs. Например, если <zoom> равно 7, а grid_precision равно 8, вы можете масштабировать до уровня 15. Принимает значения от 0 до 8. По умолчанию 8. Если 0, результаты не включают слой aggs.

Это значение определяет размер сетки geotile_grid следующим образом:

(2^grid_precision) x (2^grid_precision)

Например, значение 8 делит тайл на сетку 256x256 ячеек. Слой aggs содержит только объекты для ячеек с соответствующими данными.

grid_type

(Необязательно, строка) Определяет тип геометрии объектов в слое aggs. В слое aggs каждый объект представляет собой ячейку geotile_grid сетки. Принимает значения:

grid (По умолчанию)
Каждый объект представляет собой ограничивающую рамку ячейки.
point
Каждый объект представляет собой центр ячейки.
centroid
Каждый объект представляет собой центр данных в ячейке. Для сложных геометрий фактический центр может находиться за пределами ячейки. В этих случаях объект устанавливается в самую близкую точку к центру внутри ячейки.
query
(Необязательно, объект) Язык запросов, используемый для фильтрации документов для поиска.
runtime_mappings

(Необязательно, объект объектов) Определяет один или несколько полей во время выполнения в запросе поиска. Эти поля имеют приоритет над сопоставленными полями с одинаковым именем.

Свойства объектов runtime_mappings
<field-name>

(Обязательно, объект) Настройка для поля во время выполнения. Ключом является имя поля.

Свойства <field-name>
type

(Обязательно, строка) Тип поля, который может быть любым из следующих:

  • boolean
  • composite
  • date
  • double
  • geo_point
  • ip
  • keyword
  • long
script

(Необязательно, строка) Скрипт Painless, выполняемый во время запроса. Скрипт имеет доступ ко всему контексту документа, включая исходный _source и любые сопоставленные поля вместе с их значениями.

Этот скрипт должен содержать emit, чтобы возвращать вычисленные значения. Например:

"script": "emit(doc['@timestamp'].value.dayOfWeekEnum.toString())"
size
(Необязательно, целое число) Максимальное количество объектов для возврата в слое hits. Принимает значения от 0 до 10000. По умолчанию 10000. Если 0, результаты не включают слой hits.
sort

(Необязательно, массив объектов сортировки) Сортирует объекты в слое hits.

По умолчанию API вычисляет ограничивающую рамку для каждого объекта. Он сортирует объекты по диагонали этой рамки, от большей к меньшей.

track_total_hits

(Необязательно, целое число или логическое значение) Количество совпадений с запросом для точного подсчёта. По умолчанию установлено значение 10000.

Если true, то возвращается точное количество совпадений за счёт некоторого снижения производительности. Если false, ответ не включает общее количество совпадений с запросом.

Ответ

Возвращаемые векторные тайлы содержат следующие данные:

hits

(объект) Слой, содержащий результаты для запроса geo_bounding_box.

Свойства hits
extent
(целое число) Размер стороны тайла в пикселях. Векторные тайлы являются квадратными с равными сторонами.
version
(целое число) Основной номер версии спецификации векторных тайлов Mapbox Mapbox vector tile specification.
features

(массив объектов) Массив объектов. Содержит объект для каждого <field> значения, соответствующего запросу geo_bounding_box.

Свойства объектов features
geometry

(объект) Геометрия объекта.

Свойства geometry
type

(строка) Тип геометрии объекта. Допустимые значения:

  • UNKNOWN
  • POINT
  • LINESTRING
  • POLYGON
coordinates
(массив целых чисел или массив массивов) Координаты тайла для объекта.
properties

(объект) Свойства объекта.

Свойства properties
_id
(строка) _id документа для документа объекта.
_index
(строка) Название индекса для документа объекта.
<field>
Значение поля. Возвращается только для полей в параметре fields.
type

(целое число) Идентификатор типа геометрии объекта. Значения:

  • 1 (POINT)
  • 2 (LINESTRING)
  • 3 (POLYGON)
aggs

(объект) Слой, содержащий результаты агрегации geotile_grid и её под-агрегаций.

Свойства aggs
extent
(целое число) Размер стороны тайла в пикселях. Векторные тайлы являются квадратными с равными сторонами.
version
(целое число) Основной номер версии спецификации векторных тайлов Mapbox Mapbox vector tile specification.
features

(массив объектов) Массив объектов. Содержит объект для каждой ячейки geotile_grid.

Свойства объектов features
geometry

(объект) Геометрия объекта.

Свойства geometry
type

(строка) Тип геометрии объекта. Допустимые значения:

  • UNKNOWN
  • POINT
  • LINESTRING
  • POLYGON
coordinates
(массив целых чисел или массив массивов) Координаты тайла для объекта.
properties

(объект) Свойства объекта.

Свойства properties
_count
(длинное целое число) Количество документов ячейки.
_key
(строка) Ключ корзины ячейки в формате <zoom>/<x>/<y>.
<sub-aggregation>.value
Результаты под-агрегаций для ячейки. Возвращаются только для под-агрегаций в параметре aggs.
type

(целое число) Идентификатор типа геометрии объекта. Значения:

  • 1 (POINT)
  • 2 (LINESTRING)
  • 3 (POLYGON)
meta

(объект) Слой, содержащий метаданные запроса.

Свойства meta
extent
(целое число) Размер стороны тайла в пикселях. Векторные тайлы квадратные с равными сторонами.
version
(целое число) Основной номер версии спецификации векторного тайла Mapbox.
features

(массив объектов) Содержит привязку к прямоугольнику.

Свойства объектов features
geometry

(объект) Геометрия объекта.

Свойства geometry
type

(строка) Тип геометрии объекта. Допустимые значения:

  • UNKNOWN
  • POINT
  • LINESTRING
  • POLYGON
coordinates
(массив целых чисел или массив массивов) Координаты тайла для объекта.
properties

(объект) Свойства объекта.

Свойства properties
_shards.failed
(целое число) Количество фрагментов, которые не выполнили поиск. См. свойство ответа API поиска shards.
_shards.skipped
(целое число) Количество фрагментов, которые пропустили поиск. См. свойство ответа API поиска shards.
_shards.successful
(целое число) Количество фрагментов, которые успешно выполнили поиск. См. свойство ответа API поиска shards.
_shards.total
(целое число) Общее количество фрагментов, требующих запроса, включая невыделенные фрагменты. См. свойство ответа API поиска shards.
aggregations._count.avg
(вещественное число) Среднее значение _count для объектов в слое aggs.
aggregations._count.count
(целое число) Количество уникальных значений _count для объектов в слое aggs.
aggregations._count.max
(вещественное число) Наибольшее значение _count для объектов в слое aggs.
aggregations._count.min
(вещественное число) Наименьшее значение _count для объектов в слое aggs.
aggregations._count.sum
(вещественное число) Сумма значений _count для объектов в слое aggs.
aggregations.<sub-aggregation>.avg
(вещественное число) Среднее значение результатов под-агрегации.
aggregations.<agg_name>.count
(целое число) Количество уникальных значений из результатов под-агрегации.
aggregations.<agg_name>.max
(вещественное число) Наибольшее значение из результатов под-агрегации.
aggregations.<agg_name>.min
(вещественное число) Наименьшее значение из результатов под-агрегации.
aggregations.<agg_name>.sum
(вещественное число) Сумма значений результатов под-агрегации.
hits.max_score
(вещественное число) Максимальный документ _score для результатов поиска.
hits.total.relation

(строка) Указывает, является ли hits.total.value точным или нижней границей. Возможные значения:

eq
Точное значение
gte
Нижняя граница
hits.total.value
(целое число) Общее количество результатов поиска.
timed_out
(Булево) Если true, поиск завершился с таймаутом. Результаты могут быть частичными или пустыми.
took
(целое число) Время, затраченное Elasticsearch на выполнение поиска в миллисекундах. См. свойство ответа API поиска took.
type

(целое число) Идентификатор типа геометрии объекта. Возможные значения:

  • 1 (POINT)
  • 2 (LINESTRING)
  • 3 (POLYGON)

Примеры

Следующие запросы создают индекс museum и добавляют несколько геопространственных значений location.

PUT museums
{
  "mappings": {
    "properties": {
      "location": {
        "type": "geo_point"
      },
      "name": {
        "type": "keyword"
      },
      "price": {
        "type": "long"
      },
      "included": {
        "type": "boolean"
      }
    }
  }
}

POST museums/_bulk?refresh
{ "index": { "_id": "1" } }
{ "location": "52.374081,4.912350", "name": "NEMO Science Museum",  "price": 1750, "included": true }
{ "index": { "_id": "2" } }
{ "location": "52.369219,4.901618", "name": "Museum Het Rembrandthuis", "price": 1500, "included": false }
{ "index": { "_id": "3" } }
{ "location": "52.371667,4.914722", "name": "Nederlands Scheepvaartmuseum", "price":1650, "included": true }
{ "index": { "_id": "4" } }
{ "location": "52.371667,4.914722", "name": "Amsterdam Centre for Architecture", "price":0, "included": true }

Следующий запрос ищет в индексе значения location, которые пересекают векторный тайл 13/4207/2692.

GET museums/_mvt/location/13/4207/2692
{
  "grid_precision": 2,
  "fields": [
    "name",
    "price"
  ],
  "query": {
    "term": {
      "included": true
    }
  },
  "aggs": {
    "min_price": {
      "min": {
        "field": "price"
      }
    },
    "max_price": {
      "max": {
        "field": "price"
      }
    },
    "avg_price": {
      "avg": {
        "field": "price"
      }
    }
  }
}

API возвращает результаты в виде двоичного векторного тайла. При декодировании в JSON тайл содержит следующие данные:

{
  "hits": {
    "extent": 4096,
    "version": 2,
    "features": [
      {
        "geometry": {
          "type": "Point",
          "coordinates": [
            3208,
            3864
          ]
        },
        "properties": {
          "_id": "1",
          "_index": "museums",
          "name": "NEMO Science Museum",
          "price": 1750
        },
        "type": 1
      },
      {
        "geometry": {
          "type": "Point",
          "coordinates": [
            3429,
            3496
          ]
        },
        "properties": {
          "_id": "3",
          "_index": "museums",
          "name": "Nederlands Scheepvaartmuseum",
          "price": 1650
        },
        "type": 1
      },
      {
        "geometry": {
          "type": "Point",
          "coordinates": [
            3429,
            3496
          ]
        },
        "properties": {
          "_id": "4",
          "_index": "museums",
          "name": "Amsterdam Centre for Architecture",
          "price": 0
        },
        "type": 1
      }
    ]
  },
  "aggs": {
    "extent": 4096,
    "version": 2,
    "features": [
      {
        "geometry": {
          "type": "Polygon",
          "coordinates": [
            [
              [
                3072,
                3072
              ],
              [
                4096,
                3072
              ],
              [
                4096,
                4096
              ],
              [
                3072,
                4096
              ],
              [
                3072,
                3072
              ]
            ]
          ]
        },
        "properties": {
          "_count": 3,
          "max_price.value": 1750.0,
          "min_price.value": 0.0,
          "avg_price.value": 1133.3333333333333
        },
        "type": 3
      }
    ]
  },
  "meta": {
    "extent": 4096,
    "version": 2,
    "features": [
      {
        "geometry": {
          "type": "Polygon",
          "coordinates": [
            [
              [
                0,
                0
              ],
              [
                4096,
                0
              ],
              [
                4096,
                4096
              ],
              [
                0,
                4096
              ],
              [
                0,
                0
              ]
            ]
          ]
        },
        "properties": {
          "_shards.failed": 0,
          "_shards.skipped": 0,
          "_shards.successful": 1,
          "_shards.total": 1,
          "aggregations._count.avg": 3.0,
          "aggregations._count.count": 1,
          "aggregations._count.max": 3.0,
          "aggregations._count.min": 3.0,
          "aggregations._count.sum": 3.0,
          "aggregations.avg_price.avg": 1133.3333333333333,
          "aggregations.avg_price.count": 1,
          "aggregations.avg_price.max": 1133.3333333333333,
          "aggregations.avg_price.min": 1133.3333333333333,
          "aggregations.avg_price.sum": 1133.3333333333333,
          "aggregations.max_price.avg": 1750.0,
          "aggregations.max_price.count": 1,
          "aggregations.max_price.max": 1750.0,
          "aggregations.max_price.min": 1750.0,
          "aggregations.max_price.sum": 1750.0,
          "aggregations.min_price.avg": 0.0,
          "aggregations.min_price.count": 1,
          "aggregations.min_price.max": 0.0,
          "aggregations.min_price.min": 0.0,
          "aggregations.min_price.sum": 0.0,
          "hits.max_score": 0.0,
          "hits.total.relation": "eq",
          "hits.total.value": 3,
          "timed_out": false,
          "took": 2
        },
        "type": 3
      }
    ]
  }
}

© 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/7.17/search-vector-tile-api.html

END_OF_DOCUMENT_MARKER

Spec-Zone.ru

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