# groonga - オープンソースのカラムストア機能付き全文検索エンジン

- English page

### ナビゲーション

- 索引
- 次へ |
- 前へ |
- groonga v2.0.4ドキュメント »
- 7. リファレンスマニュアル »
- 7.8. 組み込み関数一覧 »

# 7.8.2. geo_distance

## 7.8.2.1. 概要

`geo_distance` は二点間の距離を計算します。

## 7.8.2.2. 構文

`geo_distance` は二つの点を指定します。引数 `approximate_type` は省略可能です。

    geo_distance(point1, point2)
    geo_distance(point1, point2, approximate_type)

`approximate_type` のデフォルト値は `"rectangle"` です。 `approximate_type` を省略した場合、 `geo_distance` は二点間の距離を `"rectangle"` が指定されたものとして計算します。

## 7.8.2.3. 使い方

`geo_distance` はgroongaの組み込み関数の一つです。

組み込み関数を grn_expr にて使うことができます。

`geo_distance` 関数は `point1` と `point2` の座標値から二点間の距離(近似値)を計算します。

ノート

groongaは三つの組み込み関数を距離の計算のために提供しています。 `geo_distance()` 、 `geo_distance2()` 、 `geo_distance3()` です。これらの違いは距離の計算アルゴリズムにあります。 `geo_distance2()` と `geo_distance3()` はバージョン1.2.9より非推奨となりました。 `geo_distance2(point1, point2)` の代りに `geo_distance(point1, point2, "sphere")` を使用してください。 `geo_distance3(point1, point2)` の代りに `geo_distance(point1, point2, "ellipsoid")` を使用してください。

例とともに `geo_distance` について学びましょう。このセクションでは簡単な例を示します。

使い方を示すためのスキーマ定義とサンプルデータは以下の通りです。これらのサンプルは東京と札幌の距離の計算方法を示します。

1. 距離の計算にlocationカラムの値を使う ( `Stations` テーブル)
2. 距離の計算に明示的に指定した位置を使う ( `Geo` テーブル)

### 7.8.2.3.1. locationカラムの値を使う

使用例を示すための `Stations` テーブルのスキーマ定義とサンプルデータは以下の通りです。

実行例:

    table_create Stations TABLE_HASH_KEY ShortText
    # [[0,0.0,0.0],true]
    column_create Stations location COLUMN_SCALAR WGS84GeoPoint
    # [[0,0.0,0.0],true]
    load --table Stations
    [
    ["_key", "location"],
    ["Tokyo", "128452975x503157902"],
    ]
    # [[0,0.0,0.0],1]

テーブルとして `Stations` があります。 `Stations` テーブルには `location` カラムが存在します。 `location` カラムには座標の値を保存します。東京の座標がサンプルデータとして保存されています。

実行例:

    select Stations --output_columns _score --filter 1 --scorer '_score = geo_distance(location, "155047000x508862800", "rectangle")'
    # [
    #   [0,0.0,0.0],
    #   [
    #     [
    #       [1],
    #       [
    #         ["_score","Int32"]
    #       ],
    #       [830849]
    #     ]
    #   ]
    # ]

このサンプルは `geo_distance` が `location` カラムと座標値から距離を計算していることを示します。

札幌の座標値は "155047000x508862800"です。

### 7.8.2.3.2. 明示的に指定した位置を使う

使用例を示すための `Geo` テーブルのスキーマ定義とサンプルデータは以下の通りです。

実行例:

    table_create Geo TABLE_HASH_KEY ShortText
    # [[0,0.0,0.0],true]
    column_create Geo distance COLUMN_SCALAR Int32
    # [[0,0.0,0.0],true]
    load --table Geo
    [
    {"_key": "the record for geo_distance() result"}
    ]
    # [[0,0.0,0.0],1]

テーブルとして `Geo` があります。 `Geo` テーブルには `distance` カラムがあります。 `distance` カラムは距離を保存します。

実行例:

    select Geo --output_columns distance --scorer 'distance = geo_distance("128452975x503157902", "155047000x508862800", "rectangle")'
    # [
    #   [0,0.0,0.0],
    #   [
    #     [
    #       [1],
    #       [
    #         ["distance","Int32"]
    #       ],
    #       [830849]
    #     ]
    #   ]
    # ]

このサンプルは `geo_distance` が東京の座標と札幌の座標から距離を計算していることを示します。

## 7.8.2.4. 引数

### 7.8.2.4.1. 必須引数

必須引数は二つあります。 `point1` と `point2` です。

#### 7.8.2.4.1.1. `point1`

