지리 함수

{# END}

지리 함수는 BigQuery GEOGRAPHY 값에 대해 작동하거나 이러한 값을 생성합니다. 지리 함수의 서명은 ST_로 시작합니다. BigQuery는 지리 데이터 분석, 지형 지물 간의 공간적 관계 파악, GEOGRAPHY 구성 또는 조작에 사용할 수 있는 다음과 같은 함수를 지원합니다.

입력 인수가 NULL이면 모든 BigQuery 지리 함수는 NULL을 반환합니다.

카테고리

지리 함수는 함수 동작에 따라 다음과 같은 카테고리로 분류됩니다.

카테고리	함수	설명
생성자	`ST_GEOGPOINT` `ST_MAKELINE` `ST_MAKEPOLYGON` `ST_MAKEPOLYGONORIENTED`	좌표 또는 기존 지리로부터 새 지리 값을 빌드하는 함수입니다.
파서	`ST_GEOGFROM` `ST_GEOGFROMGEOJSON` `ST_GEOGFROMTEXT` `ST_GEOGFROMWKB` `ST_GEOGPOINTFROMGEOHASH`	WKT 및 GeoJSON 같은 외부 형식을 사용하여 지리를 생성하는 함수입니다.
포맷터	`ST_ASBINARY` `ST_ASGEOJSON` `ST_ASTEXT` `ST_GEOHASH`	WKT 같은 외부 형식으로 지리를 내보내는 함수입니다.
변환	`ST_BOUNDARY` `ST_BUFFER` `ST_BUFFERWITHTOLERANCE` `ST_CENTROID` `ST_CENTROID_AGG`(집계) `ST_CLOSESTPOINT` `ST_CONVEXHULL` `ST_DIFFERENCE` `ST_EXTERIORRING` `ST_INTERIORRINGS` `ST_INTERSECTION` `ST_SIMPLIFY` `ST_SNAPTOGRID` `ST_UNION` `ST_UNION_AGG`(집계)	입력에 따라 새 지리를 생성하는 함수입니다.
접근자	`ST_DIMENSION` `ST_DUMP` `ST_ENDPOINT` `ST_GEOMETRYTYPE` `ST_ISCOLLECTION` `ST_ISEMPTY` `ST_NPOINTS` `ST_NUMGEOMETRIES` `ST_NUMPOINTS` `ST_POINTN` `ST_STARTPOINT` `ST_X` `ST_Y`	지리 속성에 부작용 없이 액세스할 수 있는 함수입니다.
조건자	`ST_CONTAINS` `ST_COVEREDBY` `ST_COVERS` `ST_DISJOINT` `ST_DWITHIN` `ST_EQUALS` `ST_INTERSECTS` `ST_INTERSECTSBOX` `ST_TOUCHES` `ST_WITHIN`	두 지리 또는 지리의 속성 사이의 공간적 관계에 `TRUE` 또는 `FALSE`를 반환하는 함수입니다. 이 함수는 일반적으로 필터 절에 사용됩니다.
조치	`ST_ANGLE` `ST_AREA` `ST_AZIMUTH` `ST_BOUNDINGBOX` `ST_DISTANCE` `ST_EXTENT`(집계) `ST_LENGTH` `ST_MAXDISTANCE` `ST_PERIMETER`	하나 이상의 지리에서 측정값을 계산하는 함수입니다.
클러스터링	`ST_CLUSTERDBSCAN`	지역에서 클러스터링을 수행하는 함수입니다.
S2 함수	`S2_CELLIDFROMPOINT` `S2_COVERINGCELLIDS`	GEOGRAPHY의 S2 셀 범위 작업을 위한 함수입니다.

S2_CELLIDFROMPOINT

S2_CELLIDFROMPOINT(point_geography[, level => cell_level])

설명

GEOGRAPHY 지점을 포함하는 S2 셀 ID를 반환합니다.

선택적 INT64 매개변수 level은 반환된 셀의 S2 셀 수준을 지정합니다. 이 인수 이름 지정은 선택사항입니다.

이 기능은 S2 Geometry Library를 활용하는 시스템과의 상호 운용성을 위한 고급 기능입니다.

제약조건

셀 ID를 부호 없는 64비트 정수 표현과 동등한 부호가 있는 INT64 비트로 반환합니다.
음수 셀 ID를 반환할 수 있습니다.
유효한 S2 셀 수준은 0~30입니다.
level을 명시적으로 지정하지 않으면 기본값은 30입니다.
이 함수는 단일 지점 GEOGRAPHY만 지원합니다. 입력이 여러 지점, 유도선, 다각형이거나 빈 GEOGRAPHY일 수 있는 경우 SAFE 프리픽스를 사용합니다.
복잡한 GEOGRAPHY의 범위를 계산하려면 S2_COVERINGCELLIDS를 사용합니다.

반환 유형

INT64

예시

WITH data AS (
  SELECT 1 AS id, ST_GeogPoint(-122, 47) AS geo
  UNION ALL
  -- empty geography is not supported
  SELECT 2 AS id, ST_GeogFromText('POINT EMPTY') AS geo
  UNION ALL
  -- only points are supported
  SELECT 3 AS id, ST_GeogFromText('LINESTRING(1 2, 3 4)') AS geo
)
SELECT id,
       SAFE.S2_CellIdFromPoint(geo) cell30,
       SAFE.S2_CellIdFromPoint(geo, level => 10) cell10
FROM data;

+----+---------------------+---------------------+
| id | cell30              | cell10              |
+----+---------------------+---------------------+
| 1  | 6093613931972369317 | 6093613287902019584 |
| 2  | NULL                | NULL                |
| 3  | NULL                | NULL                |
+----+---------------------+---------------------+

S2_COVERINGCELLIDS

S2_COVERINGCELLIDS(
    geography
    [, min_level => cell_level]
    [, max_level => cell_level]
    [, max_cells => max_cells]
    [, buffer => buffer])

설명

입력된 GEOGRAPHY를 포함하는 S2 셀 ID의 배열을 반환합니다. 함수는 최대 max_cells개의 셀을 반환합니다. 선택적 인수 min_level와 max_level는 반환된 S2 셀의 최소 및 최대 수준을 지정합니다. 배열 크기는 선택적 max_cells 인수로 제한됩니다. 선택사항인 buffer 인수는 버퍼링 계수를 미터 단위로 지정합니다. 대상 리전이 입력 지리 범위에서 이 양만큼 확장됩니다.

이 기능은 S2 Geometry Library를 활용하는 시스템과의 상호 운용성을 위한 고급 기능입니다.

제약조건

셀 ID를 부호 없는 64비트 정수 표현과 동등한 부호가 있는 INT64 비트로 반환합니다.
음수 셀 ID를 반환할 수 있습니다.
유효한 S2 셀 수준은 0~30입니다.
max_cells를 명시적으로 지정하지 않으면 기본값은 8입니다.
buffer는 음수가 아니어야 합니다. 명시적으로 지정되지 않으면 기본값은 0.0미터입니다.

반환 유형

ARRAY<INT64>

예시

WITH data AS (
  SELECT 1 AS id, ST_GeogPoint(-122, 47) AS geo
  UNION ALL
  SELECT 2 AS id, ST_GeogFromText('POINT EMPTY') AS geo
  UNION ALL
  SELECT 3 AS id, ST_GeogFromText('LINESTRING(-122.12 47.67, -122.19 47.69)') AS geo
)
SELECT id, S2_CoveringCellIDs(geo, min_level => 12) cells
FROM data;

+----+--------------------------------------------------------------------------------------+
| id | cells                                                                                |
+----+--------------------------------------------------------------------------------------+
| 1  | [6093613931972369317]                                                                |
| 2  | []                                                                                   |
| 3  | [6093384954555662336, 6093390709811838976, 6093390735581642752, 6093390740145045504, |
|    |  6093390791416217600, 6093390812891054080, 6093390817187069952, 6093496378892222464] |
+----+--------------------------------------------------------------------------------------+

ST_ANGLE

ST_ANGLE(point_geography_1, point_geography_2, point_geography_3)

설명

2개의 교차선을 나타내는 3점 GEOGRAPHY 값을 사용합니다. 이 선 사이의 각도를 반환합니다. 점 2 및 점 1은 첫 번째 줄을 나타내고 점 2 및 점 3은 두 번째 줄을 나타냅니다. 이 선 사이의 각도는 라디안 단위이며 [0, 2pi) 범위입니다. 각도는 첫 번째 선에서 두 번째 선까지 시계 방향으로 측정됩니다.

ST_ANGLE에는 다음과 같은 특이 사례가 있습니다.

점 2와 3이 같은 경우 NULL을 반환합니다.
점 2와 1이 같은 경우 NULL을 반환합니다.
점 2와 3이 정확히 대척점이면 NULL을 반환합니다.
점 2와 1이 정확히 대척점이면 NULL을 반환합니다.
입력 지리가 단일 점이 아니거나 빈 지리인 경우 오류가 발생합니다.

반환 유형

FLOAT64

예시

WITH geos AS (
  SELECT 1 id, ST_GEOGPOINT(1, 0) geo1, ST_GEOGPOINT(0, 0) geo2, ST_GEOGPOINT(0, 1) geo3 UNION ALL
  SELECT 2 id, ST_GEOGPOINT(0, 0), ST_GEOGPOINT(1, 0), ST_GEOGPOINT(0, 1) UNION ALL
  SELECT 3 id, ST_GEOGPOINT(1, 0), ST_GEOGPOINT(0, 0), ST_GEOGPOINT(1, 0) UNION ALL
  SELECT 4 id, ST_GEOGPOINT(1, 0) geo1, ST_GEOGPOINT(0, 0) geo2, ST_GEOGPOINT(0, 0) geo3 UNION ALL
  SELECT 5 id, ST_GEOGPOINT(0, 0), ST_GEOGPOINT(-30, 0), ST_GEOGPOINT(150, 0) UNION ALL
  SELECT 6 id, ST_GEOGPOINT(0, 0), null, null UNION ALL
  SELECT 7 id, null, ST_GEOGPOINT(0, 0), null UNION ALL
  SELECT 8 id, null, null, ST_GEOGPOINT(0, 0))
SELECT ST_ANGLE(geo1,geo2,geo3) AS angle FROM geos ORDER BY id;

+---------------------+
| angle               |
+---------------------+
| 4.71238898038469    |
| 0.78547432161873854 |
| 0                   |
| NULL                |
| NULL                |
| NULL                |
| NULL                |
| NULL                |
+---------------------+

ST_AREA

ST_AREA(geography_expression[, use_spheroid])

설명

입력 GEOGRAPHY에서 다각형이 차지하는 면적을 제곱미터 단위로 반환합니다.

geography_expression이 점 또는 선이면 0이 반환됩니다. geography_expression이 컬렉션이면 컬렉션의 다각형 면적이 반환됩니다. 컬렉션에 다각형이 포함되지 않았으면 0이 반환됩니다.

선택적인 use_spheroid 매개변수는 이 함수의 거리 측정 방식을 결정합니다. use_spheroid가 FALSE이면 이 함수는 완전한 구의 표면에서 거리를 측정합니다.

use_spheroid 매개변수는 현재 FALSE 값만 지원합니다. use_spheroid의 기본값은 FALSE입니다.

반환 유형

FLOAT64

ST_ASBINARY

ST_ASBINARY(geography_expression)

설명

입력된 GEOGRAPHY의 WKB 표현을 반환합니다.

WKB를 사용하여 GEOGRAPHY를 구성하려면 ST_GEOGFROMWKB를 참조하세요.

반환 유형

BYTES

ST_ASGEOJSON

ST_ASGEOJSON(geography_expression)

설명

입력된 GEOGRAPHY의 RFC 7946 준수 GeoJSON 표현을 반환합니다.

BigQuery GEOGRAPHY에는 구면 측지 모서리가 사용되는 반면 GeoJSON Geometry 객체에는 명시적으로 평면 모서리가 사용됩니다. 이 두 유형의 모서리가 서로 변환되도록 BigQuery는 필요한 경우 선에 점을 추가하여 변환된 일련의 모서리가 원래 모서리로부터 10미터 이내에서 유지되도록 합니다.

GeoJSON을 사용하여 GEOGRAPHY를 구성하려면 ST_GEOGFROMGEOJSON을 참조하세요.

반환 유형

STRING

ST_ASTEXT

ST_ASTEXT(geography_expression)

설명

입력된 GEOGRAPHY의 WKT 표현을 반환합니다.

WKT를 사용하여 GEOGRAPHY를 구성하려면 ST_GEOGFROMTEXT를 참조하세요.

반환 유형

STRING

ST_AZIMUTH

ST_AZIMUTH(point_geography_1, point_geography_2)

설명

2개의 점 GEOGRAPHY 값을 사용하고 점 1과 2에 의해 형성된 선분의 방위각을 반환합니다. 방위각은 진북을 향한 점과 점 1에서 점 2 사이의 선분을 기준으로 측정된 라디안 단위 각도입니다.

양의 각도는 구의 표면에서 시계 방향으로 측정됩니다. 예를 들어 선분의 방위는 다음과 같습니다.

북쪽: 0
동쪽: PI/2
남쪽: PI
서쪽: 3PI/2

ST_AZIMUTH에는 다음과 같은 특이 사례가 있습니다.

두 입력 지점이 동일한 경우 NULL을 반환합니다.
두 입력 지점이 정확히 대척점인 경우 NULL을 반환합니다.
입력 지리적 위치 중 하나가 단일 점이 아니거나 빈 지리인 경우 오류가 발생합니다.

반환 유형

FLOAT64

예시


WITH geos AS (
  SELECT 1 id, st_geogpoint(1, 0) geo1, st_geogpoint(0, 0) geo2 UNION ALL
  SELECT 2, st_geogpoint(0, 0), st_geogpoint(1, 0) UNION ALL
  SELECT 3, st_geogpoint(0, 0), st_geogpoint(0, 1) UNION ALL
  -- identical
  SELECT 4, st_geogpoint(0, 0) geo1, st_geogpoint(0, 0) geo2 UNION ALL
  -- antipode
  SELECT 5, st_geogpoint(-30, 0), st_geogpoint(150, 0) UNION ALL
  -- nulls
  SELECT 6, st_geogpoint(0, 0), null UNION ALL
  SELECT 7, null, st_geogpoint(0, 0))
SELECT ST_AZIMUTH(geo1, geo2) AS azimuth FROM geos ORDER BY id;

+--------------------+
| azimuth            |
+--------------------+
| 4.71238898038469   |
| 1.5707963267948966 |
| 0                  |
| NULL               |
| NULL               |
| NULL               |
| NULL               |
+--------------------+

ST_BOUNDARY

ST_BOUNDARY(geography_expression)

설명

지정된 입력 GEOGRAPHY에 있는 각 구성요소 경계의 합집합을 포함하는 단일 GEOGRAPHY를 반환합니다.

GEOGRAPHY의 각 구성요소 경계는 다음과 같이 정의됩니다.

점의 경계는 비어 있습니다.
유도선의 경계는 유도선의 끝점으로 구성됩니다.
다각형의 경계는 다각형 셸을 형성하는 유도선과 각 다각형 구멍으로 구성됩니다.

반환 유형

GEOGRAPHY

ST_BOUNDINGBOX

ST_BOUNDINGBOX(geography_expression)

설명

지정된 geography의 경계 상자를 나타내는 STRUCT를 반환합니다. 경계 상자는 geography를 둘러싸는 최소한의 직사각형입니다. 직사각형의 모서리는 상수 경도 및 위도 선을 따릅니다.

주의사항:

입력이 NULL이거나 빈 지리이면 NULL을 반환합니다.
더 작은 직사각형이 허용될 경우 경계 상자가 반대 자오선을 통과할 수 있습니다. 이 경우 경계 상자의 경도 경계는 [-180, 180] 범위를 벗어나므로 xmin은 동쪽 값 xmax보다 작습니다.

반환 유형

STRUCT<xmin FLOAT64, ymin FLOAT64, xmax FLOAT64, ymax FLOAT64>할 수 있습니다.

경계 상자 부분:

xmin: 직사각형의 경계를 이루는 서쪽 상수 경도 선입니다.
xmax: 직사각형의 경계를 이루는 가장 동쪽 상수 경도 선입니다.
ymin: 직사각형의 경계를 이루는 최소 상수 위도 선입니다.
ymax: 직사각형의 경계를 이루는 최대 상수 위도 선입니다.

예시

WITH data AS (
  SELECT 1 id, ST_GEOGFROMTEXT('polygon((-125 48, -124 46, -117 46, -117 49, -125 48))') g
  UNION ALL
  SELECT 2 id, ST_GEOGFROMTEXT('polygon((172 53, -130 55, -141 70, 172 53))') g
  UNION ALL
  SELECT 3 id, ST_GEOGFROMTEXT('point empty') g
  UNION ALL
  SELECT 4 id, ST_GEOGFROMTEXT('polygon((172 53, -141 70, -130 55, 172 53))', oriented => TRUE)
)
SELECT id, ST_BOUNDINGBOX(g) AS box
FROM data

+----+------------------------------------------+
| id | box                                      |
+----+------------------------------------------+
| 1  | {xmin:-125, ymin:46, xmax:-117, ymax:49} |
| 2  | {xmin:172, ymin:53, xmax:230, ymax:70}   |
| 3  | NULL                                     |
| 4  | {xmin:-180, ymin:-90, xmax:180, ymax:90} |
+----+------------------------------------------+

ST_BOUNDINGBOX의 집계 버전은 ST_EXTENT를 참조하세요.

ST_BUFFER

ST_BUFFER(
    geography,
    buffer_radius
    [, num_seg_quarter_circle => num_segments]
    [, use_spheroid => boolean_expression]
    [, endcap => endcap_style]
    [, side => line_side])

설명

입력 GEOGRAPHY 주위의 버퍼를 나타내는 GEOGRAPHY를 반환합니다. 이 함수는 ST_BUFFERWITHTOLERANCE와 비슷하지만 결과 geography가 이상적인 버퍼 반경에서 벗어날 수 있는지 결정하기 위해 허용 오차를 제공하는 대신 세그먼트 수를 지정합니다.

geography: 버퍼 반경으로 둘러싸는 입력 GEOGRAPHY입니다.
buffer_radius: 입력 지리 주위의 버퍼 반경을 나타내는 DOUBLE입니다. 반경은 미터 단위입니다. 음수인 buffer_radius로 버퍼링되면 다각형이 축소됩니다. 한 점으로 축소된 다각형 셸 및 구멍은 삭제됩니다.
num_seg_quarter_circle: (선택사항) DOUBLE을 분기의 근사치를 계산하는 데 사용되는 세그먼트 수를 지정합니다. 기본값은 8.0입니다. 이 인수 이름 지정은 선택사항입니다.
endcap: (선택사항) STRING을 사용하면 2개의 끝부분 스타일 중 하나인 ROUND 및 FLAT 중 하나를 지정할 수 있습니다. 기본값은 ROUND입니다. 이 옵션은 버퍼링된 유도선의 끝부분에만 영향을 미칩니다.
side: (선택사항) STRING를 사용하면 BOTH, LEFT, RIGHT 행의 세 가지 방법 중 하나를 지정할 수 있습니다. 기본값은 BOTH입니다. 이 옵션은 유도선이 버퍼링되는 방식에만 영향을 미칩니다.
use_spheroid: (선택사항) BOOL은 이 함수가 거리를 측정하는 방식을 결정합니다. use_spheroid가 FALSE이면 이 함수는 완전한 구의 표면에서 거리를 측정합니다. use_spheroid 매개변수는 현재 FALSE 값만 지원합니다. use_spheroid의 기본값은 FALSE입니다.

반환 유형

GEOGRAPHY

예시

다음 예시에서는 한 지점의 ST_BUFFER 결과를 보여줍니다. 버퍼링된 점은 근사치의 원입니다. num_seg_quarter_circle = 2인 경우 1/4 원에 두 개의 선 세그먼트가 있으므로 버퍼링된 원은 8개의 변을 가지며 ST_NUMPOINTS는 9개 꼭짓점을 반환합니다. num_seg_quarter_circle = 8인 경우 1/4 원에 8개의 선 세그먼트가 있으므로 버퍼링된 원은 32개의 변이 있고 ST_NUMPOINTS는 33개의 꼭짓점을 반환합니다.

SELECT
  -- num_seg_quarter_circle=2
  ST_NumPoints(ST_Buffer(ST_GeogFromText('POINT(1 2)'), 50, 2)) AS eight_sides,
  -- num_seg_quarter_circle=8, since 8 is the default
  st_NumPoints(ST_Buffer(ST_GeogFromText('POINT(100 2)'), 50)) AS thirty_two_sides;

+-------------+------------------+
| eight_sides | thirty_two_sides |
+-------------+------------------+
| 9           | 33               |
+-------------+------------------+

ST_BUFFERWITHTOLERANCE

ST_BUFFERWITHTOLERANCE(
    geography,
    buffer_radius,
    tolerance_meters => tolernace
    [, use_spheroid => boolean_expression]
    [, endcap => endcap_style]
    [, side => line_side])

입력 GEOGRAPHY 주위의 버퍼를 나타내는 GEOGRAPHY를 반환합니다. 이 함수는 ST_BUFFER와 비슷하지만, 결과 지리가 이상적인 버퍼 반경에서 벗어날 수 있는지를 결정하기 위해 세그먼트 대신 허용 범위를 제공합니다.

geography: 버퍼 반경으로 둘러싸는 입력 GEOGRAPHY입니다.
buffer_radius: 입력 지리 주위의 버퍼 반경을 나타내는 DOUBLE입니다. 반경은 미터 단위입니다. 음수인 buffer_radius로 버퍼링되면 다각형이 축소됩니다. 한 점으로 축소된 다각형 셸 및 구멍은 삭제됩니다.
tolerance_meters: DOUBLE는 도형의 근사치를 허용하는 허용 오차를 미터 단위로 지정합니다. 허용 오차는 다각형이 이상적인 반경에서 벗어날 수 있는지를 결정합니다. 이 인수 이름 지정은 선택사항입니다.
endcap: (선택사항) STRING을 사용하면 2개의 끝부분 스타일 중 하나인 ROUND 및 FLAT 중 하나를 지정할 수 있습니다. 기본값은 ROUND입니다. 이 옵션은 버퍼링된 유도선의 끝부분에만 영향을 미칩니다.
side: (선택사항) STRING를 사용하면 BOTH, LEFT, RIGHT의 세 가지 선 스타일 중 하나를 지정할 수 있습니다. 기본값은 BOTH입니다. 이 옵션은 버퍼링된 유도선의 끝부분에만 영향을 미칩니다.
use_spheroid: (선택사항) BOOL은 이 함수가 거리를 측정하는 방식을 결정합니다. use_spheroid가 FALSE이면 이 함수는 완전한 구의 표면에서 거리를 측정합니다. use_spheroid 매개변수는 현재 FALSE 값만 지원합니다. use_spheroid의 기본값은 FALSE입니다.

반환 유형

GEOGRAPHY

예시

다음 예시에서는 서로 다른 두 범위의 허용 범위에 속하지만 100의 버퍼 반경이 지정된 특정 지점에서 ST_BUFFERWITHTOLERANCE의 결과를 보여줍니다. 버퍼링된 점은 근사치의 원입니다. tolerance_meters=25인 경우 허용 범위는 버퍼 반경의 상당 부분이므로 5개의 세그먼트만 입력 점 주위의 원을 근사화하는 데 사용됩니다. tolerance_meters=1이면 허용 범위가 버퍼 반경의 훨씬 작은 값이므로 입력 지점 주위의 원을 근사화하는 데 24개의 모서리가 사용됩니다.

SELECT
  -- tolerance_meters=25, or 25% of the buffer radius.
  ST_NumPoints(ST_BufferWithTolerance(ST_GeogFromText('POINT(1 2)'), 100, 25)) AS five_sides,
  -- tolerance_meters=1, or 1% of the buffer radius.
  st_NumPoints(ST_BufferWithTolerance(ST_GeogFromText('POINT(100 2)'), 100, 1)) AS twenty_four_sides;

+------------+-------------------+
| five_sides | twenty_four_sides |
+------------+-------------------+
| 6          | 24                |
+------------+-------------------+

ST_CENTROID

ST_CENTROID(geography_expression)

설명

입력된 GEOGRAPHY의 중심을 단일 점 GEOGRAPHY로 반환합니다.

GEOGRAPHY의 중심은 GEOGRAPHY에서 가장 고차원인 구성요소의 가중 평균 중심입니다. 각 차원의 구성요소 중심은 다음과 같이 정의됩니다.

점의 중심은 입력 좌표의 산술 평균입니다.
유도선의 중심은 길이에 따라 가중치가 적용된 모든 모서리의 중심입니다. 각 모서리의 중심은 모서리의 측지 중간점입니다.
다각형의 중심은 질량 중심입니다.

입력 GEOGRAPHY가 비어 있으면 빈 GEOGRAPHY가 반환됩니다.

제약조건

드물지만 GEOGRAPHY의 중심을 지구 표면의 단일 점으로 정의할 수 없는 경우에는 확정된 점이나 임의의 점이 반환됩니다. 이러한 경우는 대척점 쌍의 중심과 같이 중심이 정확히 지구 중심에 존재하는 경우에만 발생할 수 있으며 발생 가능성이 거의 없습니다.

반환 유형

GEOGRAPHY

ST_CENTROID_AGG

ST_CENTROID_AGG(geography)

설명

입력 GEOGRAPHY 집합의 중심을 단일 점 GEOGRAPHY로 계산합니다.

입력 GEOGRAPHY 집합의 중심은 각 개별 GEOGRAPHY 중심의 가중 평균입니다. 전체 집합의 중심을 계산하는 데는 입력에 있는 가장 고차원인 GEOGRAPHY만 사용됩니다. 예를 들어 입력에 선이 있는 GEOGRAPHY와 점만 있는 GEOGRAPHY가 모두 포함되었으면 선이 있는 경우가 가장 차원이 높으므로 ST_CENTROID_AGG는 이 GEOGRAPHY의 가중 평균을 반환합니다. 이 예시에서 ST_CENTROID_AGG는 집계 중심을 계산할 때 점만 있는 GEOGRAPHY를 무시합니다.

ST_CENTROID_AGG는 입력된 GEOGRAPHY의 NULL 값을 무시합니다.

ST_CENTROID_AGG의 비집계 버전과 개별 GEOGRAPHY 값의 중심에 대한 정의는 ST_CENTROID를 참조하세요.

반환 유형

GEOGRAPHY

예시

다음 쿼리는 GEOGRAPHY 값 집합의 집계 중심을 계산합니다. 첫 번째 쿼리의 입력에는 점만 포함되어 있으므로 각 값이 집계 중심을 계산하는 데 사용됩니다. 또한 ST_UNION_AGG 결과에 대해 ST_CENTROID를 호출할 경우 ST_CENTROID_AGG와 달리 합집합을 구하는 과정에서 중복 요소가 삭제되므로 ST_CENTROID_AGG와 같지 않습니다. 두 번째 쿼리의 입력에는 차원이 혼합되었으므로 집합에서 가장 고차원 값인 선만 집계 중심에 영향을 줍니다.

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)      |
+-----------------+

