# groonga - An open-source fulltext search engine and column store.

- 日本語版はこちら

### Navigation

- index
- next |
- previous |
- groonga v2.0.4 documentation »
- 7. リファレンスマニュアル »
- 7.8. 組み込み関数一覧 »

# 7.8.2. geo_distance

## 7.8.2.1. Summary

`geo_distance` calculates the value of distance between specified two points.

## 7.8.2.2. Syntax

`geo_distance` requires two point. The parameter `approximate_type` is optional:

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

The default value of `approximate_type` is `"rectangle"`. If you omit `approximate_type`, `geo_distance` calculates the value of distance as if `"rectangle"` was specified.

## 7.8.2.3. Usage

`geo_distance` is one of the groonga builtin functions.

You can call a builtin function in grn_expr

`geo_distance` function calculates the value of distance (approximate value) between the coordinate of `point1` and the coordinate of `point2`.

Note

groonga provides three built in functions for calculating the value of distance. There are `geo_distance()`, `geo_distance2()` and `geo_distance3()`. The difference of them is the algorithm of calculating distance. `geo_distance2()` and `geo_distance3()` were deprecated since version 1.2.9. Use `geo_distance(point1, point2, "sphere")` instead of `geo_distance2(point1, point2)`. Use `geo_distance(point1, point2, "ellipsoid")` instead of `geo_distance3(point1, point2)`.

Lets's learn about `geo_distance` usage with examples. This section shows simple usages.

Here are two schema definition and sample data to show usage. Those samples show how to calculate the value of distance between Tokyo and Sapporo.

1. Using the column value of location for calculating the distance (`Stations` table)
2. Using the explicitly specified value of location for calculating the distance (`Geo` table)

### 7.8.2.3.1. Using the column value of location

Here are a schema definition of `Stations` table and sample data to show usage.

Execution example:

    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]

There is a table named `Stations`. `Stations` table has one column, `location`. `location` column stores the value of coordinate. The coordinate of Tokyo is stored as sample data.

Execution example:

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

This sample shows that `geo_distance` use the value of `location` column and the value of coordinate to calculate distance.

Note that the coordinate of Sapporo is "155047000x508862800".

### 7.8.2.3.2. Using the explicitly specified value of location

Here are a schema definition of `Geo` table and sample data to show usage.

Execution example:

    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]

There is a table named `Geo`. `Geo` table has one column, `distance`. `distance` column stores the value of distance.

Execution example:

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

This sample shows that `geo_distance` use the coordinate of Tokyo and the coordinate of Sapporo to calculate distance.

## 7.8.2.4. Parameters

### 7.8.2.4.1. Required parameter

There are two required parameter, `point1` and `point2`.

#### 7.8.2.4.1.1. `point1`

It specifies the start point that you want to calculate the value of distance between two points.

You can specify the value of GeoPoint type. [1]

See データ型 about GeoPoint.

#### 7.8.2.4.1.2. `point2`

It specifies the end point that you want to calculate the value of distance between two points.

You can specify the value of GeoPoint type or the string indicating the coordinate.

See データ型 about GeoPoint and the coordinate.

### 7.8.2.4.2. Optional parameter

There is a optional parameter, `approximate_type`.

#### 7.8.2.4.2.1. `approximate_type`

It specifies how to approximate the geographical features for calculating the value of distance.

You can specify the value of `approximate_type` by one of the followings.

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

Note

There is a limitation about `geo_distance`. `geo_distance` can not calculate the value of distance between two points across meridian, euator or the date line. This is temporary limitation according to the implementation of groonga, but it will be fixed in the future release.

Note

There is a limitation about `geo_distance` above notice. But it relaxes the limitation if you use `rectangle` as approximate type. You can calculate the correct distance if two point are placed at northern hemisphere.

##### 7.8.2.4.2.1.1. `"rectangle"`

This parameter require to approximate the geographical features by square approximation.

Since the value of distance is calculated by simple formula, you can calculate the value of distance fast. But, the error of distance increases as it approaches the pole.

You can also specify `rect` as abbrev expression.

Here is a sample about calculating the value of distance with column value.

Execution example:

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

Here is a sample about calculating the value of distance with explicitly specified point.

Execution example:

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

Note

`geo_distance` uses square approximation as default. If you omit `approximate_type`, `geo_distance` behaves like `rectangle` was specified.

Note

`geo_distance` accepts the string indicating the coordinate as the value of `point1` when the value of `approximate_type` is `"rectangle"`. If you specified the string indicating the coordinate as the value of `point1` with `sphere` or `ellipsoid`, `geo_distance` returns 0 as the value of distance.

##### 7.8.2.4.2.1.2. `"sphere"`

This parameter require to approximate the geographical features by spherical approximation.

It is slower than `rectangle`, but the error of distance becomes smaller than `rectangle`.

You can also specify `sphr` as abbrev expression.

Here is a sample about calculating the value of distance with column value.

Execution example:

    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"`

This parameter require to approximate the geographical features by ellipsoid approximation.

It uses the calculation of distance by the formula of Hubeny. It is slower than `sphere`, but the error of distance becomes smaller than `sphere`.

You can also specify `ellip` as abbrev expression.

Here is a sample about calculating the value of distance with column value.

## 7.8.2.5. Return value

`geo_distance` returns the value of distance in float type. The unit of return value is meter.

Execution example:

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

Footnote

[1] | You can specify whether TokyoGeoPoint or WGS84GeoPoint.

### Navigation

- index
- next |
- previous |
- groonga v2.0.4 documentation »
- 7. リファレンスマニュアル »
- 7.8. 組み込み関数一覧 »