Struktura zapytań i klauzule

Zapytanie składa się z kilku klauzul: SELECT, FROM, WHERE, ORDER BY, LIMIT i PARAMETERS.

Klauzule używają nazw pól, nazw zasobów, operatorów, warunków i kolejności, które łączą się w jedno żądanie zapytania.

Aby utworzyć zapytanie, musisz:

  • Określ zasób, z którego chcesz pobrać dane.
  • Dodaj pola i dane, aby określić, jakie dane mają zostać zwrócone.
  • Dodaj segmenty, aby grupować wyniki.
  • Dodaj przypisane zasoby, aby niejawnie łączyć powiązane dane zasobów.
  • filtrować, sortować i ograniczać wyniki;

SELECT klauzula

Klauzula SELECT:

  • Jest wymaganą klauzulą w zapytaniu.
  • Określa zestaw pól do pobrania w żądaniu.
  • Odbiera listę pól zasobów, kolumn niestandardowych, niestandardowych zmiennych Floodlight, pól segmentów i danych oddzielonych przecinkami, a potem zwraca wartości w odpowiedzi.

Z tego przykładowego zapytania dowiesz się, jak wybrać atrybuty zasobu campaign:

SELECT
  campaign.id,
  campaign.name
FROM campaign

Wiele typów pól

W jednym żądaniu możesz poprosić o różne typy pól.

Przykładowe zapytanie poniżej przedstawia jedno zapytanie z kombinacją tych elementów:

  • Pola zasobu: campaign.id, campaign.name, bidding_strategy.id i bidding_strategy.name.
  • Pola segmentu: segments.device i segments.date.
  • Pola danych: metrics.impressions i 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

Aby dowiedzieć się więcej o dzielenie raportów wyszukiwania na segmenty, zapoznaj się z artykułem Segmentacja.

Pole głównego zasobu

Zwykle w klauzuli SELECT uwzględniasz główne pole zasobu, ale nie jest to wymagane (nie jest wymagane).

To przykładowe zapytanie używa pola głównego zasobu (ad_group.status) tylko do filtrowania wyników.

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

Niestandardowe zmienne Floodlight

W klauzuli SELECT możesz uwzględniać niestandardowe zmienne Floodlight, podając ich identyfikatory.

W tym przykładzie zapytanie zawiera zmienną niestandardową o identyfikatorze 123454321 dla zasobu kampanii.

SELECT
  conversion_custom_metrics.id[123454321]
FROM campaign

SELECT
  conversion_custom_dimensions.id[123454321]
FROM campaign

Kolumny niestandardowe

W klauzuli SELECT możesz uwzględnić kolumny niestandardowe, podając ich identyfikatory.

W tym przykładzie zapytanie obejmuje kolumnę niestandardową o identyfikatorze 12345678 dla zasobu kampanii.

SELECT
  custom_columns.id[12345678]
FROM campaign

Dowiedz się, jak uzyskać identyfikatory kolumn niestandardowych.

Pola danych

Możesz wybrać pola wskaźników dla danego zasobu bez dodawania innych pól z zasobu w klauzuli SELECT.

To przykładowe zapytanie wybiera wskaźniki impressions i clicks dla zasobu campaign.

SELECT
  metrics.impressions,
  metrics.clicks
FROM campaign

Listę pól danych, których możesz używać w zapytaniach, znajdziesz w sekcji metrics.

Pola segmentów

W klauzuli SELECT możesz wybierać pola segmentów bez określania towarzyszących pól zasobów ani danych.

W tym przykładzie zapytanie dzieli wyniki według urządzenia.

SELECT segments.device
FROM campaign

Na stronie segments znajdziesz listę pól segmentów, których możesz używać w zapytaniach.

Pola niedozwolone

W klauzuli SELECT nie możesz używać tych pól:

  • pola, których nie można wybrać, czyli pola z atrybutem metadanych Selectable oznaczonym jako false;
  • pola powtarzane, czyli pola z atrybutem metadanych Repeated oznaczone jako true;
  • pola, które nie są dostępne dla danego zasobu w klauzuli FROM. Atrybutów niektórych zasobów nie można wybierać razem. Niektóre zasoby udostępniają tylko podzbiór wszystkich danych i segmentów.
  • niezgodne segmenty lub dane. Więcej informacji znajdziesz w sekcji Podział na segmenty.

Szczegółowe informacje o tym, gdzie znaleźć te informacje w przypadku poszczególnych zasobów, znajdziesz w dokumentacji referencyjnej.

Klauzula FROM

