쿼리 구조 및 절

쿼리는 여러 절(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 절에 리소스가 지정된 경우 사용할 수 없는 리소스 필드, 세그먼트 필드, 측정항목 필드를 필터링하는 예/아니요 선택 필드가 있습니다.

기여 분석 리소스

기여 분석 리소스를 사용할 수 있는 경우 FROM 절에 지정된 리소스와 암시적으로 조인됩니다. 값을 반환하려면 SELECT 절에 속성만 추가하면 됩니다.

이 쿼리 예에서는 campaign이 ad_group 리소스의 기여 분석 리소스이므로 광고 그룹 ID와 캠페인 ID를 모두 반환합니다.

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

하나 이상의 필드가 선택되면 기여 분석 리소스의 resource_name 필드가 반환됩니다.

이 예시 쿼리에서는 campaign.id가 선택되어 있으므로 campaign.resource_name가 응답에 포함됩니다.

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

참고: FROM 절의 리소스에 다른 리소스가 segment로 나열된 경우 해당 리소스의 속성을 선택하면 세그먼트 역할을 합니다.

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

참고: AND 구분자는 연산자 조건(WHERE segments.device != "DESKTOP" AND segments.device != "MOBILE") 간에만 사용할 수 있으며 단일 연산자 조건 (WHERE segments.device != "DESKTOP" AND "MOBILE") 내에서는 사용할 수 없습니다.

보고서 분류에 대해 자세히 알아보려면 분류를 참고하세요.

대소문자 구분

문자열 값을 필터링할 때 각 연산자의 기본 대소문자 구분은 결과를 올바르게 필터링하는 데 중요한 역할을 합니다.

다음 표에는 각 연산자의 기본 대소문자 구분 여부가 나와 있습니다.

기본 대소문자 구분
=/!=	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"

MCC 확장 사용 설정

enable_mcc_expansion 매개변수를 true로 설정하면 FROM 절의 리소스에 대해 login_customer_id 및 그 아래의 모든 게재 계정의 측정항목, 필드, 세그먼트를 포함할 수 있습니다. metrics_currency 매개변수에 명시적으로 지정되지 않는 한 응답은 login_customer_id의 통화를 사용합니다.

참고: enable_mcc_expansion 매개변수는 bidding_strategy와만 호환됩니다. API는 시간이 지남에 따라 추가 리소스를 포함하게 됩니다.

이 쿼리 예에서는 enable_mcc_expansion 매개변수가 true로 설정되어 있으므로 login_customer_id 및 그 아래의 모든 게재 계정에서 bidding_strategy.name, bidding_strategy.type, metrics.cost_micros를 반환합니다.

SELECT
  bidding_strategy.name,
  bidding_strategy.type,
  metrics.cost_micros
FROM bidding_strategy
WHERE segments.date DURING LAST_14_DAYS
PARAMETERS enable_mcc_expansion = true

자세히 알아보기

• 쿼리 문법