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 sortowania, które łączą się w jedno żądanie zapytania.

Ogólnie rzecz biorąc, aby utworzyć zapytanie:

• Określ zasób, z którego mają zostać pobrane dane.
• Dodaj pola i wskaźniki, aby zdefiniować dane, które chcesz zwracać.
• Dodaj segmenty, aby pogrupować wyniki.
• Dodaj przypisane zasoby, aby pośrednio złączyć powiązane dane zasobów.
• Filtruj, porządkuj i ograniczaj wyniki.

Klauzula SELECT

Klauzula SELECT:

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

To przykładowe zapytanie pokazuje, jak wybrać atrybuty zasobu campaign:

SELECT
  campaign.id,
  campaign.name
FROM campaign

Wiele typów pól

W ramach tego samego żądania możesz poprosić o różne typy pól.

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

• Pola zasobów: 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

Więcej informacji o segmentowaniu raportów wyszukiwania znajdziesz w artykule Segmentacja.

Pole głównego zasobu

Zwykle dodajesz główne pole zasobu w klauzuli SELECT, ale jest to opcjonalne (nie jest to wymagane).

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

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

Niestandardowe zmienne Floodlight

Niestandardowe zmienne Floodlight możesz umieścić w klauzuli SELECT, używając ich identyfikatorów.

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

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, używając ich identyfikatorów.

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

SELECT
  custom_columns.id[12345678]
FROM campaign

Sprawdź, jak uzyskać identyfikatory kolumn niestandardowych.

Pola danych

Możesz wybrać pola wskaźników dla danego zasobu, nie dodając żadnych innych pól z tego zasobu w klauzuli SELECT.

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

SELECT
  metrics.impressions,
  metrics.clicks
FROM campaign

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

Pola segmentów

Możesz wybierać pola segmentów bez określania powiązanych pól zasobów ani wskaźników w klauzuli SELECT.

To przykładowe zapytanie dzieli wyniki na segmenty według urządzenia.

SELECT segments.device
FROM campaign

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

Zabronione pola

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 oznaczonym jako true.
• Pola niedostępne w przypadku danego zasobu w klauzuli FROM. Atrybutów niektórych zasobów nie można wybrać razem. Niektóre zasoby udostępniają tylko podzbiór wszystkich wskaźników i segmentów.
• Niezgodne segmenty lub dane. Więcej informacji znajdziesz w sekcji Segmentacja.

Informacje o tym, gdzie znaleźć te informacje o poszczególnych zasobach, znajdziesz w dokumentacji referencyjnej.

Klauzula FROM

Klauzula FROM:

• Jest wymaganą klauzulą w przypadku zapytań kierowanych do SearchAds360Service (zarówno w metodach Search, jak i SearchStream).
• nie należy uwzględniać w przypadku zapytań kierowanych do usługi SearchAds360FieldService.
• Określa główny zasób zwracany przez zapytanie.
• Możesz określić tylko jeden zasób.
• Określa pola, których możesz użyć we wszystkich innych klauzulach w zapytaniu.

Uwaga: na każdej stronie zasobu w sekcji Materiały referencyjne znajduje się pole wyboru Tak/Nie, które odfiltrowuje pola zasobów, pola segmentów i pola wskaźników, których nie można używać, gdy zasób jest określony w klauzuli FROM.

Przypisane zasoby

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

To przykładowe zapytanie zwraca zarówno identyfikator grupy reklam, jak i identyfikator kampanii, ponieważ campaign jest przypisanym zasobem ad_group.

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

Uwaga: nie wszystkie zasoby mają przypisane zasoby. Sekcja Dokumentacja zawiera szczegółowe informacje o zasobach przypisanych do poszczególnych zasobów.

Pole resource_name

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

W tym przykładowym zapytaniu zostanie uwzględniona odpowiedź ad_group.resource_name, mimo że nie została bezpośrednio wybrana w zapytaniu:

SELECT ad_group.id
FROM ad_group

Pole resource_name przypisanego zasobu jest zwracane, gdy wybrane jest co najmniej jedno pole.

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

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

Uwaga: jeśli zasób w klauzuli FROM zawiera inny zasób jako segment, wybranie dowolnych atrybutów tego zasobu będzie działać jako segment.

Klauzula WHERE

Klauzula WHERE:

