Abfragestruktur und -klauseln

Eine Abfrage besteht aus einer Reihe von Klauseln: SELECT, FROM, WHERE, ORDER BY, LIMIT und PARAMETERS.

In Klauseln werden Feldnamen, Ressourcennamen, Operatoren, Bedingungen und Sortierungen verwendet, die zu einer einzelnen Abfrage kombiniert werden.

Im Grunde geht es beim Erstellen einer Abfrage so vor:

• Geben Sie eine Ressource an, aus der Daten abgerufen werden sollen.
• Fügen Sie Felder und Messwerte hinzu, um die Daten zu definieren, die zurückgegeben werden sollen.
• Fügen Sie Segmente hinzu, um Ihre Ergebnisse zu gruppieren.
• Fügen Sie zugeordnete Ressourcen hinzu, um zugehörige Ressourcendaten implizit zusammenzuführen.
• Ergebnisse filtern, sortieren und eingrenzen

SELECT-Klausel

Die SELECT-Klausel:

• Ist eine erforderliche Klausel in einer Abfrage.
• Gibt eine Reihe von Feldern an, die in der Anfrage abgerufen werden sollen.
• Nimmt eine durch Kommas getrennte Liste von Ressourcenfeldern, benutzerdefinierten Spalten, benutzerdefinierten Floodlight-Variablen, Segmentfeldern und Messwerten entgegen und gibt die Werte in der Antwort zurück.

In dieser Beispielabfrage wird gezeigt, wie Sie Attribute der campaign-Ressource auswählen:

SELECT
  campaign.id,
  campaign.name
FROM campaign

Mehrere Feldtypen

Sie können in einer Anfrage verschiedene Feldtypen anfordern.

Die folgende Beispielabfrage zeigt eine einzelne Abfrage mit einer Kombination aus:

• Ressourcenfelder: campaign.id, campaign.name, bidding_strategy.id und bidding_strategy.name
• Segmentfelder: segments.device und segments.date
• Messwertfelder: metrics.impressions und 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

Weitere Informationen zum Segmentieren von Suchberichten finden Sie unter Segmentierung.

Feld „Hauptressource“

Normalerweise sollten Sie das Hauptressourcenfeld in die SELECT-Klausel aufnehmen. Dies ist jedoch nicht erforderlich.

In dieser Beispielabfrage wird ein Hauptressourcenfeld (ad_group.status) verwendet, um nur die Ergebnisse zu filtern.

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

Benutzerdefinierte Floodlight-Variablen

Sie können benutzerdefinierte Floodlight-Variablen mithilfe ihrer IDs in die SELECT-Klausel aufnehmen.

In diesem Beispiel enthält die Abfrage eine benutzerdefinierte Variable mit der ID 123454321 für die Kampagnenressource.

SELECT
  conversion_custom_metrics.id[123454321]
FROM campaign

SELECT
  conversion_custom_dimensions.id[123454321]
FROM campaign

Benutzerdefinierte Spalten

Sie können benutzerdefinierte Spalten mithilfe ihrer IDs in die SELECT-Klausel aufnehmen.

In diesem Beispiel enthält die Abfrage eine benutzerdefinierte Spalte mit der ID 12345678 für die Kampagnenressource.

SELECT
  custom_columns.id[12345678]
FROM campaign

Informationen zum Abrufen von IDs für benutzerdefinierte Spalten

Messwertfelder

Sie können Messwertfelder für eine bestimmte Ressource auswählen, ohne andere Felder der Ressource in die SELECT-Klausel aufzunehmen.

In dieser Beispielabfrage werden die Messwerte impressions und clicks für die Ressource campaign ausgewählt.

SELECT
  metrics.impressions,
  metrics.clicks
FROM campaign

Unter metrics finden Sie eine Liste der Messwertfelder, die Sie in Ihren Abfragen verwenden können.

Segmentfelder

Sie können Segmentfelder auswählen, ohne in der SELECT-Klausel zugehörige Ressourcenfelder oder Messwerte anzugeben.

In dieser Beispielabfrage werden die Ergebnisse nach Gerät segmentiert.

SELECT segments.device
FROM campaign

Unter segments finden Sie eine Liste der Segmentfelder, die Sie in Ihren Abfragen verwenden können.

Unzulässige Felder

