Geo-point datatype · Elasticsearch 5.4 中文文檔

# Geo-point datatype 原文鏈接 : [https://www.elastic.co/guide/en/elasticsearch/reference/5.4/geo-point.html](https://www.elastic.co/guide/en/elasticsearch/reference/5.4/geo-point.html) 譯文鏈接 : [http://www.apache.wiki/display/Elasticsearch](http://www.apache.wiki/display/Elasticsearch) 貢獻者 : [王賢才](/display/~wangxiancai)，[ApacheCN](/display/~apachecn)，[Apache中文網](/display/~apachechina) geo-points類型字段使用橫縱坐標經偉度，使用方法 1.在邊界框內或多邊形內，找中心點和離中心點的一定距離的點。 2.從地理位置或從中心點的距離組成搜索文本 3.根據位置距離給搜索文本評分 4.根據得分進行搜索文本排序有四種方法可以指定地理點，如下所示 PUT my_index { ? "mappings": { ??? "my_type": { ????? "properties": { ??????? "location": { ????????? "type": "geo_point" ??????? } ????? } ??? } ? } } PUT my_index/my_type/1 { ? "text": "Geo-point as an object", ? "location": { ??? "lat": 41.12, ??? "lon": -71.34 ? } } PUT my_index/my_type/2 { ? "text": "Geo-point as a string", ? "location": "41.12,-71.34" } PUT my_index/my_type/3 { ? "text": "Geo-point as a geohash", ? "location": "drm3btev3e86" } PUT my_index/my_type/4 { ? "text": "Geo-point as an array", ? "location": [ -71.34, 41.12 ] } GET my_index/_search { ? "query": { ??? "geo_bounding_box": { ????? "location": { ??????? "top_left": { ????????? "lat": 42, ????????? "lon": -72 ??????? }, ??????? "bottom_right": { ????????? "lat": 40, ????????? "lon": -74 ??????? } ????? } ??? } ? } } | ? | Geo-point 可以用對象表示描述：有橫坐標和縱坐標兩點. | | ? | Geo-point 可以帶有“，”間隔符的字符串表示描述. | | ? | Geo-point 可以用geohash哈希來表示描述. | | ? | Geo-point 可以用這樣的數組格式: [?lon,?lat]來表示描 | | ? | 可以用查詢邊界框里面的點來表示描述. | 注意:表示為數組或字符串的地理點請注意用string類型描述geo-points格式，和數組類型描述geo-points格式正好，模縱坐標可以放string類型或數組類型，但是數組是可以轉換成JOSN格式 Geo_point 字段參數下面是Geo_point 字段參數 [`ignore_malformed`](https://www.elastic.co/guide/en/elasticsearch/reference/current/ignore-malformed.html "ignore_malformed") 參數：如果true,異常Geo_point數據被忽略，false,將會拋出異常，不接受執行整個搜索文本（默認為false）使用geo-points腳本使用腳本查詢一個地理點的數據時，該值作為一個GeoPoint對象返回，它允許訪問。LAT和LON。值分別為： ``` def geopoint = doc['location'].value; ``` ``` def lat????? = geopoint.lat; ``` ``` def lon????? = geopoint.lon; ``` 對于性能的原因，請直接訪問搜索文本的經度值： ``` def lat????? = doc['location'].lat; ``` ``` def lon????? = doc['location'].lon; ``` [https://www.elastic.co/guide/en/elasticsearch/reference/current/geo-shape.html](https://www.elastic.co/guide/en/elasticsearch/reference/current/geo-shape.html) Geo-Shape datatype Geo_shape數據類型有利于有助于索引和搜索任意地理形狀，如：矩形和多邊形。我們這樣使用它：數據索引或執行點狀數據查詢你能使用geo_shape 查詢引擎，查詢搜索文本。 Mapping Options Geo_shape mapping 繪制geo_shape 類型的 geo_json 幾何對象 | **Option** | **Description** | **Default** | | tree | 使用PrefixTree?：geohash類型的GeohashPrefixTree?或`quadtree`?類型的QuadPrefixTree | geohash | | precision | 這個參數可以用來代替tree_levels設置為適當的值tree_levels參數。該值指定所需的精度，Elasticsearch將計算出最佳有價值的精度tree_levels。值應該是一個數字，然后是可選的距離單位。有效距離的單位包括：英寸，寸碼，米，公里，米，厘米，毫米 | meters | | tree_levels | 這一點被prefixTree應用最多。這可以用來控制形狀表示的精度，因些需要索引很多個詞，選擇prefixtree默認值，由于此參數要求對底層實現有一定程度的理解，因此用戶可以使用精度參數。然而，Elasticsearch只用tree_levels參數，這是通過映射的API，即使你使用精度的參數返回。 | 50m | | strategy | 策略參數定義了如何在索引和搜索時間中表示形狀的方法。它也影響的能力提供建議讓Elasticsearch自動設置這個參數。有兩種策略可供選擇：遞歸和術語。長期的戰略支撐點類型（的points_only參數將被自動設置為true），遞歸策略支持所有的形狀類型。（重要：參見前綴樹獲取更詳細的信息） | recursive | | distance_error_pct | 作為一個暗示，PrefixTree如何精確的應。默認值為0.025（2.5%），最大支持值為0.5。性能備注：這個值將默認為0如果精度或tree_level定義明確定義。這保證映射中定義的級別的空間精度。這會導致高分辨率的內存使用率低（例如，100米的大圖形和0.001錯誤）。提高索引性能（在查詢精度成本）明確隨著合理的distance_error_pct tree_level或精度，指出大的形狀將有更大的誤報。 | 0.025 | | orientation | 可以定義如何解釋/ multipolygons多邊形頂點順序。這個參數定義了兩個坐標系統規則（右手或左手）中的一個，每個規則可以用三種不同的方式指定。1。右手定則：右，逆時針逆時針，2。左手定則：左，順時針，順時針。默認方向（逆時針）符合定義的頂點按逆時針順序與外環內環OGC標準（S）的頂點（孔）按順時針方向的。在geo_shape映射這個參數設置顯式設置為一個geo_shape場坐標列表頂點順序但可在每個GeoJSON文件重寫。 | ccw | | points_only | 設置此選項為true（默認為false）配置點的geo_shape字段類型形狀（注：多點尚未支持）。這優化為Geohash和四叉樹索引和搜索性能的時候它是已知的唯一的點會被索引。目前geo_shape查詢無法執行的geo_point字段類型。這個選項，架起了一座橋梁，通過提高在geo_shape場點的表現讓geo_shape查詢優化一點場。 | false | **Prefix trees** 有效的指數代表的形狀，形狀轉換成一系列的哈希值代表方格（通常被稱為“柵格”）使用一個prefixtree實現。樹的概念來自這樣一個事實：prefixtree采用多重網格層，每一個增加的精度水平代表地圖。這可以看作是在更高的縮放級別上增加地圖或圖像的細節級別。提供了多個prefixtree實現 1. geohashprefixtree使用geohashes方格。geohashes是Base32編碼字符串的緯度和經度的比特交織。所以哈希越長，它就越精確。每個字符添加到Geohash代表另一個樹的水平和增加了5位精度的Geohash。一個Geohash表示一個矩形的面積，32個矩形。在Elasticsearch級別的最大量為24。 2. quadprefixtree -使用一個四叉樹的方格。類似Geohash，四叉樹交錯的經度和緯度產生的哈希位有點集。四叉樹中的樹級別代表這個位集中的2位，每個坐標的一位。在Elasticsearch的四叉樹級別的最大量為50。 ##### Spatial strategies prefixtree的實現依賴于一種分解提供的形狀spatialstrategy（S）為近似方格。每種策略都回答以下問題： 1. 什么類型的形狀可以被索引？ 2. 可以使用什么類型的查詢操作或形狀？ 3. 它支持每個字段超過一個形狀嗎？提供了以下策略實現（具有相應的功能）： | **Strategy** | **Supported Shapes** | **Supported Queries** | **Multiple Shapes** | | `recursive` | [All](https://www.elastic.co/guide/en/elasticsearch/reference/current/geo-shape.html#input-structure "Input Structureedit") | `INTERSECTS`,?`DISJOINT`,?`WITHIN`,?`CONTAINS` | Yes | | `term` | [Points](https://www.elastic.co/guide/en/elasticsearch/reference/current/geo-shape.html#point "Pointedit") | `INTERSECTS` | Yes | ##### Accuracy geo_shape不提供100%的準確度，取決于它是如何配置它可能會返回一些假陽性或假陰性的某些查詢。為了解決這個問題，這是選擇的tree_levels參數調整的預期因此適當的重要價值。例如，一個點可以在一個特定的網格單元的邊界，因此可能不匹配的查詢匹配的細胞在它旁邊?-?雖然外形非常接近的點。例子 PUT /example { ??? "mappings": { ??????? "doc": { ??????????? "properties": { ??????????????? "location": { ??????????????????? "type": "geo_shape", ??????????????????? "tree": "quadtree", ??????????????????? "precision": "1m" ??????????????? } ??????????? } ??????? } ??? } } 這個映射圖位置字段中使用quad_tree實現和精度1m geo_shape型。Elasticsearch轉化為tree_levels設置26。 ##### Performance considerations Elasticsearch使用路徑的前綴樹的索引和查詢。級別越高（因而精度越高）生成的代碼越多。當然，計算這些代碼，將它們保存在內存中，并將它們存儲在磁盤上都是有代價的。尤其是樹級別較高的情況下，即使只有少量的數據，索引也可能變得非常大。此外，功能的大小也很重要。大而復雜的多邊形可以在較高的樹級別占用大量空間。哪個設置正確取決于用例。一般情況下，索引精度和查詢性能都會降低準確性。為實現在Elasticsearch默認索引的大小和在赤道精密50M的合理水平之間的一種折衷。這使得索引數以千萬計的形狀，而不會過度膨脹的結果指數太大，相對于輸入大小。 #### Input Structure GeoJSON格式的是用來表示形狀輸入如下： | **GeoJSON Type** | **Elasticsearch Type** | **Description** | | Point | point | 單一地理坐標 | | LineString | linestring | 給定兩個或多個點的任意線。 | | Polygon | polygon | 一個封閉的多邊形的第一個和最后一個點必須匹配，因此需要n + 1個頂點創建一個N邊多邊形和至少4個頂點。 | | MultiPoint | multipoint | An array of unconnected, but likely related points. | | MultiLineString | multilinestring | An array of separate linestrings. | | MultiPolygon | multipolygon | 一組單獨的多邊形。 | | GeometryCollection | geometrycollection | A GeoJSON shape similar to the?multi*?shapes except that multiple types can coexist (e.g., a Point and a LineString). | | N/A | envelope | A bounding rectangle, or envelope, specified by specifying only the top left and bottom right points. | | N/A | circle | A circle specified by a center point and radius with units, which default to?METERS. | 對于所有類型，都需要內部類型和坐標字段。在GeoJSON，因此Elasticsearch，正確的坐標為經度、緯度（x，y）的坐標數組。這不同于許多地理空間API（例如，谷歌地圖），它們通常使用緯度、經度（y、x）。 ##### [Point](http://geojson.org/geojson-spec.html#id2) 一個點是一個單一的地理坐標位置，如建筑物或當前位置通過智能手機的地理定位API了。 POST /example/doc { ??? "location" : { ??????? "type" : "point", ??????? "coordinates" : [-77.03653, 38.897676] ??? } } ##### [LineString](http://geojson.org/geojson-spec.html#id3) 由兩個或兩個以上的位置數組定義的線。通過指定兩點的線表示一條直線。指定多于兩個點會創建任意路徑。 POST /example/doc { ??? "location" : { ??????? "type" : "linestring", ??????? "coordinates" : [[-77.03653, 38.897676], [-77.009051, 38.889939]] ??? } } 上面的線就畫一直線，從白宮到美國的首都大廈。 ##### [Polygon](http://www.geojson.org/geojson-spec.html#id4) 多邊形是由一個點的列表定義的。每個（外部）列表中的第一個和最后一個點必須是相同的（多邊形必須是閉合的）。 POST /example/doc { ??? "location" : { ??????? "type" : "polygon", ??????? "coordinates" : [ ??????????? [ [100.0, 0.0], [101.0, 0.0], [101.0, 1.0], [100.0, 1.0], [100.0, 0.0] ] ??????? ] ??? } } 第一個數組代表多邊形的外邊界，其他數組表示內部形狀（”holes”） POST /example/doc { ??? "location" : { ??????? "type" : "polygon", ??????? "coordinates" : [ ??????????? [ [100.0, 0.0], [101.0, 0.0], [101.0, 1.0], [100.0, 1.0], [100.0, 0.0] ], ??????????? [ [100.2, 0.2], [100.8, 0.2], [100.8, 0.8], [100.2, 0.8], [100.2, 0.2] ] ??????? ] ??? } } 重要注意事項： GeoJSON并不要求如此明確的多邊形頂點在日界線內，頂點的特定順序是可能的。為了減輕模糊開放地理空間聯盟（OGC）的簡單功能接入規范定義了下面的頂點順序 1. 外圈-逆時針方向 2. 內圈-順時針方向多邊形不越過日界線，頂點順序將不在Elasticsearch。多邊形做過日界線，Elasticsearch需要頂點順序符合OGC規范。否則，可能會創建一個意外的多邊形，并返回意外的查詢/過濾結果。下面提供了一個不明確多邊形的示例。Elasticsearch將OGC標準消除產生一個多邊形，越過日界線歧義。 POST /example/doc { ??? "location" : { ??????? "type" : "polygon", ??????? "coordinates" : [ ??????????? [ [-177.0, 10.0], [176.0, 15.0], [172.0, 0.0], [176.0, -15.0], [-177.0, -10.0], [-177.0, 10.0] ], ??????????? [ [178.2, 8.2], [-178.8, 8.2], [-180.8, -8.8], [178.2, 8.8] ] ??????? ] ??? } } 一個定位參數可以定義設置geo_shape映射時（參見“映射optionsedit”）。這將定義的映射geo_shape場坐標列表頂點順序。它也可以覆蓋在每個文檔上。下面是覆蓋文檔方向的示例： POST /example/doc { ??? "location" : { ??????? "type" : "polygon", ??????? "orientation" : "clockwise", ??????? "coordinates" : [ ??????????? [ [-177.0, 10.0], [176.0, 15.0], [172.0, 0.0], [176.0, -15.0], [-177.0, -10.0], [-177.0, 10.0] ], ??????????? [ [178.2, 8.2], [-178.8, 8.2], [-180.8, -8.8], [178.2, 8.8] ] ??????? ] ??? } } ##### [MultiPoint](http://www.geojson.org/geojson-spec.html#id5) GeoJSON點列表。 POST /example/doc { ??? "location" : { ??????? "type" : "multipoint", ??????? "coordinates" : [ ??????????? [102.0, 2.0], [103.0, 2.0] ??????? ] ??? } } ##### [MultiLineString](http://www.geojson.org/geojson-spec.html#id6) GeoJSON線要素列表 POST /example/doc { ??? "location" : { ??????? "type" : "multilinestring", ??????? "coordinates" : [ ??????????? [ [102.0, 2.0], [103.0, 2.0], [103.0, 3.0], [102.0, 3.0] ], ??????????? [ [100.0, 0.0], [101.0, 0.0], [101.0, 1.0], [100.0, 1.0] ], ??????????? [ [100.2, 0.2], [100.8, 0.2], [100.8, 0.8], [100.2, 0.8] ] ??????? ] ??? } } ##### [MultiPolygon](http://www.geojson.org/geojson-spec.html#id7) GeoJSON多邊形列表。 POST /example/doc { ??? "location" : { ??????? "type" : "multipolygon", ??????? "coordinates" : [ ??????????? [ [[102.0, 2.0], [103.0, 2.0], [103.0, 3.0], [102.0, 3.0], [102.0, 2.0]] ], ??????????? [ [[100.0, 0.0], [101.0, 0.0], [101.0, 1.0], [100.0, 1.0], [100.0, 0.0]], ????????????? [[100.2, 0.2], [100.8, 0.2], [100.8, 0.8], [100.2, 0.8], [100.2, 0.2]] ] ??????? ] ??? } } ##### [Geometry Collection](http://geojson.org/geojson-spec.html#geometrycollection) GeoJSON幾何對象的集合。 POST /example/doc { ??? "location" : { ??????? "type": "geometrycollection", ??????? "geometries": [ ??????????? { ??????????????? "type": "point", ??????????????? "coordinates": [100.0, 0.0] ??????????? }, ??????????? { ??????????????? "type": "linestring", ??????????????? "coordinates": [ [101.0, 0.0], [102.0, 1.0] ] ??????????? } ??????? ] ??? } } ##### Envelope Elasticsearch支持一個信封式的，包括對形狀代表一個矩形的左上角和右下角點的坐標： POST /example/doc { ??? "location" : { ??????? "type" : "envelope", ??????? "coordinates" : [ [-45.0, 45.0], [45.0, -45.0] ] ??? } } ##### Circle Elasticsearch支持圓式，它由一個中心點和半徑： POST /example/doc { ??? "location" : { ??????? "type" : "circle", ??????? "coordinates" : [-45.0, 45.0], ??????? "radius" : "100m" ??? } } 注：內半徑場是必需的。如果未指定，則半徑的單位將默認為米。 #### Sorting and Retrieving index Shapes 由于復雜的輸入結構和形狀的索引表示，目前不可能對形狀進行分類或直接檢索它們的字段。geo_shape值僅為檢索通過`_source`?field.