매개변수화된 쿼리 실행
BigQuery에서는 사용자 입력을 사용해 쿼리를 구성할 때 SQL 삽입을 피할 수 있도록 쿼리 매개변수를 지원합니다. 이 기능은 GoogleSQL 구문에서만 사용이 가능하며, 쿼리 매개변수는 임의의 표현식 대신 사용할 수 있습니다. 매개변수는 식별자, 열 이름, 표 이름 또는 쿼리의 다른 부분을 대체할 수 없습니다.
이름 지정 매개변수를 지정하려면 식별자 앞에 @
문자를 사용합니다(예: @param_name
). 또는 자리표시자 값 ?
를 사용해 위치 매개변수를 지정합니다. 쿼리에서는 위치 또는 이름 지정 매개변수를 사용할 수 있으나 동시에 둘 다 사용할 수는 없습니다.
다음과 같은 방법으로 BigQuery에서 매개변수화된 쿼리를 실행할 수 있습니다.
- bq 명령줄 도구의
bq query
명령어 - API
- 클라이언트 라이브러리
다음 예시에서는 매개변수 값을 매개변수화된 쿼리에 전달하는 방법을 보여줍니다.
콘솔
매개변수화된 쿼리는 Google Cloud Console에서 지원되지 않습니다.
bq
-
In the Google Cloud console, activate Cloud Shell.
At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
--parameter
를 사용하여name:type:value
형식의 매개변수 값을 제공합니다. 이름이 비어 있으면 위치 매개변수가 생성됩니다. 유형을 생략하여STRING
을 가정할 수도 있습니다.--parameter
플래그를--use_legacy_sql=false
플래그와 함께 사용해 GoogleSQL 구문을 지정해야 합니다.(선택사항)
--location
플래그를 사용하여 위치를 지정합니다.bq query \ --use_legacy_sql=false \ --parameter=corpus::romeoandjuliet \ --parameter=min_word_count:INT64:250 \ 'SELECT word, word_count FROM `bigquery-public-data.samples.shakespeare` WHERE corpus = @corpus AND word_count >= @min_word_count ORDER BY word_count DESC;'
API
이름 지정 매개변수를 사용하려면 query
작업 구성에서 parameterMode
를 NAMED
로 설정합니다.
query
작업 구성의 매개변수 목록으로 queryParameters
를 채웁니다. 쿼리에서 사용된 @param_name
을 사용하여 각 매개변수의 name
을 설정합니다.
useLegacySql
을 false
로 설정하여 GoogleSQL 구문을 사용 설정합니다.
{
"query": "SELECT word, word_count FROM `bigquery-public-data.samples.shakespeare` WHERE corpus = @corpus AND word_count >= @min_word_count ORDER BY word_count DESC;",
"queryParameters": [
{
"parameterType": {
"type": "STRING"
},
"parameterValue": {
"value": "romeoandjuliet"
},
"name": "corpus"
},
{
"parameterType": {
"type": "INT64"
},
"parameterValue": {
"value": "250"
},
"name": "min_word_count"
}
],
"useLegacySql": false,
"parameterMode": "NAMED"
}
위치 매개변수를 사용하려면 query
작업 구성에서 parameterMode
를 POSITIONAL
로 설정합니다.
C#
이 샘플을 사용해 보기 전에 BigQuery 빠른 시작: 클라이언트 라이브러리 사용의 C# 설정 안내를 따르세요. 자세한 내용은 BigQuery C# API 참고 문서를 확인하세요.
BigQuery에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.
이름 지정 매개변수를 사용하는 방법:이 샘플을 사용해 보기 전에 BigQuery 빠른 시작: 클라이언트 라이브러리 사용의 C# 설정 안내를 따르세요. 자세한 내용은 BigQuery C# API 참고 문서를 확인하세요.
BigQuery에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.
위치 매개변수를 사용하는 방법:Go
이 샘플을 사용해 보기 전에 BigQuery 빠른 시작: 클라이언트 라이브러리 사용의 Go 설정 안내를 따르세요. 자세한 내용은 BigQuery Go API 참고 문서를 확인하세요.
BigQuery에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.
이름 지정 매개변수를 사용하는 방법:자바
이 샘플을 사용해 보기 전에 BigQuery 빠른 시작: 클라이언트 라이브러리 사용의 Java 설정 안내를 따르세요. 자세한 내용은 BigQuery Java API 참고 문서를 확인하세요.
BigQuery에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.
이름 지정 매개변수를 사용하는 방법:Node.js
이 샘플을 사용해 보기 전에 BigQuery 빠른 시작: 클라이언트 라이브러리 사용의 Node.js 설정 안내를 따르세요. 자세한 내용은 BigQuery Node.js API 참고 문서를 확인하세요.
BigQuery에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.
이름 지정 매개변수를 사용하는 방법:Python
이 샘플을 사용해 보기 전에 BigQuery 빠른 시작: 클라이언트 라이브러리 사용의 Python 설정 안내를 따르세요. 자세한 내용은 BigQuery Python API 참고 문서를 확인하세요.
BigQuery에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.
이름 지정 매개변수를 사용하는 방법:매개변수화된 쿼리에서 배열 사용
쿼리 매개변수에서 배열 유형을 사용하려면 유형을 ARRAY<T>
로 설정합니다. 여기서 T
는 배열 요소의 유형입니다. [1, 2,
3]
과 같이 대괄호로 묶이고 쉼표로 구분된 요소 목록으로 값을 구성합니다.
배열 유형에 대한 자세한 내용은 데이터 유형 참조를 확인하세요.
Console
매개변수화된 쿼리는 Google Cloud Console에서 지원되지 않습니다.
bq
-
In the Google Cloud console, activate Cloud Shell.
At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
이 쿼리에서는 미국 주에서 태어난 남아의 이름 중 W로 시작하는 가장 인기 있는 이름을 선택합니다.
bq query \ --use_legacy_sql=false \ --parameter='gender::M' \ --parameter='states:ARRAY<STRING>:["WA", "WI", "WV", "WY"]' \ 'SELECT name, SUM(number) AS count FROM `bigquery-public-data.usa_names.usa_1910_2013` WHERE gender = @gender AND state IN UNNEST(@states) GROUP BY name ORDER BY count DESC LIMIT 10;'
>
문자로 명령어 결과가 의도치 않게 파일로 리디렉션되지 않도록 배열 유형 선언을 작은따옴표로 묶어야 합니다.
API
배열 값 매개변수를 사용하려면 query
작업 구성에서 parameterType
을 ARRAY
로 설정합니다.
배열 값이 스칼라인 경우 parameterType
을 STRING
등의 값 유형으로 설정합니다. 배열 값이 구조체인 경우에는 STRUCT
로 설정하고 필요한 필드 정의를 structTypes
에 추가합니다.
예를 들어 이 쿼리에서는 미국 주에서 태어난 남아의 이름 중 W로 시작하는 가장 인기 있는 이름을 선택합니다.
{
"query": "SELECT name, sum(number) as count\nFROM `bigquery-public-data.usa_names.usa_1910_2013`\nWHERE gender = @gender\nAND state IN UNNEST(@states)\nGROUP BY name\nORDER BY count DESC\nLIMIT 10;",
"queryParameters": [
{
"parameterType": {
"type": "STRING"
},
"parameterValue": {
"value": "M"
},
"name": "gender"
},
{
"parameterType": {
"type": "ARRAY",
"arrayType": {
"type": "STRING"
}
},
"parameterValue": {
"arrayValues": [
{
"value": "WA"
},
{
"value": "WI"
},
{
"value": "WV"
},
{
"value": "WY"
}
]
},
"name": "states"
}
],
"useLegacySql": false,
"parameterMode": "NAMED"
}
C#
이 샘플을 사용해 보기 전에 BigQuery 빠른 시작: 클라이언트 라이브러리 사용의 C# 설정 안내를 따르세요. 자세한 내용은 BigQuery C# API 참고 문서를 확인하세요.
BigQuery에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.
Go
이 샘플을 사용해 보기 전에 BigQuery 빠른 시작: 클라이언트 라이브러리 사용의 Go 설정 안내를 따르세요. 자세한 내용은 BigQuery Go API 참고 문서를 확인하세요.
BigQuery에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.
Java
이 샘플을 사용해 보기 전에 BigQuery 빠른 시작: 클라이언트 라이브러리 사용의 Java 설정 안내를 따르세요. 자세한 내용은 BigQuery Java API 참고 문서를 확인하세요.
BigQuery에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.
Node.js
이 샘플을 사용해 보기 전에 BigQuery 빠른 시작: 클라이언트 라이브러리 사용의 Node.js 설정 안내를 따르세요. 자세한 내용은 BigQuery Node.js API 참고 문서를 확인하세요.
BigQuery에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.
Python
이 샘플을 사용해 보기 전에 BigQuery 빠른 시작: 클라이언트 라이브러리 사용의 Python 설정 안내를 따르세요. 자세한 내용은 BigQuery Python API 참고 문서를 확인하세요.
BigQuery에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.
매개변수화된 쿼리에서 타임스탬프 사용
쿼리 매개변수에서 타임스탬프를 사용하기 위해 기본 REST API는 YYYY-MM-DD HH:MM:SS.DDDDDD time_zone
형식의 TIMESTAMP
유형 값을 사용합니다. 클라이언트 라이브러리를 사용하는 경우에는 해당 언어로 기본 제공 날짜 객체를 만들고 라이브러리는 이 형식을 올바른 형식으로 변환합니다. 자세한 내용은 다음 언어별 예시를 참조하세요.
TIMESTAMP
유형에 대한 자세한 내용은 데이터 유형 참조를 확인하세요.
Console
매개변수화된 쿼리는 Google Cloud Console에서 지원되지 않습니다.
bq
-
In the Google Cloud console, activate Cloud Shell.
At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
이 쿼리는 타임스탬프 매개변수 값에 한 시간을 추가합니다.
bq query \ --use_legacy_sql=false \ --parameter='ts_value:TIMESTAMP:2016-12-07 08:00:00' \ 'SELECT TIMESTAMP_ADD(@ts_value, INTERVAL 1 HOUR);'
API
타임스탬프 매개변수를 사용하려면 쿼리 작업 구성에서 parameterType
을 TIMESTAMP
로 설정합니다.
이 쿼리는 타임스탬프 매개변수 값에 한 시간을 추가합니다.
{
"query": "SELECT TIMESTAMP_ADD(@ts_value, INTERVAL 1 HOUR);",
"queryParameters": [
{
"name": "ts_value",
"parameterType": {
"type": "TIMESTAMP"
},
"parameterValue": {
"value": "2016-12-07 08:00:00"
}
}
],
"useLegacySql": false,
"parameterMode": "NAMED"
}
C#
이 샘플을 사용해 보기 전에 BigQuery 빠른 시작: 클라이언트 라이브러리 사용의 C# 설정 안내를 따르세요. 자세한 내용은 BigQuery C# API 참고 문서를 확인하세요.
BigQuery에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.
Go
이 샘플을 사용해 보기 전에 BigQuery 빠른 시작: 클라이언트 라이브러리 사용의 Go 설정 안내를 따르세요. 자세한 내용은 BigQuery Go API 참고 문서를 확인하세요.
BigQuery에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.
Java
이 샘플을 사용해 보기 전에 BigQuery 빠른 시작: 클라이언트 라이브러리 사용의 Java 설정 안내를 따르세요. 자세한 내용은 BigQuery Java API 참고 문서를 확인하세요.
BigQuery에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.
Node.js
이 샘플을 사용해 보기 전에 BigQuery 빠른 시작: 클라이언트 라이브러리 사용의 Node.js 설정 안내를 따르세요. 자세한 내용은 BigQuery Node.js API 참고 문서를 확인하세요.
BigQuery에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.
Python
이 샘플을 사용해 보기 전에 BigQuery 빠른 시작: 클라이언트 라이브러리 사용의 Python 설정 안내를 따르세요. 자세한 내용은 BigQuery Python API 참고 문서를 확인하세요.
BigQuery에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.
매개변수화된 쿼리에서 구조체 사용
쿼리 매개변수에서 구조체를 사용하려면 유형을 STRUCT<T>
로 설정합니다. 여기서 T
는 구조체 내 필드 및 유형을 정의합니다. 필드 정의는 쉼표로 구분하며 field_name TF
형식을 사용합니다. 여기서 TF
는 필드 유형입니다. 예를 들어 STRUCT<x INT64, y STRING>
은 이름이 x
이고 유형이 INT64
인 필드와 이름이 y
이고 유형이 STRING
인 두 번째 필드가 포함된 구조체를 정의합니다.
STRUCT
유형에 대한 자세한 내용은 데이터 유형 참조를 확인하세요.
Console
매개변수화된 쿼리는 Google Cloud Console에서 지원되지 않습니다.
bq
-
In the Google Cloud console, activate Cloud Shell.
At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
이 간단한 쿼리에서는 매개변수 값을 반환해 구조화된 유형의 사용을 보여줍니다.
bq query \ --use_legacy_sql=false \ --parameter='struct_value:STRUCT<x INT64, y STRING>:{"x": 1, "y": "foo"}' \ 'SELECT @struct_value AS s;'
API
구조 매개변수를 사용하려면 쿼리 작업 구성에서 parameterType
을 STRUCT
로 설정합니다.
구조의 각 필드 객체를 작업의 queryParameters
에 있는 structTypes
에 추가합니다.
구조 값이 스칼라인 경우 type
을 STRING
등의 값 유형으로 설정합니다. 구조체 값이 배열인 경우 이를 ARRAY
로 설정하고 중첩 arrayType
필드를 적절한 유형으로 설정합니다. 구조체 값이 구조체이면 type
을 STRUCT
로 설정하고 필요한 structTypes
를 추가합니다.
이 간단한 쿼리에서는 매개변수 값을 반환하여 구조화된 유형의 사용을 보여줍니다.
{
"query": "SELECT @struct_value AS s;",
"queryParameters": [
{
"name": "struct_value",
"parameterType": {
"type": "STRUCT",
"structTypes": [
{
"name": "x",
"type": {
"type": "INT64"
}
},
{
"name": "y",
"type": {
"type": "STRING"
}
}
]
},
"parameterValue": {
"structValues": {
"x": {
"value": "1"
},
"y": {
"value": "foo"
}
}
}
}
],
"useLegacySql": false,
"parameterMode": "NAMED"
}
C#
.NET용 BigQuery 클라이언트 라이브러리는 구조체 매개변수를 지원하지 않습니다.
Go
이 샘플을 사용해 보기 전에 BigQuery 빠른 시작: 클라이언트 라이브러리 사용의 Go 설정 안내를 따르세요. 자세한 내용은 BigQuery Go API 참고 문서를 확인하세요.
BigQuery에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.
Java
이 샘플을 사용해 보기 전에 BigQuery 빠른 시작: 클라이언트 라이브러리 사용의 Java 설정 안내를 따르세요. 자세한 내용은 BigQuery Java API 참고 문서를 확인하세요.
BigQuery에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.
Node.js
이 샘플을 사용해 보기 전에 BigQuery 빠른 시작: 클라이언트 라이브러리 사용의 Node.js 설정 안내를 따르세요. 자세한 내용은 BigQuery Node.js API 참고 문서를 확인하세요.
BigQuery에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.
Python
이 샘플을 사용해 보기 전에 BigQuery 빠른 시작: 클라이언트 라이브러리 사용의 Python 설정 안내를 따르세요. 자세한 내용은 BigQuery Python API 참고 문서를 확인하세요.
BigQuery에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.