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

Запрос состоит из ряда условий: 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

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

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

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

SELECT
  conversion_custom_metrics.id[123454321]
FROM campaign

SELECT
  conversion_custom_dimensions.id[123454321]
FROM campaign

Пользовательские колонки

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

В этом примере запрос включает пользовательский столбец с ID 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

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

В этом примере запроса для поля segments.date в предложении WHERE указывается 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 :

• Является необязательным условием в запросе.
• Указывает порядок возврата результатов. Порядок следующий: 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 :

• Является необязательным условием в запросе.
• Позволяет ограничить количество результатов, возвращаемых запросом.

Этот пункт полезен, например, если вас интересует только выборка или краткое изложение результатов.

В этом примере запроса общее количество результатов ограничено 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 . По умолчанию используется валюта учетной записи, указанной параметром customer_id . Если вы установите этот параметр, вам потребуется использовать трехсимвольный код валюты ISO 4217. Например: USD, EUR.

В этом примере запроса возвращается метрика cost_micros в валюте учетной записи, указанной в customer_id .

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"

Включить расширение MCC

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

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

Этот пример запроса возвращает значения bidding_strategy.name , bidding_strategy.type и metrics.cost_micros из всех учетных записей в иерархии учетных записей, корнем которой является 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

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

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