Erste Schritte mit BigQuery Graph Measures

1. Übersicht

Die meisten SQL-Fehler, die die Codeüberprüfung überstehen, sind Aggregationsfehler. Eine Zahl ist in der Tabelle, in der sie enthalten ist, korrekt, wird durch einen Join kopiert und die Summe ist falsch.

Mit BigQuery Graph können Sie einmal beschreiben, wie Ihre Tabellen als Eigenschaftsgraph verbunden sind, und dann die Verbindungen abfragen. Messwerte für Diagramme fügen der Beschreibung noch die Aggregation hinzu. Sie deklarieren MEASURE(SUM(streams)) für den Knoten, der die Zahl enthält. Jede Abfrage, die den Graphen liest, erhält die richtige Summe mit der richtigen Granularität – ohne GROUP BY-Trick und ohne CTE, an die sich jemand erinnern muss.

In diesem Codelab erstellen Sie einen Musik-Katalog mit fünf Tabellen, fügen einen Messwert hinzu und sehen, wie auf dieselbe Frage zwei unterschiedliche Antworten zurückgegeben werden: 12,6 Milliarden mit SUM und 5,1 Milliarden mit AGG. Die Lücke ist die Form des Katalogs. Ein Song, der in vier Playlists enthalten ist, wird nach dem Glätten des Diagramms zu vier Zeilen. SUM fügt alle vier hinzu. Anschließend lernen Sie die Regeln kennen, die die zweite Antwort richtig machen.

Wo Sie Text eingeben

In diesem Lab werden genau zwei Orte in dieser Reihenfolge verwendet:

	Bitte wo?	Was Sie dort tun
1	Cloud Shell-Terminal	einige wenige Befehle, nur im Schritt Einrichtung
2	BigQuery-Konsole	Alles andere: Abfragen in den Abfrageeditor einfügen, durch den Graph-Modellierer klicken, mit einem Kundenservicemitarbeiter chatten

Jede Anleitung ist getaggt, damit Sie immer wissen, welche gemeint ist:

• 👉💻 Cloud Shell – geben Sie dies im Cloud Shell-Terminal ein.
• 👉📋 Abfrageeditor: Fügen Sie den Code in den BigQuery-Abfrageeditor ein und klicken Sie auf Ausführen.
• 👉🌐 Konsole: Klicken Sie in der BigQuery-Konsole. Sie müssen nichts eingeben, es sei denn, im Schritt wird dazu aufgefordert.
• 👀 – Sehen Sie sich das Ergebnis an.

Lerninhalte

• Messwert für eine Knotentabelle deklarieren – im visuellen Diagrammmodellierer oder in SQL
• So wird ein Diagramm mit GRAPH_EXPAND in eine breite Tabelle umgewandelt
• Warum AGG die einzige Funktion ist, mit der ein Maß gelesen werden kann, und was bei jedem anderen Versuch zurückgegeben wird
• Die sechs Aggregate, die von einem Messwert unterstützt werden, und wie Sie damit rechnen
• Wie eine Messung eine anders gruppierte Frage ohne Änderungen beantwortet
• Optional: Wie GQL und der Tab „Diagramm“ eine Frage beantworten, die mit einer Summe nicht beantwortet werden kann, und wie ein BigQuery-Daten-Agent Ihre Messwerte verwendet, ohne dass er darüber informiert wird

Voraussetzungen

• Ein Google-Konto mit verfügbarer Abrechnung und ein Browser Sie benötigen kein Google Cloud-Projekt im Voraus. Bei der Einrichtung wird eines für Sie erstellt.
• Nur für den optionalen Chat-Schritt: Die Gemini Data Analytics API ist aktiviert und die Rolle Gemini Data Analytics Data Agent Creator ist zugewiesen.

Sie müssen nichts auf Ihrem Computer installieren. Alles wird in Cloud Shell und der BigQuery-Konsole ausgeführt.

Produktstatus und Kosten

BigQuery Graph ist allgemein verfügbar. Graph-Messwerte, der visuelle Graph-Modellierer, die Graph-Visualisierung und die Verwendung eines Graphen als Wissensquelle für einen Data Agent befinden sich in der Vorschauphase und unterliegen den Nutzungsbedingungen für Pre-GA-Angebote.

GRAPH_EXPAND und AGG werden zu On-Demand-Preisen ausgeführt. Für GQL-Abfragen (der optionale Pfadschritt) ist laut Dokumentation eine Reservierung mit der Enterprise- oder Enterprise Plus-Version erforderlich. Daher ist dieser Schritt optional.

Das Dataset ist nur wenige Kilobyte groß. Bei On-Demand-Preisen wird jede Abfrage mit dem Mindestbetrag von 10 MB abgerechnet. Das gesamte Codelab kostet also nur einen Bruchteil eines Cents.

Die Daten sind fiktiv. Cymbal Records, Northwind Audio, die Künstler, Songs und Playlists gibt es nicht. Die Zahlen sind bewusst gerundet, damit Sie jedes Ergebnis im Kopf nachvollziehen können.

2. Einrichtung

Dies ist der einzige Schritt, in dem Cloud Shell verwendet wird. Dabei wird ein Projekt erstellt, die Abrechnung dafür eingerichtet und die Rohdatentabellen werden erstellt. Das Diagramm, die Messung und jede Abfrage können Sie anschließend in der BigQuery-Konsole ausführen.

Eines kann Ihnen in diesem Lab nicht zur Verfügung gestellt werden: ein Google Cloud-Projekt mit aktivierter Abrechnung. In Schritt 1 erhalten Sie ein Konto, über das die Zahlung erfolgen kann. In Schritt 4 wird dieses Konto in ein Projekt umgewandelt. Führen Sie die Schritte in dieser Reihenfolge aus. In jedem Schritt nach Schritt 4 wird das Projekt gelesen, das in Schritt 4 erstellt wird.

1. Konto mit Abrechnung erstellen (~1 Minute)

👉🌐 Das solltest du als Erstes tun. Melden Sie sich mit einem Google-Konto an, für das die Abrechnung aktiviert ist. Jedes solche Konto ist geeignet. Wenn Sie noch kein Rechnungskonto haben, können Sie ein kostenloses Probeabo starten. Damit erhalten Sie ein Rechnungskonto, das für Schritt 4 erforderlich ist.

Für BigQuery ist weiterhin eine Abrechnung erforderlich. Das Dataset music ist einige Kilobyte groß und jede Abfrage in diesem Lab wird mit dem On-Demand-Mindestbetrag von 10 MB abgerechnet. BigQuery führt jedoch keine Abfrage für ein Projekt aus, dem kein Rechnungskonto zugewiesen ist.

2. Cloud Shell öffnen (ca. 1 Minute)

👉 🌐 Console: Klicken Sie oben in der Google Cloud Console auf Cloud Shell aktivieren. Das Symbol in der Kopfzeile hat die Form eines Terminals. Unten auf der Seite wird ein Terminal geöffnet.

👉🌐 Console: Wenn Sie heute an irgendeiner Stelle zur Autorisierung aufgefordert werden, klicken Sie auf Autorisieren, um fortzufahren.

👉💻 Cloud Shell: Prüfen Sie, mit welchem Konto Sie in Cloud Shell angemeldet sind:

gcloud auth list

