쿼리 구조

리소스, 세그먼트, 측정항목 필드에 대한 쿼리는 GoogleAdsService Search 또는 SearchStream 메서드로 전송할 수 있습니다. Google Ads 쿼리 언어로 쿼리를 구성하려면 언어 문법을 사용하여 빌드해야 합니다. 쿼리는 여러 절로 구성됩니다.

• SELECT
• FROM
• WHERE
• ORDER BY
• LIMIT
• PARAMETERS

절은 필드 이름, 리소스 이름, 연산자, 조건, 정렬을 사용하여 올바른 데이터를 선택하는 데 도움이 됩니다. 단일 쿼리로 결합되면 Google Ads API를 사용하여 요청할 수 있습니다.

핵심사항: GoogleAdsFieldService는 모든 리소스 필드, 세그먼트 필드, 측정항목에 관한 메타데이터와 아래에 정의된 대로 각 항목 간의 관계 및 각 절의 사용 가능 여부를 Google Ads 쿼리 언어 클라이언트용 카탈로그로 제공합니다. 자세한 내용은 GoogleAdsField 문서를 참고하세요.

조항

동영상: GAQL 필드 호환성

SELECT

SELECT 절은 요청에서 가져올 필드 집합을 지정합니다. SELECT는 리소스 필드, 세그먼트 필드, 측정항목의 쉼표로 구분된 목록을 사용하여 응답에 값을 반환합니다. SELECT 절은 쿼리에서 필수입니다.

아래 샘플 쿼리는 지정된 리소스의 속성을 선택하는 예를 보여줍니다.

SELECT
  campaign.id,
  campaign.name
FROM campaign

단일 요청에서 여러 필드 유형을 요청할 수 있습니다. 예를 들면 다음과 같습니다.

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

• 리소스 필드

  • campaign.id
  • campaign.name

• 리소스 필드

  • bidding_strategy.id
  • bidding_strategy.name

• 세그먼트 필드

  • segments.device
  • segments.date

• 측정항목

  • metrics.impressions
  • metrics.clicks

다음과 같은 제한사항으로 인해 일부 필드는 SELECT 절에서 허용되지 않을 수 있습니다.

• 선택할 수 없는 필드에 쿼리합니다. 이러한 필드의 Selectable 메타데이터 속성은 false로 표시됩니다.
• 반복되는 입력란의 속성을 선택합니다. 이러한 필드의 isRepeated 메타데이터 속성은 true로 표시됩니다.
• FROM 절에서 지정된 리소스에 사용할 수 없는 필드를 선택합니다. 일부 리소스의 속성은 함께 선택할 수 없으며, FROM 절의 리소스에는 모든 측정항목과 분류 기준 중 일부만 사용할 수 있습니다.
• 서로 호환되지 않는 세그먼트 또는 측정항목을 선택합니다. 자세한 내용은 분류 섹션을 참고하세요.

위 조건과 관련된 정보는 참조 문서 또는 GoogleAdsFieldService에서 확인할 수 있습니다.

FROM

FROM 절은 반환할 기본 리소스를 지정합니다. FROM 절의 리소스는 지정된 쿼리의 다른 모든 절에서 사용할 수 있는 필드를 정의합니다. FROM 절에는 하나의 리소스만 지정할 수 있습니다. FROM 절은 GoogleAdsService Search 또는 SearchStream 메서드에 대한 쿼리에서 필수이지만 GoogleAdsFieldService를 사용할 때는 지정해서는 안 됩니다.

지정된 쿼리의 FROM 절에는 리소스가 하나만 있을 수 있지만 기여 분석 리소스의 필드도 사용할 수 있습니다. 이러한 리소스는 FROM 절의 리소스와 암시적으로 조인되므로 값을 반환하려면 SELECT 절에 속성만 추가하면 됩니다. 일부 리소스에는 저작자 표시 리소스가 없습니다. 다음 예에서는 광고 그룹에서 광고 그룹 ID와 캠페인 ID를 모두 요청할 수 있습니다.

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

기본 리소스의 resource_name 필드는 항상 반환됩니다. 다음 예에서는 쿼리에서 명시적으로 선택되지 않았음에도 불구하고 ad_group.resource_name가 응답에 포함됩니다.

SELECT ad_group.id
FROM ad_group

하나 이상의 필드가 선택된 경우 다른 리소스에도 동일하게 적용됩니다. 예를 들어 다음 쿼리의 응답에는 campaign.resource_name가 포함됩니다.

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

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

WHERE

WHERE 절은 요청의 데이터를 필터링할 때 적용할 조건을 지정합니다. WHERE 절을 사용할 때는 AND를 사용하여 하나 이상의 조건을 지정하고 구분할 수 있습니다. 각 조건은 field_name Operator value 패턴을 따라야 합니다. WHERE 절은 쿼리에서 선택사항입니다.

다음은 WHERE를 사용하여 특정 기간의 측정항목을 반환하는 예입니다.

SELECT
  campaign.id,
  campaign.name,
  metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_30_DAYS

여러 조건을 결합하여 데이터를 필터링할 수 있습니다. 이 예에서는 지난 30일 동안 모바일에서 노출된 모든 캠페인의 클릭수를 요청합니다.

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

WHERE 절의 세그먼트는 SELECT 절에 있어야 하며, 핵심 날짜 세그먼트라고 하는 다음 날짜 세그먼트는 예외입니다.

• segments.date
• segments.week
• segments.month
• segments.quarter
• segments.year