Klauzula FROM:

  • Jest to wymagana klauzula w przypadku zapytań do tabeli SearchAds360Service (zarówno w przypadku metody Search, jak i SearchStream).
  • Nie powinien być uwzględniany w przypadku zapytań kierowanych do SearchAds360FieldService.
  • Określa główny zasób zwracany przez zapytanie.
  • Możesz określić tylko 1 zasób.
  • Określa pola, których możesz używać we wszystkich pozostałych klauzulach w zapytaniu.

Przypisane zasoby

Jeśli przypisane zasoby są dostępne, zostaną domyślnie połączone z zasobem określonym w klauzuli FROM. Aby zwrócić ich wartości, wystarczy dodać ich atrybuty do klauzuli SELECT.

To przykładowe zapytanie zwraca zarówno identyfikator grupy reklam, jak i identyfikator kampanii, ponieważ zasób campaign jest przypisany do zasobu ad_group.

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

Pole resource_name

Pole resource_name głównego zasobu w klauzuli FROM jest zawsze zwracane.

W tym przykładowym zapytaniu pole ad_group.resource_name zostanie uwzględnione w odpowiedzi, mimo że nie zostało w nim wyraźnie wybrane:

SELECT ad_group.id
FROM ad_group

Gdy wybrane jest co najmniej 1 pole, zwracane jest pole resource_name przypisanego zasobu.

W tym przykładowym zapytaniu element campaign.resource_name zostanie uwzględniony w odpowiedzi, ponieważ wybrano element campaign.id:

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

Klauzula WHERE

Klauzula WHERE:

  • Jest to opcjonalna klauzula w zapytaniu.
  • Określa warunki filtrowania i dzielenia na segmenty danych w ramach żądania. Warunki mają następujący format: FIELD_NAME OPERATOR VALUE (oddzielone spacjami).
  • Może zawierać wiele warunków oddzielonych separatorem AND.

Z tego przykładowego zapytania dowiesz się, jak za pomocą klauzuli WHERE zwracać dane impressions za wybrany okres:

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

Aby dowiedzieć się więcej o dzielenie raportów wyszukiwania na segmenty, zapoznaj się z artykułem Segmentacja.

Więcej informacji o określaniu zakresów dat w zapytaniach znajdziesz w sekcji Zakresy dat.

Filtrowanie według pola resource_name

Za pomocą pola resource_name możesz filtrować i porządkować dane.

W tym przykładowym zapytaniu do filtrowania wyników według danej kampanii użyto pola campaign.resource_name:

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

Wiele warunków

Aby filtrować dane, możesz łączyć ze sobą wiele warunków.

To przykładowe zapytanie zwraca liczbę danych clicks dla wszystkich kampanii z danymi impressions na urządzeniach mobilnych z ostatnich 30 dni.

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

Aby dowiedzieć się więcej o podziale raportów na segmenty, zapoznaj się z artykułem Podział na segmenty.

Rozróżnianie wielkości liter

Podczas filtrowania według wartości ciągu znaków do prawidłowego filtrowania wyników ważne jest domyślne rozróżnianie wielkości liter w przypadku każdego operatora.

W tabeli poniżej pokazujemy, jak domyślnie jest rozróżniana wielkość liter w przypadku poszczególnych operatorów.

Domyślne rozróżnianie wielkości liter
=/!= Case sensitive
IN/NOT IN Case sensitive
LIKE/NOT LIKE Case insensitive
CONTAINS (...) Case sensitive
REGEXP_MATCH/NOT REGEXP_MATCH Case sensitive

Za pomocą modyfikatora (?i) możesz zmienić domyślną czułość funkcji REGEXP_MATCH i NOT REGEXP_MATCH na nieczułą na wielkość liter, na przykład:

SELECT campaign.id
FROM campaign
WHERE campaign.name REGEXP_MATCH "(?i).*test.*"

Pełną listę operatorów, których możesz używać do filtrowania danych, znajdziesz w sekcji Informacje o gramatyce zapytań.

Podstawowe segmenty dat

Te pola segmentów są nazywane głównymi segmentami dat: segments.date, segments.week, segments.month, segments.quarter i segments.year.

Aby określić datę lub przedział czasu, możesz użyć podstawowych segmentów dat w klauzuli WHERE.

W tym przykładowym zapytaniu w klauzuli WHERE dla pola segments.date jest podany parametr DURING LAST_30_DAYS:

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

Szczegółowe informacje o korzystaniu z podstawowych segmentów dat znajdziesz w sekcji Podział na segmenty > Podstawowe segmenty dat.

Zabronione filtrowanie

