쿼리는 SELECT
, FROM
, WHERE
, ORDER BY
, LIMIT
, PARAMETERS
등의 여러 절로 구성됩니다.
절에는 단일 쿼리 요청으로 결합되는 필드 이름, 리소스 이름, 연산자, 조건, 순서가 사용됩니다.
기본적으로 쿼리를 작성하려면 다음 단계를 따르세요.
- 데이터를 검색할 리소스를 지정합니다.
- 필드와 측정항목을 추가하여 반환할 데이터를 정의합니다.
- 세그먼트를 추가하여 결과를 그룹화하세요.
- 기여 분석 리소스를 추가하여 관련 리소스 데이터를 암시적으로 조인합니다.
- 결과를 필터링하고 정렬하고 제한합니다.
SELECT
절
SELECT
절의 특징은 다음과 같습니다.
- 쿼리의 필수 절입니다.
- 요청에서 가져올 필드 집합을 지정합니다.
- 쉼표로 구분된 리소스 필드, 맞춤 열, 맞춤 플러드라이트 변수, 세그먼트 필드, 측정항목의 목록을 가져와서 응답으로 값을 반환합니다.
다음 쿼리 예시는 campaign
리소스의 속성을 선택하는 방법을 보여줍니다.
SELECT
campaign.id,
campaign.name
FROM campaign
여러 필드 유형
동일한 요청에서 다른 필드 유형을 요청할 수 있습니다.
아래의 쿼리 예는 다음을 조합한 단일 쿼리를 보여줍니다.
- 리소스 필드:
campaign.id
,campaign.name
,bidding_strategy.id
,bidding_strategy.name
- 세그먼트 필드:
segments.device
및segments.date
- 측정항목 필드:
metrics.impressions
및metrics.clicks
SELECT
campaign.id,
campaign.name,
bidding_strategy.id,
bidding_strategy.name,
segments.device,
segments.date,
metrics.impressions,
metrics.clicks
FROM campaign
WHERE segments.date DURING LAST_30_DAYS
검색 보고서 분류 기준에 대한 자세한 내용은 분류 기준을 참조하세요.
기본 리소스 필드
일반적으로 SELECT
절에 기본 리소스 필드를 포함하지만 이는 선택 사항입니다 (필수 아님).
이 쿼리 예시는 기본 리소스 필드 (ad_group.status
)를 사용하여 결과만 필터링합니다.
SELECT campaign.id
FROM ad_group
WHERE ad_group.status = PAUSED
맞춤 플러드라이트 변수
ID를 사용하여 SELECT 절에 맞춤 플러드라이트 변수를 포함할 수 있습니다.
이 예에서 쿼리에는 캠페인 리소스에 대해 ID가 123454321인 맞춤 변수가 포함되어 있습니다.
SELECT
conversion_custom_metrics.id[123454321]
FROM campaign
SELECT
conversion_custom_dimensions.id[123454321]
FROM campaign
맞춤 열
ID를 사용하여 SELECT 절에 맞춤 열을 포함할 수 있습니다.
이 예시의 쿼리에는 캠페인 리소스에 대해 ID가 12345678인 맞춤 열이 포함되어 있습니다.
SELECT
custom_columns.id[12345678]
FROM campaign
맞춤 열 ID를 가져오는 방법을 참고하세요.
측정항목 필드
SELECT
절에 리소스의 다른 필드를 포함하지 않고 특정 리소스의 측정항목 필드를 선택할 수 있습니다.
이 쿼리 예시는 campaign
리소스에 대해 impressions
및 clicks
측정항목을 선택합니다.
SELECT
metrics.impressions,
metrics.clicks
FROM campaign
쿼리에 사용할 수 있는 측정항목 필드 목록은 metrics
를 참조하세요.
세그먼트 필드
SELECT
절에 수반되는 리소스 필드 또는 측정항목을 지정하지 않고도 세그먼트 필드를 선택할 수 있습니다.
이 쿼리 예에서는 기기별로 결과를 분류합니다.
SELECT segments.device
FROM campaign
쿼리에서 사용할 수 있는 세그먼트 필드 목록은 segments
를 참고하세요.
금지된 입력란
SELECT
절에는 다음 필드를 사용할 수 없습니다.
- 선택할 수 없는 필드, 즉
Selectable
메타데이터 속성이false
로 표시된 필드입니다. - 반복되는 필드, 즉
Repeated
메타데이터 속성이true
로 표시된 필드입니다. FROM
절의 지정된 리소스에 사용할 수 없는 필드입니다. 일부 리소스의 속성은 함께 선택할 수 없습니다. 일부 리소스는 모든 측정항목 및 세그먼트의 하위 집합만 제공합니다.- 호환되지 않는 세그먼트 또는 측정항목입니다. 자세한 내용은 세분화를 참고하세요.
각 리소스의 이 정보를 찾을 수 있는 위치에 대한 자세한 내용은 참조 문서를 확인하세요.
FROM 절
FROM
절의 특징은 다음과 같습니다.
SearchAds360Service
에 대한 쿼리(Search
및SearchStream
메서드 모두)에 필수 절입니다.SearchAds360FieldService
에 대한 쿼리에는 포함되면 안 됩니다.- 쿼리가 반환하는 기본 리소스를 지정합니다.
- 단일 리소스만 지정할 수 있습니다.
- 쿼리의 다른 모든 절에서 사용할 수 있는 필드를 정의합니다.
기여 리소스
기여 분석 리소스를 사용할 수 있는 경우 이러한 리소스는 FROM
절에 지정된 리소스와 암시적으로 조인됩니다. 값을 반환하려면 SELECT
절에 속성을 추가하기만 하면 됩니다.
이 쿼리 예시는 광고그룹 ID와 캠페인 ID를 모두 반환합니다. campaign
가 ad_group
리소스의 기여 리소스이기 때문입니다.
SELECT
campaign.id,
ad_group.id
FROM ad_group
resource_name
필드
FROM
절에서 기본 리소스의 resource_name
필드가 항상 반환됩니다.
이 쿼리 예시에서는 ad_group.resource_name
가 쿼리에서 명시적으로 선택되지 않았더라도 응답에 포함됩니다.
SELECT ad_group.id
FROM ad_group
1개 이상의 필드가 선택되면 기여 리소스의 resource_name
필드가 반환됩니다.
이 쿼리 예시에서는 campaign.id
가 선택되었으므로 campaign.resource_name
가 응답에 포함됩니다.
SELECT
campaign.id,
ad_group.id
FROM ad_group
WHERE 절
WHERE
절의 특징은 다음과 같습니다.
- 쿼리의 선택적 절입니다.
- 요청 데이터를 필터링하고 세분화하기 위한 조건을 지정합니다.
조건은 다음 패턴을 따릅니다.
FIELD_NAME
OPERATOR
VALUE
(공백으로 구분) AND
구분자로 구분된 여러 조건을 포함할 수 있습니다.
이 쿼리 예시는 WHERE
절을 사용하여 지정된 기간의 impressions
측정항목을 반환하는 방법을 보여줍니다.
SELECT
campaign.id,
campaign.name,
metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_30_DAYS
검색 보고서 분류 기준에 대한 자세한 내용은 분류 기준을 참조하세요.
쿼리에서 기간을 지정하는 방법에 대한 자세한 내용은 기간을 참조하세요.
resource_name
필드로 필터링
resource_name
필드를 사용하여 데이터를 필터링하거나 정렬할 수 있습니다.
이 쿼리 예시는 campaign.resource_name
필드를 사용하여 지정된 캠페인별로 결과를 필터링합니다.
SELECT
campaign.id,
campaign.name
FROM campaign
WHERE campaign.resource_name = 'customers/1234567/campaigns/987654'
여러 조건
여러 조건을 조합하여 데이터를 필터링할 수 있습니다.
이 쿼리 예시는 지난 30일 동안 모바일에서 impressions
측정항목이 있는 모든 캠페인의 clicks
측정항목 수를 요청합니다.
SELECT
campaign.id,
campaign.name,
segments.device,
metrics.clicks
FROM campaign
WHERE metrics.impressions > 0
AND segments.device = MOBILE
AND segments.date DURING LAST_30_DAYS
보고서 분류에 대한 자세한 내용은 분류 기준을 참조하세요.
대소문자 구분
문자열 값을 필터링할 때 각 연산자의 기본 대소문자 구분은 결과를 올바르게 필터링하는 데 중요한 역할을 합니다.
다음 표에는 각 연산자의 기본 대소문자 구분이 나와 있습니다.
기본 대소문자 구분 | |
---|---|
=/!= |
Case sensitive |
IN/NOT IN |
Case sensitive |
LIKE/NOT LIKE |
Case insensitive |
CONTAINS (...) |
Case sensitive |
REGEXP_MATCH/NOT REGEXP_MATCH |
Case sensitive |
(?i)
수정자를 사용하여 REGEXP_MATCH
및 NOT REGEXP_MATCH
의 기본 민감도를 대소문자를 구분하지 않도록 변경할 수 있습니다. 예를 들면 다음과 같습니다.
SELECT campaign.id
FROM campaign
WHERE campaign.name REGEXP_MATCH "(?i).*test.*"
데이터를 필터링하는 데 사용할 수 있는 연산자의 전체 목록은 쿼리 문법 참조를 확인하세요.
핵심 날짜 세그먼트
segments.date
, segments.week
, segments.month
, segments.quarter
, segments.year
세그먼트 필드를 핵심 날짜 세그먼트라고 합니다.
WHERE
절에서 핵심 날짜 세그먼트를 사용하여 날짜 또는 기간을 지정할 수 있습니다.
이 쿼리 예시는 WHERE
절의 segments.date
필드에 DURING LAST_30_DAYS
를 지정합니다.
SELECT
campaign.id,
campaign.name,
segments.date,
metrics.clicks
FROM campaign
WHERE segments.date DURING LAST_30_DAYS
핵심 날짜 세그먼트 사용에 관한 자세한 내용은 분류 기준 > 핵심 날짜 세그먼트를 참고하세요.
금지된 필터링
다음 필터링은 허용되지 않습니다.
- 선택되지 않은 세그먼트 필드(핵심 날짜 세그먼트 제외)
- 프리미티브 (예:
Int64Value
,StringValue
등)를 제외한 모든 메시지 유형의 필드 - 프리미티브(예:
Int64Value
,StringValue
등)를 제외한 모든 메시지 유형의 반복되는 필드 속성
ORDER BY 절
ORDER BY
절의 특징은 다음과 같습니다.
- 쿼리의 선택적 절입니다.
- 결과가 반환되는 순서를 지정합니다. 순서는
FIELD_NAME
ORDERING_OPTION
(공백으로 구분됨) 패턴을 따릅니다. ASC
(오름차순) 또는DESC
(내림차순)의 두 가지 옵션이 허용됩니다. 기본값은 오름차순입니다.
이 쿼리 예시는 클릭수를 기준으로 내림차순(내림차순)으로 캠페인을 정렬합니다.
SELECT
campaign.name,
metrics.clicks
FROM campaign
ORDER BY metrics.clicks DESC
여러 순서 지정
쉼표로 구분된 목록을 사용하여 ORDER BY
절에 여러 필드를 지정할 수 있습니다. 결과는 쿼리에 지정한 순서와 동일한 순서로 정렬됩니다.
이 쿼리 예에서는 광고 그룹 데이터를 선택하고 결과를 캠페인 이름에 따라 오름차순으로 정렬한 다음 노출수를 기준으로 내림차순으로 정렬하고, 클릭수를 기준으로 내림차순으로 정렬합니다.
SELECT
campaign.name,
ad_group.name,
metrics.impressions,
metrics.clicks
FROM ad_group
ORDER BY
campaign.name,
metrics.impressions DESC,
metrics.clicks DESC
순서 지정 및 한도 결합
ORDER BY
절을 LIMIT
절과 함께 사용하여 결과를 세분화할 수 있습니다.
이 쿼리 예시는 지난 30일 동안 노출수가 가장 높은 캠페인 5개를 반환합니다.
SELECT
campaign.id,
campaign.name,
metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_30_DAYS
ORDER BY metrics.impressions DESC
LIMIT 5
금지된 주문
다음은 주문이 허용되지 않습니다.
- 선택되지 않은 리소스의 속성 기준
- 선택되지 않은 측정항목 기준
- 선택되지 않은 세그먼트 기준
- 이 필드 유형은 다음과 같습니다.
MESSAGE
- 반복 필드
- 반복되는 필드의 속성입니다.
LIMIT 절
LIMIT
절의 특징은 다음과 같습니다.
- 쿼리의 선택적 절입니다.
- 쿼리가 반환하는 결과의 수를 제한할 수 있습니다.
이 절은 예를 들어 샘플이나 결과 요약에만 관심이 있는 경우에 유용합니다.
이 쿼리 예시는 총 결과 수를 50개로 제한합니다.
SELECT
campaign.name,
ad_group.name,
segments.device,
metrics.impressions
FROM ad_group
ORDER BY metrics.impressions DESC
LIMIT 50
PARAMETERS 절
PARAMETERS
절을 사용하면 요청의 메타 매개변수를 지정할 수 있습니다.
초안 포함
include_drafts
매개변수는 초안 항목을 결과에 포함할지 여부를 제어합니다. 기본값은 false
입니다. 초안 항목을 포함하려면 true
로 설정합니다.
이 쿼리 예시는 임시 캠페인과 일반 캠페인을 모두 반환합니다.
SELECT campaign.name
FROM campaign
PARAMETERS include_drafts=true
선택 해제된 resource_name
생략
omit_unselected_resource_names
매개변수를 사용하면 SELECT
절에서 명시적으로 요청되지 않은 모든 리소스의 resource_name
필드를 제외할 수 있습니다. 기본값은 false
입니다. 이 매개변수를 true
로 설정하는 경우 SELECT
절에서 기본 리소스 및 모든 기여 리소스의 리소스 이름을 명시적으로 요청하는 것이 좋습니다.
이 쿼리 예시는 campaign.resource_name
와 customer.resource_name
필드가 SELECT
절에 포함되어 있지 않으므로 모두 반환하지 않습니다.
SELECT
campaign.name,
customer.id
FROM campaign
PARAMETERS omit_unselected_resource_names = true
이 쿼리 예시는 SELECT
절에서 명시적으로 요청되므로 campaign.resource_name
필드를 반환합니다.
SELECT
campaign.name,
campaign.resource_name
FROM campaign
PARAMETERS omit_unselected_resource_names = true
측정항목에 사용되는 통화 변경
metrics_currency
매개변수를 사용하면 SELECT
절에 포함된 측정항목을 계산할 때 사용할 통화를 지정할 수 있습니다.
기본값은 계정의 현지 통화를 사용하는 것입니다. 이 매개변수를 설정하는 경우 ISO 4217 3자 통화 코드를 사용해야 합니다.
예: USD, EUR.
이 쿼리 예시는 cost_micros 측정항목을 계정의 현지 통화로 반환합니다.
SELECT
campaign.name,
metrics.cost_micros
FROM campaign
WHERE segments.date >= "2018-08-15"
AND segments.date < "2018-08-16"
이 쿼리 예시는 칠레 페소 (CLP)의 cost_micros 측정항목을 반환합니다.
SELECT
campaign.name,
metrics.cost_micros
FROM campaign
WHERE segments.date >= "2018-08-15"
AND segments.date < "2018-08-16"
PARAMETERS metrics_currency = "CLP"