標準 SQL 中的地理函式

地理位置函式會對 BigQuery GEOGRAPHY 值進行運算或產生這些值。任何地理位置函式的簽名都是以 ST_ 開頭。BigQuery 支援下列函式,這些函示可用來分析地理資料、判斷地貌之間的空間關係,以及建構或操控 GEOGRAPHY

地理函式可以依據行為模式的不同劃分為以下類別:

  • 建構函式:利用座標或現有 GEOGRAPHY 建構新 GEOGRAPHY 值的函式,例如 ST_GEOGPOINT
  • 解析器:利用 WKTGeoJSON 等外部格式建立 GEOGRAPHY 的函式。例如 ST_GEOGFROMTEXT,這個函式可以利用 WKT 建立 GEOGRAPHY
  • 格式器:將 GEOGRAPHY 匯出為 WKT 和 GeoJSON 等外部格式的函式。例如 ST_ASTEXT,這個函式可以將 GEOGRAPHY 的格式設為 WKT。
  • 轉換:利用符合某項屬性的其他 GEOGRAPHY 產生新 GEOGRAPHY 的函式。範例包括 ST_INTERSECTIONST_BOUNDARY
  • 述詞:針對兩個 TRUE 之間的部分空間關係或針對地理位置的某項屬性傳回 FALSEGEOGRAPHY 的函式。這些函式通常用於篩選條件子句,例如 ST_DWITHIN 就是述詞。
  • 存取子:提供對 GEOGRAPHY 屬性的存取權限,但沒有副作用的函式,例如 ST_NUMPOINTS
  • 測量:對一或多個 GEOGRAPHY 的測量結果進行運算的函式,例如 ST_DISTANCE
  • Aggregate 函式:地理位置特定的 Aggregate 函式,例如 ST_UNION_AGG

如果任何輸入引數為 NULL,所有 BigQuery 地址位置函式都會傳回 NULL

ST_GEOGPOINT

ST_GEOGPOINT(longitude, latitude)

說明

建立具有單一點的 GEOGRAPHYST_GEOGPOINT 會利用指定的 FLOAT64 經度與緯度參數建立一個點,並在 GEOGRAPHY 值中傳回該點。

限制

  • 緯度必須介於 [-90, 90] 的範圍之間。若緯度超出此範圍,會發生錯誤。
  • 系統允許超出 [-180, 180] 範圍的精度;ST_GEOGPOINT 可使用輸入經度模數 360 取得位於 [-180, 180] 範圍內的經度。

傳回類型

GEOGRAPHY

ST_MAKELINE

ST_MAKELINE(geography_1, geography_2)
ST_MAKELINE(array_of_geography)

說明

按照所提供的順序串聯每個輸入 GEOGRAPHY 的點或線頂點,建立具備單一 LineString 的 GEOGRAPHY

ST_MAKELINE 有兩個變因。第一個變因的輸入內容必須是兩個 GEOGRAPHY,第二個變因的輸入內容必須是 GEOGRAPHY 類型的 ARRAY。在任一變因中,每個輸入內容的 GEOGRAPHY 必須包含下列其中一個值:

  • 只有一個點。
  • 只有一個 LineString。

ST_MAKELINE 的第一個變因中,如果輸入的其中一個 GEOGRAPHYNULL,則 ST_MAKELINE 會傳回 NULL。在第二個變因中,如果輸入 ARRAY 或輸入 ARRAY 中的任何元素為 NULL,則 ST_MAKELINE 會傳回 NULL

限制

每條邊線的跨度必須嚴格小於 180 度。

附註:BigQuery 的接合程序可能會捨棄足夠短的邊緣,並將兩個頂點接合在一起。例如,如果兩個輸入 GEOGRAPHY 各包含一個點,且兩個點之間的距離小於接合半徑,則這些點會接合在一起。在這種情況下,結果會是只有一個點的 GEOGRAPHY

傳回類型

GEOGRAPHY

ST_MAKEPOLYGON

ST_MAKEPOLYGON(geography_expression)
ST_MAKEPOLYGON(geography_expression, array_of_geography)

說明

利用 LineString 輸入建立含有單一多邊形的 GEOGRAPHY,當中的每個輸入 LineString 都用來建立多邊形環。

