› › ›

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

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

resp = client.search_mvt(
    index="my-index",
    field="my-geo-field",
    zoom="15",
    x="5271",
    y="12710",
)
print(resp)

const response = await client.searchMvt({
  index: "my-index",
  field: "my-geo-field",
  zoom: 15,
  x: 5271,
  y: 12710,
});
console.log(response);

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>

(Обязательно, целое число) Уровень детализации (zoom level) векторного тайла для поиска. Принимает значения от 0 до 29.

<x>

(Обязательно, целое число) Координата X для векторного тайла для поиска.

<y>

(Обязательно, целое число) Координата Y для векторного тайла для поиска.

Описание

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

Запрос geo_bounding_box по полю <field>. Запрос использует тайл <zoom>/<x>/<y> в качестве прямоугольника.
Агрегацию geotile_grid или geohex_grid по полю <field>. Параметр grid_agg определяет тип агрегации. Агрегация использует тайл <zoom>/<x>/<y> в качестве прямоугольника.
Необязательно, агрегацию geo_bounds по полю <field>. Поиск включает эту агрегацию только если параметр exact_bounds равен true.
Если необязательный параметр with_labels имеет значение true, внутренний поиск включает динамическое поле runtime, которое вызывает функцию getLabelPosition значения геометрии doc value. Это позволяет генерировать новые точки с предполагаемыми метками геометрии, так что, например, многоугольники будут иметь только одну метку.

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

resp = client.search(
    index="my-index",
    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
            }
        }
    },
)
print(resp)

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

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 или geohex_grid. Слой содержит только элементы для ячеек с соответствующими данными.
Слой meta, содержащий:
- Элемент, содержащий прямоугольник. По умолчанию это прямоугольник тайла.
- Диапазоны значений для любых вложенных агрегаций по geotile_grid или geohex_grid.
- Метаданные для поиска.

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

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

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

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

exact_bounds

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

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

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

buffer: (Необязательно, целое число) Размер буфера обрезки в пикселях за пределами тайла. Это позволяет избежать артефактов контура геометрий, выходящих за пределы тайла. По умолчанию 5.

grid_agg

(Необязательно, строка) Агрегация, используемая для создания сетки для <field>.

Допустимые значения для grid_agg

geotile (По умолчанию): geotile_grid агрегация.
geohex: geohex_grid агрегация.

grid_precision

(Необязательно, целое число) Уровень точности для ячеек в grid_agg. Принимает значения от 0 до 8. По умолчанию используется 8. Если 0, результаты не включают слой aggs.

Точность сетки для geotile

Для grid_agg geotile вы можете использовать ячейки в слое aggs в качестве плиток для меньших уровней масштабирования. grid_precision представляет дополнительные уровни масштабирования, доступные через эти ячейки. Конечная точность вычисляется следующим образом:

<zoom> + grid_precision

Например, если <zoom> равно 7, а grid_precision равно 8, то агрегация geotile_grid будет использовать точность 15. Максимальная конечная точность равна 29.

grid_precision также определяет количество ячеек для сетки следующим образом:

(2^grid_precision) x (2^grid_precision)

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

Точность сетки для geohex

Для grid_agg geohex Elasticsearch использует <zoom> и grid_precision для вычисления конечной точности следующим образом:

<zoom> + grid_precision

Эта точность определяет разрешение H3 шестиугольных ячеек, создаваемых агрегацией geohex. В следующей таблице показано соответствие разрешения H3 для каждой точности.

Например, если <zoom> равно 3, а grid_precision равно 3, точность равна 6. При точности 6 шестиугольные ячейки имеют разрешение H3 2. Если <zoom> равно 3, а grid_precision равно 4, точность равна 7. При точности 7 шестиугольные ячейки имеют разрешение H3 3.