ST_CLOSESTPOINT

ST_CLOSESTPOINT(geography_1, geography_2[, use_spheroid])

설명

geography_1 상에서 geography_2와의 거리가 가능한 한 가장 짧은 한 점을 포함하는 GEOGRAPHY를 반환합니다. 이는 ST_CLOSESTPOINT에서 반환된 점과 geography_2 사이의 거리가 geography_1에 있는 어떤 점과 geography_2 사이의 거리보다 짧거나 같다는 의미입니다.

입력 GEOGRAPHY 중 어느 하나라도 비어 있으면 ST_CLOSESTPOINT는 NULL을 반환합니다.

use_spheroid 매개변수는 현재 FALSE 값만 지원합니다. use_spheroid의 기본값은 FALSE입니다.

반환 유형

GEOGRAPHY

ST_CLUSTERDBSCAN

ST_CLUSTERDBSCAN(geography_column, epsilon, minimum_geographies)
OVER over_clause

over_clause:
  { named_window | ( [ window_specification ] ) }

window_specification:
  [ named_window ]
  [ PARTITION BY partition_expression [, ...] ]
  [ ORDER BY expression [ { ASC | DESC }  ] [, ...] ]

지리 열에서 DBSCAN 클러스터링을 수행합니다. 0부터 시작하는 클러스터 번호를 반환합니다.

