> ## Documentation Index
> Fetch the complete documentation index at: https://docs.prophecy.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Distance

> Calculate the distance between two points

export const gemName_0 = "Distance"

export const execution_engine_0 = "the SQL warehouse"

<Info>This gem runs in {execution_engine_0}.</Info>

## Overview

Use the Distance gem to calculate the distance between two geographic points.

<Tip>
  The {gemName_0} gem has a corresponding interactive gem example. See [Interactive gem
  examples](/data-analysis/gems/gems#interactive-gem-examples) to learn how to run sample pipelines
  for this and other gems.
</Tip>

## Prerequisites

* Add `ProphecyDatabricksSqlSpatial` version 0.0.1 or higher to your project.

## Parameters

Configure the Distance gem using the following parameters.

<Note>
  Geographic points must be in Well-known Text
  ([WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)) format. Use the
  [CreatePoint](/data-analysis/gems/spatial/create-point) gem to convert longitude and latitude
  coordinates to WKT format.
</Note>

### Spatial Object Fields

Use these parameters to specify the columns containing the source and destination geographic points for distance calculation.

| Parameter          | Description                                      |
| ------------------ | ------------------------------------------------ |
| Source Type        | Format of the source column.                     |
| Source Column      | Column that contains the source geo points.      |
| Destination Type   | Format of the destination column.                |
| Destination Column | Column that contains the destination geo points. |

### Select Output Options

Use the checkboxes defined below to choose which output columns the Distance gem should generate.

| Checkbox                    | Description                                                                                           |
| --------------------------- | ----------------------------------------------------------------------------------------------------- |
| Output Distance             | Return a column that includes the distance between points in a specified unit of distance             |
| Output Cardinal Direction   | Return a column that includes the cardinal direction from the source point to the destination point   |
| Output Direction in Degrees | Return a column that includes the direction in degrees from the source point to the destination point |

<Note>
  You can select zero, one, or multiple checkboxes. All checkboxes are disabled by default.
</Note>

## Example

Assume you have the following airline route table, and you would like to calculate the distance between start and destination cities.

| `start`  | `destination` | `src_point`              | `dst_point`               |
| -------- | ------------- | ------------------------ | ------------------------- |
| New York | Los Angeles   | POINT (-74.0060 40.7128) | POINT (-118.2437 34.0522) |
| London   | Paris         | POINT (-0.1278 51.5074)  | POINT (2.3522 48.8566)    |
| Tokyo    | Sydney        | POINT (139.6917 35.6895) | POINT (151.2093 -33.8688) |
| Toronto  | Chicago       | POINT (-79.3470 43.6511) | POINT (-87.6298 41.8781)  |
| Dubai    | Mumbai        | POINT (55.2962 25.2760)  | POINT (72.8777 19.0760)   |

To find the distance and direction between cities, set the following gem configurations.

1. Set source and destination:
   1. Set **Source Type** to **Point**.

   2. Set **Source Column** to `start`.

   3. Set **Destination Type** to **Point**.

   4. Set **Destination Column** to `destination`.

2. Set output options:
   1. Select the **Output Distance** checkbox.

   2. From the **Units** dropdown, select **Kilometers**.

   3. Select the **Output Cardinal Direction** checkbox.

   4. Select the **Output Direction in Degrees** checkbox.

   5. Run the gem.

### Result

The resulting table will have three new columns: `distance_kilometers`, `cardinal_direction`, and `direction_degrees`.

| `start`  | `destination` | `src_point`              | `dst_point`               | `distance_kilometers` | `cardinal_direction` | `direction_degrees` |
| -------- | ------------- | ------------------------ | ------------------------- | --------------------- | -------------------- | ------------------- |
| New York | Los Angeles   | POINT (-74.0060 40.7128) | POINT (-118.2437 34.0522) | 3944.42               | W                    | 273.7               |
| London   | Paris         | POINT (-0.1278 51.5074)  | POINT (2.3522 48.8566)    | 343.92                | SE                   | 148.1               |
| Tokyo    | Sydney        | POINT (139.6917 35.6895) | POINT (151.2093 -33.8688) | 7792.96               | S                    | 169.9               |
| Toronto  | Chicago       | POINT (-79.3470 43.6511) | POINT (-87.6298 41.8781)  | 705.64                | W                    | 256.6               |
| Dubai    | Mumbai        | POINT (55.2962 25.2760)  | POINT (72.8777 19.0760)   | 1936.68               | E                    | 107.3               |

<Note>Scroll horizontally to view the full table.</Note>