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 ordering, które są łączone w jedno żądanie.

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

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

klauzula SELECT

Klauzula SELECT:

  • Jest wymaganą klauzulą w zapytaniu.
  • Określa zbiór pól do pobrania w żądaniu.
  • Zajmuje rozdzielaną przecinkami listę pól zasobów, kolumn niestandardowych, niestandardowych Floodlight, pola segmentu i dane oraz zwraca wartości w polach .

To przykładowe zapytanie pokazuje, jak wybrać atrybuty atrybutu campaign zasób:

SELECT
  campaign.id,
  campaign.name
FROM campaign

Wiele typów pól

W tym samym żądaniu możesz zgłosić żądanie różnych typów pól.

Przykładowe zapytanie poniżej przedstawia 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

Patrz: segmentacja. .

Pole głównego zasobu

Zwykle należy uwzględnić główne pole zasobów w polu SELECT klauzuli. Jest to jednak opcjonalne (nie wymagane).

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

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

Niestandardowe zmienne Floodlight

W klauzuli SELECT możesz uwzględnić niestandardowe zmienne Floodlight, używając ich ID

W tym przykładzie zapytanie zawiera zmienną niestandardową o identyfikatorze 123454321 dla parametru zasób 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, używając ich identyfikatorów.

W tym przykładzie zapytanie zawiera kolumnę niestandardową o identyfikatorze 12345678, która wskazuje zasób 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 uwzględniania innych z zasobu w klauzuli SELECT.

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

SELECT
  metrics.impressions,
  metrics.clicks
FROM campaign

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

Pola segmentów

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

To przykładowe zapytanie segmentuje wyniki według urządzenia.

SELECT segments.device
FROM campaign

Zobacz segments, 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ć, tj. pola z metadanymi Selectable oznaczony jako false.
  • Pola powtarzane, czyli pola z atrybutem metadanych Repeated oznaczono jako true.
  • Pola, które są niedostępne w przypadku danego zasobu w klauzuli FROM. Atrybutów niektórych zasobów nie można wybrać razem. Tylko niektóre zasoby Podzbiór wszystkich danych i segmentów.
  • Niezgodne segmenty lub dane. Więcej informacji znajdziesz w sekcji Segmentacja. i informacjami o nich.

Zapoznaj się z dokumentacją: gdzie można znaleźć te informacje dotyczące każdego zasobu.

Klauzula FROM

Klauzula FROM:

  • Jest wymaganą klauzulą przy zapytaniach do SearchAds360Service. (metody Search i SearchStream).
  • Nie powinien być uwzględniany w przypadku zapytań kierowanych do SearchAds360FieldService.
  • Określa główny zasób zwracany przez zapytanie.
  • Możesz podać tylko jeden zasób.
  • Definiuje pola, których możesz używać we wszystkich innych klauzulach w zapytaniu.
.

Przypisane zasoby

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

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

resource_name pole

Pole resource_name głównego zasobu w klauzuli FROM ma zawsze wartość .

W tym przykładowym zapytaniu odpowiedź ad_group.resource_name zostanie uwzględniona w odpowiedzi chociaż nie jest ona wyraźnie wybrana w zapytaniu:

SELECT ad_group.id
FROM ad_group

Pole resource_name przypisanego zasobu to zwracany, gdy wybierzesz co najmniej jedno pole.

W tym przykładowym zapytaniu sekcja campaign.resource_name zostanie uwzględniona w tagu odpowiedź, bo wybrano campaign.id:

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

Klauzula WHERE

Klauzula WHERE:

  • Jest opcjonalną klauzulą w zapytaniu.
  • Określa warunki filtrowania i podziału danych na segmenty w żądaniu. Warunki są zgodne z tym wzorcem: FIELD_NAME OPERATOR VALUE (oddzielone przez puste spacje).
  • Może zawierać wiele warunków rozdzielonych separatorem AND.

W tym przykładowym zapytaniu pokazujemy, jak użyć klauzuli WHERE do zwrócenia wartości impressions dane dla danego okresu:

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

Patrz: segmentacja. .

Więcej informacji o określaniu daty znajdziesz w sekcji Zakresy dat. zakresy zapytań.

