Skip to content

Commit 4a8b9a5

Browse files
learn-build-service-prod[bot]learn-build-service-prod[bot]
authored
Merge pull request #2597 from MicrosoftDocs/main638798797504420851sync_temp
For protected branch, push strategy should use PR and merge to target branch method to work around git push error
2 parents 7e6d42e + e9ca885 commit 4a8b9a5

File tree

9 files changed

+611
-3
lines changed

9 files changed

+611
-3
lines changed

‎data-explorer/kusto/query/geo-closest-point-on-line-function.md‎

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
---
2+
title: geo_closest_point_on_line()
3+
description: Learn how to use the geo_closest_point_on_line() function to calculate a point on a line or a multiline, which is closest to a given point on Earth.
4+
ms.reviewer: mbrichko
5+
ms.topic: reference
6+
ms.date: 04/09/2025
7+
---
8+
# geo_closest_point_on_line()
9+
10+
> [!INCLUDE [applies](../includes/applies-to-version/applies.md)] [!INCLUDE [fabric](../includes/applies-to-version/fabric.md)] [!INCLUDE [azure-data-explorer](../includes/applies-to-version/azure-data-explorer.md)] [!INCLUDE [monitor](../includes/applies-to-version/monitor.md)] [!INCLUDE [sentinel](../includes/applies-to-version/sentinel.md)]
11+
12+
Calculates a point on a line or a multiline, which is closest to a given point on Earth.
13+
14+
## Syntax
15+
16+
`geo_closest_point_on_line(`*longitude*`,`*latitude*`,`*lineString*`)`
17+
18+
[!INCLUDE [syntax-conventions-note](../includes/syntax-conventions-note.md)]
19+
20+
## Parameters
21+
22+
| Name | Type | Required | Description |
23+
|--|--|--|--|
24+
| *longitude* | `real` | :heavy_check_mark: | The geospatial coordinate longitude value in degrees. A valid value is in the range [-180, +180].|
25+
| *latitude* | `real` | :heavy_check_mark: | The geospatial coordinate latitude value in degrees. A valid value is in the range [-90, +90].|
26+
| *lineString* | `dynamic` | :heavy_check_mark: | A line or multiline in the [GeoJSON format](https://tools.ietf.org/html/rfc7946).|
27+
28+
## Returns
29+
30+
A point in [GeoJSON Format](https://tools.ietf.org/html/rfc7946) and of a [dynamic](scalar-data-types/dynamic.md) data type on a line or multiline which is the closest to a given point on Earth. If the coordinate or lineString are invalid, the query produces a null result.
31+
32+
> [!NOTE]
33+
>
34+
> * The geospatial coordinates are interpreted as represented by the [WGS-84](https://earth-info.nga.mil/index.php?dir=wgs84&action=wgs84) coordinate reference system.
35+
> * The [geodetic datum](https://en.wikipedia.org/wiki/Geodetic_datum) used to measure distance on Earth is a sphere. Line edges are [geodesics](https://en.wikipedia.org/wiki/Geodesic) on the sphere.
36+
> * If input line edges are straight cartesian lines, consider using [geo_line_densify()](geo-line-densify-function.md) in order to convert planar edges to geodesics.
37+
> * In order to calculate a distance between the closest point on a line or multiline to a given point, use [geo_distance_point_to_line()](geo-distance-point-to-line-function.md)
38+
39+
### LineString definition and constraints
40+
41+
dynamic({"type": "LineString","coordinates": [[lng_1,lat_1], [lng_2,lat_2],..., [lng_N,lat_N]]})
42+
43+
dynamic({"type": "MultiLineString","coordinates": [[line_1, line_2, ..., line_N]]})
44+
45+
* LineString coordinates array must contain at least two entries.
46+
* Coordinates [longitude, latitude] must be valid where longitude is a real number in the range [-180, +180] and latitude is a real number in the range [-90, +90].
47+
* Edge length must be less than 180 degrees. The shortest edge between the two vertices is chosen.
48+
49+
> [!TIP]
50+
>
51+
> * Using literal LineString or a MultiLineString may result in better performance.
52+
53+
## Examples
54+
55+
The following example finds the point on a road which is the closest to North Las Vegas Airport.
56+
57+
:::image type="content" source="media/geo-distance-point-to-line-function/distance-point-to-line.png" alt-text="Screenshot of a map showing the distance between North Las Vegas Airport and a specific road.":::
58+
59+
:::moniker range="azure-data-explorer"
60+
> [!div class="nextstepaction"]
61+
> <a href="https://dataexplorer.azure.com/clusters/help/databases/Samples?query=H4sIAAAAAAAAA1XPS2rDMBCA4asIrRJwgzQvaQK9QXddBmOCY4IhtUzsTQi5e53KyHSjxafh12i898NsxrScTRqaWz905tNcu9S0tzR109z8u9t9eM8HryrAlUE5gHfktTKXx3D%2B6dvd09j5MXb2aL%2BW8e95yV9tZduU7pd%2BOM%2FdZI%2BnU654xsjVOwLqletqdRTV7M6hSHFywPB2r0DBbY7M8c9jZMDNyQXJvuSpOJNI7gSiuM2LEPrsgjEWjwhRs7NzobiC%2BLUjAcue4IDyv3xAQi0OvCy6vovCdf3a738BdPjpOIABAAA%3D" target="_blank">Run the query</a>
62+
::: moniker-end
63+
64+
```kusto
65+
print point_on_line = geo_closest_point_on_line(-115.199625, 36.210419, dynamic({ "type":"LineString","coordinates":[[-115.115385,36.229195],[-115.136995,36.200366],[-115.140252,36.192470],[-115.143558,36.188523],[-115.144076,36.181954],[-115.154662,36.174483],[-115.166431,36.176388],[-115.183289,36.175007],[-115.192612,36.176736],[-115.202485,36.173439],[-115.225355,36.174365]]}))
66+
```
67+
68+
**Output**
69+
70+
| point_on_line |
71+
|--------------------|
72+
| { "type": "Point", "coordinates": [ -115.192612, 36.176736]} |
73+
74+
The following example returns a null result because of the invalid LineString input.
75+
76+
:::moniker range="azure-data-explorer"
77+
> [!div class="nextstepaction"]
78+
> <a href="https://dataexplorer.azure.com/clusters/help/databases/Samples?query=H4sIAAAAAAAAAysoyswrUShKLS7NKVGwVcgszivNydFIT82PT87JL04tLokvyAeqiM%2FPi8%2FJzEvVMNQx1FFIqcxLzM1M1qhWUCqpLEhVslLyAcoFlwDNSleq1dTUBABo%2F2JEVgAAAA%3D%3D" target="_blank">Run the query</a>
79+
::: moniker-end
80+
81+
```kusto
82+
print isnull(geo_closest_point_on_line(1,1, dynamic({ "type":"LineString"})))
83+
```
84+
85+
**Output**
86+
87+
| result |
88+
|--------|
89+
| true |
90+
91+
The following example returns a null result because of the invalid coordinate input.
92+
93+
:::moniker range="azure-data-explorer"
94+
> [!div class="nextstepaction"]
95+
> <a href="https://dataexplorer.azure.com/clusters/help/databases/Samples?query=H4sIAAAAAAAAAw3MPQrEIBBA4asMUylMkZ8usDfYbksRCWYIgjuKTooQ9u5r%2FT5ebUkUGvcrK7wgdblyNieXEHPp3DXUMkQoEnISNus0EawExy37N0XzAOpdGTd8j%2FzRsTuRMJbSjiS7csfNuZlmT26hxfuftfYPobhZWXUAAAA%3D" target="_blank">Run the query</a>
96+
::: moniker-end
97+
98+
```kusto
99+
print result = isnull(geo_closest_point_on_line(300, 3, dynamic({ "type":"LineString","coordinates":[[1,1],[2,2]]})))
100+
```
101+
102+
**Output**
103+
104+
| result |
105+
|--------|
106+
| true |

‎data-explorer/kusto/query/geo-closest-point-on-polygon-function.md‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
---
2+
title: geo_closest_point_on_polygon()
3+
description: Learn how to use the geo_closest_point_on_polygon() function to calculate a point on a polygon or a multipolygon, which is closest to a given point on Earth.
4+
ms.reviewer: mbrichko
5+
ms.topic: reference
6+
ms.date: 04/09/2025
7+
---
8+
# geo_closest_point_on_polygon()
9+
10+
> [!INCLUDE [applies](../includes/applies-to-version/applies.md)] [!INCLUDE [fabric](../includes/applies-to-version/fabric.md)] [!INCLUDE [azure-data-explorer](../includes/applies-to-version/azure-data-explorer.md)] [!INCLUDE [monitor](../includes/applies-to-version/monitor.md)] [!INCLUDE [sentinel](../includes/applies-to-version/sentinel.md)]
11+
12+
Calculates a point on a polygon or a multipolygon, which is closest to a given point on Earth.
13+
14+
## Syntax
15+
16+
`geo_closest_point_on_polygon(`*longitude*`,`*latitude*`,`*polygon*`)`
17+
18+
[!INCLUDE [syntax-conventions-note](../includes/syntax-conventions-note.md)]
19+
20+
## Parameters
21+
22+
|Name|Type|Required|Description|
23+
|--|--|--|--|
24+
| *longitude* | `real` | :heavy_check_mark: | Geospatial coordinate, longitude value in degrees. Valid value is a real number and in the range [-180, +180].|
25+
| *latitude* | `real` | :heavy_check_mark: | Geospatial coordinate, latitude value in degrees. Valid value is a real number and in the range [-90, +90].|
26+
| *polygon* | `dynamic` | :heavy_check_mark: | Polygon or multipolygon in the [GeoJSON format](https://tools.ietf.org/html/rfc7946).|
27+
28+
## Returns
29+
30+
A point in [GeoJSON Format](https://tools.ietf.org/html/rfc7946) and of a [dynamic](scalar-data-types/dynamic.md) data type on a polygon or multipolygon which is the closest to a given point on Earth. If polygon contains input point, the result with be the same point. If the coordinates or polygons are invalid, the query produces a null result.
31+
32+
> [!NOTE]
33+
>
34+
> * The geospatial coordinates are interpreted as represented by the [WGS-84](https://earth-info.nga.mil/index.php?dir=wgs84&action=wgs84) coordinate reference system.
35+
> * The [geodetic datum](https://en.wikipedia.org/wiki/Geodetic_datum) used for measurements on Earth is a sphere. Polygon edges are [geodesics](https://en.wikipedia.org/wiki/Geodesic) on the sphere.
36+
> * If input polygon edges are straight cartesian lines, consider using [geo_polygon_densify()](geo-polygon-densify-function.md) to convert planar edges to geodesics.
37+
> * In order to calculate a distance between the closest point on a polygon or multipolygon to a given point, use [geo_distance_point_to_polygon()](geo-distance-point-to-polygon-function.md)
38+
39+
**Polygon definition and constraints**
40+
41+
dynamic({"type": "Polygon","coordinates": [LinearRingShell, LinearRingHole_1, ..., LinearRingHole_N]})
42+
43+
dynamic({"type": "MultiPolygon","coordinates": [[LinearRingShell, LinearRingHole_1,..., LinearRingHole_N],..., [LinearRingShell, LinearRingHole_1,..., LinearRingHole_M]]})
44+
45+
* LinearRingShell is required and defined as a `counterclockwise` ordered array of coordinates [[lng_1,lat_1],...,[lng_i,lat_i],...,[lng_j,lat_j],...,[lng_1,lat_1]]. There can be only one shell.
46+
* LinearRingHole is optional and defined as a `clockwise` ordered array of coordinates [[lng_1,lat_1],...,[lng_i,lat_i],...,[lng_j,lat_j],...,[lng_1,lat_1]]. There can be any number of interior rings and holes.
47+
* LinearRing vertices must be distinct with at least three coordinates. The first coordinate must be equal to the last. At least four entries are required.
48+
* Coordinates [longitude, latitude] must be valid. Longitude must be a real number in the range [-180, +180] and latitude must be a real number in the range [-90, +90].
49+
* LinearRingShell encloses at most half of the sphere. LinearRing divides the sphere into two regions. The smaller of the two regions will be chosen.
50+
* LinearRing edge length must be less than 180 degrees. The shortest edge between the two vertices will be chosen.
51+
* LinearRings must not cross and must not share edges. LinearRings may share vertices.
52+
* Polygon doesn't necessarily contain its vertices.
53+
54+
> [!TIP]
55+
>
56+
> * Using literal polygons may result in better performance.
57+
58+
## Examples
59+
60+
The following example calculates a location in Central Park which is the closest to a given point.
61+
62+
:::moniker range="azure-data-explorer"
63+
> [!div class="nextstepaction"]
64+
> <a href="https://dataexplorer.azure.com/clusters/help/databases/Samples?query=H4sIAAAAAAAAA1WQy2rDMBBF94X8g9AqASfoNQ%2Bl9B%2B6N8YYRwQTRzK2Nqb032vHGNLVDHfOXO5MH7JoQ8xj09dDMz7El7jNsXl27fFH5nkI8iq%2FUz%2FfU5SFbFMab11scpjktSzLM9mLdx4Kpy7k0VfFJgErMojGggWzDlkpZFQWUHujd4yN0t4Z5yw7fnkgG0AyVgER7RhZTcy4WIH1G%2BYAtEVQa9mx9xxV9Xv6PHwMYxezuIdUt32awpTrIS1KneLSvI46bkEWX7HukoLi3z9Of0WJZPIhAQAA" target="_blank">Run the query</a>
65+
::: moniker-end
66+
67+
```kusto
68+
let central_park = dynamic({"type":"Polygon","coordinates":[[[-73.9495,40.7969],[-73.95807266235352,40.80068603561921],[-73.98201942443848,40.76825672305777],[-73.97317886352539,40.76455136505513],[-73.9495,40.7969]]]});
69+
print geo_closest_point_on_polygon(-73.9839, 40.7705, central_park)
70+
```
71+
72+
**Output**
73+
74+
|print_0|
75+
|---|
76+
|{"type": "Point","coordinates": [-73.981205580153926, 40.769359452843211] }|
77+
78+
79+
The following example returns a null result because of the invalid coordinate input.
80+
81+
:::moniker range="azure-data-explorer"
82+
> [!div class="nextstepaction"]
83+
> <a href="https://dataexplorer.azure.com/clusters/help/databases/Samples?query=H4sIAAAAAAAAAzWLwQrDIBBEf0X2pODBHHoJ9B96F5FgJAjbXVFzkJJ%2F75aS0xvmzdRWaKiW%2B4lDPVXpdCLqI3NMyD33ESvLIjJJwHkw6YdzdrH7pO1dkv7AmDXDquD192AhMbe90DZyF%2BG9d9YF6xf53RT8yhAuY8wX36BVQYUAAAA%3D" target="_blank">Run the query</a>
84+
::: moniker-end
85+
86+
```kusto
87+
print result = isnull(geo_closest_point_on_polygon(500,1,dynamic({"type": "Polygon","coordinates": [[[0,0],[10,10],[10,1],[0,0]]]})))
88+
```
89+
90+
**Output**
91+
92+
| result |
93+
|--------|
94+
| true |
95+
96+
The following example returns a null result because of the invalid polygon input.
97+
98+
:::moniker range="azure-data-explorer"
99+
> [!div class="nextstepaction"]
100+
> <a href="https://dataexplorer.azure.com/clusters/help/databases/Samples?query=H4sIAAAAAAAAA02KMQoDIRBFryJTKUyhbWDvkF5EFlcWwcyI4xYScvcY0mz1H%2B%2F91gsN1bNcdahNFaGrVn1mjqmyZBmx8XpEpgV1nkzaocNj0v4qSb9hzJbhoeD5r4CQmPtRaB9ZVvDeW7QBvbPo7vuzIXyMMV96app8hAAAAA%3D%3D" target="_blank">Run the query</a>
101+
::: moniker-end
102+
103+
```kusto
104+
print result = isnull(geo_closest_point_on_polygon(1,1,dynamic({"type": "Polygon","coordinates": [[[0,0],[10,10],[10,10],[0,0]]]})))
105+
```
106+
107+
**Output**
108+
109+
| result |
110+
|--------|
111+
| true |

‎data-explorer/kusto/query/geo-distance-2points-function.md‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ title: geo_distance_2points()
33
description: Learn how to use the geo_distance_2points() function to calculate the shortest distance between two geospatial coordinates on Earth.
44
ms.reviewer: mbrichko
55
ms.topic: reference
6-
ms.date: 08/11/2024
6+
ms.date: 04/09/2025
77
---
88
# geo_distance_2points()
99

@@ -13,7 +13,7 @@ Calculates the shortest distance in meters between two geospatial coordinates on
1313

1414
## Syntax
1515

16-
`geo_distance_2points(`*p1_longitude*`,`*p1_latitude*`,`*p2_longitude*`,`*p2_latitude*`)`
16+
`geo_distance_2points(`*p1_longitude*`,`*p1_latitude*`,`*p2_longitude*`,`*p2_latitude*`,`[ *use_spheroid* ]`)`
1717

1818
[!INCLUDE [syntax-conventions-note](../includes/syntax-conventions-note.md)]
1919

@@ -25,6 +25,7 @@ Calculates the shortest distance in meters between two geospatial coordinates on
2525
|*p1_latitude*| `real` | :heavy_check_mark: | The latitude value in degrees of the first geospatial coordinate. A valid value is in the range [-90, +90].|
2626
|*p2_longitude*| `real` | :heavy_check_mark: | The longitude value in degrees of the second geospatial coordinate. A valid value is in the range [-180, +180].|
2727
|*p2_latitude*| `real` | :heavy_check_mark: | The latitude value in degrees of the second geospatial coordinate. A valid value is in the range [-90, +90].|
28+
|*use_spheroid*| `bool` | | If `false` will use a sphere as [geodetic datum](https://en.wikipedia.org/wiki/Geodetic_datum) for measuring distance. If `true` will measure distance using spheroid. If unspecified, the default value `false` is used.
2829

2930
## Returns
3031

@@ -33,7 +34,7 @@ The shortest distance, in meters, between two geographic locations on Earth. If
3334
> [!NOTE]
3435
>
3536
> * The geospatial coordinates are interpreted as represented by the [WGS-84](https://earth-info.nga.mil/index.php?dir=wgs84&action=wgs84) coordinate reference system.
36-
> * The [geodetic datum](https://en.wikipedia.org/wiki/Geodetic_datum) used to measure distance on Earth is a sphere.
37+
> * Most applications should measure distance using sphere ('use_spheroid' = false) which is more performant. If extra precision is needed, 'use_spheroid' option can be set to 'true', for extra precision, which might be more relevant for bigger distances, which might get impacted due to earth curvature.
3738
3839
## Examples
3940

0 commit comments

Comments
 (0)