ST_MAKEPOLYOGN 有兩個變因。以第一個變因來說,輸入的 LineString 是由僅含一個 LineString 的單一 GEOGRAPHY 提供。以第二個變因來說,輸入內容含有單一 GEOGRAPHYGEOGRAPHY 陣列,且各項元素都包含一個 LineString。系統會使用兩個變因中的第一個 GEOGRAPHY 來建立多邊形殼。在輸入 ARRAY 中提供的其他 GEOGRAPHY 則指定了一個多邊形孔。每個只含一個 LineString 的輸入 GEOGRAPHY 必須滿足以下條件:

  • LineString 必須含有至少三個不同的頂點。
  • 必須關閉 LineString:也就是說,第一個和最後一個頂點必須相同。如果第一個和最後一個頂點不同,函式會從第一個頂點到最後一個頂點建立最終邊緣。

ST_MAKEPOLYGON 的第一個變因中,如果輸入的其中一個 GEOGRAPHYNULL,則 ST_MAKEPOLYGON 會傳回 NULL。在第二個變因中,如果輸入 ARRAY 或輸入 ARRAY 中的任何元素為 NULL,則 ST_MAKEPOLYOGN 會傳回 NULL

注意事項:ST_MAKEPOLYGON 接受空白的 GEOGRAPHY 輸入內容。ST_MAKEPOLYGON 會將空的 GEOGRAPHY 解譯為具有空的 LineString,如此會建立一個完整的環:即覆蓋整個地球的多邊形。

限制

總之,輸入環必須形成一個有效的多邊形:

  • 多邊形殼必須覆蓋每個多邊形孔。
  • 只能有一個多邊形殼 (必須是第一個輸入環)。這表示多邊形孔不能是巢狀。
  • 多邊形環只能在兩個環界線的頂點相交。

每條邊線的跨度必須嚴格小於 180 度。

每個多邊形環都會將球體分成兩個區域。ST_MAKEPOLYGON 的第一個輸入 LineString 會形成多邊形殼,並選擇內部為兩個區域中的較小者。每個後續的輸入 LineString 都會指定多邊形孔,因此多邊形的內部已有明確定義。如要定義多邊形殼,讓多邊形內部成為兩個區域中較大者,請參閱 ST_MAKEPOLYGONORIENTED 的說明。

附註:BigQuery 的接合程序可能會捨棄足夠短的邊緣,並將兩個頂點接合在一起。因此,當頂點接合在一起時,足夠小的多邊形孔可能會消失,或者輸出 GEOGRAPHY 可能只包含一條線或一個點。

傳回類型

GEOGRAPHY

ST_MAKEPOLYGONORIENTED

ST_MAKEPOLYGONORIENTED(array_of_geography)

說明

ST_MAKEPOLYGON 一樣,但每個輸入 LineString 的頂點順序決定了每個多邊形環的方向。多邊形環的方向會以下列方式定義多邊形的內部:如果有人按照輸入頂點的順序沿著多邊形界線前進,多邊形的內部會在左側。這適用於提供的每個多邊形環。

由於 ST_MAKEPOLYGONORIENTED 可以建構多邊形,使得內部位於多邊形環的任一側,因此多邊形建構函式的這個變體更具彈性。不過,多邊形環的正確方向對於建立所需多邊形而言至關重要。

如果輸入 ARRAY 或任何在 ARRAY 中的元素為 NULL,則 ST_MAKEPOLYGONORIENTED 會傳回 NULL

注意事項:ST_MAKEPOLYGONORIENTED 的輸入引數可能含有空白的 GEOGRAPHYST_MAKEPOLYGONORIENTED 會將空白的 GEOGRAPHY 解譯為具備空白 LineString,這樣會建立一個完整的環:覆蓋整個地球的多邊形。

限制

總之,輸入環必須形成一個有效的多邊形:

  • 多邊形殼必須覆蓋每個多邊形孔。
  • 只能有一個多邊形殼 (必須是第一個輸入環)。這表示多邊形孔不能是巢狀。
  • 多邊形環只能在兩個環界線的頂點相交。

每條邊線的跨度必須嚴格小於 180 度。

ST_MAKEPOLYGONORIENTED 依賴於每個 LineString 的輸入頂點順序來確定多邊形的方向。這適用於多邊形殼和任何多邊形孔。ST_MAKEPOLYGONORIENTED 預期所有多邊形孔的殼體方向都相反。請參閱 ST_MAKEPOLYGON 的說明,瞭解替代的多邊形建構函式和建立有效多邊形的其他限制。

附註:基於 BigQuery 的接合程序,系統會捨棄足夠短的邊緣,並將兩個頂點接合為單一點。因此,LineString 中的頂點可能會接合在一起,使一或多個邊緣消失。如此一來,足夠小的多邊形孔可能會消失,或者產生的 GEOGRAPHY 可能只包含一條線或一個點。

傳回類型

GEOGRAPHY