Точность	Уникальные ячейки плитки	Разрешение H3	Уникальные шестиугольные ячейки	Соотношение
1	4	0	122	30.5
2	16	0	122	7.625
3	64	1	842	13.15625
4	256	1	842	3.2890625
5	1024	2	5882	5.744140625
6	4096	2	5882	1.436035156
7	16384	3	41162	2.512329102
8	65536	3	41162	0.6280822754
9	262144	4	288122	1.099098206
10	1048576	4	288122	0.2747745514
11	4194304	5	2016842	0.4808526039
12	16777216	6	14117882	0.8414913416
13	67108864	6	14117882	0.2103728354
14	268435456	7	98825162	0.3681524172
15	1073741824	8	691776122	0.644266719
16	4294967296	8	691776122	0.1610666797
17	17179869184	9	4842432842	0.2818666889
18	68719476736	10	33897029882	0.4932667053
19	274877906944	11	237279209162	0.8632167343
20	1099511627776	11	237279209162	0.2158041836
21	4398046511104	12	1660954464122	0.3776573213
22	17592186044416	13	11626681248842	0.6609003122
23	70368744177664	13	11626681248842	0.165225078
24	281474976710656	14	81386768741882	0.2891438866
25	1125899906842620	15	569707381193162	0.5060018015
26	4503599627370500	15	569707381193162	0.1265004504
27	18014398509482000	15	569707381193162	0.03162511259
28	72057594037927900	15	569707381193162	0.007906278149
29	288230376151712000	15	569707381193162	0.001976569537

Шестиугольные ячейки не идеально совмещаются с векторной плиткой. Некоторые ячейки могут пересекаться с более чем одной векторной плиткой. Для вычисления разрешения H3 для каждой точности Elasticsearch сравнивает среднюю плотность шестиугольных ячеек на каждом разрешении со средней плотностью ячеек плитки на каждом уровне масштабирования. Elasticsearch использует разрешение H3, которое наиболее близко к соответствующей плотности geotile.

grid_type

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

Допустимые значения для grid_type

grid (По умолчанию): Каждый объект является Polygon геометрии ячейки. Для grid_agg типа geotile, объект является ограничивающей рамкой ячейки. Для grid_agg типа geohex, объект представляет собой границы шестиугольной ячейки.
point: Каждый объект — это Point, представляющий центр ячейки.
centroid: Каждый объект — это Point, представляющий центр данных внутри ячейки. Для сложных геометрий фактический центр может находиться вне ячейки. В этих случаях объект устанавливается в ближайшую к центру точку внутри ячейки.

size: (Необязательно, целое число) Максимальное количество объектов, возвращаемых в слое hits. Принимает значения от 0 до 10000. По умолчанию 10000. Если 0, результаты не включают слой hits.

track_total_hits

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

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

with_labels

(Необязательно, булево значение) Если true, слои hits и aggs будут содержать дополнительные точки, представляющие предполагаемые позиции меток для исходных объектов.

Объекты Point и MultiPoint будут иметь одну из выбранных точек.
Объекты Polygon и MultiPolygon будут иметь одну сгенерированную точку, либо центр, если он находится внутри многоугольника, либо другую точку внутри многоугольника, выбранную из отсортированного дерева треугольников sorted triangle-tree.
Объекты LineString также предоставят примерно центральную точку, выбранную из дерева треугольников triangle-tree.
Результаты агрегации предоставят одну центральную точку для каждого корзины агрегации.

Все атрибуты из исходных объектов также будут скопированы в новые метки. Кроме того, новые объекты будут различимы по тегу _mvt_label_position.

Тело запроса

aggs

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

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.

buffer

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

fields

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

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

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

Свойства объектов fields

field

(Обязательно, строка) Поле для возврата. Поддерживаются шаблоны (*).

format

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

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

geojson (по умолчанию)

GeoJSON

wkt

Well Known Text

mvt(<spec>)

Бинарный Mapbox векторный тайл. API возвращает тайл в виде строки, закодированной в base64. У <spec> формат <zoom>/<x>/<y> с двумя необязательными суффиксами: @<extent> и/или :<buffer>. Например, 2/0/1 или 2/0/1@4096:5.

mvt параметры

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

grid_agg

(Необязательно, строка) Агрегация, используемая для создания сетки для <field>.

Допустимые значения для grid_agg

geotile (По умолчанию): geotile_grid агрегация.
geohex: geohex_grid агрегация.

grid_precision

(Необязательно, целое число) Уровень точности для ячеек в grid_agg. Принимает значения от 0 до 8. По умолчанию используется значение 8. Если 0, результаты не включают слой aggs.

Точность сетки для geotile

Для grid_agg уровня geotile можно использовать ячейки в слое aggs в качестве тайлов для более низких уровней масштабирования. grid_precision представляет собой дополнительные уровни масштабирования, доступные благодаря этим ячейкам. Конечная точность вычисляется следующим образом:

<zoom> + grid_precision

grid_precision также определяет количество ячеек для сетки следующим образом:

(2^grid_precision) x (2^grid_precision)

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

Точность сетки для geohex

Для grid_agg уровня geohex Elasticsearch использует <zoom> и grid_precision для вычисления конечной точности следующим образом:

<zoom> + grid_precision

Точность	Уникальные ячейки тайла	Разрешение H3	Уникальные шестиугольные ячейки	Соотношение
1	4	0	122	30.5
2	16	0	122	7.625
3	64	1	842	13.15625
4	256	1	842	3.2890625
5	1024	2	5882	5.744140625
6	4096	2	5882	1.436035156
7	16384	3	41162	2.512329102
8	65536	3	41162	0.6280822754
9	262144	4	288122	1.099098206
10	1048576	4	288122	0.2747745514
11	4194304	5	2016842	0.4808526039
12	16777216	6	14117882	0.8414913416
13	67108864	6	14117882	0.2103728354
14	268435456	7	98825162	0.3681524172
15	1073741824	8	691776122	0.644266719
16	4294967296	8	691776122	0.1610666797
17	17179869184	9	4842432842	0.2818666889
18	68719476736	10	33897029882	0.4932667053
19	274877906944	11	237279209162	0.8632167343
20	1099511627776	11	237279209162	0.2158041836
21	4398046511104	12	1660954464122	0.3776573213
22	17592186044416	13	11626681248842	0.6609003122
23	70368744177664	13	11626681248842	0.165225078
24	281474976710656	14	81386768741882	0.2891438866
25	1125899906842620	15	569707381193162	0.5060018015
26	4503599627370500	15	569707381193162	0.1265004504
27	18014398509482000	15	569707381193162	0.03162511259
28	72057594037927900	15	569707381193162	0.007906278149
29	288230376151712000	15	569707381193162	0.001976569537

Шестиугольные ячейки не идеально выравниваются на векторизованном тайле. Некоторые ячейки могут пересекать более одного векторизованного тайла. Для вычисления разрешения H3 для каждой точности Elasticsearch сравнивает среднюю плотность шестиугольных ячеек для каждого разрешения со средней плотностью ячеек тайла для каждого уровня масштабирования. Elasticsearch использует разрешение H3, которое наиболее близко к соответствующей плотности geotile.

grid_type

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

Допустимые значения для grid_type

grid (По умолчанию): Каждый объект является Polygon геометрии ячейки. Для grid_agg geotile объект представляет собой рамку ограничивающей области ячейки. Для grid_agg geohex объект представляет собой границы шестиугольной ячейки.
point: Каждый объект является Point, представляющим центр ячейки.
centroid: Каждый объект представляет собой Point, являющийся центром данных внутри ячейки. Для сложных геометрий фактический центр может находиться за пределами ячейки. В таких случаях объект устанавливается на ближайшую точку к центру внутри ячейки.

query

(Необязательно, объект) Query DSL, используемый для фильтрации документов при поиске.

runtime_mappings

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

Свойства объектов runtime_mappings

<field-name>

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

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

type

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

boolean
composite
date
double
geo_point
ip
keyword
long
lookup

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, ответ не содержит общее число совпадений с запросом.

with_labels

Объекты Point и MultiPoint будут иметь одну из выбранных точек.
Объекты Polygon и MultiPolygon будут иметь одну сгенерированную точку, либо центр, если он находится внутри многоугольника, или другую точку внутри многоугольника, выбранную из отсортированного дерева треугольников.
Объекты LineString также предоставят приблизительно центральную точку, выбранную из дерева треугольников.
Результаты агрегации предоставят одну центральную точку для каждого агрегированного значения.

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

Ответ

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

hits

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

Свойства hits

extent: (целое число) Размер стороны тайла в пикселях. Векторные тайлы квадратные с равными сторонами.

version

(целое число) Номер основной версии спецификации векторных тайлов Mapbox.

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

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

Свойства aggs

extent

(целое число) Размер стороны тайла в пикселях. Векторные тайлы квадратные с равными сторонами.

version

(целое число) Номер основной версии спецификации векторных тайлов Mapbox.

features

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

Свойства объектов 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.

resp = client.indices.create(
    index="museums",
    mappings={
        "properties": {
            "location": {
                "type": "geo_point"
            },
            "name": {
                "type": "keyword"
            },
            "price": {
                "type": "long"
            },
            "included": {
                "type": "boolean"
            }
        }
    },
)
print(resp)

