Link Search Menu Expand Document Documentation Menu
文档

地理形状字段类型

1.0 版引入

地理形状字段类型包含地理形状，例如多边形或地理点集合。为了索引地理形状，OpenSearch 将形状细分为三角形网格，并将每个三角形存储在 BKD 树中。这提供了 10-7十进制度的精度，表示近乎完美的空间分辨率。此过程的性能主要受您正在索引的多边形中顶点数量的影响。

示例

创建包含地理形状字段类型的映射

PUT testindex
{
  "mappings": {
    "properties": {
      "location": {
        "type": "geo_shape"
      }
    }
  }
}

格式

地理形状可以以下列格式进行索引

在 GeoJSON 和 WKT 中，坐标必须在坐标数组内以 经度，纬度 的顺序指定。请注意，在此格式中经度在前。

地理形状类型

下表描述了可能的地理形状类型及其与 GeoJSON 和 WKT 类型的关系。

OpenSearch 类型 GeoJSON 类型 WKT 类型 描述
点 Point POINT 一个由经纬度指定的地理点。OpenSearch 使用世界大地测量系统 (WGS84) 坐标。
线串 LineString LINESTRING 由两个或更多点指定的线。可以是直线或由连接线段组成的路径。
多边形 Polygon POLYGON 由坐标形式的顶点列表指定的多边形。多边形必须闭合，意味着最后一个点必须与第一个点相同。因此，要创建 n 边形，需要 n+1 个顶点。最小顶点数为四个，这将创建一个三角形。
多点 MultiPoint MULTIPOINT 不连接的离散相关点的数组。
多线串 MultiLineString MULTILINESTRING 线串数组。
多多边形 MultiPolygon MULTIPOLYGON 多边形数组。
几何集合 GeometryCollection GEOMETRYCOLLECTION 可能包含不同类型的地理形状的集合。
包络 不适用 BBOX 由左上角和右下角顶点指定的边界矩形。

Point

点是经纬度指定的一对坐标。

以 GeoJSON 格式索引点

PUT testindex/_doc/1
{
  "location" : {
    "type" : "point",
    "coordinates" : [74.0060, 40.7128]
  }
}

以 WKT 格式索引点

PUT testindex/_doc/1
{
  "location" : "POINT (74.0060 40.7128)"
}

线串

线串是由两个或更多点指定的线。如果这些点共线，则线串是一条直线。否则，线串表示由线段组成的路径。

以 GeoJSON 格式索引线串

PUT testindex/_doc/2
{
  "location" : {
    "type" : "linestring",
    "coordinates" : [[74.0060, 40.7128], [71.0589, 42.3601]]
  }
}

以 WKT 格式索引线串

PUT testindex/_doc/2
{
  "location" : "LINESTRING (74.0060 40.7128, 71.0589 42.3601)"
}

Polygon

多边形由坐标形式的顶点列表指定。多边形必须闭合，意味着最后一个点必须与第一个点相同。在以下示例中，使用四个点创建了一个三角形。

GeoJSON 要求您逆时针列出多边形的顶点。WKT 对顶点没有特定的顺序要求。

以 GeoJSON 格式索引多边形（三角形）

PUT testindex/_doc/3
{
  "location" : {
    "type" : "polygon",
    "coordinates" : [
      [
        [74.0060, 40.7128], 
        [73.7562, 42.6526], 
        [71.0589, 42.3601], 
        [74.0060, 40.7128]
      ]
    ]
  }
}

以 WKT 格式索引多边形（三角形）

PUT testindex/_doc/3
{
  "location" : "POLYGON ((74.0060 40.7128, 71.0589 42.3601, 73.7562 42.6526, 74.0060 40.7128))"
}

多边形内部可能存在孔洞。在这种情况下，coordinates 字段将包含多个数组。第一个数组代表外部多边形，每个后续数组代表一个孔洞。孔洞表示为多边形，并指定为坐标数组。

GeoJSON 要求您逆时针列出多边形的顶点，顺时针列出孔洞的顶点。WKT 对顶点没有特定的顺序要求。

以 GeoJSON 格式索引带有三角形孔洞的多边形（三角形）

PUT testindex/_doc/4
{
  "location" : {
    "type" : "polygon",
    "coordinates" : [
      [
        [74.0060, 40.7128], 
        [73.7562, 42.6526], 
        [71.0589, 42.3601], 
        [74.0060, 40.7128]
      ],
      [
        [72.6734,41.7658], 
        [73.0515, 41.5582], 
        [72.6506, 41.5623],
        [72.6734, 41.7658]
      ]
    ]
  }
}

以 WKT 格式索引带有三角形孔洞的多边形（三角形）

PUT testindex/_doc/4
{
  "location" : "POLYGON ((74.0060 40.7128, 71.0589 42.3601, 73.7562 42.6526, 74.0060 40.7128), (72.6734 41.7658, 72.6506 41.5623, 73.0515 41.5582, 72.6734 41.7658))"
}

您可以通过顺时针或逆时针列出顶点来在 OpenSearch 中指定多边形。这适用于不跨越日期线（窄于 180°）的多边形。然而，跨越日期线（宽于 180°）的多边形可能会有歧义，因为 WKT 对顶点没有特定的顺序要求。因此，您必须通过逆时针列出顶点来指定跨越日期线的多边形。

您可以在映射时定义 orientation 参数来指定顶点的遍历顺序