ST_GEOGFROMGEOJSON

ST_GEOGFROMGEOJSON(geojson_string)

說明

傳回與輸入 GeoJSON 表示法相對應的 GEOGRAPHY 值。

ST_GEOGFROMGEOJSON 接受符合 RFC 7946 規範的輸入值。

BigQuery GEOGRAPHY 具有球面測地線,而 GeoJSON Geometry 物件明確擁有平面邊緣。為了在這兩種邊緣系統之間進行轉換,BigQuery 會在必要時為線條加入額外的資料點,讓產生的邊緣序列維持在原始邊緣的 10 公尺範圍之內。

請參閱 ST_ASGEOJSON 說明,將 GEOGRAPHY 的格式設為 GeoJSON。

限制

輸入有下列限制:

  • ST_GEOGFROMGEOJSON 只接受 JSON 幾何圖形片段,且無法用來擷取整份 JSON 文件。
  • 輸入 JSON 片段必須包含 GeoJSON 幾何圖形類型,其中包括 PointMultiPointLineStringMultiLineStringPolygonMultiPolygonGeometryCollection。其他任何 GeoJSON 類型 (例如 FeatureFeatureCollection) 都會發生錯誤。
  • GeoJSON 幾何圖形類型 coordinates 成員中的位置必須只包含兩個元素。第一個元素是經度,第二個元素是緯度。因此,針對 coordinates 成員中的位置,ST_GEOGFROMGEOJSON 不支援選用的第三個元素。

傳回類型

GEOGRAPHY

ST_GEOGFROMTEXT

ST_GEOGFROMTEXT(wkt_string)
ST_GEOGFROMTEXT(wkt_string, oriented)

說明

傳回與輸入 WKT 表示法對應的 GEOGRAPHY 值。

這個函式支援 BOOLoriented 類型的選用參數。如果這個參數設定為 TRUE,系統會假設輸入中的任何多邊形方向如下:如果有人按照輸入頂點的順序沿著多邊形界線前進,多邊形的內部會在左側。這可讓 WKT 顯示大於半球的多邊形。如果 orientedFALSE 或遭到省略,這個函式會傳回具備較小面積的多邊形。另請參閱 ST_MAKEPOLYGONORIENTED 的說明,這個函式與 ST_GEOGFROMTEXToriented=TRUE 相似。

如要將 GEOGRAPHY 的格式設為 WKT,請使用 ST_ASTEXT

限制

假設所有輸入邊緣都是球面測地線,而「不是」平面直線。如要讀取平面投影中的資料,請考慮使用 ST_GEOGFROMGEOJSON。如要進一步瞭解球面測地線和平面線條之間的差異,請參閱座標系與邊緣一文。

傳回類型

GEOGRAPHY

範例

下列查詢會將 WKT 字串 POLYGON((0 0, 0 2, 2 2, 0 2, 0 0)) 讀取為非定向多邊形和定向多邊形,並檢查是否每個結果都包含點 (1, 1)

WITH polygon AS (SELECT 'Polygon((0 0, 0 2, 2 2, 2 0, 0 0))' AS p)
SELECT
  ST_CONTAINS(ST_GEOGFROMTEXT(p), ST_GEOGPOINT(1, 1)) AS fromtext_default,
  ST_CONTAINS(ST_GEOGFROMTEXT(p, FALSE), ST_GEOGPOINT(1, 1)) AS non_oriented,
  ST_CONTAINS(ST_GEOGFROMTEXT(p, TRUE),  ST_GEOGPOINT(1, 1)) AS oriented
FROM polygon;

+-------------------+---------------+-----------+
| fromtext_default  | non_oriented  | oriented  |
+-------------------+---------------+-----------+
| true              | true          | false     |
+-------------------+---------------+-----------+

ST_GEOGFROMWKB

ST_GEOGFROMWKB(wkb_bytes)

說明

傳回與輸入 WKB 表示法相對應的 GEOGRAPHY 值。

如要將 GEOGRAPHY 的格式設為 WKB,請使用 ST_ASBINARY

限制

假設所有輸入邊緣都是球面測地線,而「不是」平面直線。如要讀取平面投影中的資料,請考慮使用 ST_GEOGFROMGEOJSON

傳回類型

GEOGRAPHY

ST_GEOGPOINTFROMGEOHASH

ST_STGEOGPOINTFROMGEOHASH(geohash)

說明

傳回與 GeoHash 中定義的定界框中間點相對應的 GEOGRAPHY 值。

傳回類型

GEOGRAPHY

ST_ASGEOJSON

ST_ASGEOJSON(geography_expression)