resp1 = client.bulk(
    index="museums",
    refresh=True,
    operations=[
        {
            "index": {
                "_id": "1"
            }
        },
        {
            "location": "POINT (4.912350 52.374081)",
            "name": "NEMO Science Museum",
            "price": 1750,
            "included": True
        },
        {
            "index": {
                "_id": "2"
            }
        },
        {
            "location": "POINT (4.901618 52.369219)",
            "name": "Museum Het Rembrandthuis",
            "price": 1500,
            "included": False
        },
        {
            "index": {
                "_id": "3"
            }
        },
        {
            "location": "POINT (4.914722 52.371667)",
            "name": "Nederlands Scheepvaartmuseum",
            "price": 1650,
            "included": True
        },
        {
            "index": {
                "_id": "4"
            }
        },
        {
            "location": "POINT (4.914722 52.371667)",
            "name": "Amsterdam Centre for Architecture",
            "price": 0,
            "included": True
        }
    ],
)
print(resp1)

response = client.indices.create(
  index: 'museums',
  body: {
    mappings: {
      properties: {
        location: {
          type: 'geo_point'
        },
        name: {
          type: 'keyword'
        },
        price: {
          type: 'long'
        },
        included: {
          type: 'boolean'
        }
      }
    }
  }
)
puts response

response = client.bulk(
  index: 'museums',
  refresh: true,
  body: [
    {
      index: {
        _id: '1'
      }
    },
    {
      location: 'POINT (4.912350 52.374081)',
      name: 'NEMO Science Museum',
      price: 1750,
      included: true
    },
    {
      index: {
        _id: '2'
      }
    },
    {
      location: 'POINT (4.901618 52.369219)',
      name: 'Museum Het Rembrandthuis',
      price: 1500,
      included: false
    },
    {
      index: {
        _id: '3'
      }
    },
    {
      location: 'POINT (4.914722 52.371667)',
      name: 'Nederlands Scheepvaartmuseum',
      price: 1650,
      included: true
    },
    {
      index: {
        _id: '4'
      }
    },
    {
      location: 'POINT (4.914722 52.371667)',
      name: 'Amsterdam Centre for Architecture',
      price: 0,
      included: true
    }
  ]
)
puts response

const response = await client.indices.create({
  index: "museums",
  mappings: {
    properties: {
      location: {
        type: "geo_point",
      },
      name: {
        type: "keyword",
      },
      price: {
        type: "long",
      },
      included: {
        type: "boolean",
      },
    },
  },
});
console.log(response);

const response1 = await client.bulk({
  index: "museums",
  refresh: "true",
  operations: [
    {
      index: {
        _id: "1",
      },
    },
    {
      location: "POINT (4.912350 52.374081)",
      name: "NEMO Science Museum",
      price: 1750,
      included: true,
    },
    {
      index: {
        _id: "2",
      },
    },
    {
      location: "POINT (4.901618 52.369219)",
      name: "Museum Het Rembrandthuis",
      price: 1500,
      included: false,
    },
    {
      index: {
        _id: "3",
      },
    },
    {
      location: "POINT (4.914722 52.371667)",
      name: "Nederlands Scheepvaartmuseum",
      price: 1650,
      included: true,
    },
    {
      index: {
        _id: "4",
      },
    },
    {
      location: "POINT (4.914722 52.371667)",
      name: "Amsterdam Centre for Architecture",
      price: 0,
      included: true,
    },
  ],
});
console.log(response1);

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": "POINT (4.912350 52.374081)", "name": "NEMO Science Museum",  "price": 1750, "included": true }
{ "index": { "_id": "2" } }
{ "location": "POINT (4.901618 52.369219)", "name": "Museum Het Rembrandthuis", "price": 1500, "included": false }
{ "index": { "_id": "3" } }
{ "location": "POINT (4.914722 52.371667)", "name": "Nederlands Scheepvaartmuseum", "price":1650, "included": true }
{ "index": { "_id": "4" } }
{ "location": "POINT (4.914722 52.371667)", "name": "Amsterdam Centre for Architecture", "price":0, "included": true }

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

resp = client.search_mvt(
    index="museums",
    field="location",
    zoom="13",
    x="4207",
    y="2692",
    grid_agg="geotile",
    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"
            }
        }
    },
)
print(resp)

const response = await client.searchMvt({
  index: "museums",
  field: "location",
  zoom: 13,
  x: 4207,
  y: 2692,
  grid_agg: "geotile",
  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",
      },
    },
  },
});
console.log(response);

GET museums/_mvt/location/13/4207/2692
{
  "grid_agg": "geotile",
  "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/8.17/search-vector-tile-api.html

END_OF_DOCUMENT_MARKER