Die folgenden Felder können nicht in der SELECT-Klausel verwendet werden:

• Nicht auswählbare Felder, d. h. Felder mit dem Metadatenattribut Selectable, das als false gekennzeichnet ist.
• Wiederkehrende Felder, d. h. Felder mit dem Metadatenattribut Repeated, das als true gekennzeichnet ist.
• Felder, die für die angegebene Ressource in der FROM-Klausel nicht verfügbar sind. Attribute einiger Ressourcen können nicht gleichzeitig ausgewählt werden. Bei einigen Ressourcen ist nur ein Teil aller Messwerte und Segmente verfügbar.
• Inkompatible Segmente oder Messwerte Weitere Informationen finden Sie unter Segmentierung.

Weitere Informationen dazu, wo Sie diese Informationen für die einzelnen Ressourcen finden, finden Sie in der Referenzdokumentation.

FROM-Klausel

Die FROM-Klausel:

• Ist eine erforderliche Klausel für Abfragen an SearchAds360Service (sowohl Search als auch SearchStream).
• Sollte nicht für Abfragen an SearchAds360FieldService enthalten sein.
• Gibt die Hauptressource an, die von der Abfrage zurückgegeben wird.
• Es kann nur eine einzelne Ressource angegeben werden.
• Hier werden die Felder definiert, die Sie in allen anderen Klauseln der Abfrage verwenden können.

Hinweis :Auf jeder Ressourcenseite im Abschnitt Referenz gibt es ein Auswahlfeld Ja/Nein, mit dem Ressourcenfelder, Segmentfelder und Messwertfelder herausgefiltert werden, die nicht verwendet werden können, wenn in der FROM-Klausel eine Ressource angegeben ist.

Zugewiesene Ressourcen

Wenn zugeordnete Ressourcen verfügbar sind, werden sie implizit mit der Ressource verknüpft, die Sie in der FROM-Klausel angeben. Sie müssen die entsprechenden Attribute nur der SELECT-Klausel hinzufügen, um die Werte zurückzugeben.

In dieser Beispielabfrage werden sowohl die Anzeigengruppen-ID als auch die Kampagnen-ID zurückgegeben, da campaign eine zugeordnete Ressource der Ressource ad_group ist.

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

Hinweis :Nicht alle Ressourcen haben zugeordnete Ressourcen. Der Abschnitt Referenz enthält Details zu den zugewiesenen Ressourcen, die für jede Ressource verfügbar sind.

Feld resource_name

Das Feld resource_name der Hauptressource in der FROM-Klausel wird immer zurückgegeben.

In dieser Beispielabfrage wird ad_group.resource_name in die Antwort einbezogen, obwohl sie nicht explizit in der Abfrage ausgewählt wurde:

SELECT ad_group.id
FROM ad_group

Das Feld resource_name einer zugewiesenen Ressource wird zurückgegeben, wenn mindestens ein Feld ausgewählt ist.

In dieser Beispielabfrage wird campaign.resource_name in die Antwort eingeschlossen, da campaign.id ausgewählt ist:

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

Hinweis: Wenn in der FROM-Klausel eine andere Ressource als segment aufgeführt ist, wird die Auswahl beliebiger Attribute dieser Ressource als Segment behandelt.

WHERE-Klausel

Die WHERE-Klausel:

• Eine optionale Klausel in einer Abfrage.
• Gibt Bedingungen für das Filtern und Segmentieren der Daten für die Anfrage an. Bedingungen folgen diesem Muster: FIELD_NAME OPERATOR VALUE (durch Leerzeichen getrennt).
• Kann mehrere Bedingungen enthalten, die durch das Trennzeichen AND getrennt sind.

In dieser Beispielabfrage wird gezeigt, wie mit der WHERE-Klausel impressions-Messwerte für einen bestimmten Zeitraum zurückgegeben werden:

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

Weitere Informationen zum Segmentieren von Suchberichten finden Sie unter Segmentierung.

Weitere Informationen zum Angeben von Zeitraumoptionen in Abfragen finden Sie unter Zeitraumoptionen.

Nach dem Feld resource_name filtern

Mit dem Feld resource_name können Sie Daten filtern oder sortieren.

In dieser Beispielabfrage wird das Feld campaign.resource_name verwendet, um die Ergebnisse nach einer bestimmten Kampagne zu filtern:

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