說明

傳回輸入 GEOGRAPHY 的符合 RFC 7946 規範的 GeoJSON 表示法。

BigQuery GEOGRAPHY 具有球面測地線,而 GeoJSON Geometry 物件明確擁有平面邊緣。為了在這兩種邊緣系統之間進行轉換,BigQuery 會在必要時為線條加入額外的資料點,讓產生的邊緣序列維持在原始邊緣的 10 公尺範圍之內。

請參閱 ST_GEOGFROMGEOJSON 的說明,利用 GeoJSON 建立 GEOGRAPHY

傳回類型

STRING

ST_ASTEXT

ST_ASTEXT(geography_expression)

說明

傳回輸入 GEOGRAPHYWKT 表示法。

請參閱 ST_GEOGFROMTEXT 的說明,利用 WKT 建立 GEOGRAPHY

傳回類型

STRING

ST_GEOHASH

ST_GEOHASH(geography_expression, maxchars)

說明

傳回 geography_expressionGeoHash 表示法。產生的 GeoHash 最多將包含 maxchars 個字元。字元越少,精確度就越低 (或者,用另一種方式表達,就是定界框會越大)。

空白 GEOGRAPHY 物件的 ST_GeoHash 會傳回 NULL

限制

  • 系統僅支援表示單一點的 GEOGRAPHY 物件。
  • maxchars 的最大值是 20。

範例

傳回精確度為 10 個字元的西雅圖中心的 GeoHash。

SELECT ST_GEOHASH(ST_GEOGPOINT(-122.35, 47.62), 10) geohash

+--------------+
| geohash      |
+--------------+
| c22yzugqw7   |
+--------------+

傳回類型

STRING

ST_ASBINARY

ST_ASBINARY(geography_expression)

說明

傳回輸入 GEOGRAPHYWKB 表示法。

請參閱 ST_GEOGFROMWKB 的說明,利用 WKB 建立 GEOGRAPHY

傳回類型

BYTES

ST_BOUNDARY

ST_BOUNDARY(geography_expression)

說明

傳回單一 GEOGRAPHY,其中包含指定輸入 GEOGRAPHY 中每個元件的界線聯集。

GEOGRAPHY 每個元件的界線定義如下:

  • 點的界線為空。
  • LineString 的界線由 LineString 的端點組成。
  • 多邊形的界線由形成多邊形殼和每個多邊形孔的 LineString 組成。

傳回類型

GEOGRAPHY

ST_CENTROID

ST_CENTROID(geography_expression)

說明

傳回輸入 GEOGRAPHY 的「質心」來當做單一點 GEOGRAPHY

GEOGRAPHY 的「質心」GEOGRAPHY 中最高維度元件質心的加權平均值。每個維度中元件的質心定義如下:

  • 點的質心是輸入座標的算術平均值。
  • LineString 的質心是按長度加權的所有邊緣的質心。每個邊緣的質心是邊緣的測地線中點。
  • 多邊形的質心即為質量中心。

如果輸入 GEOGRAPHY 為空,函式會傳回空白 GEOGRAPHY

限制

GEOGRAPHY 的質心無法由地球表面的單一點定義 (儘管發生機率極低),這個函式會傳回具有確定性的任意點。只有在質心正好位於地球中心時 (例如一對對徑點的質心) 才會發生這種情況,而且發生的可能性極小。

傳回類型

GEOGRAPHY

ST_CLOSESTPOINT

ST_CLOSESTPOINT(geography_1, geography_2)
ST_CLOSESTPOINT(geography_1, geography_2, use_spheroid)

說明

傳回一個 GEOGRAPHY,其中包含 geography_1 中的點且該點與 geography_2 之間的距離可能最短。這表示 ST_CLOSESTPOINT 傳回的點和 geography_2 之間的距離小於或等於 geography_1 中的其他任何點和 geography_2 之間的距離。

如果任一輸入 GEOGRAPHY 為空,ST_CLOSESTPOINT 會傳回 NULL

選用的 use_spheroid 參數可決定此函式如何測量距離。如果 use_spheroidFALSE,函式會測量完美球體表面上的距離。

use_spheroid 參數目前僅支援 FALSE 值。use_spheroid 的預設值為 FALSE

傳回類型

GEOGRAPHY

ST_DIFFERENCE

ST_DIFFERENCE(geography_1, geography_2)

說明

傳回代表 geography_1geography_2 點集差異的 GEOGRAPHY

如果 geometry_1 完全包含在 geometry_2 中,則 ST_DIFFERENCE 會傳回空白 GEOGRAPHY