👀 Ihr eigenes Konto sollte mit einem * gekennzeichnet sein. Es muss das Konto sein, mit dem Sie sich in Schritt 1 angemeldet haben. Falls nicht, führen Sie gcloud auth login aus und wählen Sie die richtige aus.

Sie möchten ein größeres Terminal? Klicken Sie auf Editor öffnen (das Symbol mit dem offenen Ordner und dem Stift), um den Cloud Shell-Editor aufzurufen. Öffnen Sie dann mit Ansicht → Terminal ein Terminal darin. Für dieses Lab ist der Editor nicht erforderlich. Sie bearbeiten keine Datei. Das Vollbildterminal ist jedoch besser geeignet, um die Einrichtungs-Ausgabe zu lesen.

3. Lab abrufen (ca. 1 Minute)

👉💻 Cloud Shell – Repository klonen:

cd ~
rm -rf ~/bq-graph-measures-lab
git clone https://github.com/cuppibla/bq-graph-measures-lab.git
cd ~/bq-graph-measures-lab

Warum zuerst die rm -rf? Ihr Cloud Shell-Basisverzeichnis bleibt zwischen den Sitzungen erhalten. Bei einem zweiten Versuch mit diesem Lab wird also fatal: destination path ... already exists angezeigt. Durch das Entfernen des Ordners wird sichergestellt, dass dieser Block zweimal ausgeführt werden kann. Es enthält keine Ihrer Daten.

4. Projekt erstellen (~2 Minuten)

👉💻 Cloud Shell: Ein Skript sucht nach Ihrem Rechnungskonto, erstellt ein Projekt dafür und verweist Cloud Shell auf dieses Projekt:

cd ~/bq-graph-measures-lab
./setup_project.sh

👀 Erwarte eine ✓ für das ausgewählte Rechnungskonto, eine ✓ für das erstellte Projekt und einen Abschluss wie:

Project ready: bq-graph-4271
  Next:  ./setup.sh

bq-graph-4271 ist Ihre Projekt-ID. Ihre Projekt-ID hat andere Ziffern. Dabei passieren vier Dinge:

Abrechnung	das neueste [YYYY-MM-DD] GDP Credit:-Konto, falls vorhanden, oder ein anderes offenes Rechnungskonto
project	bq-graph-XXXX wird erstellt und mit dem Rechnungskonto verknüpft.
Auswahlen	schreibt die ID in ~/project_id.txt und führt gcloud config set project aus. Sie müssen sie also nicht mehr eingeben.
waits	bis zu zwei Minuten lang Umfragen ausliefern, bis das neue Projekt tatsächlich für die Auslieferung zugelassen ist.

🌐 Dasselbe Projekt ist jetzt in der Console verfügbar. Die ID finden Sie im Dashboard auf der Karte Projektinformationen:

Warum wird es am Ende angezeigt? Ein Google Cloud-Projekt, das vor Sekunden erstellt wurde, darf noch nicht bereitgestellt werden: Die IAM-Richtlinie wird noch weitergegeben und Aufrufe werden mit 403 IAM_PERMISSION_DENIED zurückgegeben. Das ist die wahrscheinlichste Fehlerquelle bei dieser Einrichtung und kein Abrechnungs- oder Berechtigungsproblem. Die Zeilen oben haben bereits bewiesen, dass das Projekt vorhanden ist und die Abrechnung verknüpft ist. Das Skript fängt diese Wartezeit hier ab, damit ./setup.sh nicht in sie hineinläuft.

Sicher, noch einmal auszuführen Wenn etwas schiefgeht, führen Sie einfach ./setup_project.sh noch einmal aus. ~/project_id.txt wird zuerst gelesen und dieses Projekt wird wieder aufgenommen, sofern es noch vorhanden ist. Die Abrechnung wird damit verknüpft, wenn sie nicht abgeschlossen wurde. Bei einem zweiten Lauf wird also nicht stillschweigend ein zweites Projekt erstellt.

No open billing account? Das Script wird an dieser Stelle beendet, bevor Änderungen vorgenommen werden. Es wird eine Anleitung ausgegeben. In neun von zehn Fällen ist in Cloud Shell ein anderes Konto angemeldet als das Konto, das für die Abrechnung verwendet wird. Vergleichen Sie gcloud auth list mit Schritt 1.

Could not create a project? Bei einigen Konten, insbesondere bei Unternehmenskonten, ist das Erstellen von Projekten nicht zulässig. Außerdem hat jedes Konto ein Projektkontingent. Das Skript gibt Konsolenanweisungen zum manuellen Erstellen einer solchen ID aus. Sobald Sie sie haben, fügen Sie die ID in ~/project_id.txt ein und führen Sie ./setup_project.sh noch einmal aus. Das Skript verwendet dann dieses Projekt.

Sie haben bereits ein Projekt, das Sie verwenden möchten? Skript überspringen Führen Sie stattdessen gcloud config set project YOUR_PROJECT_ID aus, prüfen Sie mit gcloud config get-value project, ob die Änderung übernommen wurde, und fahren Sie direkt mit Schritt 5 fort. Sie benötigen die Rolle BigQuery-Administrator.

5. Dataset erstellen (ca. 3 Minuten)

👉💻 Cloud Shell: Ein weiteres Script erstellt die Tabellen:

cd ~/bq-graph-measures-lab
./setup.sh

Das Skript gibt jeden Schritt aus, während es ausgeführt wird. So funktioniert es:

project	liest das Projekt ab gcloud config und weigert sich, ohne fortzufahren.
API	ermöglicht bigquery.googleapis.com
Datensatz	erstellt das Dataset music in der Multiregion US und fünf Tabellen mit jeweils einem PRIMARY KEY ... NOT ENFORCED
Prüfen	zählt die Zeilen in jeder Tabelle und wird beendet, wenn eine Anzahl nicht stimmt

👀 Erwartungen:

BigQuery Graph Measures · setup
  ✓ project: bq-graph-4271
  ✓ BigQuery API enabled

Creating dataset music (US) and five tables...
  ✓ music.Labels              2 rows
  ✓ music.Artists             3 rows
  ✓ music.Songs               5 rows
  ✓ music.Playlists           4 rows
  ✓ music.PlaylistEntries    10 rows

🎉 ready — open BigQuery Studio: https://console.cloud.google.com/bigquery?project=bq-graph-4271

Sie haben Cloud Shell verwendet. Sie können sie schließen.

Jede Abfrage in diesem Lab ist auch eine Datei in diesem Repository. sql/01_... bis sql/09_..., nummeriert nach Schritt. Wenn Sie lieber einen Befehl im Terminal ausführen, anstatt ihn in die Konsole einzufügen: bq query --nouse_legacy_sql < sql/02_sum_vs_agg.sql.

6. BigQuery und einen Abfrageeditor öffnen

👉🌐 Console (Konsole): Klicken Sie auf den Link am Ende der Ausgabe oder öffnen Sie BigQuery über das Navigationsmenü. Maximieren Sie im Bereich Explorer auf der linken Seite Ihr Projekt. Es enthält ein music-Dataset mit fünf Tabellen.

👉🌐 Console: Klicken Sie oben in BigQuery Studio in der Zeile Neu erstellen auf SQL-Abfrage. Ein leerer Editor-Tab wird geöffnet.