Filtrowanie jest niedozwolone w przypadku:

  • W niewybranych polach segmentu, z wyjątkiem podstawowych segmentów dat.
  • W polach dowolnego typu wiadomości, z wyjątkiem typów prymitywnych (np. Int64Value, StringValue itp.).
  • W atrybutach powtarzanych pól dowolnego typu wiadomości, z wyjątkiem typów prymitywnych (np. Int64Value, StringValue itp.).

Klauzula ORDER BY

Klauzula ORDER BY:

  • Jest to opcjonalna klauzula w zapytaniu.
  • Określa kolejność, w jakiej zwracane są wyniki. Kolejność jest następująca: FIELD_NAME ORDERING_OPTION (oddzielone spacją).
  • Dostępne są 2 opcje: ASC (rosnąco) lub DESC (malejąco). Domyślnie sortowanie jest rosnące.

W tym przykładzie zapytania porządkują kampanie według liczby kliknięć w kolejności malejącej (od najwyższej do najniższej):

SELECT
  campaign.name,
  metrics.clicks
FROM campaign
ORDER BY metrics.clicks DESC

Wiele zamówień

W klauzuli ORDER BY możesz określić wiele pól, rozdzielając je przecinkami. Wyniki będą uporządkowane w tej samej kolejności, w jakiej zostały określone w zapytaniu.

To przykładowe zapytanie wybiera dane grupy reklam, a następnie porządkuje wyniki w kolejności rosnącej według nazwy kampanii, następnie malejąco według liczby wyświetleń, a następnie w kolejności malejącej według liczby kliknięć:

SELECT
  campaign.name,
  ad_group.name,
  metrics.impressions,
  metrics.clicks
FROM ad_group
ORDER BY
  campaign.name,
  metrics.impressions DESC,
  metrics.clicks DESC

Łączenie kolejności i limitów

Aby doprecyzować wyniki, możesz użyć klauzuli ORDER BY w połączeniu z klauzulą LIMIT.

To przykładowe zapytanie zwraca 5 kampanii z największą liczbą wyświetleń w ciągu ostatnich 30 dni:

SELECT
  campaign.id,
  campaign.name,
  metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_30_DAYS
ORDER BY metrics.impressions DESC
LIMIT 5

Zamówienie niedozwolone

Zamawianie jest niedozwolone:

  • Według atrybutów niewybranych zasobów.
  • według niewybranych danych.
  • według niewybranych segmentów.
  • W przypadku tych typów pól:
    • MESSAGE
    • Pola powtarzane
    • Atrybuty pól powtarzanych.

Klauzula LIMIT

Klauzula LIMIT:

  • Jest opcjonalną klauzulą w zapytaniu.
  • Umożliwia ograniczenie liczby wyników zwracanych przez zapytanie.

Ta klauzula jest przydatna, jeśli na przykład chcesz zobaczyć tylko próbkę lub podsumowanie wyników.

To przykładowe zapytanie ogranicza łączną liczbę wyników do 50:

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

Klauzula PARAMETERS

Klauzula PARAMETERS umożliwia określenie metaparametrów żądania.

Uwzględnij wersje robocze

Parametr include_drafts określa, czy w wynikach mają być uwzględniane elementy w wersji roboczej. Wartość domyślna to false. Aby uwzględnić elementy w wersji roboczej, ustaw tę wartość na true.

To przykładowe zapytanie zwraca zarówno wersje robocze kampanii, jak i zwykłe kampanie:

SELECT campaign.name
FROM campaign
PARAMETERS include_drafts=true

Pomiń niewybrane resource_name

Parametr omit_unselected_resource_names umożliwia wykluczenie pola resource_name w przypadku wszystkich zasobów, które nie są wymagane w klauzuli SELECT. Wartość domyślna to false. Jeśli ustawisz ten parametr na true, zalecamy jawne wysyłanie żądań nazwy zasobu podstawowego i wszystkich przypisanych zasobów w klauzuli SELECT.

To przykładowe zapytanie nie zwraca ani pola campaign.resource_name, ani pola customer.resource_name, ponieważ nie są one uwzględnione w klauzuli SELECT:

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

To przykładowe zapytanie zwraca pole campaign.resource_name, ponieważ jest ono wyraźnie wymagane w nawiasach klamrowych SELECT:

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

Zmiana waluty używanej w danych

Parametr metrics_currency umożliwia określenie waluty, która ma być używana przy obliczaniu danych uwzględnionych w klauzuli SELECT. Domyślnie używana jest waluta lokalna konta. Jeśli ustawisz ten parametr, musisz użyć 3-literowego kodu waluty ISO 4217. Na przykład: PLN, EUR.

To przykładowe zapytanie zwraca dane cost_micros w walucie lokalnej konta.

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

To przykładowe zapytanie zwraca dane cost_micros w peso chilijskich (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"

Więcej informacji