限制

BigQuery GEOGRAPHY 表示的基礎幾何物件與「封閉」的點集相對應。因此,ST_DIFFERENCE 可封閉 geography_1geography_2 的點集差異。這表示,如果 geography_1geography_2 相交,則 geography_2 的部分界線可能有差異。

傳回類型

GEOGRAPHY

ST_INTERSECTION

ST_INTERSECTION(geography_1, geography_2)

說明

傳回代表兩個輸入 GEOGRAPHY 之點集交集的 GEOGRAPHY。因此,交集中的每個點都會同時顯示在 geography_1geography_2 中。

如果兩個輸入 GEOGRAPHY 不相交,也就是說,沒有點同時顯示在輸入 geometry_1geometry_2 中,則函式會傳回空白 GEOGRAPHY

如要瞭解相關述詞函式,請參閱 ST_INTERSECTSST_DISJOINT 的說明。

傳回類型

GEOGRAPHY

ST_SNAPTOGRID

ST_SNAPTOGRID(geography_expression, grid_size)

說明

傳回輸入 GEOGRAPHY,其中的每個頂點都已與經度/緯度格線對齊。格線大小由 grid_size 參數 (單位為度數) 決定。

限制

系統不支援任意格線大小。grid_size 參數會四捨五入,因此格式為 \(10^n\),其中 \(-10 < n < 0\)。

傳回類型

GEOGRAPHY

ST_UNION

ST_UNION(geography_1, geography_2)
ST_UNION(array_of_geography)

說明

傳回代表所有輸入 GEOGRAPHY 點集聯集的 GEOGRAPHY

ST_UNION 有兩個變因。第一個變因的輸入內容必須是兩個 GEOGRAPHY,第二個變因的輸入則為 GEOGRAPHY 類型的 ARRAY

ST_UNION 的第一個變因中,如果輸入的 GEOGRAPHYNULL,則 ST_UNION 會傳回 NULL。在第二個變因中,如果輸入的 ARRAY 值為 NULL,則 ST_UNION 會傳回 NULL。對於並非 NULL 的輸入 ARRAY,會計算聯集並忽略 NULL 元素,以免影響輸出。

如要瞭解 ST_UNION 的 Aggregate 版本,請參閱 ST_UNION_AGG

傳回類型

GEOGRAPHY

ST_X

ST_X(geography_expression)

說明

傳回單一點輸入 GEOGRAPHY 的經度度數。

針對並非單一點的任何輸入 GEOGRAPHY,包括空白 GEOGRAPHY 在內,ST_X 都會傳會錯誤。請使用 SAFE. 前置字串取得 NULL

傳回類型

FLOAT64

範例

下列範例使用 ST_XST_Y 從單一點地理位置擷取座標。

WITH points AS
   (SELECT ST_GEOGPOINT(i, i + 1) AS p FROM UNNEST([0, 5, 12]) AS i)
 SELECT
   p,
   ST_X(p) as longitude,
   ST_Y(p) as latitude
FROM points;

+--------------+-----------+----------+
| p            | longitude | latitude |
+--------------+-----------+----------+
| POINT(0 1)   | 0.0       | 1.0      |
| POINT(5 6)   | 5.0       | 6.0      |
| POINT(12 13) | 12.0      | 13.0     |
+--------------+-----------+----------+

ST_Y

ST_Y(geography_expression)

說明

傳回單一點輸入 GEOGRAPHY 的緯度度數。

針對並非單一點的任何輸入 GEOGRAPHY,包括空白 GEOGRAPHY 在內,ST_Y 都會傳會錯誤。請改用 SAFE. 前置字串傳回 NULL

傳回類型

FLOAT64

範例

請參閱 ST_X 查看使用方式範例。

ST_CONTAINS

ST_CONTAINS(geography_1, geography_2)

說明

如果沒有 geography_2 的點位於 geography_1 之外,且內部相交,則會傳回 TRUE;否則會傳回 FALSE

注意事項:GEOGRAPHY「並不」包含本身的界線。請與 ST_COVERS 進行比較。

傳回類型

BOOL

範例

以下查詢會測試多邊形 POLYGON((1 1, 20 1, 10 20, 1 1)) 是否包含三個點 (0, 0)(1, 1)(10, 10) 的每一個,哪一個點分別位於多邊形的外部、界線上以及內部。

SELECT
  ST_GEOGPOINT(i, i) AS p,
  ST_CONTAINS(ST_GEOGFROMTEXT('POLYGON((1 1, 20 1, 10 20, 1 1))'),
              ST_GEOGPOINT(i, i)) AS `contains`