Diesen Tab behalten. Jeder 👉📋-Block in diesem Lab gehört hierher:Wählen Sie alles aus, was sich im Editor befindet, fügen Sie den neuen Block ein und klicken Sie auf Ausführen. Das Ergebnis wird im Bereich darunter angezeigt.

Tabellen

Zwei Dinge in diesen Tabellen sind später wichtig. Jede Tabelle deklariert ihren Primärschlüssel als NOT ENFORCED. BigQuery prüft ihn nicht, aber für den Property Graph, den Sie erstellen möchten, ist ein expliziter Schlüssel erforderlich, um zu wissen, was eine Zeile identifiziert. Die letzte Tabelle, PlaylistEntries, ist eine Verknüpfungstabelle: Ein Song, der sich in vier Playlists befindet, hat vier Zeilen. In dieser Tabelle wird die ganze Geschichte erzählt.

Die Tabellen sind so miteinander verknüpft: Ein Label nimmt Künstler unter Vertrag, ein Künstler veröffentlicht Songs und ein Song wird über PlaylistEntries in Playlists platziert. Cymbal Records besitzt Ava Sterling und Mina Okafor und damit vier Songs. Northwind Audio besitzt Kai Nakamura und den Song „Midnight Drive“.

Tabelle	Zeilen	Schlüssel	Was sie enthält
Labels	2	label_id	Name, Marketingbudget
Künstler	3	artist_id	Name, welches Label
Titel	5	song_id	Titel, Künstler, Streams
Playlists	4	playlist_id	Name, Follower
PlaylistEntries	10	entry_id	Welcher Song ist in welcher Playlist enthalten?

✅ Checkpoint : 🎉 ready in Cloud Shell, fünf Tabellen unter music im Explorer und ein leerer Tab für den Abfrage-Editor sind geöffnet.

3. Diagramm erstellen – Option A: Visual Modeler

Ein Attributgraph beschreibt, wie die Tabellen miteinander verbunden sind. Sie können sie im Modellierer für visuelle Diagramme zusammenklicken (dieser Schritt, alles per Klick) oder als SQL schreiben (nächster Schritt, ein Einfügen). Beide Methoden führen zum selben Objekt. Verwenden Sie also nur eine der beiden.

Sie sind bereits mit DDL vertraut? Fahren Sie mit dem nächsten Schritt fort und fügen Sie den Code ein. Sie können später zurückkehren und den Modeler öffnen. Dort wird jede Grafik angezeigt, unabhängig davon, wie sie erstellt wurde.

1. Graph-Shell erstellen

👉🌐 Console: Öffnen Sie in BigQuery Studio in der Zeile Create new (Neu erstellen) das Menü AI and knowledge (KI und Wissen) und klicken Sie auf Graph (Diagramm).

👉🌐 Console: Geben Sie MusicGraph als Graph name (Graphname) und music als Graph destination in dataset (Ziel des Graphen im Dataset) ein. Die Region wird aus dem Dataset (USA) übernommen.

👉🌐 Console: Wähle unter Data sources (Datenquellen) die fünf Tabellen „Artists“ (Künstler), „Labels“ (Labels), „PlaylistEntries“ (Playlist-Einträge), „Playlists“ (Playlists) und „Songs“ (Songs) aus und klicke auf Create (Erstellen).

👀 Die Arbeitsfläche wird mit fünf farbigen Knoten ohne Linien zwischen ihnen geöffnet. Im Bereich Details auf der rechten Seite sind Knoten (5) und Kanten (0) aufgeführt. Jeder Knoten enthält bereits den Primärschlüssel und alle Spalten der zugehörigen Tabelle als Attribute. Klicken Sie auf einen beliebigen Knoten, um sie aufzurufen.

2. Vier Kanten zeichnen

Eine Kante ist ein Fremdschlüssel, der gezeichnet wird. Jede Beziehung verläuft von der Tabelle, die den Schlüssel enthält, zur Tabelle, auf die sie verweist.

👉🌐 Console (Konsole): Klicken Sie auf New edge (Neuer Edge). Wählen Sie im Dialogfeld Tabelle auswählen die Option PlaylistEntries aus und klicken Sie auf Hinzufügen. Im Bereich Kante hinzufügen:

1. Legen Sie als Name EntryToSong fest.
2. Klicken Sie auf Primärschlüssel hinzufügen und akzeptieren Sie entry_id.
3. Legen Sie unter Quelle den Quellknoten auf „PlaylistEntries“ fest. Verwenden Sie dann Dem Knoten referenzierte Spalten hinzufügen und Dem Edge referenzierte Spalten hinzufügen, um für beide entry_id auszuwählen.
4. Legen Sie unter Ziel für Zielknoten „Titel“ fest und wählen Sie dann für Referenzierte Spalten im Knoten und Referenzierte Spalten im Edge jeweils song_id aus.
5. Klicken Sie auf Fertig.

👉🌐 Console (Konsole) – wiederholen Sie diesen Schritt noch dreimal:

Name der Kante	Tabelle	Quellknoten → Zielknoten	die Spalte, die auf beiden Seiten ausgewählt werden soll
EntryToPlaylist	PlaylistEntries	PlaylistEntries → Playlists	Quelle: entry_id, Ziel: playlist_id
SongToArtist	Titel	Titel → Künstler	Quelle: song_id, Ziel: artist_id
ArtistToLabel	Künstler	Künstler → Labels	Quelle: artist_id, Ziel: label_id

Lassen Sie alle Kanten ohne zusätzliche Attribute.

👀 Im Detailbereich steht jetzt Kanten (4) und auf dem Arbeitsbereich wird die Kette „Labels ← Künstler ← Songs ← PlaylistEntries → Playlists“ angezeigt.

3. Messung hinzufügen

👉🌐 Console: Klicke auf den Knoten Songs und dann oben im Detailbereich auf das Symbol Bearbeiten (Stift). Klicken Sie unter den Eigenschaften des Labels auf Eigenschaft hinzufügen und dann auf Feld hinzufügen.

👉 🌐 Konsole: Geben Sie total_streams als Feldname ein und fügen Sie Folgendes in das Feld Ausdruck ein:

MEASURE(SUM(streams))

👉🌐 Console (Konsole): Klicken Sie auf Add (Hinzufügen) und dann auf Done (Fertig).

4. Den geschriebenen Code lesen und dann veröffentlichen

👉🌐 Console: Öffnen Sie im rechten Bereich den Tab Code. Der Modeler hat die CREATE PROPERTY GRAPH-Anweisung für Sie geschrieben. Scrolle zum Knoten „Songs“. Seine Attributliste endet jetzt mit

MEASURE(SUM(streams)) AS `total_streams`

Das ist die gesamte Funktion in einer Zeile. Alles nach diesem Schritt bezieht sich darauf, was diese Zeile bewirkt.

👉 🌐 Console: Klicken Sie auf Publish (Veröffentlichen).

Bei Option B werden einige weitere Messwerte angegeben, z. B. Anzahl der Songs, Budgets, Follower und Placements. Im Schritt Jede Aggregation, die eine Messung unterstützt wird das Diagramm mit allen Aggregationen in SQL neu erstellt. Sie müssen sie also nicht manuell hinzufügen.