計算しようとしている二点間の開始地点を指定します。

GeoPoint型の値を指定することができます。 [1]

GeoPoint型については データ型 を参照してください。

#### 7.8.2.4.1.2. `point2`

計算しようとしている二点間の終了地点を指定します。

GeoPoint型の値か座標を表す文字列を指定することができます。

GeoPoint型や座標の表記については データ型 を参照してください。

### 7.8.2.4.2. 省略可能引数

省略可能な引数として `approximate_type` があります。

#### 7.8.2.4.2.1. `approximate_type`

距離を計算するときに地形をどのように近似するかを指定します。

`approximate_type` の値は以下を指定することができます。

> - `rectangle`
> - `sphere`
> - `ellipsoid`

ノート

`geo_distance` には制限があります。子午線や日付変更線、赤道といった境界をまたぐ距離の計算を行うことができません。これはgroongaの実装上の一時的な制限ですが、将来的には修正される予定です。

ノート

`geo_distance` には上記の制限がありますが、近似方法に `rectangle` を選択した場合には制限が緩和されます。二点が北半球に存在する場合に限っては距離を正しく算出することができます。

##### 7.8.2.4.2.1.1. `rectangle`

この引数は地形を方形近似することを要求します。

簡易な式で距離の計算を行うので、高速に距離を求めることができますが、極付近では誤差が増大します。

`rect` を省略表記として指定することができます。

カラムの値で距離を計算するサンプルは以下の通りです。

実行例:

    select Stations --output_columns _score --filter 1 --scorer '_score = geo_distance(location, "155047000x508862800", "rectangle")'
    # [
    #   [0,0.0,0.0],
    #   [
    #     [
    #       [1],
    #       [
    #         ["_score","Int32"]
    #       ],
    #       [830849]
    #     ]
    #   ]
    # ]

明示的に位置を指定して距離を計算するサンプルは以下の通りです。

実行例:

    select Geo --output_columns distance --scorer 'distance = geo_distance("128452975x503157902", "155047000x508862800", "rectangle")'
    # [
    #   [0,0.0,0.0],
    #   [
    #     [
    #       [1],
    #       [
    #         ["distance","Int32"]
    #       ],
    #       [830849]
    #     ]
    #   ]
    # ]

ノート

`geo_distance` は方形近似をデフォルトとして使用します。 `approximate_type` を省略すると `geo_distance` は `rectangle` が指定されたものとして振舞います。

ノート

`geo_distance` は `approximate_type` の値が `"rectangle"` であるときに `point1` の値として座標を表す文字列を受けつけます。もし `sphere` や `ellipsoid` と一緒に座標を表す文字列を `point1` へ指定した場合、 `geo_distance` は距離の値として0を返します。

##### 7.8.2.4.2.1.2. `sphere`

この引数は球面近似で地形を近似することを要求します。

球面近似は `rectangle` よりも遅いです。しかし `rectangle` よりも誤差は小さくなります。

`sphr` を省略表記として指定することができます。

カラムの値で距離を計算するサンプルは以下の通りです。

実行例:

    select Stations --output_columns _score --filter 1 --scorer '_score = geo_distance(location, "155047000x508862800", "sphere")'
    # [
    #   [0,0.0,0.0],
    #   [
    #     [
    #       [1],
    #       [
    #         ["_score","Int32"]
    #       ],
    #       [830802]
    #     ]
    #   ]
    # ]

##### 7.8.2.4.2.1.3. `ellipsoid`

この引数は楕円近似で地形を近似することを要求します。

ヒュベニの距離計算式により距離を計算します。 `sphere` よりも遅いですが、 `sphere` より誤差は小さくなります。

`ellip` を省略表記として指定することができます。

カラムの値で距離を計算するサンプルは以下の通りです。

## 7.8.2.5. 返値

`geo_distance` はFloat型の値を距離として返します。単位はメートルです。

実行例:

    select Stations --output_columns _score --filter 1 --scorer '_score = geo_distance(location, "155047000x508862800", "ellipsoid")'
    # [
    #   [0,0.0,0.0],
    #   [
    #     [
    #       [1],
    #       [
    #         ["_score","Int32"]
    #       ],
    #       [831438]
    #     ]
    #   ]
    # ]

脚注

[1] | 日本測地系座標か世界測地系座標のいずれかを指定することができます。

### ナビゲーション

- 索引
- 次へ |
- 前へ |
- groonga v2.0.4ドキュメント »
- 7. リファレンスマニュアル »
- 7.8. 組み込み関数一覧 »