OVER 절과 이를 사용하는 방법에 대한 자세한 내용은 윈도우 함수 호출을 참조하세요.

입력 매개변수

geography_column: 클러스터링된 GEOGRAPHY의 열입니다.
epsilon: 코어 값 주변의 미터로 측정된 반경을 지정하는 epsilon입니다. 음수가 아닌 FLOAT64 값입니다.
minimum_geographies: 단일 클러스터의 최소 지리 수를 지정합니다. 고밀도 입력만 클러스터를 형성하고, 그렇지 않으면 노이즈로 분류됩니다. 음수가 아닌 INT64 값입니다.

지리 유형 및 DBSCAN 알고리즘

DBSCAN 알고리즘은 고밀도 데이터 클러스터를 식별하고 저밀도 노이즈 영역의 이상점을 표시합니다. geography_column을 통해 전달된 지리 정보는 DBSCAN 알고리즘으로, 다음 세 가지 방법 중 하나로 분류됩니다.

핵심 값: 지리는 자체 지리 값을 포함하여 minimum_geographies 지리에서 epsilon 거리 내에 있는 경우 핵심 값입니다. 핵심 값은 새 클러스터를 시작하거나 epsilon 거리 내에 핵심 값과 동일한 클러스터에 추가됩니다. 핵심 값은 클러스터에서 epsilon 거리 내에 있는 다른 모든 핵심 및 경계 값과 함께 그룹화됩니다.
경계 값: 지리가 핵심 값의 epsilon 거리 내에 있는 경우 경계 값입니다. epsilon 거리 내 핵심 값과 동일한 클러스터에 추가됩니다. 경계 값은 둘 이상의 클러스터에서 epsilon 거리 이내일 수 있습니다. 이 경우 한 클러스터에 임의로 할당할 수 있으며 함수에서 후속 호출 시 동일한 결과를 생성합니다.
노이즈: 핵심 값이나 경계 값도 아닌 경우 지리는 노이즈입니다. 노이즈 값은 NULL 클러스터에 할당됩니다. 빈 GEOGRAPHY는 언제나 항상 노이즈로 분류됩니다.

제약조건

minimum_geographies 인수는 음수가 아닌 INT64이며, epsilon은 음수가 아닌 FLOAT64입니다.
빈 지리는 클러스터에 조인할 수 없습니다.
경계 값에 대해 여러 클러스터링 할당을 수행할 수 있습니다. 지리가 경계 값인 경우 ST_CLUSTERDBSCAN이 임의의 유효한 클러스터에 이 값을 할당합니다.

반환 유형

지리 열의 각 지리에 대한 INT64입니다.

예시

이 예시에서는 minimum_geographies 인수가 1인 반경 100,000미터로 DBSCAN 클러스터링을 수행합니다. 분석 대상 지리는 점, 선, 다각형이 혼합되어 있습니다.

WITH Geos as
  (SELECT 1 as row_id, st_geogfromtext('point empty') as geo UNION ALL
    SELECT 2, st_geogfromtext('multipoint(1 1, 2 2, 4 4, 5 2)') UNION ALL
    SELECT 3, st_geogfromtext('point(14 15)') UNION ALL
    SELECT 4, st_geogfromtext('linestring(40 1, 42 34, 44 39)') UNION ALL
    SELECT 5, st_geogfromtext('polygon((40 2, 40 1, 41 2, 40 2))'))