PUT testindex
{
  "mappings": {
    "properties": {
      "location": {
        "type": "geo_shape",
        "orientation" : "left"
      }
    }
  }
}

随后索引的文档可以覆盖 orientation 设置

PUT testindex/_doc/3
{
  "location" : {
    "type" : "polygon",
    "orientation" : "cw",
    "coordinates" : [
      [[74.0060, 40.7128], 
      [71.0589, 42.3601], 
      [73.7562, 42.6526], 
      [74.0060, 40.7128]]
    ]
  }
}

多点

多点是不连接的离散相关点的数组。

以 GeoJSON 格式索引多点

PUT testindex/_doc/6
{
  "location" : {
    "type" : "multipoint",
    "coordinates" : [
      [74.0060, 40.7128], 
      [71.0589, 42.3601]
    ]
  }
}

以 WKT 格式索引多点

PUT testindex/_doc/6
{
  "location" : "MULTIPOINT (74.0060 40.7128, 71.0589 42.3601)"
}

多线串

多线串是线串的数组。

以 GeoJSON 格式索引线串

PUT testindex/_doc/2
{
  "location" : {
    "type" : "multilinestring",
    "coordinates" : [
      [[74.0060, 40.7128], [71.0589, 42.3601]],
      [[73.7562, 42.6526], [72.6734, 41.7658]]
      ]
  }
}

以 WKT 格式索引线串

PUT testindex/_doc/2
{
  "location" : "MULTILINESTRING ((74.0060 40.7128, 71.0589 42.3601), (73.7562 42.6526, 72.6734 41.7658))"
}

多多边形

多多边形是多边形的数组。在此示例中，第一个多边形包含一个孔洞，而第二个不包含。

以 GeoJSON 格式索引多多边形

PUT testindex/_doc/4
{
  "location" : {
    "type" : "multipolygon",
    "coordinates" : [
    [
      [
        [74.0060, 40.7128], 
        [73.7562, 42.6526], 
        [71.0589, 42.3601], 
        [74.0060, 40.7128]
      ],
      [
        [73.0515, 41.5582], 
        [72.6506, 41.5623], 
        [72.6734, 41.7658], 
        [73.0515, 41.5582]
      ]
    ],
    [
      [
        [73.9146, 40.8252], 
        [73.8871, 41.0389], 
        [73.6853, 40.9747], 
        [73.9146, 40.8252]
      ]
    ]
  ]
  }
}

以 WKT 格式索引多多边形

PUT testindex/_doc/4
{
  "location" : "MULTIPOLYGON (((74.0060 40.7128, 71.0589 42.3601, 73.7562 42.6526, 74.0060 40.7128), (72.6734 41.7658, 72.6506 41.5623, 73.0515 41.5582, 72.6734 41.7658)), ((73.9146 40.8252, 73.6853 40.9747, 73.8871 41.0389, 73.9146 40.8252)))"
}

几何集合

几何集合是可能包含不同类型的地理形状的集合。

以 GeoJSON 格式索引几何集合

PUT testindex/_doc/7
{
  "location" : {
    "type": "geometrycollection",
    "geometries": [
      {
        "type": "point",
        "coordinates": [74.0060, 40.7128]
      },
      {
        "type": "linestring",
        "coordinates": [[73.7562, 42.6526], [72.6734, 41.7658]]
      }
    ]
  }
}

以 WKT 格式索引几何集合

PUT testindex/_doc/7
{
  "location" : "GEOMETRYCOLLECTION (POINT (74.0060 40.7128), LINESTRING(73.7562 42.6526, 72.6734 41.7658))"
}

包络

包络是由左上角和右下角顶点指定的边界矩形。GeoJSON 格式为 [[minLon, maxLat], [maxLon, minLat]]。

以 GeoJSON 格式索引包络

PUT testindex/_doc/2
{
  "location" : {
    "type" : "envelope",
    "coordinates" : [[71.0589, 42.3601], [74.0060, 40.7128]]
  }
}

在 WKT 格式中，使用 BBOX (minLon, maxLon, maxLat, minLat)。

以 WKT BBOX 格式索引包络

PUT testindex/_doc/8
{
  "location" : "BBOX (71.0589, 74.0060, 42.3601, 40.7128)"
}

参数

下表列出了地理形状字段类型接受的参数。所有参数均为可选。

参数 描述
强制转换 (coerce) 一个布尔值，指定是否自动闭合未闭合的线性环。默认值为 false。
忽略畸形值 (ignore_malformed) 一个布尔值，指定是否忽略格式错误的 GeoJSON 或 WKT 地理形状且不抛出异常。默认值为 false（当地理形状格式错误时抛出异常）。
ignore_z_value 特定于具有三个坐标的点。如果 ignore_z_value 为 true，则第三个坐标不会被索引，但仍会存储在 _source 字段中。如果 ignore_z_value 为 false，则会抛出异常。默认值为 true。
orientation 指定地理形状坐标列表中顶点的遍历顺序。orientation 可取以下值
1. RIGHT: 逆时针。通过使用以下字符串之一（大写或小写）指定 RIGHT 方向：right、counterclockwise、ccw。
2. LEFT: 顺时针。通过使用以下字符串之一（大写或小写）指定 LEFT 方向：left、clockwise、cw。此值可以被单个文档覆盖。
默认值为 RIGHT。
剩余 350 字符

有问题？。

想要贡献？ 或 。