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

Запрос состоит из нескольких предложений: 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 . Вам нужно только добавить их атрибуты в предложение 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

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

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

См. раздел «Сегментация», чтобы узнать больше о сегментации отчетов.

Чувствительность к регистру

При фильтрации строковых значений чувствительность к регистру по умолчанию для каждого оператора играет важную роль в правильной фильтрации результатов.

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

Чувствительность к регистру по умолчанию
=/!= 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"

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