Abfragestruktur und -klauseln

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

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

So erstellen Sie eine Abfrage:

• 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 die Ergebnisse zu gruppieren.
• Fügen Sie zugeschriebene Ressourcen hinzu, um zugehörige Ressourcendaten implizit zu verknüpfen.
• Filtern, sortieren und begrenzen Sie die Ergebnisse.

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.
• Akzeptiert eine durch Kommas getrennte Liste von Ressourcenfeldern, benutzerdefinierten Spalten, benutzerdefinierten Floodlight-Variablen, Segmentfeldern und Messwerten und gibt die Werte in der Antwort zurück.

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

SELECT
  campaign.id,
  campaign.name
FROM campaign

Mehrere Feldtypen

Sie können in derselben 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.

Hauptressourcenfeld

Normalerweise würden Sie das Hauptressourcenfeld in die SELECT-Klausel einfügen. Dies ist jedoch optional (nicht erforderlich).

In dieser Beispielabfrage wird ein Hauptressourcenfeld (ad_group.status) verwendet, um 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 einfügen.

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 einfügen.

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 aus der Ressource in die SELECT-Klausel einzufügen.

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 begleitende 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, bei denen das Metadatenattribut Selectable als false gekennzeichnet ist.

• Wiederholte Felder, d. h. Felder, bei denen das Metadatenattribut Repeated 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 zusammen ausgewählt werden. Für einige Ressourcen ist nur eine Teilmenge aller Messwerte und Segmente verfügbar.

• Inkompatible Segmente oder Messwerte. Weitere Informationen finden Sie unter Segmentierung.

In der Referenzdokumentation finden Sie Details dazu, wo Sie diese Informationen für jede Ressource finden.

`FROM`-Klausel

Die FROM-Klausel:

• Ist eine erforderliche Klausel für Abfragen an SearchAds360Service (sowohl die Methoden Search als auch SearchStream).

• Darf nicht für Abfragen an SearchAds360FieldService verwendet werden.

• Gibt die Hauptressource an, die von der Abfrage zurückgegeben wird.

• Kann nur eine einzelne Ressource angeben.

• Definiert die Felder, die Sie in allen anderen Klauseln der Abfrage verwenden können.

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

Zugeordnete 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 nur ihre Attribute zur SELECT-Klausel hinzufügen, um ihre 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. Im Referenzbereich finden Sie Details zu den zugeordnete Ressourcen, die für jede Ressource verfügbar sind.

resource_name-Feld

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 aufgenommen, obwohl es in der Abfrage nicht explizit ausgewählt ist:

SELECT ad_group.id
FROM ad_group

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

In dieser Beispielabfrage wird campaign.resource_name in die Antwort aufgenommen, 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, fungiert die Auswahl von Attributen dieser Ressource als Segment.

`WHERE`-Klausel

Die WHERE-Klausel:

• Ist eine optionale Klausel in einer Abfrage.

• Gibt Bedingungen zum Filtern und Segmentieren der Daten für die Anfrage an. Die 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 Sie die WHERE-Klausel verwenden, um impressions-Messwerte für einen bestimmten Zeitraum zurückzugeben:

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 Zeit räumen in Abfragen finden Sie unter Zeiträume.

Nach dem Feld resource_name filtern

Sie können das Feld resource_name verwenden, um Daten zu filtern oder zu 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 für die letzten 30 Tage angefordert.

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 AND Trennzeichen kann nur zwischen Operatorbedingungen verwendet werden (WHERE segments.device != "DESKTOP" AND segments.device != "MOBILE"), nicht innerhalb einer einzelnen Operatorbedingung (WHERE segments.device != "DESKTOP" AND "MOBILE").

Weitere Informationen zum Segmentieren von Berichten finden Sie unter Segmentierung.

Berücksichtigung der Groß-/Kleinschreibung

Beim Filtern nach Stringwerten spielt die Standardeinstellung für die Berücksichtigung der Groß-/Kleinschreibung jedes Operators eine wichtige Rolle, um die Ergebnisse korrekt zu filtern.

In der folgenden Tabelle ist die Standardeinstellung für die Berücksichtigung der Groß-/Kleinschreibung für jeden Operator aufgeführt.

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 (?i) Modifikator können Sie die Standardeinstellung für die Berücksichtigung der Groß-/Kleinschreibung für REGEXP_MATCH und NOT REGEXP_MATCH in „Case insensitive“ ändern. Beispiel:

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

Eine vollständige Liste der Operatoren, die Sie zum Filtern Ihrer Daten verwenden können, finden Sie in der Referenz zur Abfragegrammatik.

Hauptdatumssegmente

Die folgenden Segmentfelder werden als Hauptdatumssegmente bezeichnet: segments.date, segments.week, segments.month, segments.quarter, und segments.year.