Filtruj według pola resource_name

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

To przykładowe zapytanie używa pola campaign.resource_name do filtrowania wyników przez daną kampanię:

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

Wiele warunków

Możesz łączyć wiele warunków, aby filtrować dane.

To przykładowe zapytanie prosi o liczbę danych typu clicks we wszystkich kampaniach z danymi impressions z ostatnich 30 dni na urządzeniach mobilnych.

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

Patrz: segmentacja. .

Rozróżnianie wielkości liter

Podczas filtrowania według wartości ciągów znaków domyślnie uwzględniana jest wielkość liter każdego operatora odgrywa ważną rolę w prawidłowym filtrowaniu wyników.

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ść Atrybuty REGEXP_MATCH i NOT REGEXP_MATCH nie uwzględniają wielkości liter, na przykład:

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

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

Podstawowe segmenty dat

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

Do określenia daty lub godziny możesz użyć podstawowych segmentów dat w klauzuli WHERE okresu przejściowego.

To przykładowe zapytanie określa pole DURING LAST_30_DAYS dla pola segments.date w klauzuli WHERE:

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

Zobacz sekcję Segmentacja > Podstawowe segmenty dat informacje o korzystaniu z podstawowych segmentów dat.

Zabronione filtrowanie

Filtrowanie jest niedozwolone:

  • w niewybranych polach segmentów (z wyjątkiem głównych segmentów dat),
  • W polach dowolnego typu wiadomości oprócz elementów podstawowych (na przykład Int64Value, StringValue itp.).
  • W przypadku atrybutów pól powtarzanych dowolnego typu wiadomości z wyjątkiem elementów podstawowych (na przykład Int64Value, StringValue itp.).

Klauzula ORDER BY

Klauzula ORDER BY:

  • Jest opcjonalną klauzulą w zapytaniu.
  • Określa kolejność zwracania wyników. Zamówienie jest zgodne z tym wzór: FIELD_NAME ORDERING_OPTION (rozdzielone spacją).
  • Zezwala na 2 opcje: ASC (rosnąco) i DESC (malejąco). Wartość domyślna to rosnąco.

W tym przykładzie 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ć większą liczbę pól, rozdzielając je przecinkami z listy. Wyniki zostaną uporządkowane w takiej samej kolejności, jaka została określona w polu zapytania.

To przykładowe zapytanie wybiera dane grupy reklam i porządkuje wyniki w kolejności rosnącej porządkuj je według nazwy kampanii, a potem malejąco według liczby wyświetleń, 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

Klauzuli ORDER BY możesz używać w połączeniu z klauzulą LIMIT, aby zawęź wyniki.

To przykładowe zapytanie zwraca pięć kampanii z największą liczbą wyświetleń ostatnie 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

Zabronione zamówienia

Zamawianie jest niedozwolone:

  • Według atrybutów niewybranych zasobów.
  • Według niewybranych danych.
  • Przez niewybrane segmenty.
  • 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 interesują Cię tylko próbki 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 dla żądania.

Uwzględnij wersje robocze

Parametr include_drafts określa, czy wersje robocze elementów są uwzględniane w wyniki. Wartość domyślna to false. Aby uwzględnić elementy w wersji roboczej, ustaw wartość true.

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

SELECT campaign.name
FROM campaign
PARAMETERS include_drafts=true

Pomiń niewybrane miejsce: resource_name

Parametr omit_unselected_resource_names umożliwia wykluczenie parametru resource_name wszystkich zasobów, które nie są wymagane w klauzulę SELECT. Wartość domyślna to false. Jeśli ustawisz ten parametr na true, zalecamy jawne żądanie nazwy zasobu podstawowego i wszystkie przypisane zasoby w klauzuli SELECT.

To przykładowe zapytanie nie zwraca campaign.resource_name ani customer.resource_name, ponieważ nie znajdują się one w polu SELECT klauzula:

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 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 pozwala określić walutę, która ma być używana. podczas obliczania danych uwzględnionych w klauzuli SELECT. Domyślnie na koncie używana jest waluta lokalna. Jeśli ustawisz tę opcję użyj 3-znakowego kodu waluty w formacie ISO 4217. np. USD, EUR.

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

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