✅ Checkpoint:Im Explorer music gibt es jetzt den Ordner Graphs mit MusicGraph. Klicken Sie darauf: fünf Knoten, vier Kanten und die MEASURE(SUM(streams))-Zeile auf dem Tab „Code“. Überspringen Sie den nächsten Schritt und fahren Sie mit SUM und AGG nebeneinander fort.

4. Graph erstellen – Option B: SQL

Überspringen Sie diesen Schritt, wenn Sie das Diagramm im Modeler erstellt haben.

👉📋 Abfrageeditor – fügen Sie die Abfrage ein und klicken Sie auf Ausführen:

CREATE OR REPLACE PROPERTY GRAPH music.MusicGraph
  NODE TABLES (
    music.Labels KEY (label_id)
      PROPERTIES (label_id, label_name, marketing_budget,
        MEASURE(SUM(marketing_budget)) AS total_budget),
    music.Artists KEY (artist_id)
      PROPERTIES (artist_id, artist_name, label_id,
        MEASURE(COUNT(artist_id)) AS artist_count),
    music.Songs KEY (song_id)
      PROPERTIES (song_id, title, artist_id, streams,
        MEASURE(SUM(streams))   AS total_streams,
        MEASURE(COUNT(song_id)) AS song_count),
    music.Playlists KEY (playlist_id)
      PROPERTIES (playlist_id, playlist_name, followers,
        MEASURE(SUM(followers)) AS total_followers),
    music.PlaylistEntries KEY (entry_id)
      PROPERTIES (entry_id, playlist_id, song_id,
        MEASURE(COUNT(entry_id)) AS placement_count)
  )
  EDGE TABLES (
    music.PlaylistEntries AS EntryToSong
      SOURCE KEY (entry_id) REFERENCES PlaylistEntries(entry_id)
      DESTINATION KEY (song_id) REFERENCES Songs(song_id) NO PROPERTIES,
    music.PlaylistEntries AS EntryToPlaylist
      SOURCE KEY (entry_id) REFERENCES PlaylistEntries(entry_id)
      DESTINATION KEY (playlist_id) REFERENCES Playlists(playlist_id) NO PROPERTIES,
    music.Songs AS SongToArtist
      SOURCE KEY (song_id) REFERENCES Songs(song_id)
      DESTINATION KEY (artist_id) REFERENCES Artists(artist_id) NO PROPERTIES,
    music.Artists AS ArtistToLabel
      SOURCE KEY (artist_id) REFERENCES Artists(artist_id)
      DESTINATION KEY (label_id) REFERENCES Labels(label_id) NO PROPERTIES
  )

👀 Im Ergebnisbereich wird angezeigt, dass die Attributgrafik erstellt wurde.

Einmal lesen

Das Diagramm enthält fünf Knotentabellen und vier Kantentabellen. Für jede Knotentabelle wird der KEY angegeben und die PROPERTIES werden aufgeführt. Die Zeilen, die mit MEASURE beginnen, sind der neue Teil: In jeder Zeile wird eines der unterstützten Aggregate um eine Property gewrappt und es wird ein Alias dafür angegeben, was erforderlich ist.

Jede Kanten-Tabelle ist ein Fremdschlüssel, ausgeschrieben: SOURCE KEY in der Tabelle, die den Schlüssel enthält, DESTINATION KEY in der Tabelle, auf die er verweist. NO PROPERTIES bedeutet, dass die Kante nichts Eigenes enthält.

PlaylistEntries wird dreimal angezeigt: einmal als Knotentabelle und zweimal als physische Tabelle hinter den Kanten EntryToSong und EntryToPlaylist. Das ist bewusst so und wir werden später erklären, warum.

Erstellte Inhalte ansehen

👉🌐 Console: Erweitern Sie im Bereich „Explorer“ zuerst music, dann Graphs und klicken Sie auf MusicGraph. Die Diagrammseite wird auf einer Arbeitsfläche mit fünf Knoten und vier Kanten geöffnet. Klicken Sie auf einen Knoten, um seine Eigenschaften aufzurufen. Die Messwerte werden mit ihrem Aggregat aufgeführt. Öffnen Sie den Tab Code, um die Aussage hinter dem Bild zu sehen.

✅ Checkpoint: music hat einen Ordner Graphs, der MusicGraph enthält, und auf dem Tab „Code“ wird MEASURE(SUM(streams)) AS total_streams angezeigt.

5. SUM und AGG nebeneinander

Das ist das gesamte Codelab in einer Abfrage. In beiden Spalten wird versucht, dieselbe Frage zu beantworten: „Gesamtzahl der Streams pro Label“ aus derselben Tabelle.

Diese Tabelle wird von GRAPH_EXPAND erstellt. Der Graph wird vereinfacht: Er beginnt bei einer Tabelle und folgt jeder Kante nach außen als LEFT JOIN, bis jede verbundene Tabelle nebeneinander in einem einzigen breiten Ergebnis steht. Eine Zeile pro Placement, nicht pro Song, und jede Spalte mit dem Namen TableLabel_property. Sehen Sie sich das Ergebnis an, bevor Sie eine Anfrage stellen.

👉📋 Abfrageeditor – fügen Sie die Abfrage ein und klicken Sie auf Ausführen:

SELECT Labels_label_name, Songs_title, Songs_streams, Playlists_playlist_name
FROM GRAPH_EXPAND("music.MusicGraph")
ORDER BY Songs_title, Playlists_playlist_name

👀 Erwartet werden 10 Zeilen – eine für jedes Placement in PlaylistEntries. Das ist genau das, was in Setup geladen wurde. „Neon Summer“ belegt vier davon, eine pro Playlist, auf der der Song zu finden ist, und Songs_streams wird in jeder Playlist mit 2.000.000.000 angegeben. Mit diesen Zeilen ist alles in Ordnung. Die Playlists haben wirklich vier Videos. Eine Spalte, die zu einem Song gehört, wird jetzt in Zeilen wiederholt, die zu Placements gehören. Das ist das Problem, das mit der nächsten Abfrage gemessen wird.

Nun zum Vergleich.

👉📋 Abfrageeditor – fügen Sie die Abfrage ein und klicken Sie auf Ausführen:

SELECT
  Labels_label_name,
  SUM(Songs_streams)       AS with_sum,
  AGG(Songs_total_streams) AS with_agg
FROM GRAPH_EXPAND("music.MusicGraph")
GROUP BY 1 ORDER BY 1

👀 Ergebnis:

Labels_label_name	with_sum	with_agg
Cymbal Records	12.600.000.000	5.100.000.000
Northwind Audio	9.000.000.000	4.500.000.000

Prüfen Sie es manuell. Die vier Songs von Cymbal haben 2,0 Milliarden, 1,5 Milliarden, 1,2 Milliarden und 0,4 Milliarden Streams. Das sind 5,1 Milliarden. AGG ist richtig. SUM ist zweieinhalb Mal zu groß und Northwinds einzelner Song wurde verdoppelt.

Drei neue Syntaxelemente

• GRAPH_EXPAND("music.MusicGraph") ist eine Tabellenwertfunktion, die den Graphen in eine breite Tabelle umwandelt, indem jede Kante als LEFT JOIN betrachtet wird. Jede Spalte hat den Namen TableLabel_property. Songs_streams ist die Rohspalte aus der Tabelle „Songs“ und Songs_total_streams ist der von Ihnen deklarierte Messwert.
• SUM(Songs_streams) ist normales SQL für diese breite Tabelle und enthält alle Duplikate, die durch das Zusammenführen entstanden sind.
• AGG(Songs_total_streams) wird so ausgewertet, wie der Messwert deklariert wurde: SUM(streams) einmal pro song_id, unabhängig davon, wie viele Zeilen ein Song in der breiten Tabelle belegt.