Sie können Hauptdatumssegmente in der WHERE-Klausel verwenden, um ein Datum oder einen Zeitraum anzugeben.

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

Weitere Informationen zur Verwendung von Hauptdatumssegmenten finden Sie unter Segmentierung > Hauptdatumssegmente.

Unzulässige Filter

Filter sind nicht zulässig:

• Für nicht ausgewählte Segmentfelder, mit Ausnahme von Hauptdatumssegmenten.

• Für Felder eines beliebigen Nachrichtentyps, mit Ausnahme von einfachen Typen (z. B. Int64Value, StringValue usw.).

• Für Attribute wiederholter Felder eines beliebigen Nachrichtentyps, mit Ausnahme von einfachen Typen (z. B. Int64Value, StringValue usw.).

`ORDER BY`-Klausel

Die ORDER BY-Klausel:

• Ist eine optionale Klausel in einer Abfrage.
• Gibt die Reihenfolge an, in der die Ergebnisse zurückgegeben werden. Die Sortierung folgt diesem Muster: FIELD_NAME ORDERING_OPTION (durch ein Leerzeichen getrennt).
• Es gibt zwei Optionen: ASC (aufsteigend) oder DESC (absteigend). Die Standardeinstellung ist aufsteigend.

In dieser Beispielabfrage werden die Kampagnen nach Anzahl der Klicks in absteigender Reihenfolge sortiert (vom höchsten zum niedrigsten Wert):

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

Mehrere Sortierungen

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

In dieser Beispielabfrage werden Anzeigengruppendaten ausgewählt und die Ergebnisse in aufsteigender Reihenfolge nach Kampagnennamen, 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 zu verfeinern.

In dieser Beispielabfrage werden die fünf Kampagnen mit den höchsten 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

Unzulässige Sortierungen

Sortierungen sind nicht zulässig:

• Nach Attributen nicht ausgewählter Ressourcen.
• Nach nicht ausgewählten Messwerten.
• Nach nicht ausgewählten Segmenten.
• Für diese Feldtypen:
  • MESSAGE
  • Wiederholte Felder
  • Attribute wiederholter Felder.

`LIMIT`-Klausel

Die LIMIT-Klausel:

• Ist eine optionale Klausel in einer Abfrage.
• Ermöglicht es Ihnen, die Anzahl der Ergebnisse zu begrenzen, die von der Abfrage zurückgegeben werden.

Diese Klausel ist beispielsweise nützlich, wenn Sie nur an einer Stichprobe oder 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 PARAMETERS-Klausel können Sie Metaparameter für die Anfrage angeben.

Entwürfe einschließen

Mit dem Parameter include_drafts wird gesteuert, ob Entwurfseinheiten in die Ergebnisse aufgenommen werden. Die Standardeinstellung ist false. Setzen Sie den Parameter auf true, um Entwurfseinheiten einzuschließen.

In dieser Beispielabfrage werden sowohl Entwurfskampagnen als auch reguläre Kampagnen zurückgegeben:

SELECT campaign.name
FROM campaign
PARAMETERS include_drafts=true

Nicht ausgewählte resource_name weglassen

Mit dem omit_unselected_resource_names Parameter können Sie das resource_name Feld aller Ressourcen ausschließen, die in der SELECT Klausel nicht explizit angefordert werden. Die Standardeinstellung ist false. Wenn Sie diesen Parameter auf true setzen, empfehlen wir, den Ressourcennamen der primären Ressource und aller zugeordneten Ressourcen explizit in der SELECT-Klausel 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 explizit in der SELECT-Klausel 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 verwendet werden soll, der in der SELECT-Klausel enthalten ist. Standardmäßig wird die Währung des Kontos verwendet, das durch customer_id angegeben wird. 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 Währung des Kontos zurückgegeben, das durch customer_id angegeben wird.

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"

MCC-Erweiterung aktivieren

Wenn der Parameter enable_mcc_expansion auf „true“ gesetzt ist, können Sie Messwerte, Felder und Segmente aus allen Konten einbeziehen, die unter customer_id für die Ressource in der FROM-Klausel verwaltet werden. In der Antwort wird die Währung von customer_id verwendet, sofern sie nicht explizit im Parameter metrics_currency angegeben ist.

Hinweis: Der Parameter enable_mcc_expansion ist nur mit bidding_strategy kompatibel. Im Laufe der Zeit werden der API weitere Ressourcen hinzugefügt.

In dieser Beispielabfrage werden bidding_strategy.name, bidding_strategy.type und metrics.cost_micros aus allen Konten in der Kontohierarchie zurückgegeben, die unter customer_id verwaltet werden, da der Parameter enable_mcc_expansion auf true gesetzt 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