쿼리 구조 및 절

쿼리는 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 절에 속성을 추가하기만 하면 됩니다.

이 쿼리 예시는 광고그룹 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

참고: 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"

자세히 알아보기

• 쿼리 문법