FROM UNNEST([0, 1, 10]) AS i;

+--------------+----------+
| p            | contains |
+--------------+----------+
| POINT(0 0)   | false    |
| POINT(1 1)   | false    |
| POINT(10 10) | true     |
+--------------+----------+

ST_COVEREDBY

ST_COVEREDBY(geography_1, geography_2)

說明

如果 geography_1geography_2 為空白,則會傳回 FALSE。如果沒有 geography_1 的點位於 geography_2 的外部,則會傳回 TRUE

在兩個 GEOGRAPHY ab 的情況下,ST_COVEREDBY(a, b) 會傳回與 ST_COVERS(b, a) 相同的結果。請注意,引數的順序是相反的。

傳回類型

BOOL

ST_COVERS

ST_COVERS(geography_1, geography_2)

說明

如果 geography_1geography_2 為空白,則會傳回 FALSE。如果沒有 geography_2 的點位於 geography_1 的外部,則會傳回 TRUE

傳回類型

BOOL

範例

以下查詢會測試多邊形 POLYGON((1 1, 20 1, 10 20, 1 1)) 是否包含三個點 (0, 0)(1, 1)(10, 10) 的每一個,哪一個點分別位於多邊形的外部、邊界上以及內部。

SELECT
  ST_GEOGPOINT(i, i) AS p,
  ST_COVERS(ST_GEOGFROMTEXT('POLYGON((1 1, 20 1, 10 20, 1 1))'),
            ST_GEOGPOINT(i, i)) AS `covers`
FROM UNNEST([0, 1, 10]) AS i;

+--------------+--------+
| p            | covers |
+--------------+--------+
| POINT(0 0)   | false  |
| POINT(1 1)   | true   |
| POINT(10 10) | true   |
+--------------+--------+

ST_DISJOINT

ST_DISJOINT(geography_1, geography_2)

說明

如果 geography_1geography_2 的交集為空,也就是說,geography_1 中沒有點也會出現在 geography_2 中,則會傳回 TRUE

ST_DISJOINTST_INTERSECTS 的邏輯否定。

傳回類型

GEOGRAPHY

ST_DWITHIN

ST_DWITHIN(geography_1, geography_2), distance)
ST_DWITHIN(geography_1, geography_2, distance, use_spheroid)

說明

如果 geography_1 中的至少一個點與 geography_2 中的一個點間距離小於或等於 distance 引數提供的距離,則會傳回 TRUE;否則,會傳回 FALSE。如果任一輸入 GEOGRAPHY 為空,ST_DWithin 會傳回 FALSE。在地球表面上,提供的 distance 以公尺為單位。

選用的 use_spheroid 參數可決定此函式如何測量距離。如果 use_spheroidFALSE,函式會測量完美球體表面上的距離。

use_spheroid 參數目前僅支援 FALSE 值。use_spheroid 的預設值為 FALSE

傳回類型

BOOL

ST_EQUALS

ST_EQUALS(geography_1, geography_2)

說明

如果 geography_1geography_2 表示相同的 GEOGRAPHY 值,則會傳回 TRUE。更準確地說,這表示下列其中一個條件成立:

  • ST_COVERS(geography_1, geography_2) = TRUEST_COVERS(geography_2, geography_1) = TRUE
  • geography_1geography_2 都為空白。

因此,即使點或頂點的順序不同,只要這些點仍表示相同的幾何結構,則兩個 GEOGRAPHY 也可能相等。

限制

ST_EQUALS 不保證是遞移性函式。

傳回類型

BOOL

ST_INTERSECTS

ST_INTERSECTS(geography_1, geography_2)

說明

如果 geography_1geography_2 的點集交集不是空的,則會傳回 TRUE。因此,如果至少有一個點出現在兩個輸入 TRUE 中,這個函式會傳回 GEOGRAPHY

如果 ST_INTERSECTS 傳回 TRUE,即表示 ST_DISJOINT 會傳回 FALSE

傳回類型

BOOL

ST_INTERSECTSBOX

ST_INTERSECTSBOX(geography, lng1, lat1, lng2, lat2)

說明

如果 geography 使矩形在 [lng1, lng2][lat1, lat2] 之間相交,則會傳回 TRUE。矩形的邊會遵循經度與緯度的常數線。lng1lng2 會指定圍繞矩形的最小與最大經線,而 lat1lat2 會指定圍繞矩形的最小與最大常數緯線。

請以度為單位指定所有經度與緯度的引數。

限制

輸入引數有以下限制:

  • 緯度應在 [-90, 90] 度數範圍內。
  • 經度應在 [-180, 180] 度數範圍內。