Mehrere Bedingungen

Sie können mehrere Bedingungen kombinieren, um Ihre Daten zu filtern.

In dieser Beispielabfrage wird die Anzahl der clicks-Messwerte für alle Kampagnen mit impressions-Messwerten auf Mobilgeräten in den letzten 30 Tagen abgefragt.

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

Hinweis :Das Trennzeichen AND kann nur zwischen Operatorbedingungen (WHERE segments.device != "DESKTOP" AND segments.device != "MOBILE") und nicht innerhalb einer einzelnen Operatorbedingung (WHERE segments.device != "DESKTOP" AND "MOBILE") verwendet werden.

Weitere Informationen zur Segmentierung von Berichten finden Sie unter Segmentierung.

Groß-/Kleinschreibung

Wenn Sie nach Stringwerten filtern, spielt die standardmäßige Unterscheidung zwischen Groß- und Kleinschreibung der einzelnen Operatoren eine wichtige Rolle für die korrekte Filterung der Ergebnisse.

In der folgenden Tabelle sehen Sie, ob die Groß- und Kleinschreibung für die einzelnen Operatoren standardmäßig berücksichtigt wird.

Standardeinstellung für die Berücksichtigung der Groß-/Kleinschreibung
=/!=	Case sensitive
IN/NOT IN	Case sensitive
LIKE/NOT LIKE	Case insensitive
CONTAINS (...)	Case sensitive
REGEXP_MATCH/NOT REGEXP_MATCH	Case sensitive

Mit dem Modifikator (?i) können Sie die Standardempfindlichkeit für REGEXP_MATCH und NOT REGEXP_MATCH in „Groß- und Kleinschreibung ignorieren“ ändern, z. B. so:

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

Eine vollständige Liste der Operatoren, mit denen Sie Ihre Daten filtern können, finden Sie in der Referenz zur Abfragesprache.

Wichtige Zeiträume

Die folgenden Segmentfelder werden als Datensegmente für die Hauptanalyse bezeichnet: segments.date, segments.week, segments.month, segments.quarter und segments.year.

Mithilfe von grundlegenden Datumssegmenten in der WHERE-Klausel können Sie einen Zeitraum angeben.

In dieser Beispielabfrage wird DURING LAST_30_DAYS für das Feld segments.date in der WHERE-Klausel angegeben:

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

Unter Segmentierung > Kernzeitraumsegmente finden Sie ausführliche Informationen zur Verwendung von Kernzeitraumsegmenten.

Verbotene Filterung

Folgendes ist nicht zulässig:

• In nicht ausgewählten Segmentfeldern, mit Ausnahme von Kerndatumssegmenten.
• Auf Feldern beliebiger Nachrichtentypen, mit Ausnahme von primitiven Feldern (z. B. Int64Value, StringValue usw.).
• Auf Attribute von wiederholten Feldern beliebiger Nachrichtentypen, mit Ausnahme von einfachen Feldern (z. B. Int64Value, StringValue usw.).

ORDER BY-Klausel

Die ORDER BY-Klausel:

• Eine optionale Klausel in einer Abfrage.
• Gibt die Reihenfolge an, in der die Ergebnisse zurückgegeben werden. Die Reihenfolge folgt diesem Muster: FIELD_NAME ORDERING_OPTION (durch ein Leerzeichen getrennt).
• Es sind zwei Optionen zulässig: ASC (aufsteigend) oder DESC (absteigend). Standardmäßig ist „Aufsteigend“ ausgewählt.

In dieser Beispielabfrage werden die Kampagnen nach der Anzahl der Klicks in absteigender Reihenfolge (höchster Wert zuerst) sortiert:

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

Mehrere Bestellungen

Sie können mehrere Felder in der ORDER BY-Klausel in einer durch Kommas getrennten Liste angeben. Die Ergebnisse werden in der Reihenfolge sortiert, die Sie in der Abfrage angeben.

In dieser Beispielabfrage werden Anzeigengruppendaten ausgewählt und die Ergebnisse in aufsteigender Reihenfolge nach Kampagnenname, dann in absteigender Reihenfolge nach Anzahl der Impressionen und dann in absteigender Reihenfolge nach Anzahl der Klicks sortiert:

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