Im Cache gespeicherte Ergebnisse berücksichtigen keine Änderungen am Graphen. Ergebnisse von Abfragen, die GRAPH_EXPAND aufrufen, werden wie alle anderen im Cache gespeichert. Eine Änderung des Diagramms führt nicht dazu, dass der Cache ungültig wird. Wenn Sie eine Abfrage nach dem Ändern des Diagramms noch einmal ausführen, öffnen Sie im Abfrageeditor Mehr → Abfrageeinstellungen und deaktivieren Sie Im Cache gespeicherte Ergebnisse verwenden.

✅ Checkpoint:Zwei Labels, zwei Spalten und die with_agg-Zahlen stimmen mit der manuellen Zählung überein.

6. Warum SUMME zu viele Werte zählt

Nehmen Sie einen Song und sehen Sie sich an, was durch die Joins passiert.

👉📋 Abfrageeditor – fügen Sie die Abfrage ein und klicken Sie auf Ausführen:

SELECT 'BEFORE - the Songs table' AS step, title, streams, CAST(NULL AS STRING) AS playlist
FROM music.Songs WHERE title = 'Neon Summer'
UNION ALL
SELECT 'AFTER - joined to playlists', s.title, s.streams, pl.playlist_name
FROM music.Songs s
LEFT JOIN music.PlaylistEntries e ON e.song_id = s.song_id
LEFT JOIN music.Playlists pl ON pl.playlist_id = e.playlist_id
WHERE s.title = 'Neon Summer'
ORDER BY step DESC, playlist

👀 Ergebnis:

Schritt	Titel	Streams	Playlist
VORHER: Tabelle „Songs“	Neon Summer	2.000.000.000	null
DANACH – zu Playlists hinzugefügt	Neon Summer	2.000.000.000	Gym Pump
DANACH – zu Playlists hinzugefügt	Neon Summer	2.000.000.000	Aktuell im Trend
DANACH – zu Playlists hinzugefügt	Neon Summer	2.000.000.000	Rising Pop
DANACH – zu Playlists hinzugefügt	Neon Summer	2.000.000.000	Roadtrip

Aus einer Zeile wurden vier. Die Anzahl der Streams hat sich nicht geändert, sie wurde kopiert. Wir addieren, was die Kopien für Cymbal Records tun: „Neon Summer“ mit 2,0 Milliarden Streams auf vier Playlists ergibt 8,0, „Paper Crown“ mit 1,5 Milliarden Streams auf zwei Playlists ergibt 3,0, „Double Shot“ mit 1,2 Milliarden Streams auf einer Playlist und „Slow Arrow“ mit 0,4 Milliarden Streams auf einer Playlist. Das sind 12,6 Milliarden, die zurückgegebene Zahl SUM. „Northwind’s Midnight Drive“ ist in zwei Playlists enthalten, daher wurde die Zahl von 4,5 Milliarden auf 9,0 Milliarden verdoppelt.

Das ist Fan-out und kein Fehler im Join. Die Playlistzeilen sind echt. Der Fehler besteht darin, dass eine Zahl, die zu einem Song gehört, über Zeilen hinweg summiert wird, die zu Placements gehören.

Das Problem wird durch die Maßnahme behoben, da sie zusammen mit KEY (song_id) für den Knoten „Songs“ deklariert wurde. Der Schlüssel ist die Körnung. Wenn AGG total_streams auswertet, werden die Daten zuerst nach Song-Schlüssel zusammengefasst und dann auf die Gruppierungsebene hochgerechnet.

Was hat sich geändert?

Sie haben früher geschrieben	Mit einem Messwert
SUM(streams) in jeder entsprechenden Anfrage	MEASURE(SUM(streams)) einmal in der Grafik
SUM(...), um den Text vorlesen zu lassen	AGG(...), um sie zu lesen – und nur AGG
Drei JOINs	GRAPH_EXPAND(), eine flache Tabelle
Ein CTE, das vor dem Zusammenführen aggregiert wird	Nichts. Die KEY bestimmt die Granularität.

✅ Checkpoint:Fünf Zeilen – eine VORHER, vier NACHHER – und Sie können 12,6 Milliarden daraus rekonstruieren.

7. Regel: Nur AGG liest einen Messwert

Messwerte haben einen eigenen Typ, MEASURE, und werden von genau einer Funktion akzeptiert. Die vier Abfragen unten schlagen absichtlich fehl. Führen Sie jede aus und lesen Sie den roten Fehler. Das sind die vier Möglichkeiten, die jeder zuerst ausprobiert. Wenn Sie wissen, was dabei passiert, sparen Sie später Zeit.

👉📋 Abfrageeditor – AGG für eine einfache Spalte:

SELECT AGG(Songs_streams) FROM GRAPH_EXPAND("music.MusicGraph")

👀 No matching signature for aggregate function AGG ... Argument 1: expected MEASURE, found INT64

👉📋 Abfrageeditor: Eine Messwertspalte ohne AGG:

SELECT Songs_total_streams FROM GRAPH_EXPAND("music.MusicGraph") LIMIT 1

👀 Returning expressions of type MEASURE is not allowed

👉📋 Abfrageeditor: Ein in GQL referenzierter Messwert, der nie Messwerte enthält (diese ist eine GQL-Abfrage – siehe Anmerkung zur Version in der Übersicht):

GRAPH music.MusicGraph
MATCH (s:Songs)
RETURN s.total_streams
LIMIT 1

👀 total_streams is not exposed by element type GRAPH_NODE(...)

👉📋 Abfrageeditor – SUM über eine Messspalte, die verlockende:

SELECT Labels_label_name, SUM(Songs_total_streams)
FROM GRAPH_EXPAND("music.MusicGraph")
GROUP BY 1

👀 MEASURE-typed arguments are only permitted in the AGG function

Das Typsystem erzwingt die Regel für Sie. Ein Messwert ist nur über GRAPH_EXPAND sichtbar und nur über AGG lesbar. Die zuvor zu viel gezählten 12,6 Milliarden können nur durch das Summieren der Rohspalte zustande kommen, nicht durch eine falsche Verarbeitung der Messung.

✅ Checkpoint:Vier rote Fehler und Sie können sagen, welche Regel jeweils durchgesetzt wird.

8. Jedes Aggregat, das von einer Messung unterstützt wird

MEASURE() umfasst eines von sechs Aggregaten: SUM, AVG, MIN, MAX, COUNT und COUNT(DISTINCT). Erstellen Sie das Diagramm mit allen sechs Knoten neu. Die Kanten bleiben NO PROPERTIES. Das ist die empfohlene Vorgehensweise, wenn eine Kante ihre physische Tabelle mit einem Knoten gemeinsam nutzt.

👉📋 Abfrageeditor – fügen Sie die Abfrage ein und klicken Sie auf Ausführen:

CREATE OR REPLACE PROPERTY GRAPH music.MusicGraph
  NODE TABLES (
    music.Labels KEY (label_id)
      PROPERTIES (label_id, label_name, marketing_budget,
        MEASURE(SUM(marketing_budget)) AS total_budget),
    music.Artists KEY (artist_id)
      PROPERTIES (artist_id, artist_name, label_id,
        MEASURE(COUNT(artist_id)) AS artist_count),
    music.Songs KEY (song_id)
      PROPERTIES (song_id, title, artist_id, streams,
        MEASURE(SUM(streams))              AS total_streams,
        MEASURE(AVG(streams))              AS avg_streams,
        MEASURE(MIN(streams))              AS min_streams,
        MEASURE(MAX(streams))              AS max_streams,
        MEASURE(COUNT(song_id))            AS song_count,
        MEASURE(COUNT(DISTINCT artist_id)) AS distinct_artists),
    music.Playlists KEY (playlist_id)
      PROPERTIES (playlist_id, playlist_name, followers,
        MEASURE(SUM(followers)) AS total_followers),
    music.PlaylistEntries KEY (entry_id)
      PROPERTIES (entry_id, playlist_id, song_id,
        MEASURE(COUNT(entry_id)) AS placement_count)
  )
  EDGE TABLES (
    music.PlaylistEntries AS EntryToSong
      SOURCE KEY (entry_id) REFERENCES PlaylistEntries(entry_id)
      DESTINATION KEY (song_id) REFERENCES Songs(song_id) NO PROPERTIES,
    music.PlaylistEntries AS EntryToPlaylist
      SOURCE KEY (entry_id) REFERENCES PlaylistEntries(entry_id)
      DESTINATION KEY (playlist_id) REFERENCES Playlists(playlist_id) NO PROPERTIES,
    music.Songs AS SongToArtist
      SOURCE KEY (song_id) REFERENCES Songs(song_id)
      DESTINATION KEY (artist_id) REFERENCES Artists(artist_id) NO PROPERTIES,
    music.Artists AS ArtistToLabel
      SOURCE KEY (artist_id) REFERENCES Artists(artist_id)
      DESTINATION KEY (label_id) REFERENCES Labels(label_id) NO PROPERTIES
  )

Lies sie dir jetzt noch einmal durch. Jede Maßnahme durchläuft AGG. In der letzten Spalte sehen Sie, dass AGG normale Werte sind, mit denen Sie rechnen können. Das Diagramm hat sich gerade geändert. Deaktivieren Sie zuerst Im Cache gespeicherte Ergebnisse verwenden („Weitere Optionen“ → „Abfrageeinstellungen“).

👉📋 Abfrageeditor – fügen Sie die Abfrage ein und klicken Sie auf Ausführen:

SELECT
  Labels_label_name,
  AGG(Songs_total_streams)    AS total_streams,
  AGG(Songs_avg_streams)      AS avg_streams,
  AGG(Songs_min_streams)      AS min_streams,
  AGG(Songs_max_streams)      AS max_streams,
  AGG(Songs_song_count)       AS songs,
  AGG(Songs_distinct_artists) AS artists,
  AGG(Songs_total_streams) / AGG(Songs_song_count) AS streams_per_song
FROM GRAPH_EXPAND("music.MusicGraph")
GROUP BY 1
ORDER BY 1

👀 Ergebnis:

Labels_label_name	total_streams	avg_streams	min_streams	max_streams	Titel	Künstler	streams_per_song
Cymbal Records	5.100.000.000	1.275.000.000	400.000.000	2.000.000.000	4	2	1.275.000.000
Northwind Audio	4.500.000.000	4.500.000.000	4.500.000.000	4.500.000.000	1	1	4.500.000.000

Jede Zahl wird für vier Songs für Cymbal und einen für Northwind berechnet, nicht für die zehn Placement-Zeilen. Insbesondere AVG wäre in der anderen Richtung falsch gewesen: Wenn man den Durchschnitt der Rohspalte über die Placement-Zeilen hinweg berechnet, erhält man 1,575 Milliarden für Cymbal, da die 2 Milliarden von Neon Summer viermal gezählt werden.

„SUM durch AGG ersetzen“ ist also eigentlich eine Kombination aus zwei Entscheidungen. Wenn Sie die Messung deklarieren, wählen Sie weiterhin aus, zu welchem der sechs Aggregate sie gehört. Wenn Sie sie lesen, ist die Funktion immer AGG.

Messwerte für Edge-Tabellen funktionieren ebenfalls, allerdings mit einer Einschränkung: In einem Messwertausdruck darf nur auf ein Attribut verwiesen werden, das im Edge selbst deklariert ist. Listen Sie also zuerst das Attribut und dann den Messwert auf, in dem es verwendet wird.

✅ Checkpoint:Eine Zeile pro Label, jeweils sieben Zahlen und streams_per_song = avg_streams.

9. Gruppierung ändern, nicht die Messung

Mit derselben Messung wird eine andere Frage beantwortet. Nach Playlist statt nach Label gruppieren.

👉📋 Abfrageeditor – fügen Sie die Abfrage ein und klicken Sie auf Ausführen:

SELECT
  Playlists_playlist_name,
  AGG(Songs_total_streams) AS streams,
  AGG(Songs_song_count)    AS songs
FROM GRAPH_EXPAND("music.MusicGraph")
GROUP BY 1
ORDER BY 2 DESC

👀 Ergebnis:

Playlists_playlist_name	Streams	Titel
Roadtrip	6.900.000.000	3
Gym Pump	6.500.000.000	2
Aktuell im Trend	4.700.000.000	3
Rising Pop	3.500.000.000	2

Die beiden AGG-Zeilen sind bytegenau die aus SUM und AGG, nebeneinander. Nur die GROUP BY wurde verschoben. Die Playlist „Road Trip“ enthält die Songs „Neon Summer“, „Midnight Drive“ und „Slow Arrow“. Jeder Song wird in dieser Playlist einmal gezählt. Das ist genau das, was mit „Streams, die diese Playlist erreichen“ gemeint ist.

Die Person, die die Maßnahme erstellt hat, hat die Granularität einmal festgelegt. Jede spätere Anfrage von beliebigen Nutzern erbt sie.

✅ Checkpoint: „Road Trip“ mit 6,9 Milliarden Aufrufen auf Platz 1.

10. Vorteile von GRAPH_EXPAND

Sie müssen GRAPH_EXPAND nicht ausführen, um die Form zu ermitteln. Mit der Systemprozedur BQ.SHOW_GRAPH_EXPAND_SCHEMA wird die Spaltenliste in eine Variable geschrieben.

👉📋 Abfrageeditor: Fügen Sie alle drei Zeilen ein und klicken Sie dann auf Ausführen:

DECLARE schema STRING DEFAULT '';
CALL BQ.SHOW_GRAPH_EXPAND_SCHEMA('music.MusicGraph', schema);
SELECT schema;

👀 Das Ergebnis ist ein JSON-String. Jedes Feld hat einen Namen, einen Typ und einen Modus. Jede Messwertspalte enthält "is_measure": true. Für das gerade erstellte Diagramm erhalten Sie unter anderem Folgendes:

name	Typ	is_measure
Songs_title	STRING
Songs_streams	INTEGER
Songs_total_streams	INTEGER	wahr
Songs_avg_streams	GLEITKOMMAZAHL	wahr
Songs_distinct_artists	INTEGER	wahr
PlaylistEntries_placement_count	INTEGER	wahr