傳回類型

BOOL

ST_TOUCHES

ST_TOUCHES(geography_1, geography_2)

說明

如果滿足下列兩個條件,則會傳回 TRUE

  1. geography_1geography_2 相交。
  2. geography_1 的內部與 geography_2 的內部不相交。

傳回類型

BOOL

ST_WITHIN

ST_WITHIN(geography_1, geography_2)

說明

如果沒有 geography_1 的點位於 geography_2 的外部,且 geography_1geography_2 的內部相交,則會傳回 TRUE

在兩個地理位置 ab 之下,ST_WITHIN(a, b) 會傳回與 ST_CONTAINS(b, a) 相同的結果。請注意,引數的順序是相反的。

傳回類型

BOOL

ST_ISEMPTY

ST_ISEMPTY(geography_expression)

說明

如果 GEOGRAPHY 為空白,也就是說 GEOGRAPHY 並不包含任何點、線或多邊形,則會傳回 TRUE

附註:BigQuery 空 GEOGRAPHY 與特定幾何形狀無關聯。例如,運算式 ST_GEOGFROMTEXT('POINT EMPTY')ST_GEOGFROMTEXT('GEOMETRYCOLLECTION EMPTY') 的結果是相同的。

傳回類型

BOOL

ST_ISCOLLECTION

ST_ISCOLLECTION(geography_expression)

說明

如果點、LineString 與多邊形的總數大於一,則會傳回 TRUE

GEOGRAPHY 並不是集合。

傳回類型

BOOL

ST_DIMENSION

ST_DIMENSION(geography_expression)

說明

傳回輸入 GEOGRAPHY 中最高維度元素的維度。

每個可能元素的維度如下:

  • 點的維度為 0
  • LineString 的維度為 1
  • 多邊形的維度為 2

如果輸入 GEOGRAPHY 為空,ST_DIMENSION 會傳回 -1

傳回類型

INT64

ST_NUMPOINTS

ST_NUMPOINTS(geography_expression)

說明

傳回輸入 GEOGRAPHY 中的頂點數。這包括點數、LineString 頂點數與多邊形頂點數。

附註:多邊形環的第一個與最後一個頂點會計為不同的頂點。

傳回類型

INT64

ST_AREA

ST_AREA(geography_expression)
ST_AREA(geography_expression, use_spheroid)

說明

傳回輸入 GEOGRAPHY 中多邊形所涵蓋的面積,以平方公尺為單位。

如果 geography_expression 是點或線,則會傳回零。如果 geography_expression 是集合,則會傳回集合中的多邊形面積;如果集合不包含多邊形,則會傳回零。

選用的 use_spheroid 參數可決定此函式如何測量距離。如果 use_spheroidFALSE,函式會測量完美球體表面上的距離。

use_spheroid 參數目前僅支援 FALSE 值。use_spheroid 的預設值為 FALSE

傳回類型

FLOAT64

ST_DISTANCE

ST_DISTANCE(geography_1, geography_2)
ST_DISTANCE(geography_1, geography_2, use_spheroid)

說明

傳回兩個非空 GEOGRAPHY 之間的最短距離,以公尺為單位。

如果任一輸入 GEOGRAPHY 為空,ST_DISTANCE 會傳回 NULL

選用的 use_spheroid 參數可決定此函式如何測量距離。如果 use_spheroidFALSE,函式會測量完美球體表面上的距離。

use_spheroid 參數目前僅支援 FALSE 值。use_spheroid 的預設值為 FALSE

傳回類型

FLOAT64

ST_LENGTH

ST_LENGTH(geography_expression)
ST_LENGTH(geography_expression, use_spheroid)

說明

傳回輸入 GEOGRAPHY 中線條的總長度,以公尺為單位。

如果 geography_expression 是點或多邊形,則會傳回零。如果 geography_expression 是集合,則會傳回集合中的線條長度;如果集合不包含線條,則會傳回零。

選用的 use_spheroid 參數可決定此函式如何測量距離。如果 use_spheroidFALSE,函式會測量完美球體表面上的距離。

use_spheroid 參數目前僅支援 FALSE 值。use_spheroid 的預設值為 FALSE

傳回類型

FLOAT64

ST_MAXDISTANCE

ST_MAXDISTANCE(geography_1, geography_2)
ST_MAXDISTANCE(geography_1, geography_2, use_spheroid)

