Skip to content

Commit 9b23eaa

Browse files
Ja-DunnJa-Dunn
authored
Merge pull request #49585 from mamccrea/userstory1325979
geospatial article
2 parents 8c6faae + 67d457f commit 9b23eaa

File tree

2 files changed

+204
-0
lines changed

2 files changed

+204
-0
lines changed

‎articles/stream-analytics/TOC.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,8 @@
4242
href: stream-analytics-documentdb-output.md
4343
- name: Window functions
4444
href: stream-analytics-window-functions.md
45+
- name: Geospatial functions
46+
href: stream-analytics-geospatial-functions.md
4547
- name: Compatibility level
4648
href: stream-analytics-compatibility-level.md
4749
- name: Common query patterns

‎articles/stream-analytics/stream-analytics-geospatial-functions.md

Lines changed: 202 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,202 @@
1+
---
2+
title: Introduction to Azure Stream Analytics geospatial functions
3+
description: This article describes geospatial functions that are used in Azure Stream Analytics jobs.
4+
services: stream-analytics
5+
author: mamccrea
6+
ms.author: mamccrea
7+
manager: kfile
8+
ms.reviewer: mamccrea
9+
ms.service: stream-analytics
10+
ms.topic: conceptual
11+
ms.date: 09/04/2018
12+
---
13+
14+
# Introduction to Stream Analytics geospatial functions
15+
16+
Geospatial functions in Azure Stream Analytics enable real-time analytics on streaming geospatial data. With just a few lines of code, you can develop a production grade solution for complex scenarios.
17+
18+
Examples of scenarios that can benefit from geospatial functions include:
19+
20+
* Ride-sharing
21+
* Fleet management
22+
* Asset tracking
23+
* Geo-fencing
24+
* Phone tracking across cell sites
25+
26+
Stream Analytics Query Language has seven built-in geospatial functions: **CreateLineString**, **CreatePoint**, **CreatePolygon**, **ST_DISTANCE**, **ST_OVERLAPS**, **ST_INTERSECTS**, and **ST_WITHIN**.
27+
28+
## CreateLineString
29+
30+
The `CreateLineString` function accepts points and returns a GeoJSON LineString, which can be plotted as a line on a map. You must have at least two points to create a LineString. The LineString points will be connected in order.
31+
32+
The following query uses `CreateLineString` to create a LineString using three points. The first point is created from streaming input data, while the other two are created manually.
33+
34+
```SQL
35+
SELECT
36+
CreateLineString(CreatePoint(input.latitude, input.longitude), CreatePoint(10.0, 10.0), CreatePoint(10.5, 10.5))
37+
FROM input
38+
```
39+
40+
### Input example
41+
42+
|latitude|longitude|
43+
|--------------|---------------|
44+
|3.0|-10.2|
45+
|-87.33|20.2321|
46+
47+
### Output example
48+
49+
{"type" : "LineString", "coordinates" : [ [-10.2, 3.0], [10.0, 10.0], [10.5, 10.5] ]}
50+
51+
{"type" : "LineString", "coordinates" : [ [20.2321, -87.33], [10.0, 10.0], [10.5, 10.5] ]}
52+
53+
To learn more, visit the [CreateLineString](https://msdn.microsoft.com/azure/stream-analytics/reference/createlinestring) reference.
54+
55+
## CreatePoint
56+
57+
The `CreatePoint` function accepts a latitude and longitude and returns a GeoJSON point, which can be plotted on a map. Your latitudes and longitudes must be a **float** datatype.
58+
59+
The following example query uses `CreatePoint` to create a point using latitudes and longitudes from streaming input data.
60+
61+
```SQL
62+
SELECT
63+
CreatePoint(input.latitude, input.longitude)
64+
FROM input
65+
```
66+
67+
### Input example
68+
69+
|latitude|longitude|
70+
|--------------|---------------|
71+
|3.0|-10.2|
72+
|-87.33|20.2321|
73+
74+
### Output example
75+
76+
{"type" : "Point", "coordinates" : [-10.2, 3.0]}
77+
78+
{"type" : "Point", "coordinates" : [20.2321, -87.33]}
79+
80+
To learn more, visit the [CreatePoint](https://msdn.microsoft.com/azure/stream-analytics/reference/createpoint) reference.
81+
82+
## CreatePolygon
83+
84+
The `CreatePolygon` function accepts points and returns a GeoJSON polygon record. The order of points must follow right-hand ring orientation, or counter-clockwise. Imagine walking from one point to another in the order they were declared. The center of the polygon would be to your left the entire time.
85+
86+
The following example query uses `CreatePolygon` to create a polygon from three points. The first two points are created manually, and the last point is created from input data.
87+
88+
```SQL
89+
SELECT
90+
CreatePolygon(CreatePoint(input.latitude, input.longitude), CreatePoint(10.0, 10.0), CreatePoint(10.5, 10.5), CreatePoint(input.latitude, input.longitude))
91+
FROM input
92+
```
93+
94+
### Input example
95+
96+
|latitude|longitude|
97+
|--------------|---------------|
98+
|3.0|-10.2|
99+
|-87.33|20.2321|
100+
101+
### Output example
102+
103+
{"type" : "Polygon", "coordinates" : [[ [-10.2, 3.0], [10.0, 10.0], [10.5, 10.5], [-10.2, 3.0] ]]}
104+
105+
{"type" : "Polygon", "coordinates" : [[ [20.2321, -87.33], [10.0, 10.0], [10.5, 10.5], [20.2321, -87.33] ]]}
106+
107+
To learn more, visit the [CreatePolygon](https://msdn.microsoft.com/azure/stream-analytics/reference/createpolygon) reference.
108+
109+
110+
## ST_DISTANCE
111+
The `ST_DISTANCE` function returns the distance between two points in meters.
112+
113+
The following query uses `ST_DISTANCE` to generate an event when a gas station is less than 10 km from the car.
114+
115+
```SQL
116+
SELECT Cars.Location, Station.Location
117+
FROM Cars c
118+
JOIN Station s ON ST_DISTANCE(c.Location, s.Location) < 10 * 1000
119+
```
120+
121+
To learn more, visit the [ST_DISTANCE](https://msdn.microsoft.com/azure/stream-analytics/reference/st-distance) reference.
122+
123+
## ST_OVERLAPS
124+
The `ST_OVERLAPS` function compares two polygons. If the polygons overlap, the function returns a 1. The function returns 0 if the polygons don't overlap.
125+
126+
The following query uses `ST_OVERLAPS` to generate an event when a building is within a possible flooding zone.
127+
128+
```SQL
129+
SELECT Building.Polygon, Building.Polygon
130+
FROM Building b
131+
JOIN Flooding f ON ST_OVERLAPS(b.Polygon, b.Polygon)
132+
```
133+
134+
The following example query generates an event when a storm is heading towards a car.
135+
136+
```SQL
137+
SELECT Cars.Location, Storm.Course
138+
FROM Cars c, Storm s
139+
JOIN Storm s ON ST_OVERLAPS(c.Location, s.Course)
140+
```
141+
142+
To learn more, visit the [ST_OVERLAPS](https://msdn.microsoft.com/azure/stream-analytics/reference/st-overlaps) reference.
143+
144+
## ST_INTERSECTS
145+
The `ST_INTERSECTS` function compares two LineString. If the LineString intersect, then the function returns 1. The function returns 0 if the LineString don't intersect.
146+
147+
The following example query uses `ST_INTERSECTS` to determine if a paved road intersects a dirt road.
148+
149+
```SQL
150+
SELECT
151+
ST_INTERSECTS(input.pavedRoad, input.dirtRoad)
152+
FROM input
153+
```
154+
155+
### Input example
156+
157+
|datacenterArea|stormArea|
158+
|--------------------|---------------|
159+
|{“type”:”LineString”, “coordinates”: [ [-10.0, 0.0], [0.0, 0.0], [10.0, 0.0] ]}|{“type”:”LineString”, “coordinates”: [ [0.0, 10.0], [0.0, 0.0], [0.0, -10.0] ]}|
160+
|{“type”:”LineString”, “coordinates”: [ [-10.0, 0.0], [0.0, 0.0], [10.0, 0.0] ]}|{“type”:”LineString”, “coordinates”: [ [-10.0, 10.0], [0.0, 10.0], [10.0, 10.0] ]}|
161+
162+
### Output example
163+
164+
1
165+
166+
0
167+
168+
To learn more, visit the [ST_INTERSECTS](https://msdn.microsoft.com/azure/stream-analytics/reference/st-intersects) reference.
169+
170+
## ST_WITHIN
171+
The `ST_WITHIN` function determines whether a point or polygon is within a polygon. If the polygon contains the point or polygon, the function will return 1. The function will return 0 if the point or polygon isn't located within the declared polygon.
172+
173+
The following example query uses `ST_WITHIN` to determine whether the delivery destination point is within the given warehouse polygon.
174+
175+
```SQL
176+
SELECT
177+
ST_WITHIN(input.deliveryDestination, input.warehouse)
178+
FROM input
179+
```
180+
181+
### Input example
182+
183+
|deliveryDestination|warehouse|
184+
|-------------------------|---------------|
185+
|{“type”:”Point”, “coordinates”: [76.6, 10.1]}|{“type”:”Polygon”, “coordinates”: [ [0.0, 0.0], [10.0, 0.0], [10.0, 10.0], [0.0, 10.0], [0.0, 0.0] ]}|
186+
|{“type”:”Point”, “coordinates”: [15.0, 15.0]}|{“type”:”Polygon”, “coordinates”: [ [10.0, 10.0], [20.0, 10.0], [20.0, 20.0], [10.0, 20.0], [10.0, 10.0] ]}|
187+
188+
### Output example
189+
190+
0
191+
192+
1
193+
194+
To learn more, visit the [ST_WITHIN](https://msdn.microsoft.com/azure/stream-analytics/reference/st-within) reference.
195+
196+
## Next steps
197+
198+
* [Introduction to Azure Stream Analytics](stream-analytics-introduction.md)
199+
* [Get started using Azure Stream Analytics](stream-analytics-real-time-fraud-detection.md)
200+
* [Scale Azure Stream Analytics jobs](stream-analytics-scale-jobs.md)
201+
* [Azure Stream Analytics Query Language Reference](https://msdn.microsoft.com/library/azure/dn834998.aspx)
202+
* [Azure Stream Analytics Management REST API Reference](https://msdn.microsoft.com/library/azure/dn835031.aspx)

0 commit comments

Comments
 (0)