Auf dieser Seite wird erläutert, wie Sie mit der Methode tabledata.insertAll
Daten in BigQuery streamen.
Für neue Projekte empfehlen wir die Verwendung der BigQuery Storage Write API anstelle der Methode tabledata.insertAll
. Die Storage Write API bietet niedrigere Preise und robustere Features, einschließlich der Semantik genau einer Übermittlung. Wenn Sie ein vorhandenes Projekt von der Methode tabledata.insertAll
zur Storage Write API migrieren, empfehlen wir die Auswahl des Standardstreams. Die Methode tabledata.insertAll
wird weiterhin vollständig unterstützt.
Hinweis
Sorgen Sie dafür, dass Sie Schreibzugriff auf das Dataset haben, das die Zieltabelle enthält. Die Tabelle muss bereits vorhanden sein, bevor Sie damit beginnen, Daten hineinzuschreiben. Die einzige Ausnahme zu dieser Vorgehensweise sind Vorlagentabellen. Weitere Informationen zu Vorlagentabellen finden Sie unter Tabellen mithilfe von Vorlagentabellen automatisch erstellen.
Prüfen Sie die Kontingentrichtlinie für das Streaming von Daten.
-
Die Abrechnung für das Google Cloud-Projekt muss aktiviert sein.
Erteilen Sie IAM-Rollen (Identity and Access Management), die Nutzern die erforderlichen Berechtigungen zum Ausführen der einzelnen Aufgaben in diesem Dokument geben.
Das Streaming ist in der kostenlosen Stufe nicht verfügbar. Wenn Sie versuchen, das Streaming ohne aktivierte Abrechnung auszuführen, wird folgende Fehlermeldung angezeigt: BigQuery: Streaming insert is not allowed in the free tier.
Erforderliche Berechtigungen
Zum Streamen von Daten in BigQuery benötigen Sie die folgenden IAM-Berechtigungen:
bigquery.tables.updateData
(kann Daten in die Tabelle einfügen)bigquery.tables.get
(kann Tabellenmetadaten abrufen)bigquery.datasets.get
(kann Dataset-Metadaten abrufen)bigquery.tables.create
(erforderlich, wenn Sie die Tabelle mithilfe einer Vorlagentabelle automatisch erstellen)
Jede der folgenden vordefinierten IAM-Rollen enthält die Berechtigungen, die Sie benötigen, um Daten in BigQuery zu streamen:
roles/bigquery.dataEditor
roles/bigquery.dataOwner
roles/bigquery.admin
Weitere Informationen zu IAM-Rollen und Berechtigungen in BigQuery finden Sie unter Vordefinierte Rollen und Berechtigungen.
Daten in BigQuery streamen
C#
Bevor Sie dieses Beispiel ausprobieren, folgen Sie der C#-Einrichtungsanleitung in der BigQuery-Kurzanleitung zur Verwendung von Clientbibliotheken. Weitere Angaben finden Sie in der Referenzdokumentation zur BigQuery C# API.
Richten Sie zur Authentifizierung bei BigQuery die Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.
Go
Bevor Sie dieses Beispiel ausprobieren, folgen Sie der Go-Einrichtungsanleitung in der BigQuery-Kurzanleitung zur Verwendung von Clientbibliotheken. Weitere Angaben finden Sie in der Referenzdokumentation zur BigQuery Go API.
Richten Sie zur Authentifizierung bei BigQuery die Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.
Java
Bevor Sie dieses Beispiel ausprobieren, folgen Sie der Java-Einrichtungsanleitung in der BigQuery-Kurzanleitung zur Verwendung von Clientbibliotheken. Weitere Angaben finden Sie in der Referenzdokumentation zur BigQuery Java API.
Richten Sie zur Authentifizierung bei BigQuery die Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.
Node.js
Bevor Sie dieses Beispiel ausprobieren, folgen Sie der Node.js-Einrichtungsanleitung in der BigQuery-Kurzanleitung zur Verwendung von Clientbibliotheken. Weitere Angaben finden Sie in der Referenzdokumentation zur BigQuery Node.js API.
Richten Sie zur Authentifizierung bei BigQuery die Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.
PHP
Bevor Sie dieses Beispiel ausprobieren, folgen Sie der PHP-Einrichtungsanleitung in der BigQuery-Kurzanleitung zur Verwendung von Clientbibliotheken. Weitere Angaben finden Sie in der Referenzdokumentation zur BigQuery PHP API.
Richten Sie zur Authentifizierung bei BigQuery die Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.
Python
Bevor Sie dieses Beispiel ausprobieren, folgen Sie der Python-Einrichtungsanleitung in der BigQuery-Kurzanleitung zur Verwendung von Clientbibliotheken. Weitere Angaben finden Sie in der Referenzdokumentation zur BigQuery Python API.
Richten Sie zur Authentifizierung bei BigQuery die Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.
Ruby
Bevor Sie dieses Beispiel ausprobieren, folgen Sie der Ruby-Einrichtungsanleitung in der BigQuery-Kurzanleitung zur Verwendung von Clientbibliotheken. Weitere Angaben finden Sie in der Referenzdokumentation zur BigQuery Ruby API.
Richten Sie zur Authentifizierung bei BigQuery die Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.
Sie müssen das insertID
-Feld nicht ausfüllen, wenn Sie Zeilen hinzufügen.
Das folgende Beispiel zeigt, wie Sie vermeiden können, dass beim Streamen für jede Zeile eine insertID
gesendet wird.
Java
Bevor Sie dieses Beispiel ausprobieren, folgen Sie der Java-Einrichtungsanleitung in der BigQuery-Kurzanleitung zur Verwendung von Clientbibliotheken. Weitere Angaben finden Sie in der Referenzdokumentation zur BigQuery Java API.
Richten Sie zur Authentifizierung bei BigQuery die Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.
Python
Bevor Sie dieses Beispiel ausprobieren, folgen Sie der Python-Einrichtungsanleitung in der BigQuery-Kurzanleitung zur Verwendung von Clientbibliotheken. Weitere Angaben finden Sie in der Referenzdokumentation zur BigQuery Python API.
Richten Sie zur Authentifizierung bei BigQuery die Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.
Datums- und Uhrzeitdaten senden
Formatieren Sie für Datums- und Uhrzeitfelder die Daten in der Methode tabledata.insertAll
folgendermaßen:
Typ | Format |
---|---|
DATE |
Ein String im Format "YYYY-MM-DD" . |
DATETIME |
Ein String im Format "YYYY-MM-DD [HH:MM:SS]" . |
TIME |
Ein String im Format "HH:MM:SS" . |
TIMESTAMP |
Die Anzahl der Sekunden seit 01.01.1970 (die Unix-Epoche) oder ein String im Format "YYYY-MM-DD HH:MM[:SS]" . |
Bereichsdaten senden
Formatieren Sie die Daten in der tabledata.insertAll
-Methode für Felder vom Typ RANGE<T>
als JSON-Objekt mit den beiden Feldern start
und end
.
Fehlende oder NULL-Werte für die Felder start
und end
stehen für unbegrenzte Grenzen.
Diese Felder müssen dasselbe unterstützte JSON-Format vom Typ T
haben. Dabei kann T
DATE
, DATETIME
oder TIMESTAMP
sein.
Im folgenden Beispiel stellt das Feld f_range_date
eine RANGE<DATE>
-Spalte in einer Tabelle dar. Über die tabledata.insertAll
API wird eine Zeile in diese Spalte eingefügt.
{
"f_range_date": {
"start": "1970-01-02",
"end": null
}
}
Verfügbarkeit der Streamdaten
Daten stehen für Echtzeitanalysen mit GoogleSQL-Abfragen zur Verfügung, unmittelbar nachdem BigQuery eine tabledata.insertAll
-Anfrage erfolgreich bestätigt hat.
Kürzlich gestreamte Zeilen in eine nach Aufnahmezeit partitionierte Tabelle haben vorübergehend einen NULL-Wert für die Pseudospalte _PARTITIONTIME
. Für solche Zeilen weist BigQuery den endgültigen Nicht-NULL-Wert der Spalte PARTITIONTIME
im Hintergrund zu, normalerweise innerhalb weniger Minuten. In seltenen Fällen kann dies bis zu 90 Minuten dauern.
Einige kürzlich gestreamte Zeilen sind in der Regel für einige Minuten nicht zum Kopieren von Tabellen verfügbar. In seltenen Fällen kann dies bis zu 90 Minuten dauern. Wenn Sie herausfinden möchten, ob Daten zum Kopieren von Tabellen verfügbar sind, sehen Sie in der Antwort tables.get
nach, ob ein Abschnitt mit dem Namen streamingBuffer
vorhanden ist.
Wenn der Abschnitt streamingBuffer
nicht vorhanden ist, stehen Ihre Daten zum Kopieren zur Verfügung.
Sie können das Feld streamingBuffer.oldestEntryTime
auch verwenden, um das Alter von Datensätzen im Streaming-Zwischenspeicher zu ermitteln.
Best-Effort-Deduplizierung
Wenn Sie insertId
für eine eingefügte Zeile angeben, verwendet BigQuery diese ID, um Best-Effort-Deduplizierung für bis zu eine Minute zu gewährleisten. Das heißt, wenn Sie dieselbe Zeile mit derselben insertId
mehr als einmal innerhalb dieses Zeitraums in dieselbe Tabelle streamen, kann BigQuery die mehrfachen Vorkommen dieser Zeile deduplizieren und nur eines beibehalten.
Das System erwartet, dass Zeilen, die mit identischen insertId
bereitgestellt werden, identisch sind. Wenn zwei Zeilen identische insertId
haben, ist es nicht deterministisch, welche Zeile BigQuery speichert.
Das Entfernen von Duplikaten ist im Allgemeinen für Wiederholungsszenarien in einem verteilten System gedacht, wo bei bestimmten Fehlerbedingungen wie Netzwerkfehlern zwischen Ihrem System und BigQuery oder internen Fehlern in BigQuery keine Möglichkeit zum Ermitteln des Zustands eines Streaming-Insert besteht.
Verwenden Sie beim Wiederholen einer Insert-Anweisung dieselbe insertId
für denselben Satz Zeilen, damit BigQuery versuchen kann, Ihre Daten zu deduplizieren. Weitere Informationen finden Sie unter Fehlerbehebung bei Streaming-Insert-Anweisungen.
Die Deduplizierung von BigQuery gewährleistet keine bestimmte Qualität der Ergebnisse. Sie sollte daher nicht als Mechanismus verwendet werden, um Ihre Daten garantiert von Duplikaten zu bereinigen. Darüber hinaus kann BigQuery die Qualität der Best-Effort-Deduplizierung jederzeit beeinträchtigen, um eine höhere Zuverlässigkeit und Verfügbarkeit Ihrer Daten zu gewährleisten.
Wenn Sie höhere Anforderungen an die Deduplizierung Ihrer Daten haben, steht mit Google Cloud Datastore ein alternativer Dienst zur Verfügung, der Transaktionen unterstützt.
Best-Effort-Deduplizierung deaktivieren
Sie können die Best-Effort-Deduplizierung deaktivieren, wenn Sie das Feld insertId
für keine der eingefügten Zeilen ausfüllen. Dies ist die empfohlene Methode zum Einfügen von Daten.
Apache Beam und Dataflow
Verwenden Sie die Methode ignoreInsertIds()
, um die Best-Effort-Deduplizierung bei der Verwendung des BigQuery-E/A-Connectors für Java zu deaktivieren.
Duplikate manuell entfernen
Führen Sie den folgenden manuellen Prozess aus, damit nach dem Abschluss des Streamings keine doppelten Zeilen vorhanden sind:
- Fügen Sie Ihrem Tabellenschema die
insertId
als Spalte hinzu und nehmen Sie deninsertId
-Wert für jede Zeile in Ihre Daten auf. - Führen Sie nach dem Abschluss des Streamings die folgende Abfrage durch, um nach Duplikaten zu suchen:
#standardSQL SELECT MAX(count) FROM( SELECT ID_COLUMN, count(*) as count FROM `TABLE_NAME` GROUP BY ID_COLUMN)
Ist das Ergebnis größer als 1, existieren Duplikate. - Führen Sie die folgende Abfrage aus, um Duplikate zu entfernen. Geben Sie eine Zieltabelle an, lassen Sie große Ergebnisse zu und deaktivieren Sie die Ergebnisvereinfachung.
#standardSQL SELECT * EXCEPT(row_number) FROM ( SELECT *, ROW_NUMBER() OVER (PARTITION BY ID_COLUMN) row_number FROM `TABLE_NAME`) WHERE row_number = 1
Hinweise zur Abfrage zum Entfernen von Duplikaten:
- Die sicherere Strategie für die Abfrage zum Entfernen von Duplikaten ist die Anwendung auf eine neue Tabelle.
Alternativ kann sie mit der Schreibanordnung
WRITE_TRUNCATE
auf die Zieltabelle angewendet werden. - Die Abfrage zum Entfernen von Duplikaten fügt am Ende des Tabellenschemas eine
row_number
-Spalte mit dem Wert1
ein. In der Abfrage wird mit der AnweisungSELECT * EXCEPT
aus dem GoogleSQL die Spalterow_number
aus der Zieltabelle ausgeschlossen. Mit dem Präfix#standardSQL
wird der Google SQL-Dialekt für diese Abfrage aktiviert. Alternativ ist eine Auswahl nach Spaltennamen möglich, um diese Spalte auszulassen. - Zum Abfragen von Livedaten mit entfernten Duplikaten können Sie mithilfe der Abfrage zum Entfernen von Duplikaten auch eine Ansicht Ihrer Tabelle erstellen. Beachten Sie, dass die Abfragekosten für die Ansicht basierend auf den in der Ansicht ausgewählten Spalten berechnet werden. Dies kann zu hohen Werten für gescannte Byte führen.
In zeitpartitionierte Tabellen streamen
Wenn Sie Daten in eine zeitpartitionierte Tabelle streamen, hat jede Partition einen Streaming-Zwischenspeicher. Der Streaming-Zwischenspeicher bleibt erhalten, wenn Sie das Attribut writeDisposition
auf WRITE_TRUNCATE
setzen, um einen Lade-, Abfrage- oder Kopierjob auszuführen, der eine Partition überschreibt. Wenn Sie den Streaming-Zwischenspeicher entfernen möchten, prüfen Sie, ob er leer ist. Dazu rufen Sie tables.get
für die Partition auf.
Partitionierung nach Aufnahmezeit
Wenn Sie in eine nach Aufnahmezeit partitionierte Tabelle streamen, leitet BigQuery die Zielpartition aus der aktuellen UTC-Zeit ab.
Neu eintreffende Daten werden vorübergehend im Streaming-Zwischenspeicher der Partition __UNPARTITIONED__
abgelegt. Wenn genügend nicht partitionierte Daten vorhanden sind, partitioniert BigQuery die Daten in die richtige Partition. Es gibt jedoch keine SLA dafür, wie lange es dauert, bis Daten aus der Partition __UNPARTITIONED__
verschoben werden. Bei einer Abfrage können Daten im Streaming-Zwischenspeicher ausgenommen werden. Dazu werden die NULL
-Werte aus der Partition __UNPARTITIONED__
mit einer der Pseudospalten (je nach bevorzugtem Datentyp _PARTITIONTIME
oder _PARTITIONDATE
) herausgefiltert.
Wenn Sie Daten in eine täglich partitionierte Tabelle streamen, können Sie die Datumsinferenz überschreiben. Geben Sie dazu einen Partition-Decorator als Teil der insertAll
-Anfrage an. Füge den Decorator in den Parameter tableId
ein. Beispielsweise können Sie mit dem Partition-Decorator in die Partition für den 1. März 2021 der Tabelle table1
streamen:
table1$20210301
Mit einem Partition-Decorator können Sie in Partitionen mit einem Datum innerhalb der letzten 31 Tage in der Vergangenheit bzw. 16 Tage in der Zukunft streamen, abhängig vom aktuellen Datum und basierend auf der aktuellen UTC-Zeit. Wenn Sie in Partitionen mit Datumsangaben schreiben möchten, die außerhalb der zulässigen Grenzen liegen, verwenden Sie stattdessen einen Lade- oder Abfragejob, wie in Daten in partitionierten Tabellen anfügen oder überschreiben beschrieben.
Das Streaming mit einem Partitions-Decorator wird nur für täglich partitionierte Tabellen unterstützt. Für stündlich, monatlich oder jährlich partitionierte Tabellen wird es nicht unterstützt.
Zum Testen können Sie den Befehlszeilenbefehl bq insert
des bq-Befehlszeilentools verwenden.
Mit dem folgenden Befehl wird beispielsweise eine einzelne Zeile in eine Partition für das Datum 1. Januar 2017 ($20170101
) in eine partitionierte Tabelle mit dem Namen mydataset.mytable
gestreamt:
echo '{"a":1, "b":2}' | bq insert 'mydataset.mytable$20170101'
Spaltenpartitionierung nach Zeiteinheit
Sie können Daten in eine Tabelle streamen, die in einer DATE
-, DATETIME
oder TIMESTAMP
-Spalte partitioniert ist und zwischen fünf Jahren in der Vergangenheit und einem Jahr in der Zukunft liegt.
Daten außerhalb dieses Bereichs werden abgelehnt.
Wenn die Daten gestreamt werden, werden sie anfangs in der Partition __UNPARTITIONED__
abgelegt. Wenn genügend nicht partitionierte Daten vorhanden sind, partitioniert BigQuery die Daten automatisch neu und platziert sie in der entsprechenden Partition.
Es gibt jedoch kein SLA dafür, wie lange es dauert, bis Daten aus der Partition __UNPARTITIONED__
verschoben werden.
- Hinweis: Tägliche Partitionen werden anders als stündliche, monatliche und jährliche Partitionen verarbeitet. Nur Daten außerhalb des Datumsbereichs (letzte 7 Tage bis zukünftige 3 Tage) werden in die Partition UNPARTITIONED extrahiert, bis sie neu partitioniert sind. Bei einer stündlich partitionierten Tabelle werden die Daten immer in die Partition UNPARTITIONED extrahiert und später neu partitioniert.
Tabellen automatisch mithilfe von Vorlagentabellen erstellen
Vorlagentabellen bieten einen Mechanismus zum Aufteilen einer logischen Tabelle in viele kleinere Tabellen, um kleinere Datasets zu erstellen (z. B. nach Nutzer-ID). Für Vorlagentabellen gelten einige der unten beschriebenen Einschränkungen. Stattdessen wird dieses Verhalten mit partitionierten Tabellen und geclusterten Tabellen erreicht.
Zum Verwenden einer Vorlagentabelle über die BigQuery API fügen Sie zu Ihrer Anfrage insertAll
den Parameter templateSuffix
hinzu. Im bq-Befehlszeilentool muss dem Befehl insert
das Flag template_suffix
hinzugefügt werden. Findet BigQuery den Parameter templateSuffix
oder das Flag template_suffix
, wird die ausgewählte Tabelle als Basisvorlage behandelt. Es wird eine neue Tabelle erstellt, die das gleiche Schema wie die ausgewählte Tabelle hat und deren Name das angegebene Suffix enthält:
<targeted_table_name> + <templateSuffix>
Durch die Verwendung einer Vorlagentabelle kann der Overhead vermieden werden, der dabei entsteht, wenn jede Tabelle einzeln erstellt wird und für jede Tabelle das Schema angegeben werden muss. Damit BigQuery die neuen Tabellen für Sie erstellen kann, brauchen Sie nur eine einzige Vorlage zu erstellen und verschiedene Suffixe anzugeben. BigQuery speichert die Tabellen im selben Projekt und Dataset.
Tabellen, die mithilfe von Vorlagentabellen erstellt werden, stehen normalerweise innerhalb weniger Sekunden zur Verfügung. In seltenen Fällen kann es länger dauern, bis sie verfügbar sind.
Schema der Vorlagentabelle ändern
Wird das Schema einer Vorlagentabelle geändert, verwenden alle in Folge generierten Tabellen das aktualisierte Schema. Zuvor generierte Tabellen werden davon nur dann beeinflusst, wenn die vorhandene Tabelle über einen Streaming-Zwischenspeicher verfügt.
Wird das Vorlagentabellenschema in vorhandenen Tabellen, die einen Streaming-Zwischenspeicher haben, rückwärtskompatibel geändert, dann wird das Schema dieser aktiv gestreamten, generierten Tabellen ebenfalls aktualisiert. Wird das Vorlagentabellenschema jedoch auf nicht rückwärtskompatible Weise geändert, gehen alle zwischengespeicherten Daten verloren, die das alte Schema verwenden. Außerdem können Sie keine neuen Daten in vorhandene generierte Tabellen streamen, die das alte, nun jedoch nicht mehr kompatible Schema verwenden.
Warten Sie nach dem Ändern eines Vorlagentabellenschemas, bis die Änderungen wirksam sind, bevor Sie versuchen, neue Daten einzufügen oder eine Abfrage für die generierten Tabellen auszuführen. Anfragen zum Einfügen neuer Felder sollten innerhalb weniger Minuten möglich sein. Für Abfragen auf die neuen Felder könnte eine längere Wartezeit (bis zu 90 Minuten) erforderlich sein.
Wenn Sie das Schema einer generierten Tabelle ändern möchten, sollten Sie dies erst dann tun, wenn das Streaming über die Vorlagentabelle beendet wurde und die Antwort tables.get()
den Streaming-Statistik-Abschnitt der generierten Tabelle nicht mehr enthält, also keine Daten mehr in der Tabelle zwischengespeichert werden.
Partitionierte Tabellen und geclusterte Tabellen unterliegen nicht den vorherigen Einschränkungen und sind der empfohlene Mechanismus.
Vorlagentabellendetails
- Wert des Vorlagensuffixes
- Der Wert für
templateSuffix
(oder--template_suffix
) darf ausschließlich Buchstaben (a–z, A–Z), Zahlen (0–9) oder Unterstriche (_) enthalten. Die maximale gemeinsame Länge von Tabellenname und Tabellensuffix beträgt 1024 Zeichen. - Kontingent
Vorlagentabellen unterliegen den Einschränkungen von Streamingkontingenten. Ihr Projekt kann mit Vorlagentabellen bis zu 10 Tabellen pro Sekunde erstellen, ähnlich wie die
tables.insert
API. Dieses Kontingent gilt nur für Tabellen, die erstellt werden, nicht für Tabellen, die geändert werden.Wenn in Ihrer Anwendung mehr als 10 Tabellen pro Sekunde erstellt werden müssen, empfehlen wir die Verwendung von Clustertabellen. Beispiel: Sie können die Tabellen-ID mit hoher Kardinalität in die Schlüsselspalte einer einzelnen Clustering-Tabelle einfügen.
- Gültigkeitsdauer
Die generierte Tabelle übernimmt die Ablaufzeit aus dem Dataset. Wie gewöhnliche Streamingdaten können auch generierte Tabellen nicht sofort kopiert werden.
- Entfernen von Duplikaten
Das Entfernen von Duplikaten findet nur bei einheitlichen Referenzen auf eine Zieltabelle statt. Wenn Sie beispielsweise gleichzeitig sowohl mithilfe von Vorlagentabellen als auch mit einem regulären
insertAll
-Befehl in eine generierte Tabelle streamen, wird keine Deduplizierung zwischen den Zeilen durchgeführt, die von Vorlagentabellen und über einen reguläreninsertAll
-Befehl eingefügt wurden.- Aufrufe
Bei der Vorlagentabelle und den generierten Tabellen sollte es sich nicht um Ansichten handeln.
Fehler bei Streaming-Insert-Anweisungen beheben
In den folgenden Abschnitten wird die Fehlerbehebung beim Streamen von Daten in BigQuery mit der Legacy-Streaming-API erörtert. Weitere Informationen zum Beheben von Kontingentfehlern für Streaming-Insert-Anweisungen finden Sie unter Kontingentfehler für Streaming-Insert-Anweisungen.
HTTP-Fehlerantwortcodes
Wenn Sie einen HTTP-Fehlerantwortcode erhalten, z. B. bezüglich eines Netzwerkfehlers, lässt sich nicht feststellen, ob die Streaming-Insert-Anweisung erfolgreich war. Wenn Sie die Anfrage noch einmal senden, könnte eine Tabellenzeile doppelt auftreten. Um eine Duplizierung in Ihrer Tabelle zu verhindern, legen Sie beim Senden der Anfrage das Attribut insertId
fest. BigQuery verwendet das Attribut insertId
zur Deduplizierung.
Wenn Sie einen Berechtigungsfehler oder einen Fehler bezüglich eines ungültigen Tabellennamens oder eines überschrittenen Kontingents erhalten, werden keine Zeilen eingefügt und die gesamte Anfrage schlägt fehl.
HTTP-Erfolgsantwortcodes
Selbst wenn Sie einen HTTP-Erfolgsantwortcode erhalten, müssen Sie anhand des Attributs insertErrors
der Antwort prüfen, ob die Zeileneinfügungen durch BigQuery erfolgreich waren. Es kann nämlich sein, dass sie nur teilweise gelungen sind. Es kann eine der folgenden Szenarien geben:
- Alle Zeilen wurden erfolgreich eingefügt. Wenn das Attribut
insertErrors
eine leere Liste ist, wurden alle Zeilen erfolgreich eingefügt. - Einige Zeilen wurden erfolgreich eingefügt. Außer in Fällen, in denen in einer der Zeilen ein Schema nicht übereinstimmt, werden die im Attribut
insertErrors
angegebenen Zeilen nicht eingefügt und alle anderen Zeilen wurden erfolgreich eingefügt. Das Attributerrors
enthält detaillierte Informationen darüber, warum die entsprechenden Zeilen nicht eingefügt werden konnten. Das Attributindex
gibt den 0-basierten Zeilenindex der Anfrage an, auf die sich der Fehler bezieht. - Keine der Zeilen wurde erfolgreich eingefügt. Wenn BigQuery bei einzelnen Zeilen der Anfrage auf einen Schemakonflikt stößt, wird keine der Zeilen eingefügt und für jede Zeile wird ein
insertErrors
-Eintrag zurückgegeben, selbst für Zeilen ohne Schemakonflikt. Für Zeilen ohne Schemakonflikt wird ein Fehler angegeben, bei dem das Attributreason
aufstopped
gesetzt ist. Diese Zeilen können unverändert noch einmal gesendet werden. Fehlgeschlagene Zeilen enthalten detaillierte Informationen zum Schemakonflikt. Weitere Informationen zu den unterstützten Protokollpuffertypen für jeden BigQuery-Datentyp finden Sie unter Datentypkonvertierungen.
Metadatenfehler bei Streaming-Insert-Anweisungen
Da die Streaming-API von BigQuery auf hohe Einfügungsraten ausgelegt ist, sind Änderungen an den zugrunde liegenden Tabellenmetadaten beim Interagieren mit dem Streamingsystem letztendlich konsistent. In den meisten Fällen werden Metadatenänderungen innerhalb von Minuten wirksam. In diesem Zeitraum kann es jedoch vorkommen, dass API-Antworten den uneinheitlichen Zustand der Tabelle widerspiegeln.
Hier einige Szenarien:
- Schemaänderungen Das Ändern des Schemas einer Tabelle, die kürzlich Streaming-Insert-Anweisungen erhalten hat, kann zu Schemakonfliktfehlern führen, da das Streamingsystem die Schemaänderung unter Umständen nicht sofort übernimmt.
- Erstellen/Löschen einer Tabelle Beim Streamen an eine nicht vorhandene Tabelle wird eine Variante der
notFound
-Antwort zurückgegeben. Wenn Sie daraufhin die Tabelle erstellen, wird diese von nachfolgenden Streaming-Insert-Anweisungen unter Umständen nicht sofort erkannt. Ebenso kann das Löschen oder erneute Erstellen einer Tabelle dazu führen, dass für einen bestimmten Zeitraum Streaming-Insert-Anweisungen an die alte Tabelle gesendet werden und in der neu erstellten Tabelle nicht vorhanden sind. - Tabellenkürzung: Das Verkürzen der Daten einer Tabelle (z. B. mithilfe eines Abfragejobs, der für das Attribut "writeDisposition" den Wert "WRITE_TRUNCATE" verwendet) kann in gleicher Weise dazu führen, dass nachfolgende Insert-Anweisungen während des Konsistenzzeitraums entfernt werden.
Fehlende bzw. nicht verfügbare Daten
Streaming-Insert-Anweisungen werden vorübergehend im schreiboptimierten Speicher abgelegt, der andere Verfügbarkeitsmerkmale als ein verwalteter Speicher aufweist. Bestimmte Vorgänge in BigQuery interagieren nicht mit dem schreiboptimierten Speicher, z. B. Tabellenkopierjobs und API-Methoden wie tabledata.list
.
Aktuelle Streamingdaten sind nicht in der Zieltabelle oder -ausgabe enthalten.