Sortierung und Limit kombinieren

Sie können die ORDER BY-Klausel in Kombination mit der LIMIT-Klausel verwenden, um die Ergebnisse einzugrenzen.

Mit dieser Beispielabfrage werden die fünf Kampagnen mit den meisten Impressionen in den letzten 30 Tagen zurückgegeben:

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

Verbotene Anordnungen

Folgendes ist nicht zulässig:

• Nach Attributen nicht ausgewählter Ressourcen.
• Nach nicht ausgewählten Messwerten.
• Nicht ausgewählte Segmente
• Für diese Feldtypen:
  • MESSAGE
  • Wiederkehrende Felder
  • Attribute von wiederkehrenden Feldern.

LIMIT-Klausel

Die LIMIT-Klausel:

• Eine optionale Klausel in einer Abfrage.
• Hiermit lässt sich die Anzahl der Ergebnisse begrenzen, die durch die Abfrage zurückgegeben werden.

Diese Klausel ist beispielsweise nützlich, wenn Sie nur an einer Stichprobe oder einer Zusammenfassung der Ergebnisse interessiert sind.

In dieser Beispielabfrage wird die Gesamtzahl der Ergebnisse auf 50 begrenzt:

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

PARAMETERS-Klausel

Mit der Klausel PARAMETERS können Sie Metaparameter für die Anfrage angeben.

Entwürfe einschließen

Mit dem Parameter include_drafts wird festgelegt, ob Entwürfe in den Ergebnissen enthalten sind. Der Standardwert ist false. Legen Sie den Wert auf true fest, um Entwürfe zu berücksichtigen.

Mit dieser Beispielabfrage werden sowohl Kampagnen im Entwurfsstatus als auch reguläre Kampagnen zurückgegeben:

SELECT campaign.name
FROM campaign
PARAMETERS include_drafts=true

Nicht ausgewählte resource_name auslassen

Mit dem Parameter omit_unselected_resource_names können Sie das Feld resource_name aller Ressourcen ausschließen, die nicht explizit in der SELECT-Klausel angefordert werden. Der Standardwert ist false. Wenn Sie diesen Parameter auf true festlegen, empfehlen wir Ihnen, den Ressourcennamen der primären Ressource und alle zugewiesenen Ressourcen in Ihrer SELECT-Klausel explizit anzufordern.

In dieser Beispielabfrage werden weder das Feld campaign.resource_name noch das Feld customer.resource_name zurückgegeben, da sie nicht in der SELECT-Klausel enthalten sind:

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

In dieser Beispielabfrage wird das Feld campaign.resource_name zurückgegeben, da es in der SELECT-Klausel explizit angefordert wird:

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

Währung für Messwerte ändern

Mit dem Parameter metrics_currency können Sie die Währung angeben, die bei der Berechnung eines Messwerts in Ihrer SELECT-Klausel verwendet werden soll. Standardmäßig wird die Landeswährung des Kontos verwendet. Wenn Sie diesen Parameter festlegen, müssen Sie den dreistelligen Währungscode gemäß ISO 4217 verwenden. Beispiel: USD, EUR.

In dieser Beispielabfrage wird der Messwert „cost_micros“ in der Landeswährung des Kontos zurückgegeben.

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

In dieser Beispielabfrage wird der Messwert „cost_micros“ in chilenischen Pesos (CLP) zurückgegeben.

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

Kundencenter-Erweiterung aktivieren

Wenn der Parameter enable_mcc_expansion auf „wahr“ gesetzt ist, können Sie Messwerte, Felder und Segmente aus login_customer_id und allen darunter liegenden Auslieferungskonten für die Ressource in der FROM-Klausel einschließen. In der Antwort wird die Währung des login_customer_id verwendet, sofern dies nicht ausdrücklich im Parameter metrics_currency angegeben ist.

Hinweis: Der Parameter enable_mcc_expansion ist nur mit bidding_strategy kompatibel. Die API wird im Laufe der Zeit weitere Ressourcen enthalten.

In dieser Beispielabfrage werden bidding_strategy.name, bidding_strategy.type und metrics.cost_micros aus login_customer_id und allen darunter liegenden Kontos zurückgegeben, da der Parameter enable_mcc_expansion auf true festgelegt ist.

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

Weitere Informationen

• Abfragegrammatik