SELECT row_id, geo, ST_CLUSTERDBSCAN(geo, 1e5, 1) OVER () AS cluster_num FROM
Geos ORDER BY row_id
+--------+-----------------------------------+-------------+
| row_id |                geo                | cluster_num |
+--------+-----------------------------------+-------------+
|      1 |          GEOMETRYCOLLECTION EMPTY |        NULL |
|      2 |    MULTIPOINT(1 1, 2 2, 5 2, 4 4) |           0 |
|      3 |                      POINT(14 15) |           1 |
|      4 |    LINESTRING(40 1, 42 34, 44 39) |           2 |
|      5 | POLYGON((40 2, 40 1, 41 2, 40 2)) |           2 |
+--------+-----------------------------------+-------------+

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))에 각각 다각형의 외부, 경계, 내부에 위치한 3개의 점 (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_CONVEXHULL

ST_CONVEXHULL(geography_expression)

설명

GEOGRAPHY 입력에 대한 볼록 Hull을 반환합니다. 볼록 Hull은 입력을 처리하는 가장 작은 볼록 GEOGRAPHY입니다. GEOGRAPHY의 모든 점 쌍에서 점을 연결하는 측지선 에지도 동일한 GEOGRAPHY에 포함되는 경우 GEOGRAPHY는 볼록입니다.

대부분의 경우 볼록 Hull은 단일 다각형으로 구성됩니다. 주목할만한 에지 케이스에는 다음이 포함됩니다.

또한 단일 점의 볼록 Hull도 점입니다.
공선점이 두 개 이상 있는 볼록 Hull은 해당 유도선이 볼록한 한 유도선입니다.
GEOGRAPHY 입력이 반구보다 더 넓게 걸쳐 있으면 볼록 Hull은 구체 전체가 됩니다. 여기에는 대척점 쌍을 포함해 모든 입력이 포함됩니다.
입력이 NULL이거나 빈 GEOGRAPHY인 경우 ST_CONVEXHULL은 NULL을 반환합니다.

반환 유형

GEOGRAPHY

예시

ST_CONVEXHULL에서 반환된 볼록 Hull은 입력에 따라 점, 유도선 또는 다각형이 될 수 있습니다.

WITH Geographies AS
 (SELECT ST_GEOGFROMTEXT('POINT(1 1)') AS g UNION ALL
  SELECT ST_GEOGFROMTEXT('LINESTRING(1 1, 2 2)') AS g UNION ALL
  SELECT ST_GEOGFROMTEXT('MULTIPOINT(2 11, 4 12, 0 15, 1 9, 1 12)') AS g)
SELECT
  g AS input_geography,
  ST_CONVEXHULL(g) AS convex_hull
FROM Geographies;

+-----------------------------------------+--------------------------------------------------------+
|             input_geography             |                      convex_hull                       |
+-----------------------------------------+--------------------------------------------------------+
|                              POINT(1 1) |                             POINT(0.999999999999943 1) |
|                    LINESTRING(1 1, 2 2) | LINESTRING(2 2, 1.49988573656168 1.5000570914792, 1 1) |
| MULTIPOINT(1 9, 4 12, 2 11, 1 12, 0 15) |                        POLYGON((1 9, 4 12, 0 15, 1 9)) |
+-----------------------------------------+--------------------------------------------------------+

ST_COVEREDBY

ST_COVEREDBY(geography_1, geography_2)

설명

geography_1 또는 geography_2가 비어 있으면 FALSE를 반환합니다. geography_1의 어떠한 점도 geography_2의 외부에 있지 않으면 TRUE를 반환합니다.

두 GEOGRAPHY가 a, b일 때 ST_COVEREDBY(a, b)는 ST_COVERS(b, a)와 동일한 결과를 반환합니다. 인수 순서가 반대라는 점에 유의하세요.

반환 유형

BOOL

ST_COVERS

ST_COVERS(geography_1, geography_2)

설명

geography_1 또는 geography_2가 비어 있으면 FALSE를 반환합니다. geography_2의 어떠한 점도 geography_1의 외부에 있지 않으면 TRUE를 반환합니다.

반환 유형

BOOL

예시

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_DIFFERENCE

ST_DIFFERENCE(geography_1, geography_2)

설명

geography_1과 geography_2의 점 차집합을 나타내는 GEOGRAPHY를 반환합니다. 따라서 결과는 geography_2와 교차하지 않는 geography_1의 부분으로 구성됩니다.

geometry_1이 geometry_2에 완전히 포함되어 있으면 ST_DIFFERENCE는 빈 GEOGRAPHY를 반환합니다.

제약조건

BigQuery GEOGRAPHY가 나타내는 기본 도형 객체는 닫힌 점 집합에 해당합니다. 따라서 ST_DIFFERENCE는 geography_1과 geography_2의 닫힌 점 차집합을 구하는 것입니다. 이는 geography_1과 geography_2가 교차할 경우 geography_2의 경계 일부가 차집합에 포함될 수 있다는 의미입니다.

반환 유형

GEOGRAPHY

예시

다음 쿼리는 큰 다각형 POLYGON((0 0, 10 0, 10 10, 0 0))(geog1)과 geog1과 교차하는 작은 다각형 POLYGON((4 2, 6 2, 8 6, 4 2))(geog1) 간의 차이를 보여줍니다. 결과는 geog2와 교차하는 구멍이 있는 geog1입니다.

SELECT
  ST_DIFFERENCE(
      ST_GEOGFROMTEXT("POLYGON((0 0, 10 0, 10 10, 0 0))"),
      ST_GEOGFROMTEXT("POLYGON((4 2, 6 2, 8 6, 4 2))")
  );

+--------------------------------------------------------+
| difference_of_geog1_and_geog2                          |
+--------------------------------------------------------+
| POLYGON((0 0, 10 0, 10 10, 0 0), (8 6, 6 2, 4 2, 8 6)) |
+--------------------------------------------------------+

ST_DIMENSION

ST_DIMENSION(geography_expression)

설명

입력 GEOGRAPHY의 요소 중 가장 고차원인 요소의 차원 수를 반환합니다.

가능한 각 요소의 차원은 다음과 같습니다.

점의 차원 수는 0입니다.
유도선의 차원 수는 1입니다.
다각형의 차원 수는 2입니다.

입력 GEOGRAPHY가 비어 있으면 ST_DIMENSION은 -1을 반환합니다.

반환 유형

INT64

ST_DISJOINT

ST_DISJOINT(geography_1, geography_2)

설명

geography_1과 geography_2의 교차 영역이 비어 있으면, 즉 geography_1과 geography_2에 어떠한 점도 나타나지 않으면 TRUE를 반환합니다.

ST_DISJOINT는 ST_INTERSECTS의 논리적 부정입니다.

반환 유형

BOOL

ST_DISTANCE

ST_DISTANCE(geography_1, geography_2[, use_spheroid])

설명

비어 있지 않은 두 GEOGRAPHY 간의 최단 거리를 미터 단위로 반환합니다.

입력 GEOGRAPHY 중 어느 하나라도 비어 있으면 ST_DISTANCE는 NULL을 반환합니다.

use_spheroid 매개변수는 현재 FALSE 값만 지원합니다. use_spheroid의 기본값은 FALSE입니다.

반환 유형

FLOAT64

ST_DUMP

ST_DUMP(geography[, dimension])

설명

각 요소가 GEOGRAPHY 입력의 구성요소인 단순 GEOGRAPHY의 ARRAY를 반환합니다. 단순 GEOGRAPHY는 단일점, 유도선 또는 다각형으로 구성됩니다. GEOGRAPHY 입력이 단순이면 결과는 단일 요소입니다. GEOGRAPHY 입력이 컬렉션이면 ST_DUMP는 컬렉션의 각 구성요소에 대해 단순 GEOGRAPHY가 있는 ARRAY를 반환합니다.

dimension가 제공되면 이 함수는 상응하는 차원의 GEOGRAPHY만 반환합니다. 차원이 -1이며 dimension을 생략하는 것과 같습니다.

반환 유형

ARRAY

예시

다음 예시에서는 ST_DUMP가 복잡한 지리 내에서 단순 지리를 반환하는 방법을 보여줍니다.

WITH example AS (
  SELECT ST_GeogFromText('POINT(0 0)') AS geography
  UNION ALL
  SELECT ST_GeogFromText('MULTIPOINT(0 0, 1 1)') AS geography
  UNION ALL
  SELECT ST_GeogFromText('GEOMETRYCOLLECTION(POINT(0 0), LINESTRING(1 2, 2 1))'))
SELECT
  geography AS original_geography,
  ST_DUMP(geography) AS dumped_geographies
FROM example

+-------------------------------------+-------------------------------+
|         original_geographies        |      dumped_geographies       |
+-------------------------------------+-------------------------------+
| POINT(0 0)                          | [POINT(0 0)]                  |
+-------------------------------------+-------------------------------+
| MULTIPOINT(0 0, 1 1)                | [POINT(0 0), POINT(1 1)]      |
+-------------------------------------+-------------------------------+
| GEOMETRYCOLLECTION(POINT(0 0),      | [POINT(0 0),                  |
|   LINESTRING(1 2, 2 1))             |   LINESTRING(1 2, 2 1)]       |
+-------------------------------------+-------------------------------+

다음 예시에서는 차원 인수를 갖는 ST_DUMP가 지정된 차원의 단순 지리를 반환하는 방법을 보여줍니다.

WITH example AS (
  SELECT ST_GeogFromText('GEOMETRYCOLLECTION(POINT(0 0), LINESTRING(1 2, 2 1))') AS geography)
SELECT
  geography AS original_geography,
  ST_DUMP(geography, 1) AS dumped_geographies
FROM example

+-------------------------------------+------------------------------+
|         original_geographies        |      dumped_geographies      |
+-------------------------------------+------------------------------+
| GEOMETRYCOLLECTION(POINT(0 0),      | [LINESTRING(1 2, 2 1)]       |
|   LINESTRING(1 2, 2 1))             |                              |
+-------------------------------------+------------------------------+

ST_DWITHIN

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

설명

geography_1에 있는 1개 이상의 점과 geography_2에 있는 한 점 사이의 거리가 distance 인수로 지정된 거리보다 짧거나 같으면 TRUE를 반환하고, 그렇지 않으면 FALSE를 반환합니다. 두 입력 GEOGRAPHY 중 어느 하나가 비어 있으면 ST_DWithin은 FALSE를 반환합니다. 지정된 distance는 지구 표면 상의 미터 단위 거리입니다.

use_spheroid 매개변수는 현재 FALSE 값만 지원합니다. use_spheroid의 기본값은 FALSE입니다.

반환 유형

BOOL

ST_ENDPOINT

ST_ENDPOINT(linestring_geography)

설명

유도선 지리의 마지막 점을 점 지리로 반환합니다. 입력이 유도선이 아니거나 입력이 비어 있으면 오류를 반환합니다. SAFE 프리픽스를 사용하여 오류 대신 잘못된 입력에 대한 NULL을 얻습니다.

반환 유형

점 GEOGRAPHY

예시

SELECT ST_EndPoint(ST_GeogFromText('linestring(1 1, 2 1, 3 2, 3 3)')) last

+--------------+
| last         |
+--------------+
| POINT(3 3)   |
+--------------+

ST_EQUALS

ST_EQUALS(geography_1, geography_2)

설명

geography_1과 geography_2가 동일한 값을 나타내면 TRUE를 반환합니다.

동일한 값: GEOGRAPHY. 더 정확히 말해 이는 다음 조건 중 하나가 충족됨을 의미합니다. + ST_COVERS(geography_1, geography_2) = TRUE 및 ST_COVERS(geography_2, geography_1) = TRUE + geography_1 및 geography_2 둘 다 비어 있습니다.

따라서 점과 꼭짓점의 순서가 다르더라도 동일한 도형 구조를 나타내기만 하면 2개의 GEOGRAPHY가 동일할 수 있습니다.

제약조건

ST_EQUALS는 전환 함수가 아닐 수도 있습니다.

반환 유형

BOOL

ST_EXTENT

ST_EXTENT(geography_expression)

설명

입력된 GEOGRAPHY 값 집합의 경계 상자를 나타내는 STRUCT를 반환합니다. 경계 상자는 geography를 둘러싸는 최소한의 직사각형입니다. 직사각형의 모서리는 상수 경도 및 위도 선을 따릅니다.

주의사항:

모든 입력이 NULL이거나 빈 지리이면 NULL을 반환합니다.
더 작은 직사각형이 허용될 경우 경계 상자가 반대 자오선을 통과할 수 있습니다. 이 경우 경계 상자의 경도 경계는 [-180, 180] 범위를 벗어나므로 xmin은 동쪽 값 xmax보다 작습니다.
경계 상자의 경도 스팬이 180도와 같거나 크면 함수는 경도 범위가 [-180, 180]인 경계 상자를 반환합니다.

반환 유형

STRUCT<xmin FLOAT64, ymin FLOAT64, xmax FLOAT64, ymax FLOAT64>할 수 있습니다.

경계 상자 부분:

xmin: 직사각형의 경계를 이루는 서쪽 상수 경도 선입니다.
xmax: 직사각형의 경계를 이루는 가장 동쪽 상수 경도 선입니다.
ymin: 직사각형의 경계를 이루는 최소 상수 위도 선입니다.
ymax: 직사각형의 경계를 이루는 최대 상수 위도 선입니다.

예시

WITH data AS (
  SELECT 1 id, st_geogfromtext('polygon((-125 48, -124 46, -117 46, -117 49, -125 48))') g
  UNION ALL
  SELECT 2 id, st_geogfromtext('polygon((172 53, -130 55, -141 70, 172 53))') g
  UNION ALL
  SELECT 3 id, st_geogfromtext('point empty') g
)
SELECT st_extent(g) AS box
FROM data

+----------------------------------------------+
| box                                          |
+----------------------------------------------+
| {xmin:172, ymin:46, xmax:243, ymax:70}       |
+----------------------------------------------+

ST_EXTENT의 비집계 버전은 ST_BOUNDINGBOX를 참조하세요.

ST_EXTERIORRING

ST_EXTERIORRING(polygon_geography)

설명

다각형 지리의 가장 바깥쪽 링에 해당하는 유도선 지리를 반환합니다.

입력 지리가 다각형인 경우 다각형 지리의 가장 바깥쪽 링을 가져오고 해당하는 유도선을 반환합니다.
입력이 전체 GEOGRAPHY이면 빈 지리를 반환합니다.
입력이 단일 다각형이 아니면 오류를 반환합니다.

SAFE 프리픽스를 사용하면 오류 대신 잘못된 입력에 대한 NULL이 반환됩니다.

반환 유형

유도선 GEOGRAPHY
GEOGRAPHY메뉴가 비어 있습니다.

예시

WITH geo as
 (SELECT ST_GEOGFROMTEXT('POLYGON((0 0, 1 4, 2 2, 0 0))') AS g UNION ALL
  SELECT ST_GEOGFROMTEXT('''POLYGON((1 1, 1 10, 5 10, 5 1, 1 1),
                                  (2 2, 3 4, 2 4, 2 2))''') as g)
SELECT ST_EXTERIORRING(g) AS ring FROM geo;

+---------------------------------------+
| ring                                  |
+---------------------------------------+
| LINESTRING(2 2, 1 4, 0 0, 2 2)        |
| LINESTRING(5 1, 5 10, 1 10, 1 1, 5 1) |
+---------------------------------------+

ST_GEOGFROM

ST_GEOGFROM(expression)

설명

STRING 또는 BYTES 값의 표현식을 GEOGRAPHY 값으로 변환합니다.

expression이 STRING 값을 나타내는 경우 다음 형식 중 하나의 유효한 GEOGRAPHY 표현이어야 합니다.

WKT 형식. 이 형식 및 이를 사용하기 위한 요구사항을 자세히 알아보려면 ST_GEOGFROMTEXT를 참조하세요.
16진수 텍스트 형식의 WKB. 이 형식 및 이를 사용하기 위한 요구사항을 자세히 알아보려면 ST_GEOGFROMWKB를 참조하세요.
GeoJSON 형식. 이 형식 및 이를 사용하기 위한 요구사항을 자세히 알아보려면 ST_GEOGFROMGEOJSON을 참조하세요.

expression이 BYTES 값을 나타내는 경우 WKB 형식의 유효한 GEOGRAPHY 바이너리 표현식이어야 합니다. 이 형식 및 이를 사용하기 위한 요구사항을 자세히 알아보려면 ST_GEOGFROMWKB를 참조하세요.

expression이 NULL이면 출력이 NULL입니다.

반환 유형

GEOGRAPHY

예시

그러면 WKT 형식의 문자열이 사용되고 GEOGRAPHY 다각형이 반환됩니다.

SELECT ST_GEOGFROM('Polygon((0 0, 0 2, 2 2, 2 0, 0 0))') AS WKT_format

+------------------------------------+
| WKT_format                         |
+------------------------------------+
| POLYGON((2 0, 2 2, 0 2, 0 0, 2 0)) |
+------------------------------------+

WKB 형식의 16진수로 인코딩된 문자열이 사용되고 GEOGRAPHY 지점이 반환됩니다.

SELECT ST_GEOGFROM(FROM_HEX('010100000000000000000000400000000000001040')) AS WKB_format

+----------------+
| WKB_format     |
+----------------+
| POINT(2 4)     |
+----------------+

WKB 형식의 바이트가 사용되고 GEOGRAPHY 지점이 반환됩니다.

SELECT ST_GEOGFROM('010100000000000000000000400000000000001040')-AS WKB_format

+----------------+
| WKB_format     |
+----------------+
| POINT(2 4)     |
+----------------+

GEOJSON 형식의 문자열이 사용되고 GEOGRAPHY 다각형이 반환됩니다.

SELECT ST_GEOGFROM(
  '{ "type": "Polygon", "coordinates": [ [ [2, 0], [2, 2], [1, 2], [0, 2], [0, 0], [2, 0] ] ] }'
) AS GEOJSON_format

+-----------------------------------------+
| GEOJSON_format                          |
+-----------------------------------------+
| POLYGON((2 0, 2 2, 1 2, 0 2, 0 0, 2 0)) |
+-----------------------------------------+

ST_GEOGFROMGEOJSON

ST_GEOGFROMGEOJSON(geojson_string [, make_valid => constant_expression])

설명

입력된 GeoJSON 표현에 해당하는 GEOGRAPHY 값을 반환합니다.

ST_GEOGFROMGEOJSON은 RFC 7946을 준수하는 입력을 받습니다.

매개변수 make_valid가 TRUE로 설정되면 이 함수는 Open Geospatial Consortium 시맨틱스를 준수하지 않는 다각형 복구하려고 합니다. 이 매개변수는 명명된 인수 구문을 사용하며 make_valid => argument_value 구문을 사용하여 지정해야 합니다.

GEOGRAPHY를 GeoJSON 형식으로 만들려면 ST_ASGEOJSON을 참조하세요.

제약조건

입력에는 다음과 같은 제약조건이 적용됩니다.

ST_GEOGFROMGEOJSON은 JSON 도형 조각만 허용하며 전체 JSON 문서를 수집하는 데 사용할 수는 없습니다.
입력된 JSON 조각은 GeoJSON 도형 유형으로 구성되어야 하며, 여기에는 Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection이 포함됩니다. Feature, FeatureCollection 등의 다른 GeoJSON 유형이 있으면 오류가 발생합니다.
GeoJSON 도형 유형의 coordinates 멤버에 지정되는 위치는 정확히 2개의 요소로 구성되어야 합니다. 첫 번째 요소는 경도이고 두 번째 요소는 위도입니다. 따라서 ST_GEOGFROMGEOJSON은 coordinates 구성원의 위치에 선택적인 세 번째 요소를 지원하지 않습니다.

반환 유형

GEOGRAPHY

서명 1

ST_GEOGFROMTEXT(wkt_string[, oriented])

설명

입력된 WKT 표현에 해당하는 GEOGRAPHY 값을 반환합니다.

이 함수는 BOOL, oriented 유형의 선택적 매개변수를 지원합니다. 이 매개변수가 TRUE로 설정되었으면 입력에 포함된 모든 다각형의 방향을 특정 방식으로 간주하게 됩니다. 즉, 다각형 경계를 입력 꼭짓점의 순서대로 이동할 때 왼쪽 영역이 다각형의 내부가 됩니다. 이 경우 WKT는 반구보다 큰 다각형을 나타낼 수 있습니다. oriented가 FALSE이거나 생략되었으면 이 함수는 보다 작은 면적의 다각형을 반환합니다. oriented=TRUE인 ST_GEOGFROMTEXT와 유사한 ST_MAKEPOLYGONORIENTED도 참조하세요.

GEOGRAPHY를 WKT 형식으로 만들려면 ST_ASTEXT를 사용합니다.

제약조건

모든 입력 모서리는 평면 직선이 아닌 구면 측지선으로 간주됩니다. 평면 투영 데이터를 읽으려면 ST_GEOGFROMGEOJSON을 사용하는 것이 좋습니다. 구면 측지선과 평면 선 간의 차이점에 대한 자세한 내용은 좌표계와 에지를 참조하세요.
이 함수는 Z 서픽스가 있는 3차원 도형이나 M 서픽스가 있는 선형 참조 시스템 도형을 지원하지 않습니다.
이 함수는 도형 기본 요소 및 멀티파트 도형만 지원합니다. 특히 Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection만 지원합니다.

반환 유형

GEOGRAPHY

예시

다음 쿼리는 WKT 문자열 POLYGON((0 0, 0 2, 2 2, 2 0, 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     |
+-------------------+---------------+-----------+

서명 2

ST_GEOGFROMTEXT(wkt_string[, oriented => boolean_constant_1]
    [, planar => boolean_constant_2] [, make_valid => boolean_constant_3])

설명

입력된 WKT 표현에 해당하는 GEOGRAPHY 값을 반환합니다.

이 함수는 BOOL 유형(oriented, planar, make_valid)의 선택적 매개변수 세 가지를 지원합니다. 이 서명은 명명된 인수 구문을 사용하며 매개변수는 어떠한 순서로든 parameter_name => parameter_value 구문을 사용하여 지정해야 합니다.

oriented 매개변수가 TRUE로 설정되었으면 입력에 포함된 모든 다각형의 방향을 특정 방식으로 간주하게 됩니다. 즉, 입력 꼭짓점의 순서대로 다각형 경계를 따라 이동할 때 왼쪽 영역이 다각형의 내부가 됩니다. 이 경우 WKT는 반구보다 큰 다각형을 나타낼 수 있습니다. oriented가 FALSE이거나 생략되었으면 이 함수는 보다 작은 면적의 다각형을 반환합니다. oriented=TRUE인 ST_GEOGFROMTEXT와 유사한 ST_MAKEPOLYGONORIENTED도 참조하세요.

매개변수 planar이 TRUE로 설정되면 선 문자열과 다각형의 모서리가 BigQuery 기본 구면 측지선 시맨틱스 대신 평면 지도 시맨틱스를 사용하는 것으로 가정합니다. 구면 측지선과 평면 선 간의 차이점에 대한 자세한 내용은 좌표계와 에지를 참조하세요.

매개변수 make_valid가 TRUE로 설정되면 이 함수는 Open Geospatial Consortium 시맨틱스를 준수하지 않는 다각형 복구하려고 합니다.

GEOGRAPHY를 WKT 형식으로 만들려면 ST_ASTEXT를 사용합니다.

제약조건

모든 입력 모서리는 기본적으로 평면 직선이 아닌 구면 측지선으로 간주됩니다. 평면 투영 데이터를 읽으려면 planar => TRUE 인수를 전달하거나 ST_GEOGFROMGEOJSON를 사용하는 것이 좋습니다. 구면 측지선과 평면 선 간의 차이점에 대한 자세한 내용은 좌표계와 에지를 참조하세요.
이 함수는 Z 서픽스가 있는 3차원 도형이나 M 서픽스가 있는 선형 참조 시스템 도형을 지원하지 않습니다.
이 함수는 도형 기본 요소 및 멀티파트 도형만 지원합니다. 특히 Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection만 지원합니다.
oriented와 planar가 동시에 TRUE와 같을 수는 없습니다.
oriented와 make_valid가 동시에 TRUE와 같을 수는 없습니다.

예시

다음 쿼리는 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, oriented => FALSE), ST_GEOGPOINT(1, 1)) AS non_oriented,
  ST_CONTAINS(ST_GEOGFROMTEXT(p, oriented => TRUE),  ST_GEOGPOINT(1, 1)) AS oriented
FROM polygon;

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

다음 쿼리는 잘못된 다각형이 있는 WKT 문자열을 GEOGRAPHY으로 변환합니다. WKT 문자열은 유효한 다각형의 두 가지 속성을 위반합니다. 즉, 다각형을 설명하는 루프가 닫히지 않았으며 자체 교차로가 포함되어 있습니다. make_valid 옵션을 사용하면 ST_GeogFromText가 이를 여러 다각형 형태로 성공적으로 변환합니다.

WITH data AS (
  SELECT 'polygon((0 -1, 2 1, 2 -1, 0 1))' wkt)
SELECT
  SAFE.ST_GeogFromText(wkt) as geom,
  SAFE.ST_GeogFromText(wkt, make_valid => TRUE) as valid_geom
FROM data

+------+-----------------------------------------------------------------+
| geom | valid_geom                                                      |
+------+-----------------------------------------------------------------+
| NULL | MULTIPOLYGON(((0 -1, 1 0, 0 1, 0 -1)), ((1 0, 2 -1, 2 1, 1 0))) |
+------+-----------------------------------------------------------------+

ST_GEOGFROMWKB

ST_GEOGFROMWKB(wkb_bytes_expression)
ST_GEOGFROMWKB(wkb_hex_string_expression)

설명

16진수 텍스트 STRING 또는 BYTES 값의 표현식을 GEOGRAPHY 값으로 변환합니다. 표현식은 WKB 형식이어야 합니다.

GEOGRAPHY를 WKB 형식으로 만들려면 ST_ASBINARY를 사용합니다.

제약조건

모든 입력 모서리는 평면 직선이 아닌 구면 측지선으로 간주됩니다. 평면 투영 데이터를 읽으려면 ST_GEOGFROMGEOJSON을 사용하는 것이 좋습니다.

반환 유형

GEOGRAPHY

ST_GEOGPOINT

ST_GEOGPOINT(longitude, latitude)

설명

단일 점을 사용하여 GEOGRAPHY를 생성합니다. ST_GEOGPOINT는 지정된 FLOAT64 경도 및 위도 매개변수를 사용하여 단일 점을 생성한 후 GEOGRAPHY 값으로 반환합니다.

제약조건

위도 범위는 [-90, 90]입니다. 위도가 이 범위를 벗어나면 오류가 발생합니다.
경도는 [-180, 180] 범위를 벗어나도 됩니다. ST_GEOGPOINT는 입력 경도를 360으로 나눈 나머지를 사용하여 [-180, 180] 범위 내의 경도를 구합니다.

반환 유형

GEOGRAPHY

ST_GEOGPOINTFROMGEOHASH

ST_GEOGPOINTFROMGEOHASH(geohash)

설명

GeoHash에 정의된 경계 상자의 가운데 점에 해당하는 GEOGRAPHY 값을 반환합니다.

반환 유형

GEOGRAPHY

ST_GEOHASH

ST_GEOHASH(geography_expression[, maxchars])

설명

단일 점 GEOGRAPHY를 사용하여 해당 GEOGRAPHY 객체의 GeoHash 표현을 반환합니다.

geography_expression: GEOGRAPHY 객체를 나타냅니다. 단일 점을 나타내는 GEOGRAPHY 객체만 지원됩니다. 빈 GEOGRAPHY 객체 위에 ST_GEOHASH를 사용하면 NULL이 반환됩니다.
maxchars: 이 선택적 INT64 매개변수는 해시에 포함될 최대 문자 수를 지정합니다. 이보다 문자 수가 적으면 정밀도가 낮습니다. 달리 설명하면 더 큰 경계 상자에 해당합니다. 명시적으로 지정하지 않으면 maxchars 기본값은 20입니다. 유효한 maxchars 값은 1~20입니다. 이보다 낮거나 높은 값은 지정되지 않은 것으로 간주되어 기본값 20이 사용됩니다.

반환 유형

STRING

예시

시애틀 센터의 GeoHash를 10자 정밀도로 반환합니다.

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

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

ST_GEOMETRYTYPE

ST_GEOMETRYTYPE(geography_expression)

설명

입력 GEOGRAPHY를 STRING으로 설명하는 Open Geospatial Consortium(OGC) 도형 유형을 반환합니다. OGC 도형 유형은 WKT 및 GeoJSON 형식으로 사용되고 ST_ASTEXT 및 ST_ASGEOJSON용으로 인쇄되는 유형과 일치합니다. ST_GEOMETRYTYPE은 'ST_' 프리픽스가 있는 OGC 도형 유형을 반환합니다.

ST_GEOMETRYTYPE은 입력의 유형에 따라 다음을 반환합니다.

단일 지점 지리: ST_Point를 반환합니다.
점만 포함된 컬렉션: ST_MultiPoint를 반환합니다.
단일 유도선 지리: ST_LineString을 반환합니다.
유도선만 포함된 컬렉션: ST_MultiLineString을 반환합니다.
단일 다각형 지리: ST_Polygon을 반환합니다.
다각형만 포함된 컬렉션: ST_MultiPolygon을 반환합니다.
다른 차원의 요소가 있는 컬렉션이거나 입력이 빈 지리인 경우: ST_GeometryCollection을 반환합니다.

반환 유형

STRING

예시

다음 예시에서는 ST_GEOMETRYTYPE이 지리를 사용하여 OGC 도형 유형의 이름을 반환하는 방법을 보여줍니다.

WITH example AS(
  SELECT ST_GeogFromText('POINT(0 1)') AS geography
  UNION ALL
  SELECT ST_GeogFromText('MULTILINESTRING((2 2, 3 4), (5 6, 7 7))')
  UNION ALL
  SELECT ST_GeogFromText('GEOMETRYCOLLECTION(MULTIPOINT(-1 2, 0 12), LINESTRING(-2 4, 0 6))')
  UNION ALL
  SELECT ST_GeogFromText('GEOMETRYCOLLECTION EMPTY'))
SELECT
  geography AS WKT,
  ST_GeometryType(geography) AS geometry_type_name
FROM example;

+-------------------------------------------------------------------+-----------------------+
| WKT                                                               | geometry_type_name    |
+-------------------------------------------------------------------+-----------------------+
| POINT(0 1)                                                        | ST_Point              |
| MULTILINESTRING((2 2, 3 4), (5 6, 7 7))                           | ST_MultiLineString    |
| GEOMETRYCOLLECTION(MULTIPOINT(-1 2, 0 12), LINESTRING(-2 4, 0 6)) | ST_GeometryCollection |
| GEOMETRYCOLLECTION EMPTY                                          | ST_GeometryCollection |
+-------------------------------------------------------------------+-----------------------+

ST_INTERIORRINGS

ST_INTERIORRINGS(polygon_geography)

설명

다각형 지리의 내부 링에 해당하는 유도선 지리의 배열을 반환합니다. 각 내부 링은 입력 다각형 내 구멍의 경계입니다.

입력 지리가 다각형인 경우 다각형 지리의 가장 바깥쪽 링을 제외하고 내부 링에 해당하는 유도선을 반환합니다.
입력이 전체 GEOGRAPHY이면 빈 배열을 반환합니다.
입력 다각형에 구멍이 없으면 빈 배열을 반환합니다.
입력이 단일 다각형이 아니면 오류를 반환합니다.

SAFE 프리픽스를 사용하면 오류 대신 잘못된 입력에 대한 NULL이 반환됩니다.

반환 유형

ARRAY

예시

WITH geo AS (
  SELECT ST_GEOGFROMTEXT('polygon((0 0, 1 1, 1 2, 0 0))') AS g UNION ALL
  SELECT ST_GEOGFROMTEXT('polygon((1 1, 1 10, 5 10, 5 1, 1 1), (2 2, 3 4, 2 4, 2 2))') UNION ALL
  SELECT ST_GEOGFROMTEXT('polygon((1 1, 1 10, 5 10, 5 1, 1 1), (2 2.5, 3.5 3, 2.5 2, 2 2.5), (3.5 7, 4 6, 3 3, 3.5 7))') UNION ALL
  SELECT ST_GEOGFROMTEXT('fullglobe') UNION ALL
  SELECT null)
SELECT ST_INTERIORRINGS(g) AS rings FROM geo;

+----------------------------------------------------------------------------+
| rings                                                                      |
+----------------------------------------------------------------------------+
| []                                                                         |
| [LINESTRING(2 2, 3 4, 2 4, 2 2)]                                           |
| [LINESTRING(2.5 2, 3.5 3, 2 2.5, 2.5 2), LINESTRING(3 3, 4 6, 3.5 7, 3 3)] |
| []                                                                         |
| NULL                                                                       |
+----------------------------------------------------------------------------+

ST_INTERSECTION

ST_INTERSECTION(geography_1, geography_2)

설명

두 입력 GEOGRAPHY의 점 교집합을 나타내는 GEOGRAPHY를 반환합니다. 따라서 교집합의 모든 점은 geography_1과 geography_2 모두에 나타납니다.

두 입력 GEOGRAPHY에 공통 요소가 없는 경우, 즉 입력 geometry_1과 geometry_2 모두에 공통적으로 있는 점이 없는 경우에는 빈 GEOGRAPHY가 반환됩니다.

관련 조건자 함수는 ST_INTERSECTS, ST_DISJOINT를 참조하세요.

반환 유형

GEOGRAPHY

ST_INTERSECTS

ST_INTERSECTS(geography_1, geography_2)

설명

geography_1과 geography_2의 점 교집합이 비어 있지 않으면 TRUE를 반환합니다. 따라서 입력된 두 GEOGRAPHY에 나타나는 점이 1개 이상 있으면 이 함수는 TRUE를 반환합니다.

ST_INTERSECTS가 TRUE를 반환하면 ST_DISJOINT는 FALSE를 반환합니다.

반환 유형

BOOL

ST_INTERSECTSBOX

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

설명

geography가 [lng1, lng2]와 [lat1, lat2] 사이의 직사각형과 교차하면 TRUE를 반환합니다. 직사각형의 모서리는 상수 경도 및 위도 선을 따릅니다. lng1 및 lng2는 직사각형의 경계를 이루는 서쪽 끝과 동쪽 끝의 상수 경도 선을 지정하고, lat1 및 lat2은 직사각형의 경계를 이루는 최소 및 최대 상수 위도 선을 지정합니다.

모든 경도 및 위도 인수는 도 단위로 지정합니다.

제약조건

입력 인수에는 다음과 같은 제약조건이 적용됩니다.

위도는 도 단위로 [-90, 90] 범위여야 합니다.
경도는 다음 규칙 중 하나를 따라야 합니다.
- 두 경도 모두 [-180, 180]도 범위입니다.
- 경도 중 하나는 [-180, 180]도 범위이며 lng2 - lng1은 [0, 360] 간격입니다.

반환 유형

BOOL

예시

SELECT p, st_intersectsbox(p, -90, 0, 90, 20) AS box1,
       st_intersectsbox(p, 90, 0, -90, 20) AS box2
FROM UNNEST([st_geogpoint(10, 10), st_geogpoint(170, 10),
             st_geogpoint(30, 30)]) p
+----------------+--------------+--------------+
| p              | box1         | box2         |
+----------------+--------------+--------------+
| POINT(10 10)   | true         | false        |
+----------------+--------------+--------------+
| POINT(170 10)  | false        | true         |
+----------------+--------------+--------------+
| POINT(30 30)   | false        | false        |
+----------------+--------------+--------------+

ST_ISCOLLECTION

ST_ISCOLLECTION(geography_expression)

설명

점, 유도선, 다각형의 총 개수가 1보다 크면 TRUE를 반환합니다.

빈 GEOGRAPHY는 컬렉션이 아닙니다.

반환 유형

BOOL

ST_ISEMPTY

ST_ISEMPTY(geography_expression)

설명

지정된 GEOGRAPHY가 비어 있으면, 즉 GEOGRAPHY에 점, 선 또는 다각형이 전혀 포함되어 있지 않으면 TRUE를 반환합니다.

참고: 빈 BigQuery GEOGRAPHY는 특정 도형과 연결되어 있지 않습니다. 예를 들어 표현식 ST_GEOGFROMTEXT('POINT EMPTY')와 ST_GEOGFROMTEXT('GEOMETRYCOLLECTION EMPTY')의 결과가 동일합니다.

반환 유형

BOOL

ST_LENGTH

ST_LENGTH(geography_expression[, use_spheroid])

설명

입력 GEOGRAPHY에 있는 선의 총 길이를 미터 단위로 반환합니다.

geography_expression이 점 또는 다각형이면 0이 반환됩니다. geography_expression이 컬렉션이면 컬렉션의 선 길이가 반환됩니다. 컬렉션에 선이 포함되지 않았으면 0이 반환됩니다.

use_spheroid 매개변수는 현재 FALSE 값만 지원합니다. use_spheroid의 기본값은 FALSE입니다.

반환 유형

FLOAT64

ST_MAKELINE

ST_MAKELINE(geography_1, geography_2)

ST_MAKELINE(array_of_geography)

설명

각 입력된 GEOGRAPHY의 점 또는 선 꼭짓점을 지정된 순서대로 연결하여 단일 유도선이 있는 GEOGRAPHY를 만듭니다.

ST_MAKELINE에는 2가지 유형이 있습니다. 첫 번째 유형에서는 GEOGRAPHY를 2개 입력해야 합니다. 두 번째 유형에서는 GEOGRAPHY 유형의 ARRAY를 입력해야 합니다. 두 유형에서 입력된 각 GEOGRAPHY는 다음 값 중 하나로 구성되어야 합니다.

정확히 1개의 점
정확히 1개의 유도선

첫 번째 ST_MAKELINE 유형의 경우 입력된 GEOGRAPHY가 NULL이면 ST_MAKELINE은 NULL을 반환합니다. 두 번째 유형의 경우 입력된 ARRAY 또는 입력된 ARRAY의 요소가 NULL이면 ST_MAKELINE은 NULL을 반환합니다.

제약조건

모든 모서리의 범위는 180도 미만이어야 합니다.

참고: BigQuery의 맞추기 프로세스는 아주 짧은 모서리를 삭제하고 2개의 끝점을 함께 맞춥니다. 예를 들어 두 입력 GEOGRAPHY에 각각 점이 하나씩 포함되어 있고 두 점이 맞추기 반경보다 작은 거리로 분리되었으면 점이 함께 맞춰집니다. 이러한 경우 결과는 정확히 1개의 점만 있는 GEOGRAPHY가 됩니다.

반환 유형

GEOGRAPHY

ST_MAKEPOLYGON

ST_MAKEPOLYGON(geography_expression[, array_of_geography])

설명

입력 유도선을 사용하여 단일 다각형을 포함하는 GEOGRAPHY를 만듭니다. 이때 각 입력 유도선은 다각형 링을 구성하는 데 사용됩니다.

ST_MAKEPOLYGON에는 2가지 유형이 있습니다. 첫 번째 유형의 경우 정확히 1개의 유도선을 포함하는 단일 GEOGRAPHY가 입력 유도선을 제공합니다. 두 번째 유형의 경우 입력은 각각 정확히 1개의 유도선을 포함하는 단일 GEOGRAPHY 및 GEOGRAPHY의 배열로 구성됩니다. 두 유형의 첫 번째 GEOGRAPHY는 다각형 셸을 생성하는 데 사용됩니다. 입력된 ARRAY에 제공되는 추가 GEOGRAPHY는 다각형 구멍을 지정합니다. 정확히 1개의 유도선을 포함하는 모든 입력 GEOGRAPHY는 다음 조건을 충족해야 합니다.

유도선은 3개 이상의 개별 꼭짓점으로 구성되어야 합니다.
유도선은 닫혀 있어야 합니다. 즉, 첫 번째 꼭짓점과 마지막 꼭짓점이 동일해야 합니다. 첫 번째 꼭짓점과 마지막 꼭짓점이 다르면 이 함수는 첫 번째 꼭짓점에서 시작해 마지막 꼭짓점에서 끝나는 모서리를 구성합니다.

첫 번째 ST_MAKEPOLYGON 유형의 경우 입력된 GEOGRAPHY가 NULL이면 ST_MAKEPOLYGON은 NULL을 반환합니다. 두 번째 유형의 경우 입력된 ARRAY 또는 ARRAY의 요소가 NULL이면 ST_MAKEPOLYGON은 NULL을 반환합니다.

참고: ST_MAKEPOLYGON에 빈 GEOGRAPHY를 입력할 수 있습니다. ST_MAKEPOLYGON은 빈 GEOGRAPHY를 빈 유도선이 있는 것으로 해석하여 완전한 루프, 즉 지구 전체를 포함하는 다각형을 만듭니다.

제약조건

입력 링을 결합하면 유효한 다각형이 형성되어야 합니다.

다각형 셸에는 각 다각형 구멍이 포함되어야 합니다.
다각형 셸은 하나만 있을 수 있으며 첫 번째 입력 링이어야 합니다. 즉, 다각형 구멍은 중첩될 수 없습니다.
다각형 링은 두 링의 경계에 있는 꼭짓점에서만 교차할 수 있습니다.

모든 모서리의 범위는 180도 미만이어야 합니다.

각 다각형 링은 구를 2개의 영역으로 나눕니다. ST_MAKEPOLYGON의 첫 번째 입력 유도선은 다각형 셸을 형성하며 다각형 내부는 두 영역 중 더 작은 영역으로 선택됩니다. 이후의 각 입력 유도선은 다각형 구멍을 지정하므로 다각형의 내부가 정확하게 정의됩니다. 다각형 셸을 정의할 때 두 영역 중 더 큰 영역이 다각형 내부가 되도록 하려면 ST_MAKEPOLYGONORIENTED를 참조하세요.

참고: BigQuery의 맞추기 프로세스는 아주 짧은 모서리를 삭제하고 2개의 끝점을 함께 맞춥니다. 따라서 꼭짓점이 함께 맞춰질 때 아주 작은 다각형 구멍이 사라지거나 출력 GEOGRAPHY에 선 또는 점만 포함될 수 있습니다.

반환 유형

GEOGRAPHY

ST_MAKEPOLYGONORIENTED

ST_MAKEPOLYGONORIENTED(array_of_geography)

설명

ST_MAKEPOLYGON과 유사하지만 각 입력 유도선의 꼭짓점 순서에 따라 각 다각형 링의 방향이 결정된다는 차이점이 있습니다. 다각형 링의 방향은 다각형의 내부를 정의합니다. 다각형 경계를 입력 꼭짓점의 순서대로 이동할 때 왼쪽 영역이 다각형의 내부입니다. 지정된 각 다각형 링에 동일한 정의가 적용됩니다.

ST_MAKEPOLYGONORIENTED는 다각형 내부가 다각형 링의 어느 한 쪽으로 정의되는 다각형을 구성할 수 있으므로 이 변이된 다각형 생성자가 보다 유연합니다. 그러나 다각형을 원하는 대로 구성하기 위해서는 다각형 링의 올바른 방향이 중요합니다.

입력된 ARRAY 또는 ARRAY의 요소가 NULL이면 ST_MAKEPOLYGONORIENTED는 NULL을 반환합니다.

참고: ST_MAKEPOLYGONORIENTED의 입력 인수에 빈 GEOGRAPHY가 포함될 수 있습니다. ST_MAKEPOLYGONORIENTED는 빈 GEOGRAPHY를 빈 유도선이 있는 것으로 해석하여 완전한 루프, 즉 지구 전체를 포함하는 다각형을 만듭니다.

제약조건

입력 링을 결합하면 유효한 다각형이 형성되어야 합니다.

다각형 셸에는 각 다각형 구멍이 포함되어야 합니다.
다각형 셸은 하나만 있어야 하며 첫 번째 입력 링이어야 합니다. 즉, 다각형 구멍은 중첩될 수 없습니다.
다각형 링은 두 링의 경계에 있는 꼭짓점에서만 교차할 수 있습니다.

모든 모서리의 범위는 180도 미만이어야 합니다.

ST_MAKEPOLYGONORIENTED는 각 유도선의 입력 꼭짓점 순서에 따라 다각형의 방향을 결정합니다. 다각형 셸과 모든 다각형 구멍에도 같은 방식이 적용됩니다. ST_MAKEPOLYGONORIENTED를 사용할 때 모든 다각형 구멍은 셸과 반대 방향이어야 합니다. 다른 다각형 생성자와 유효한 다각형 빌드 시의 기타 제약조건은 ST_MAKEPOLYGON을 참조하세요.

참고: BigQuery의 맞추기 프로세스로 인해 길이가 아주 짧은 모서리는 삭제되고 2개의 끝점이 단일 점으로 맞춰집니다. 따라서 하나 이상의 모서리가 사라지도록 유도선의 꼭짓점을 함께 맞출 수 있습니다. 결과적으로 아주 작은 다각형 구멍이 사라지거나 결과 GEOGRAPHY에 선이나 점만 포함될 수 있습니다.

반환 유형

GEOGRAPHY

ST_MAXDISTANCE

ST_MAXDISTANCE(geography_1, geography_2[, use_spheroid])

비어 있지 않은 두 GEOGRAPHY 사이의 최장 거리, 즉 첫 번째 GEOGRAPHY에 있는 꼭짓점과 두 번째 GEOGRAPHY에 있는 꼭짓점 사이의 최장 거리를 미터 단위로 반환합니다. geography_1과 geography_2가 동일한 GEOGRAPHY이면 이 함수는 해당 GEOGRAPHY에서 가장 멀리 떨어진 두 꼭짓점 사이의 거리를 반환합니다.

입력 GEOGRAPHY 중 어느 하나라도 비어 있으면 ST_MAXDISTANCE는 NULL을 반환합니다.

use_spheroid 매개변수는 현재 FALSE 값만 지원합니다. use_spheroid의 기본값은 FALSE입니다.

반환 유형

FLOAT64

ST_NPOINTS

ST_NPOINTS(geography_expression)

설명

ST_NUMPOINTS의 별칭입니다.

ST_NUMGEOMETRIES

ST_NUMGEOMETRIES(geography_expression)

설명

입력 GEOGRAPHY의 도형 수를 반환합니다. 단일 지점, 유도선, 다각형의 경우 ST_NUMGEOMETRIES는 1을 반환합니다. 모든 도형 컬렉션의 경우 ST_NUMGEOMETRIES는 컬렉션을 구성하는 도형 수를 반환합니다. 입력이 빈 GEOGRAPHY인 경우 ST_NUMGEOMETRIES는 0을 반환합니다.

반환 유형

INT64

예시

다음 예시에서는 단일 지점 지리, 두 개의 컬렉션, 빈 지리에 대해 ST_NUMGEOMETRIES를 계산합니다.

WITH example AS(
  SELECT ST_GeogFromText('POINT(5 0)') AS geography
  UNION ALL
  SELECT ST_GeogFromText('MULTIPOINT(0 1, 4 3, 2 6)') AS geography
  UNION ALL
  SELECT ST_GeogFromText('GEOMETRYCOLLECTION(POINT(0 0), LINESTRING(1 2, 2 1))') AS geography
  UNION ALL
  SELECT ST_GeogFromText('GEOMETRYCOLLECTION EMPTY'))
SELECT
  geography,
  ST_NumGeometries(geography) AS num_geometries,
FROM example;

+------------------------------------------------------+----------------+
| geography                                            | num_geometries |
+------------------------------------------------------+----------------+
| POINT(5 0)                                           | 1              |
| MULTIPOINT(0 1, 4 3, 2 6)                            | 3              |
| GEOMETRYCOLLECTION(POINT(0 0), LINESTRING(1 2, 2 1)) | 2              |
| GEOMETRYCOLLECTION EMPTY                             | 0              |
+------------------------------------------------------+----------------+

ST_NUMPOINTS

ST_NUMPOINTS(geography_expression)

설명

입력 GEOGRAPHY의 꼭짓점 수를 반환합니다. 이 수에는 점 수, 유도선 꼭짓점 수, 다각형 꼭짓점 수가 포함됩니다.

참고: 다각형 링의 첫 번째 꼭짓점과 마지막 꼭지점은 별개의 꼭지점으로 간주됩니다.

반환 유형

INT64

ST_PERIMETER

ST_PERIMETER(geography_expression[, use_spheroid])

설명

입력 GEOGRAPHY의 다각형 경계 길이를 미터 단위로 반환합니다.

geography_expression이 점 또는 선이면 0이 반환됩니다. geography_expression이 컬렉션이면 컬렉션의 다각형 둘레가 반환됩니다. 컬렉션에 다각형이 포함되지 않았으면 0이 반환됩니다.

use_spheroid 매개변수는 현재 FALSE 값만 지원합니다. use_spheroid의 기본값은 FALSE입니다.

반환 유형

FLOAT64

ST_POINTN

ST_POINTN(linestring_geography, index)

설명

유도선 지리의 N번째 점을 점 지리로 반환합니다. 여기서 N은 색인입니다. 색인은 1부터 시작합니다. 음수 값은 유도선 끝에서부터 역으로 계산되므로 -1이 마지막 점이 됩니다. 입력이 유도선이 아니거나, 입력이 비어 있거나, 지정된 색인에 꼭짓점이 없으면 오류가 반환됩니다. SAFE 프리픽스를 사용하여 오류 대신 잘못된 입력에 대한 NULL을 얻습니다.

반환 유형

점 GEOGRAPHY

예시

다음 예시에서는 ST_POINTN, ST_STARTPOINT, ST_ENDPOINT를 사용하여 유도선에서 점을 추출합니다.

WITH linestring AS (
    SELECT ST_GeogFromText('linestring(1 1, 2 1, 3 2, 3 3)') g
)
SELECT ST_PointN(g, 1) AS first, ST_PointN(g, -1) AS last,
    ST_PointN(g, 2) AS second, ST_PointN(g, -2) AS second_to_last
FROM linestring;

+--------------+--------------+--------------+----------------+
| first        | last         | second       | second_to_last |
+--------------+--------------+--------------+----------------+
| POINT(1 1)   | POINT(3 3)   | POINT(2 1)   | POINT(3 2)     |
+--------------+--------------+--------------+----------------+

ST_SIMPLIFY

ST_SIMPLIFY(geography, tolerance_meters)

설명

지정된 입력 GEOGRAPHY인 geography의 간소화된 버전을 반환합니다. GEOGRAPHY 입력은 짧은 모서리의 직선에 가까운 체인을 단일 긴 모서리로 대체하여 단순화됩니다. 입력 geography는 tolerance_meters에 지정된 허용 범위를 초과하여 변경되지 않습니다. 따라서 단순화된 모서리는 해당 모서리에서 삭제된 모든 꼭짓점의 원본 위치의 tolerance_meters 내에서 전달됩니다. 지정된 tolerance_meters는 지구 표면상의 미터 단위 거리입니다.

ST_SIMPLIFY는 토폴로지 관계를 유지하므로 새로운 교차 모서리가 생성되지 않고 출력이 유효합니다. 허용 범위가 충분히 크면 인접 도형이 단일 객체로 축소되거나 도형이 더 작은 치수의 도형으로 단순화될 수 있습니다.

제약조건

ST_SIMPLIFY가 적용되려면 tolerance_meters가 0이 아닌 값이어야 합니다.

tolerance_meters에 의해 지정된 허용 범위가 다음 중 하나인 경우 ST_SIMPLIFY는 오류를 반환합니다.

음수인 허용 범위
7,800km를 초과하는 허용 범위

반환 유형

GEOGRAPHY

예시

다음 예시에서는 ST_SIMPLIFY가 중간 꼭짓점을 삭제하여 입력 줄 GEOGRAPHY를 간소화하는 방법을 보여줍니다.

WITH example AS
 (SELECT ST_GEOGFROMTEXT('LINESTRING(0 0, 0.05 0, 0.1 0, 0.15 0, 2 0)') AS line)
SELECT
   line AS original_line,
   ST_SIMPLIFY(line, 1) AS simplified_line
FROM example;

+---------------------------------------------+----------------------+
|                original_line                |   simplified_line    |
+---------------------------------------------+----------------------+
| LINESTRING(0 0, 0.05 0, 0.1 0, 0.15 0, 2 0) | LINESTRING(0 0, 2 0) |
+---------------------------------------------+----------------------+

다음 예시는 ST_SIMPLIFY의 결과가 원래 도형보다 더 낮은 치수를 가질 수 있는 방법을 보여줍니다.

WITH example AS
 (SELECT
    ST_GEOGFROMTEXT('POLYGON((0 0, 0.1 0, 0.1 0.1, 0 0))') AS polygon,
    t AS tolerance
  FROM UNNEST([1000, 10000, 100000]) AS t)
SELECT
  polygon AS original_triangle,
  tolerance AS tolerance_meters,
  ST_SIMPLIFY(polygon, tolerance) AS simplified_result
FROM example

+-------------------------------------+------------------+-------------------------------------+
|          original_triangle          | tolerance_meters |          simplified_result          |
+-------------------------------------+------------------+-------------------------------------+
| POLYGON((0 0, 0.1 0, 0.1 0.1, 0 0)) |             1000 | POLYGON((0 0, 0.1 0, 0.1 0.1, 0 0)) |
| POLYGON((0 0, 0.1 0, 0.1 0.1, 0 0)) |            10000 |            LINESTRING(0 0, 0.1 0.1) |
| POLYGON((0 0, 0.1 0, 0.1 0.1, 0 0)) |           100000 |                          POINT(0 0) |
+-------------------------------------+------------------+-------------------------------------+

ST_SNAPTOGRID

ST_SNAPTOGRID(geography_expression, grid_size)

설명

각 꼭짓점이 경도/위도 그리드에 맞춰진 입력 GEOGRAPHY를 반환합니다. 그리드 크기는 도 단위로 지정된 grid_size 매개변수에 따라 결정됩니다.

제약조건

임의의 그리드 크기는 지원되지 않습니다. grid_size 매개변수는 10^n 형식이 되도록 반올림됩니다. 단, -10 < n < 0입니다.

반환 유형

GEOGRAPHY

ST_STARTPOINT

ST_STARTPOINT(linestring_geography)

설명

유도선 지리의 첫 번째 점을 점 지리로 반환합니다. 입력이 유도선이 아니거나 입력이 비어 있으면 오류를 반환합니다. SAFE 프리픽스를 사용하여 오류 대신 잘못된 입력에 대한 NULL을 얻습니다.

반환 유형

점 GEOGRAPHY

예시

SELECT ST_StartPoint(ST_GeogFromText('linestring(1 1, 2 1, 3 2, 3 3)')) first

+--------------+
| first        |
+--------------+
| POINT(1 1)   |
+--------------+

ST_TOUCHES

ST_TOUCHES(geography_1, geography_2)

설명

다음 두 조건이 충족되면 TRUE를 반환합니다.

geography_1이 geography_2와 교차합니다.
geography_1의 내부와 geography_2의 내부는 분리되어 있습니다.

반환 유형

BOOL

ST_UNION

ST_UNION(geography_1, geography_2)

ST_UNION(array_of_geography)

설명

모든 입력 GEOGRAPHY의 점 합집합을 나타내는 GEOGRAPHY를 반환합니다.

ST_UNION에는 2가지 유형이 있습니다. 첫 번째 유형에서는 GEOGRAPHY를 2개 입력해야 합니다. 두 번째 유형에서는 GEOGRAPHY 유형의 ARRAY를 입력해야 합니다.

첫 번째 ST_UNION 유형의 경우 입력된 GEOGRAPHY가 NULL이면 ST_UNION은 NULL을 반환합니다. 두 번째 유형의 경우 입력된 ARRAY 값이 NULL이면 ST_UNION은 NULL을 반환합니다. 입력된 ARRAY가 NULL이 아니면 합집합이 계산되고 출력에 영향을 주지 않도록 NULL 요소가 무시됩니다.

ST_UNION의 집계 버전은 ST_UNION_AGG를 참조하세요.

반환 유형

GEOGRAPHY

ST_UNION_AGG

ST_UNION_AGG(geography)

설명

모든 입력 GEOGRAPHY의 점 합집합을 나타내는 GEOGRAPHY를 반환합니다.

ST_UNION_AGG는 입력된 GEOGRAPHY의 NULL 값을 무시합니다.

ST_UNION_AGG의 비집계 버전은 ST_UNION을 참조하세요.

반환 유형

GEOGRAPHY

ST_WITHIN

ST_WITHIN(geography_1, geography_2)

설명

geography_1의 어떠한 점도 geography_2 외부에 있지 않고 geography_1과 geography_2의 내부가 교차하면 TRUE를 반환합니다.

두 지리 위치가 a, b일 때 ST_WITHIN(a, b)은 ST_CONTAINS(b, a)와 동일한 결과를 반환합니다 인수 순서가 반대라는 점에 유의하세요.

반환 유형

BOOL

ST_X

ST_X(geography_expression)

설명

단일 점 입력 GEOGRAPHY의 경도를 도 단위로 반환합니다.

입력 GEOGRAPHY가 단일 점이 아니면(빈 GEOGRAPHY인 경우 포함) ST_X는 오류를 반환합니다. NULL이 반환되도록 하려면 SAFE. 프리픽스를 사용하세요.

반환 유형

FLOAT64

예시

다음 예시에서는 ST_X 및 ST_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는 오류를 반환합니다. 대신 NULL이 반환되도록 하려면 SAFE. 프리픽스를 사용하세요.

반환 유형

FLOAT64

예시

사용 예시는 ST_X를 참조하세요.