Alle Beschreibungen oder Synonyme, die Sie für eine Property festlegen, werden ebenfalls hier angezeigt. Im optionalen Chat-Schritt wird angezeigt, wer diese Nachrichten liest.

✅ Checkpoint:Ein JSON-String mit is_measure in jeder Spalte, die Sie mit MEASURE deklariert haben.

11. Anforderungen von GRAPH_EXPAND an die Form eines Diagramms

In diesem Schritt muss nichts ausgeführt werden – lesen Sie einfach weiter. GRAPH_EXPAND erstellt die breite Tabelle mit einer Kette von LEFT JOINs, beginnend mit einer Tabelle und den Kanten nach außen folgend. Daraus ergeben sich drei Regeln, die MusicGraph alle erfüllt.

Genau eine Root-Knotentabelle. Der Stamm ist die Knotentabelle, deren Schlüssel in keiner anderen Tabelle vorkommt – auf die also keine Edge verweist. In MusicGraph ist das PlaylistEntries: die Quelle von zwei Kanten und das Ziel von keiner. Die breite Tabelle hat 10 Zeilen, eine für jede Platzierung.

Jede Kante ist eine n:1-Beziehung von der Quelle zum Ziel. Jeder Eintrag enthält einen Song und eine Playlist, jeder Song hat einen Künstler und jeder Künstler hat ein Label. Aus diesem Grund werden die Zeilen der breiten Tabelle nie über die Zeilen des Stamms hinaus erweitert. Daten, die nicht über den Root erreicht werden können, werden nicht angezeigt: Ein Song ohne Platzierungen würde in der breiten Tabelle fehlen.

N-zu-N-Beziehungen werden zu einem Knoten. Zwischen Songs und Playlists besteht eine m:n-Beziehung. Wenn Sie die Verbindungstabelle als einzelne Kante von „Songs“ zu „Playlists“ deklariert haben, würde GRAPH_EXPAND sie als mehrdeutig ignorieren. Da keine verwendbaren Kanten mehr vorhanden wären, würde der Vorgang fehlschlagen. PlaylistEntries in eine Knotentabelle mit zwei Many-to-One-Kanten zu verschieben, ist das dokumentierte Muster und das haben Sie beim Erstellen des Diagramms auch getan.

Zwei kleinere Best Practices aus der Dokumentation:Definieren Sie einen Knoten und seine ausgehenden Kanten in derselben physischen Tabelle, wie in diesem Diagramm. Behalten Sie diese Kanten NO PROPERTIES bei, es sei denn, die Kante enthält Informationen, die der Knoten nicht enthält.

12. (OPTIONAL) Pfade mit GQL

Bisher hatte jede Frage eine Zahl als Antwort. Bei diesem nicht. Wo erreichen die Streams von Cymbal die Zuhörer? ist eine Frage zu Routen durch den Graph, die nicht durch eine Summe beantwortet werden kann, da die Route nach dem Summieren nicht mehr vorhanden ist.

Für diesen Schritt ist eine Reservierung erforderlich. Für GQL-Abfragen ist eine Reservierung in der Enterprise- oder Enterprise Plus-Version erforderlich. Wenn für Ihr Projekt On-Demand-Preise gelten, lesen Sie weiter. Alle Ergebnisse werden unten angezeigt. Fahren Sie dann mit dem nächsten Schritt fort.

1. Fragen, wo die Streams landen

👉📋 Abfrageeditor – fügen Sie die Abfrage ein und klicken Sie auf Ausführen:

GRAPH music.MusicGraph
MATCH (l:Labels)<-[:ArtistToLabel]-(a:Artists)<-[:SongToArtist]-(s:Songs)
      <-[:EntryToSong]-(e:PlaylistEntries)-[:EntryToPlaylist]->(pl:Playlists)
WHERE l.label_name = 'Cymbal Records'
RETURN pl.playlist_name, pl.followers,
       SUM(s.streams) AS streams_reaching_this_playlist,
       STRING_AGG(s.title, ', ') AS songs
GROUP BY pl.playlist_name, pl.followers
ORDER BY streams_reaching_this_playlist DESC

👀 Vier Playlists:

pl.playlist_name	pl.followers	streams_reaching_this_playlist	Titel
Aktuell im Trend	35.000.000	4.700.000.000	Double Shot, Neon Summer, Paper Crown
Rising Pop	2.000.000	3.500.000.000	Neon Summer, Paper Crown
Roadtrip	5.000.000	2.400.000.000	Neon Summer, Slow Arrow
Gym Pump	3.000.000	2.000.000.000	Neon Summer

Lesen Sie die MATCH-Zeile als Satz: Beginnen Sie mit einem Label, gehen Sie zurück zu den Künstlern, dann zu ihren Songs, dann zu den Playlist-Einträgen, in denen sich diese Songs befinden, und dann weiter zu den Playlists. Die Pfeile zeigen die Richtung an, in der die Kanten deklariert wurden. <- geht rückwärts.

Addieren Sie nun die Werte in der dritten Spalte. 12,6 Milliarden: Die Zahl, die SUM Ihnen in Schritt 4 genannt hat und die falsch war.

Hier ist es richtig. Damals ging es darum, wie viel Cymbal gestreamt wurde. Ein Song wurde nur einmal gezählt, unabhängig davon, in wie vielen Playlists er enthalten war. Diese Frage bezieht sich darauf, wo diese Streams erreicht werden. Ein Song auf vier Playlists erreicht tatsächlich vier Zielgruppen. Die Duplizierung GRAPH_EXPAND ist ein Fehler für eine Frage und die Antwort auf die andere. Bei AGG ging es nie darum, dass Duplikate schlecht sind, sondern darum, dass die Arithmetik zur Frage passt.

2. Die Pfade selbst zurückgeben

Lassen Sie die Aggregation weg und fragen Sie nach den Routen.

👉📋 Abfrageeditor – fügen Sie die Abfrage ein und klicken Sie auf Ausführen:

GRAPH music.MusicGraph
MATCH p = (l:Labels)<-[:ArtistToLabel]-(a:Artists)<-[:SongToArtist]-(s:Songs)
          <-[:EntryToSong]-(e:PlaylistEntries)-[:EntryToPlaylist]->(pl:Playlists)
WHERE l.label_name = 'Cymbal Records'
RETURN TO_JSON(p) AS path

Mit p = wird das gesamte Match benannt und mit TO_JSON gerendert.

👀 Erwartet 8 Zeilen und eine path-Spalte. Jede Zelle ist ein JSON-Array der Knoten und Kanten entlang einer Route. Jeder Knoten enthält seine labels und properties.

Acht Zeilen für vier Songs, da es eine Route pro Placement und nicht pro Song gibt.

3. Tab „Diagramm“ öffnen

👉🌐 Konsole: Klicken Sie über den Ergebnissen auf Diagramm.

Dieser Tab wird nur angezeigt, wenn ein Ergebnis Grafikelemente enthält. Bei der vorherigen Abfrage wurden Zahlen zurückgegeben, daher gab es keinen Tab „Diagramm“. Bei dieser Abfrage werden Pfade zurückgegeben, daher gibt es einen Tab „Diagramm“.