• Jest opcjonalną klauzulą w zapytaniu.
• Określa warunki filtrowania i segmentowania danych dotyczących żądania. Warunki są zgodne z tym wzorcem: FIELD_NAME OPERATOR VALUE (oddzielone spacjami).
• Może zawierać wiele warunków rozdzielonych separatorem AND.

To przykładowe zapytanie pokazuje, jak użyć klauzuli WHERE do zwrócenia danych impressions dla danego okresu:

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

Więcej informacji o segmentowaniu raportów wyszukiwania znajdziesz w artykule Segmentacja.

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

Filtruj według pola resource_name

Pole resource_name umożliwia filtrowanie i sortowanie danych.

To przykładowe zapytanie używa pola campaign.resource_name do filtrowania wyników według danej kampanii:

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

Wiele warunków

Aby filtrować dane, możesz połączyć kilka warunków.

To przykładowe zapytanie prosi o liczbę danych clicks we wszystkich kampaniach 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

Uwaga: separatora AND można używać tylko między warunkami operatora (WHERE segments.device != "DESKTOP" AND segments.device != "MOBILE"), a nie w warunkach pojedynczego operatora (WHERE segments.device != "DESKTOP" AND "MOBILE").

Więcej informacji o segmentowaniu raportów znajdziesz w artykule Segmentacja.

Rozróżnianie wielkości liter

W przypadku filtrowania wartości ciągów domyślny rozróżnianie wielkości liter w poszczególnych operatorach odgrywa ważną rolę w prawidłowym filtrowaniu wyników.

Tabela poniżej zawiera domyślną rozróżnianie wielkości liter w poszczególnych operatorach.

Domyślna 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

Możesz użyć modyfikatora (?i), aby zmienić domyślną czułość reagowania REGEXP_MATCH i NOT REGEXP_MATCH 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.

Podstawowe segmenty daty możesz określić w klauzuli WHERE, aby określić datę lub okres.

To przykładowe zapytanie określa wartość DURING LAST_30_DAYS w polu segments.date w klauzuli WHERE:

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 Segmentacja > Podstawowe segmenty dat.

Niedozwolone filtrowanie

Filtrowanie jest niedozwolone:

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

Klauzula ORDER BY

Klauzula ORDER BY:

• Jest opcjonalną klauzulą w zapytaniu.
• Określa kolejność zwracania wyników. Sposób sortowania jest zgodny z tym schematem: FIELD_NAME ORDERING_OPTION (oddzielone spacją).
• Pozwala na 2 opcje: ASC (rosnąco) i DESC (malejąco). Domyślnie rosnąco.

To przykładowe zapytanie porządkuje 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 za pomocą listy rozdzielanej przecinkami. Wyniki zostaną uporządkowane w takiej kolejności jak w zapytaniu.

To przykładowe zapytanie wybiera dane grupy reklam i porządkuje wyniki w kolejności rosnącej według nazwy kampanii, następnie w kolejności malejącej 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 zawęzić wyniki, możesz użyć klauzuli ORDER BY w połączeniu z klauzulą LIMIT.

To przykładowe zapytanie zwraca 5 kampanii o największej liczbie 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

Niedozwolone zamawianie

Zamówienie jest niedozwolone:

• Według atrybutów niewybranych zasobów.
• Według niewybranych danych.
• Na podstawie 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.
• Pozwala ograniczyć liczbę wyników zwracanych przez zapytanie.

Ta klauzula jest przydatna, gdy na przykład interesuje Cię tylko próbka 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 uwzględniane są wersje robocze elementów. Wartość domyślna to false. Aby uwzględnić wersje robocze elementów, ustaw wartość true.

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

SELECT campaign.name
FROM campaign
PARAMETERS include_drafts=true

Pomiń odznaczone pole resource_name

Parametr omit_unselected_resource_names umożliwia wykluczenie pola resource_name w przypadku wszystkich zasobów, które nie są jawnie żądane w klauzuli SELECT. Wartość domyślna to false. Jeśli ustawisz ten parametr na true, zalecamy jawne żądanie nazwy zasobu głównego i wszystkich przypisanych zasobów w klauzuli SELECT.

To przykładowe zapytanie nie zwraca pola campaign.resource_name ani pola customer.resource_name, ponieważ nie występują one 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ż jego żądanie jest zawarte w klauzuli 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 na koncie jest używana waluta lokalna. Podczas ustawiania tego parametru musisz używać 3-znakowego kodu waluty zgodnego z normą 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 wskaźnik 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

• Gramatyka zapytań