傳回兩個非空 GEOGRAPHY 之間的最長距離;也就是兩個頂點之間的距離,其中第一個頂點位於第一個 GEOGRAPHY 中,第二個頂點位於第二個 GEOGRAPHY 中。如果 geography_1geography_2 是相同的 GEOGRAPHY,此函式會傳回該 GEOGRAPHY 中兩個相距最遠頂點之間的距離。

如果任一輸入 GEOGRAPHY 為空,ST_MAXDISTANCE 會傳回 NULL

選用的 use_spheroid 參數可決定此函式如何測量距離。如果 use_spheroidFALSE,函式會測量完美球體表面上的距離。

use_spheroid 參數目前僅支援 FALSE 值。use_spheroid 的預設值為 FALSE

傳回類型

FLOAT64

ST_PERIMETER

ST_PERIMETER(geography_expression)
ST_PERIMETER(geography_expression, use_spheroid)

說明

傳回輸入 GEOGRAPHY 中多邊形邊界的長度,以公尺為單位。

如果 geography_expression 是點或線,則會傳回零。如果 geography_expression 是集合,則會傳回集合中的多邊形周長;如果集合不包含多邊形,則會傳回零。

選用的 use_spheroid 參數可決定此函式如何測量距離。如果 use_spheroidFALSE,函式會測量完美球體表面上的距離。

use_spheroid 參數目前僅支援 FALSE 值。use_spheroid 的預設值為 FALSE

傳回類型

FLOAT64

ST_UNION_AGG

ST_UNION_AGG(geography)

說明

傳回代表所有輸入 GEOGRAPHY 點集聯集的 GEOGRAPHY

ST_UNION_AGG 忽略 NULL 的輸入 GEOGRAPHY 值。

如要進一步瞭解 ST_UNION_AGG 的非 Aggregate 版本,請參閱 ST_UNION

傳回類型

GEOGRAPHY

ST_CENTROID_AGG

ST_CENTROID_AGG(geography)

說明

將輸入 GEOGRAPHY 集的質心計算為單一點 GEOGRAPHY

輸入 GEOGRAPHY 集中的「質心」是各個個別 GEOGRAPHY 質心的加權平均值。只有在輸入中具備最高維度的 GEOGRAPHY 才能成為完整集的質心。例如,如果輸入中包含具有線條的 GEOGRAPHY 以及只有點的 GEOGRAPHYST_CENTROID_AGG 會傳回具有線條的 GEOGRAPHY 的加權平均值,因為只有這些 GEOGRAPHY 具有最大維度。在這個例子中,系統計算 Aggregate 質心時 ST_CENTROID_AGG 會忽略只有點的 GEOGRAPHY

ST_CENTROID_AGG 忽略 NULL 的輸入 GEOGRAPHY 值。

如要進一步瞭解 ST_CENTROID_AGG 的非 Aggregate 版本和個別 GEOGRAPHY 值的質心定義,請參閱 ST_CENTROID

傳回類型

GEOGRAPHY

範例

以下查詢會計算一組 GEOGRAPHY 值的 aggregate 質心。第一個查詢的輸入中只包含點,因此每個值都可以成為 aggregate 質心。另外請注意,ST_CENTROID_AGG「並不」等於在 ST_UNION_AGG 的結果中呼叫 ST_CENTROID。聯集會去除重複結果,這一點與 ST_CENTROID_AGG 不同。第二項查詢的輸入含有混合維度,而只有在集中具備最高維度的值 (也就是線條) 會影響 Aggregate 質心。

SELECT ST_CENTROID_AGG(points) AS st_centroid_agg,
ST_CENTROID(ST_UNION_AGG(points)) AS centroid_of_union
FROM UNNEST([ST_GEOGPOINT(1, 5),
             ST_GEOGPOINT(1, 2),
             ST_GEOGPOINT(1, -1),
             ST_GEOGPOINT(1, -1)]) points;

+---------------------------+-------------------+
| st_centroid_agg           | centroid_of_union |
+---------------------------+-------------------+
| POINT(1 1.24961422620969) | POINT(1 2)        |
+---------------------------+-------------------+

SELECT ST_CENTROID_AGG(points) AS st_centroid_agg
FROM UNNEST([ST_GEOGPOINT(50, 26),
             ST_GEOGPOINT(34, 33.3),
             ST_GEOGFROMTEXT('LINESTRING(0 -1, 0 1)')
             ST_GEOGFROMTEXT('LINESTRING(0 1, 0 3)')]) points;

+-----------------+
| st_centroid_agg |
+-----------------+
| POINT(0 1)      |
+-----------------+
本頁內容對您是否有任何幫助?請提供意見:

傳送您對下列選項的寶貴意見...

這個網頁