Legacy streaming inserts (tabledata.insertAll): send JSON rows via the REST API; rows are available for queries within seconds but appear in a streaming buffer that incurs separate storage billing and is not reflected in INFORMATION_SCHEMA row counts immediately.
Storage Write API (v1/v2 BigQuery Write API): use the committed stream type for at-least-once delivery or the pending stream type for exactly-once delivery; rows are written in binary protobuf format which is more efficient than JSON.
For exactly-once with the pending stream: write row batches with offset sequences, then call FinalizeWriteStream followed by BatchCommitWriteStreams; rows become visible only after commit, providing transactional guarantees.
Use the default stream of the Storage Write API for at-least-once high-throughput ingestion without stream management; it behaves similarly to legacy streaming inserts but uses the more efficient binary protocol.
Choose client library (Python, Java, Go) with the BigQuery Storage Write API client; avoid constructing raw gRPC calls manually as the client handles reconnection and offset tracking.
Legacy streaming inserts charge per GB inserted; Storage Write API charges per GB for data written beyond the free monthly quota; compare unit costs at your projected volume before selecting.
Known gotchas
Legacy streaming inserts do not guarantee deduplication across retries beyond a best-effort window; if exactly-once semantics are required, use the pending stream type of the Storage Write API.
Storage Write API pending streams must be explicitly finalized and committed; uncommitted pending streams that exceed the stream expiration time are automatically discarded, losing all buffered data.
Both APIs have per-project quotas on rows per second and concurrent connections; exceeded quotas return quota errors that must be retried with exponential backoff—failure to handle these causes data loss.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp