Структура запроса и предложения

Запрос состоит из нескольких предложений: SELECT , FROM , WHERE , ORDER BY , LIMIT и PARAMETERS .

В предложениях используются имена полей , имена ресурсов , операторы , условия и порядок следования , которые объединяются в один запрос.

Проще говоря, чтобы построить запрос, вы:

• Укажите ресурс, из которого нужно получить данные.
• Добавьте поля и показатели, чтобы определить данные, которые вы хотите вернуть.
• Добавьте сегменты, чтобы сгруппировать результаты.
• Добавьте атрибутированные ресурсы, чтобы неявно объединить данные связанных ресурсов.
• Фильтруйте, упорядочивайте и ограничивайте результаты.

предложение SELECT

Предложение SELECT :

• Обязательное предложение в запросе.
• Указывает набор полей для выборки в запросе.
• Принимает разделенный запятыми список полей ресурсов, специальных столбцов, пользовательских переменных Floodlight, полей сегментов и показателей и возвращает значения в ответе.

В этом примере запроса показано, как выбрать атрибуты ресурса 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

Пользовательские переменные Floodlight

Вы можете включить пользовательские переменные Floodlight в предложение SELECT, используя их идентификаторы.

В этом примере запрос включает пользовательскую переменную с идентификатором 123454321 для ресурса кампании.

SELECT
  conversion_custom_metrics.id[123454321]
FROM campaign

SELECT
  conversion_custom_dimensions.id[123454321]
FROM campaign

Пользовательские столбцы

Вы можете включить пользовательские столбцы в предложение SELECT, используя их идентификаторы.

В этом примере запрос включает настраиваемый столбец с идентификатором 12345678 для ресурса кампании.

SELECT
  custom_columns.id[12345678]
FROM campaign

Узнайте , как получить идентификаторы пользовательских столбцов .

Поля показателей

Вы можете выбрать поля показателей для данного ресурса, не включая какие-либо другие поля из ресурса в предложение SELECT .

В этом примере запроса выбираются показатели impressions и clicks для ресурса campaign .

SELECT
  metrics.impressions,
  metrics.clicks
FROM campaign

См. metrics , где приведен список полей показателей, которые вы можете использовать в своих запросах.

Поля сегментов

Вы можете выбирать поля сегментов, не указывая сопутствующие поля ресурсов или показатели в предложении SELECT .

В этом примере результаты запроса сегментируются по устройствам.

SELECT segments.device
FROM campaign

См. segments , где представлен список полей сегментов, которые вы можете использовать в своих запросах.

Запрещенные поля

В предложении SELECT нельзя использовать следующие поля:

• Невыбираемые поля, то есть поля с атрибутом метаданных Selectable », помеченным как false .
• Повторяющиеся поля, то есть поля с атрибутом метаданных Repeated », помеченным как true .
• Поля, недоступные для данного ресурса в предложении FROM . Атрибуты некоторых ресурсов нельзя выбирать вместе. Некоторые ресурсы предоставляют только подмножество всех показателей и сегментов.
• Несовместимые сегменты или показатели. См. раздел «Сегментация» для получения дополнительной информации.

См. справочную документацию для получения подробной информации о том, где найти эту информацию для каждого ресурса.

ОТ предложения

Предложение FROM :

• Это обязательное предложение для запросов к SearchAds360Service (методы Search и SearchStream ).
• Не следует включать для запросов к SearchAds360FieldService .
• Указывает основной ресурс, возвращаемый запросом.
• Можно указать только один ресурс.
• Определяет поля, которые вы можете использовать во всех остальных предложениях запроса.

Примечание. На каждой странице ресурса в разделе «Справочник» есть поле выбора «Да/Нет» , которое отфильтровывает поля ресурсов, поля сегментов и поля показателей, которые нельзя использовать, если ресурс указан в предложении FROM .

Приписанные ресурсы

Если атрибутированные ресурсы доступны, они неявно соединяются с ресурсом, указанным в предложении FROM . Вам нужно только добавить их атрибуты в предложение SELECT , чтобы вернуть их значения.

Этот пример запроса возвращает как идентификатор группы объявлений, так и идентификатор кампании, поскольку campaign является атрибутом ресурса ресурса ad_group .

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

Примечание. Не все ресурсы имеют атрибуты. Раздел «Справочник» содержит подробную информацию о ресурсах, связанных с каждым ресурсом.

поле resource_name

Поле resource_name основного ресурса в предложении FROM всегда возвращается.

В этом примере запроса ad_group.resource_name будет включено в ответ, даже если оно не выбрано явно в запросе:

SELECT ad_group.id
FROM ad_group

Поле resource_name атрибутированного ресурса возвращается, если выбрано хотя бы одно поле.

В этом примере запроса в ответ будет включен campaign.resource_name , поскольку выбран campaign.id :

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

Примечание. Если ресурс в предложении FROM указывает другой ресурс в качестве segment , выбор любых атрибутов этого ресурса действует как сегмент.

Предложение ГДЕ

Предложение 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'

Несколько условий

Вы можете объединить несколько условий для фильтрации данных.

В этом примере запроса запрашиваются показатели количества clicks для всех кампаний с показателями impressions на мобильных устройствах за последние 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

Примечание. Разделитель 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 , чтобы указать дату или период времени.

В этом примере запроса указывается DURING LAST_30_DAYS для поля segments.date в предложении WHERE :

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 дней:

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 позволяет указать метапараметры для запроса.

Включить черновики

Параметр include_drafts определяет, будут ли черновые объекты включены в результаты. По умолчанию установлено значение false . Установите для него true , чтобы включить черновики объектов.

Этот пример запроса возвращает как проекты кампаний, так и обычные кампании:

SELECT campaign.name
FROM campaign
PARAMETERS include_drafts=true

Пропустить невыбранное resource_name

Параметр omit_unselected_resource_names позволяет исключить поле resource_name из всех ресурсов, которые явно не запрошены в предложении SELECT . По умолчанию установлено значение false . Если вы установили для этого параметра значение true , мы рекомендуем вам явно запрашивать имя основного ресурса и всех атрибутивных ресурсов в предложении SELECT .

Этот пример запроса не возвращает ни поле campaign.resource_name , ни поле customer.resource_name , поскольку они не включены в предложение SELECT :

SELECT
  campaign.name,
  customer.id
FROM campaign
PARAMETERS omit_unselected_resource_names = true

Этот пример запроса возвращает поле campaign.resource_name , поскольку оно явно запрошено в предложении SELECT :

SELECT
  campaign.name,
  campaign.resource_name
FROM campaign
PARAMETERS omit_unselected_resource_names = true

Изменить валюту, используемую в показателях

Параметр metrics_currency позволяет указать валюту, которая будет использоваться при вычислении метрики, включенной в предложение SELECT . По умолчанию для счета используется местная валюта. Если вы установите этот параметр, вам необходимо использовать трехзначный код валюты ISO 4217 . Например: доллар США, евро.

Этот пример запроса возвращает метрику Cost_micros в местной валюте аккаунта.

SELECT
  campaign.name,
  metrics.cost_micros
FROM campaign
WHERE segments.date >= "2018-08-15"
AND segments.date < "2018-08-16"

Этот пример запроса возвращает метрику Cost_micros в чилийских песо (CLP).

SELECT
  campaign.name,
  metrics.cost_micros
FROM campaign
WHERE segments.date >= "2018-08-15"
AND segments.date < "2018-08-16"
PARAMETERS metrics_currency = "CLP"

Включить расширение Центра клиентов

Если для параметра enable_mcc_expansion установлено значение true, вы можете включать метрики, поля и сегменты из login_customer_id и всех обслуживающих учетных записей ниже для ресурса в предложении FROM . В ответе будет использоваться валюта login_customer_id , если это явно не указано в параметре metrics_currency .

Примечание. Параметр enable_mcc_expansion совместим только с bidding_strategy . Со временем API будет включать дополнительные ресурсы.

Этот пример запроса возвращает bidding_strategy.name , bidding_strategy.type и metrics.cost_micros из login_customer_id и всех обслуживающих аккаунтов ниже, поскольку для параметра enable_mcc_expansion установлено значение true .

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

Узнать больше

• Грамматика запроса