다음 쿼리에서 segments.date이 선택되어 있는 것을 확인할 수 있습니다. 이 세그먼트는 핵심 날짜 세그먼트이므로 WHERE 절에 핵심 날짜 세그먼트로 구성된 유한한 날짜 범위를 제공해야 합니다.

SELECT
  campaign.id,
  campaign.name,
  segments.date,
  metrics.clicks
FROM campaign
WHERE segments.date DURING LAST_30_DAYS

위 조건을 충족하는 모든 세그먼트는 segments.date, segments.week, segments.month, segments.quarter, segments.year입니다. 이러한 세그먼트 중 하나라도 선택된 경우 WHERE 절에서 하나 이상을 사용해야 합니다.

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

필터링할 때는 연산자의 대소문자 구분을 염두에 두어야 합니다. 자세한 내용은 대소문자 구분을 참고하세요.

전체 연산자 목록은 언어 문법을 참고하세요.

ORDER BY

ORDER BY 절은 결과가 반환되는 순서를 지정합니다. 이렇게 하면 필드 이름을 기준으로 데이터를 오름차순 또는 내림차순으로 정렬할 수 있습니다. 각 순서는 field_name 뒤에 ASC 또는 DESC이 오는 것으로 지정됩니다. ASC 또는 DESC가 지정되지 않으면 순서는 기본적으로 ASC로 설정됩니다. ORDER BY 절은 쿼리에서 선택사항입니다.

다음 쿼리는 반환된 캠페인을 클릭수 기준으로 가장 높은 순서에서 가장 낮은 순서로 정렬합니다.

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

LIMIT

LIMIT 절을 사용하면 반환할 결과 수를 지정할 수 있습니다. 요약에만 관심이 있는 경우에 유용합니다.

예를 들어 LIMIT를 사용하여 다음 쿼리의 총 결과 수를 제한할 수 있습니다.

SELECT
  campaign.name,
  ad_group.name,
  segments.device,
  metrics.impressions
FROM ad_group
ORDER BY metrics.impressions DESC
LIMIT 50

핵심사항: LIMIT를 사용하면 결과를 자르거나 GoogleAdsService.Search의 page_size 필드를 사용하여 긴 결과 목록을 처리합니다.

PARAMETERS

PARAMETERS 절을 사용하면 요청에 대한 메타 매개변수를 지정할 수 있습니다. 이러한 매개변수는 반환되는 행의 유형에 영향을 줄 수 있습니다.

현재 다음과 같은 메타 매개변수가 지원됩니다.

include_drafts

초안 항목을 반환하도록 include_drafts를 true로 설정합니다. 기본값은 false입니다.

예를 들어 다음 쿼리는 일반 캠페인과 함께 캠페인 초안을 가져옵니다.

SELECT campaign.name
FROM campaign
PARAMETERS include_drafts=true

omit_unselected_resource_names

SELECT 절에서 명시적으로 요청하지 않는 한 응답의 각 리소스 유형의 리소스 이름이 반환되지 않도록 omit_unselected_resource_names를 true로 설정합니다. 기본값은 false입니다.

참고: 반환된 객체를 업데이트 또는 삭제 작업에 사용할 계획이라면 이 옵션을 false로 설정하는 것이 좋습니다. 리소스 이름이 없는 리소스는 수정 작업에 사용할 수 없기 때문입니다. 이 옵션을 true로 설정하는 경우 기본 리소스와 쿼리를 사용하여 가져오는 모든 속성 리소스의 리소스 이름을 명시적으로 요청해야 합니다.

omit_unselected_resource_names 예시
SELECT campaign.name, customer.id FROM campaign	Returned resources: campaign.resource_name customer.resource_name omit_unselected_resource_names는 기본적으로 false로 설정되므로 모든 resource_name 필드가 반환됩니다.
SELECT campaign.name, customer.id FROM campaign PARAMETERS omit_unselected_resource_names = true	Returned resources: 없음 omit_unselected_resource_names이 true로 지정되고 campaign.resource_name 및 customer.resource_name가 SELECT 절의 일부가 아닙니다.
SELECT campaign.name, campaign.resource_name FROM campaign PARAMETERS omit_unselected_resource_names = true	Returned resource: campaign.resource_name omit_unselected_resource_names은 true로 지정되고 campaign.resource_name는 SELECT 절의 일부로 요청됩니다.

추가 언어 규칙

각 절의 예시 외에도 Google Ads 쿼리 언어에는 다음과 같은 활용 가능한 동작이 있습니다.

• 기본 리소스 필드가 쿼리의 SELECT 절에 있어야 하는 것은 아닙니다. 예를 들어 하나 이상의 기본 리소스 필드만 사용하여 데이터를 필터링할 수 있습니다.

  SELECT campaign.id
  FROM ad_group
  WHERE ad_group.status = PAUSED
  

• 특정 리소스에 대해서만 측정항목을 선택할 수 있습니다. 쿼리에는 리소스의 다른 필드가 필요하지 않습니다.

  SELECT
    metrics.impressions,
    metrics.clicks,
    metrics.cost_micros
  FROM campaign
  

• 세분화 필드는 함께 표시되는 리소스 필드나 측정항목 없이 선택할 수 있습니다.

  SELECT segments.device FROM campaign
  

• resource_name 필드 (예: campaign.resource_name)는 데이터를 필터링하거나 정렬하는 데 사용할 수 있습니다.

  SELECT
    campaign.id,
    campaign.name
  FROM campaign
  WHERE campaign.resource_name = 'customers/1234567/campaigns/987654'