Die Ecke des Diagramms für Cymbal wird als Force-Layout dargestellt. Sie sehen die Anzahl der Knoten und Kanten sowie ein Chip pro Label. Ziehen Sie einen Knoten, um das Layout aufzuteilen. Klicken Sie auf einen Knoten, um seine Attribute zu lesen.

✅ Checkpoint:Die dritte Spalte der ersten Abfrage ergibt in der Summe 12, 6 Milliarden, die zweite Abfrage gibt 8 Pfade zurück und auf dem Tab „Diagramm“ werden sie dargestellt.

13. (OPTIONAL) Mit der Grafik chatten

In diesem Schritt ist kein SQL erforderlich. BigQuery-Daten-Agents können einen Graph als Wissensquelle verwenden. Laut Dokumentation werden Messwerte für die Aggregation auf mehreren Ebenen verwendet. Mal sehen, ob das stimmt.

Vorbereitung:Für diesen Schritt muss die Gemini Data Analytics API für das Projekt aktiviert sein und Sie benötigen die Rolle „Gemini Data Analytics Data Agent Creator“. Die vom Agent ausgeführten Abfragen werden wie jede andere Abfrage zu BigQuery-Computing-Preisen abgerechnet.

1. KI-Agenten erstellen

👉 🌐 Console: Klicken Sie im BigQuery-Navigationsmenü auf der linken Seite auf Agents (Agents), dann auf Agent catalog (Agent-Katalog) und dann auf Create agent (Agent erstellen).

👉🌐 Console: Geben Sie Music graph agent in Name des Agenten und Folgendes in Beschreibung des Agenten ein:

Ask questions about labels, artists, songs and playlists in the music property graph.

👉🌐 Console: Klicken Sie unter Knowledge sources (Wissensquellen) auf Add source (Quelle hinzufügen). Maximieren Sie im Dialogfeld Quellen auswählen Ihr Projekt, maximieren Sie music, maximieren Sie Diagramme, setzen Sie ein Häkchen bei MusicGraph und klicken Sie auf Bestätigen.

👀 Die Schaltfläche Quelle hinzufügen wird ausgegraut. Ein Agent kann maximal ein Diagramm enthalten und Diagramme und Tabellen können nicht kombiniert werden.

👉 🌐 Console: Lassen Sie die Region so, wie sie im Diagramm festgelegt ist. Klicken Sie auf Speichern und dann auf Veröffentlichen. Klicken Sie im Bereich Veröffentlichungskanäle auf KI-Agent veröffentlichen und schließen Sie die Bestätigung.

2. Frage stellen

👉🌐 Konsole: Klicken Sie auf Unterhaltung erstellen. Eine Chatseite wird geöffnet. Geben Sie Folgendes in das Feld Frage stellen unten ein und drücken Sie die Eingabetaste:

For each label, show total streams and how many playlists their songs are on

👀 Der Agent gibt eine Tabelle und eine Zusammenfassung in einem Satz zurück:

label_name	total_streams	playlist_placements
Cymbal Records	5.100.000.000	8
Northwind Audio	4.500.000.000	2

5,1 Milliarden Niemand hat dem Agenten etwas über Fan-out gesagt und es ist nicht passiert.

3. Die geschriebene Abfrage lesen

👉🌐 Console: Klicken Sie im Navigationsmenü auf Jobs Explorer und dann auf den neuesten Job. Die Labels enthalten ca-bq-job: true und data-agent-id mit der ID Ihres Agenten. Die zugehörige Anfrage lautet:

SELECT
  Labels_label_name AS label_name,
  AGG(Songs_total_streams) AS total_streams,
  AGG(PlaylistEntries_placement_count) AS playlist_placements
FROM GRAPH_EXPAND("music.MusicGraph")
GROUP BY label_name
ORDER BY total_streams DESC

Es wurden GRAPH_EXPAND und AGG verwendet, da sich die Messwerte im gelesenen Schema befanden. Sie werden in der Beschreibung des Agents nicht erwähnt.

✅ Checkpoint:5, 1 Milliarden in der Chatantwort und AGG(...) im SQL-Code des Jobs.

14. Bereinigen

👉💻 Cloud Shell: Löschen Sie das Dataset, seine Tabellen und die Attributgrafik:

cd ~/bq-graph-measures-lab
./cleanup.sh

👀 Erwarte ✓ dropped YOUR_PROJECT_ID.music (tables and graph).

Wenn Sie den optionalen Daten-Agenten erstellt haben, löschen Sie ihn in der Konsole unter Agents → Agent catalog (Agents → Agentenkatalog). Wenn ./setup_project.sh ein Projekt nur für dieses Lab erstellt hat, ist es am einfachsten, das gesamte Projekt zu beenden. Die ID finden Sie in ~/project_id.txt.

15. Glückwunsch

Sie haben eine Zeile deklariert, MEASURE(SUM(streams)), und sie hat 12,6 Milliarden in 5,1 Milliarden geändert – für Sie und für jede Abfrage, die danach für diesen Graphen geschrieben wird, einschließlich der von einem Agenten geschriebenen.

Das haben Sie gelernt

• Ein Messwert ist ein Aggregat, das für einen Knoten deklariert wird, neben dem KEY, mit dem die Granularität festgelegt wird.
• GRAPH_EXPAND vereinfacht das Diagramm in eine breite Tabelle mit TableLabel_property Spalten.
• AGG ist die einzige Funktion, die einen Messwert liest. Das Typsystem erzwingt dies auf vier verschiedene Arten.
• Es sind sechs Aggregate verfügbar und AGG-Ergebnisse sind normale Werte, die Sie dividieren können.
• Wenn Sie GROUP BY ändern, wird die Frage noch einmal gestellt, ohne dass sich etwas an der Maßzahl ändert.
• GRAPH_EXPAND möchte einen Stamm, Many-to-One-Kanten und Kreuzungen, die zu Knoten hochgestuft werden.

Die Entscheidungstabelle

Symptom	Ursache	Korrigieren
Eine zu große Summe	SUM über einer aufgefächerten Spalte	einen Messwert deklarieren und mit AGG lesen
„expected MEASURE, found INT64“ (MEASURE erwartet, INT64 gefunden)	AGG in einer einfachen Spalte	SUM verwenden oder die Messung deklarieren
„Ausdrücke vom Typ MEASURE dürfen nicht zurückgegeben werden“	Messspalte ohne AGG	Zusammenfassen: AGG(...)
„nicht nach Elementtyp verfügbar“	In GQL referenziertes Measure	Analysiert nur Live-Veranstaltungen hinter GRAPH_EXPAND
GRAPH_EXPAND ignoriert eine Kante oder schlägt fehl	Kreuzung als Kante modelliert	Verknüpfungstabelle in einen Knoten umwandeln
Eine alte Nummer nach dem Ändern des Diagramms	im Cache gespeichertes Ergebnis	Deaktivieren Sie Im Cache gespeicherte Ergebnisse verwenden.

Was wir (absichtlich) nicht behandelt haben

Beschreibungen und Synonyme für Attribute · verifizierte Abfragen und Glossare für Data Agents · GQL über ein MATCH hinaus · Messwerte in mehreren Diagrammen Jedes ist ein eigenes Lab.

Weitere Informationen

• Mit Messwerten arbeiten
• Property-Graph erstellen und abfragen
• Konversationelle Analyse – Übersicht
• Das Lab-Repository – jede Abfrage in diesem Codelab, nach Schritt nummeriert