geo_distance は二点間の距離を計算します。
geo_distance は二つの点を指定します。引数 approximate_type は省略可能です。
geo_distance(point1, point2)
geo_distance(point1, point2, approximate_type)
approximate_type のデフォルト値は "rectangle" です。 approximate_type を省略した場合、 geo_distance は二点間の距離を "rectangle" が指定されたものとして計算します。
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 について学びましょう。このセクションでは簡単な例を示します。
使い方による違いがわかるようにスキーマ定義とサンプルデータを用意しました。これらのサンプルは東京と札幌を例に距離の計算方法を示します。
使用例を示すための 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]
この実行例では location というカラムを持つ Stations テーブルを作成します。 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 カラムと座標値から距離を計算していることを示します。
geo_distance の第二引数として渡された値 ("155047000x508862800") は札幌の座標値です。
使用例を示すための 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]
この実行例では distance カラムを持つ Geo テーブルを作成します。 distance カラムには距離を保存します。
実行例:
select Geo --output_columns distance --scorer 'distance = geo_distance("128452975x503157902", "155047000x508862800", "rectangle")'
# [
# [0,0.0,0.0],
# [
# [
# [1],
# [
# ["distance","Int32"]
# ],
# [830849]
# ]
# ]
# ]
このサンプルは geo_distance が東京の座標と札幌の座標から距離を計算していることを示します。
必須引数は二つあります。 point1 と point2 です。
省略可能な引数として approximate_type があります。
距離を計算するときに地形をどのように近似するかを指定します。
approximate_type の値は以下を指定することができます。
- rectangle
- sphere
- ellipsoid
ノート
geo_distance には制限があります。子午線や日付変更線、赤道といった境界をまたぐ距離の計算を行うことができません。これはgroongaの実装上の一時的な制限ですが、将来的には修正される予定です。
ノート
geo_distance には上記の制限がありますが、近似方法に 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を返します。
この引数を指定すると球面近似で地形を近似して距離を計算します。
球面近似は 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]
# ]
# ]
# ]
この引数を指定すると楕円近似で地形を近似して距離を計算します。
ヒュベニの距離計算式により距離を計算します。 sphere よりも遅いですが、 sphere より誤差は小さくなります。
ellip を省略表記として指定することができます。
カラムの値で距離を計算するサンプルは以下の通りです。
実行例:
select Stations --output_columns _score --filter 1 --scorer '_score = geo_distance(location, "155047000x508862800", "ellipsoid")'
# [
# [0,0.0,0.0],
# [
# [
# [1],
# [
# ["_score","Int32"]
# ],
# [831438]
# ]
# ]
# ]