Skip to main content

Kafka to BigQuery: Topics as Apache Iceberg

Kafka to BigQuery usually means a Kafka Connect cluster with the BigQuery sink, a Dataflow pipeline, or a consumer that writes files for bq load, and tables that only BigQuery can read. This guide takes a different route.

OLake Go reads the topics itself as a change data capture (CDC) stream and keeps one row per key. It writes the result once, as Apache Iceberg tables in a BigLake catalog, Google Cloud's Iceberg representational state transfer (REST) catalog, with the files in your own Cloud Storage bucket.

BigQuery queries the tables through the catalog with a four-part name, with no dataset to create and no external table to declare. Nothing else is in the path: no Kafka Connect, no Dataflow, no load job. DuckDB and Spark read the same tables through the same catalog.

By Shubham Satish BaldavaUpdated October 30, 2026

Key takeaways

  • OLake Go turns Kafka topics into Iceberg tables in a BigLake catalog: each sync reads from the last committed offset and upserts messages on a deduplication key, so a repeated key updates its row instead of adding one.
  • BigQuery reads the catalog as a data source. Every change a sync commits is visible on the next SELECT, with no refresh and no load job.
  • The same tables, written once by OLake Go, are also queryable from DuckDB and Spark. In the run on this page all three engines returned identical rows.

The short answer. To stream Kafka to BigQuery as Iceberg, run OLake Go with the Kafka cluster as the source and a BigLake catalog with a Cloud Storage bucket as the destination, with BigQuery as the target query engine.

Put each topic in CDC Only mode with Upsert on a deduplication key. The first sync reads every retained message; every later sync reads only the messages after the committed offsets. BigQuery, DuckDB and Spark then query the same Iceberg tables, with no second copy.

How Kafka messages reach BigQuery here​

There is no separate snapshot phase, because the topic is the history. The first sync runs with a new consumer group, which has no committed offset, so it reads every message the broker still holds: on this page all 48.

OLake Go commits the Iceberg snapshot first and the consumer-group offsets second. A sync that fails mid-way therefore re-reads its messages on the next run. In Upsert mode the re-read is harmless; in Append mode it duplicates those rows.

Every later sync resumes from the committed offsets and reads only what arrived since. In Upsert mode a message whose deduplication key already exists in the table retires the old row with a positional delete and writes the new one.

A key seen for the first time becomes a new row. In Append mode every message is a row, which suits event logs that are never corrected.

One thing to keep an eye on: retention is the replay window. Kafka deletes messages past retention.ms, and OLake Go cannot read what is gone.

A job paused longer than the retention of its topics silently misses the expired messages. Set retention from your longest tolerable pause, not from disk size.

What you need​

  • A Kafka cluster on version 2.4 or later that OLake Go can reach, with JSON messages (or Avro plus a schema registry) on the topics you want. Confluent Cloud, Amazon Managed Streaming for Apache Kafka (MSK), Redpanda and self-hosted Kafka all work; the run on this page used a single-node Apache Kafka 4.3.1 in KRaft mode in Docker.
  • A field that identifies each entity in every message, such as id, when you want one row per key. Without it, run the topic in Append mode.
  • A Google Cloud project with the BigLake API enabled, a Cloud Storage bucket for the files, and a service account for OLake Go with the BigLake Editor role on the project and Storage Object User on the bucket. The run on this page used a bucket in us-central1.
  • BigQuery in the same project. Queries run in the bucket's region, and the account running them needs the BigQuery Job User role plus read access to the catalog.
  • OLake UI from the Docker Compose install, on OLake UI v0.7.1 or later with the OLake Go Kafka source on v0.12.1 or later, which is when Upsert mode for Kafka arrived. The run on this page used OLake Go v1.1.0.
  • Docker, and about 30 minutes.

Step 1: Prepare the Kafka topics​

Most readers point OLake Go at topics they already have. If you want to follow along with the exact data from this page, produce messages shaped like these first:

The two sample topics used on this page

Both topics have one partition and carry JSON values keyed by the entity id. The scripts ship with Apache Kafka under bin/; on a managed cluster, run them from a client machine that can reach the brokers with the cluster's bootstrap string.

Sample topics and messages
kafka-topics.sh --bootstrap-server localhost:9092 --create --topic customers --partitions 1
kafka-topics.sh --bootstrap-server localhost:9092 --create --topic orders --partitions 1
# key<TAB>value, one message per line
printf '1\t{"id":1,"name":"Aarav Mehta","email":"aarav@example.com","city":"Mumbai","tier":"gold","created_at":"2026-10-29T15:22:04+00:00","updated_at":"2026-10-29T15:22:04+00:00"}\n' \
  | kafka-console-producer.sh --bootstrap-server localhost:9092 --topic customers --property parse.key=true --property key.separator=$'\t'
printf '1\t{"id":1,"customer_id":2,"product":"Headphones","amount":99.19,"status":"shipped","created_at":"2026-10-29T15:22:04+00:00","updated_at":"2026-10-29T15:22:04+00:00"}\n' \
  | kafka-console-producer.sh --bootstrap-server localhost:9092 --topic orders --property parse.key=true --property key.separator=$'\t'
# Then produce whatever you like. This page started with 8 customers and 40 orders.

Kafka is already a change stream, so there is no log to switch on. OLake Go reads each topic from its retained offsets and commits the position it reached in a consumer group. Four things must be in place before the first sync.

RequirementValueWhy it matters
Message formatJSON values, or Avro with a schema registryOLake Go turns each message into a row. Anything else (Protobuf, plain text) cannot be mapped to columns.
A stable field per entityFor example id in the payload, or the message keyUpsert mode needs a deduplication key to know which earlier row a message replaces. Keep it in every message and never change it.
A consumer group for OLake Go onlyOne group per jobOLake Go stores its offsets there. Sharing the group with another consumer, or between two jobs, moves offsets under its feet.
Retention longer than your longest pauseFor example 7 daysKafka deletes messages past the retention limit. A job paused longer than that cannot read them, and they are gone.

If the cluster enforces access control lists (ACLs), the user OLake Go connects with needs Read and Describe on the topics and Read on its consumer group. This is what the setup looked like for the run on this page, with the scripts that ship with Apache Kafka; Redpanda's rpk topic create and rpk security acl create do the same:

On the Kafka cluster
# 1. The topics, with retention long enough to cover a pause
kafka-topics.sh --bootstrap-server localhost:9092 --create --topic customers --partitions 1 --config retention.ms=604800000
kafka-topics.sh --bootstrap-server localhost:9092 --create --topic orders --partitions 1 --config retention.ms=604800000

# 2. If ACLs are on: a principal for OLake Go (one command per resource type)
kafka-acls.sh --bootstrap-server localhost:9092 --add --allow-principal User:olake \
--operation Read --operation Describe --topic customers --topic orders
kafka-acls.sh --bootstrap-server localhost:9092 --add --allow-principal User:olake \
--operation Read --group olake_<job_name>

Each message needs the entity's identifier in its value, and the key is the natural place to repeat it. A record for the sample customers topic looks like this, with _kafka_key set to the same id:

One message on the customers topic (key: 3)
{"id": 3, "name": "Liam Carter", "email": "liam@example.com", "city": "Austin", "tier": "gold",
 "created_at": "2026-10-29T15:22:04+00:00", "updated_at": "2026-10-29T15:22:04+00:00"}
Retention is your replay window

A topic with retention.ms of one day keeps one day of messages. If the job is paused for two, the first day is gone before OLake Go reads it, and nothing in the destination tells you. Set retention from the longest pause you can tolerate, and alert when a job has not run for a good fraction of it.

Step 2: Set up the BigLake catalog​

BigQuery reads Iceberg tables through a catalog. BigLake is the one this page uses: it is Google Cloud's Iceberg REST catalog, OLake Go creates a namespace per job in it, and the files sit in your Cloud Storage bucket.

BigQuery, DuckDB and Spark all read from the same catalog. BigQuery treats it as a data source in the project, so a table OLake Go commits is queryable on the next statement.

CatalogOLake Go writesBigQuery readsVerified on this page
BigLake (Google Cloud Lakehouse)YesYes: native: namespaces map to BigQuery datasetsYes, end to end

BigLake is the Iceberg REST catalog built into Google Cloud's Lakehouse. OLake Go talks to it at https://biglake.googleapis.com/iceberg/v1/restcatalog, the table files land in a Cloud Storage bucket you own, and BigQuery reads the tables without any registration step. Writing to BigLake needs OLake Go 0.9.1 or later.

Everything below happens in the Google Cloud console, in the project that will hold the tables.

  1. Enable the API. Open APIs and services, then Enable APIs and services, and enable the BigLake API. BigQuery and Cloud Storage are on by default in most projects.
  2. Create a bucket. In Cloud Storage, create a bucket in the region where BigQuery will run the queries (us-central1 on this page). The bucket name becomes the catalog name in BigQuery, so pick one you are happy to type in SQL.
  3. Create a service account for OLake Go. In IAM and Admin, Service Accounts, create one (for example olake-biglake). Then grant it two roles: BigLake Editor on the project (IAM, Grant access, the service account as principal) and Storage Object User on the bucket (the bucket's Permissions tab).
  4. Download a JSON key. On the service account's Keys tab, Add key, Create new key, JSON. The file downloads once; OLake Go asks for its contents.
Google Cloud console IAM Grant access panel with the OLake service account as principal and the BigLake Editor role selected
The project-level grant: the service account OLake Go runs as, with the BigLake Editor role.

There is no catalog to create. BigLake creates a single-bucket catalog named after the bucket the first time OLake Go calls the endpoint with gs://<bucket> as the catalog path, in the default end-user credential mode, where every client brings its own storage credentials. The catalog shows up under BigLake, Catalogs after the first connection test.

Two things to know before the first sync:

  • The service account's BigLake Editor role is what lets OLake Go create namespaces and commit tables. Storage Object User on the bucket is what lets it write the Parquet and metadata files. Missing either one fails the connection test with a 403 from biglake.googleapis.com or from storage.googleapis.com, which tells you which grant is missing.
  • Leave the catalog in end-user mode. OLake Go 1.1.0 does not send the X-Iceberg-Access-Delegation header, so a catalog switched to vended credentials rejects its commits (see troubleshooting). Readers that want short-lived tokens from the catalog can switch the mode later with gcloud beta biglake iceberg catalogs update <bucket> --credential-mode=vended-credentials, after setting rest_access_delegation in a CLI config.
Google Cloud console Create private key dialog for the OLake service account with the JSON key type selected
The JSON key for the service account. The console downloads it once; its contents go into the OLake Go destination form.

Step 3: Connect Kafka to OLake Go​

  1. In the OLake UI, open Sources and click Create Source. Pick Kafka as the connector, give the source a name and keep the OLake Go version on the latest release.
  2. The Enable CDC toggle under Change data capture (CDC) reads not supported for Kafka and stays off. That is expected: the topic is the change stream, and the job's CDC Only sync mode reads it.
  3. Under Connection details, fill in Bootstrap Servers (host:port, comma-separated for several brokers), a Consumer Group ID for this job only, and a Topic Pattern regular expression that matches only the topics you want. Pick the Security Protocol the cluster uses: PLAINTEXT, SASL_PLAINTEXT or SASL_SSL, with the SASL mechanism and credentials when needed. Turn on Use Schema Registry only for Avro topics.
  4. Leave Additional configuration at its defaults, or set Max Threads to the number of partitions you want read in parallel.
  5. Click Set up source. OLake Go pings the brokers. Topics are matched against the pattern at discovery, when the job is created; if the pattern matches nothing, the Streams page comes up empty and the sync log names every topic it skipped.

Here is the source form from the run on this page. Kafka ran in another container, so the bootstrap server is host.docker.internal:19092; the topic pattern ^(customers|orders)$ keeps discovery to the two sample topics.

OLake UI Edit source form for Kafka on OLake Go v1.1.0 with the Enable CDC toggle marked not supported, bootstrap server host.docker.internal:19092, consumer group olake_kafka_to_snowflake, topic pattern ^(customers|orders)$, security protocol PLAINTEXT, schema registry off, max threads 2
The Kafka source in OLake UI: bootstrap server, a consumer group for this job only, and a topic pattern that matches the two sample topics.

Set up source pings the brokers before anything is saved. The consumer group is created on the first sync; it does not need to exist yet.

The full field reference, including SASL and schema-registry options, is on the Kafka connector page.

Step 4: Configure the Iceberg destination​

  1. Open Destinations and click Create Destination.
  2. Pick Apache Iceberg as the connector and BigLake as the catalog type.
  3. Fill in the fields below. The catalog path is the bucket, with no folder after it. Paste the whole service account JSON file into the credentials field.
  4. Click Create. OLake Go calls the BigLake endpoint, creates the catalog if it is the first contact, and writes and drops a test table in the bucket.

Here is the destination form from the run on this page. It holds the BigLake endpoint, the bucket as the catalog path, the service account JSON and the project ID.

OLake UI Edit destination form for Apache Iceberg with catalog type Big Lake, REST catalog URI https://biglake.googleapis.com/iceberg/v1/restcatalog, BigLake catalog path gs://olake-x2y-lab-bq, authentication type GCP and the project ID oauth-361809
The BigLake destination in OLake UI: the endpoint, the bucket as catalog path, GCP authentication and the project ID.
FieldValue on this pageWhat it is
REST Catalog URIhttps://biglake.googleapis.com/iceberg/v1/restcatalogThe BigLake Iceberg REST endpoint. The same for every project and region.
BigLake Catalog Pathgs://<bucket>The bucket that holds the tables. The bucket name is also the catalog name BigQuery uses. Bucket root only; a folder after it is not supported.
Authentication TypeGCPGoogle OAuth through the service account. The only choice for BigLake.
GCP Service Account JSONthe key file contentsUsed for both the catalog calls and the Cloud Storage writes.
Catalog Nameolake_icebergA label OLake Go uses in its own logs. Lowercase letters and underscores only.
GCP Auth Scopeshttps://www.googleapis.com/auth/cloud-platformThe OAuth scope on the token. Leave the default.
GCP Project IDthe project IDRoutes and bills the catalog calls. Required for multi-bucket catalogs, harmless to set for a single bucket.
Enable Arrow WritesoffKeeps the default Java writer, which is what this page was tested with.

Step 5: Create the job and run the first sync​

This job lists BigQuery, Spark and DuckDB as target query engines. Kafka streams offer one sync mode, CDC Only, and the upsert type on this job is Positional Deletes, which all three engines read. The decisions on the Streams page are the ingestion mode and the deduplication key.

From OLake Go v1.1.1 and OLake UI v0.8.2 Kafka upserts can also write deletion vectors.

  1. Open Jobs and click Create Job. Give it a name and a schedule. Every Day at a fixed hour, or a cron expression, both work; the schedule is how often the change stream is drained, not how often a full copy runs.
  2. Select the source and the destination you created.
  3. Under Advanced Settings, set Target Query Engines to Google BigQuery, Apache Spark and DuckDB. OLake Go then resolves an Iceberg delete format every one of those engines can read, so you never pick one by hand.
  4. Click Next. OLake Go discovers the topics and opens the Streams page.
  5. Tick the topics to replicate. For each one, set the sync mode to CDC Only and the ingestion mode to Upsert. Under Dedup Keys, pick id: that is the field OLake Go uses to match a later message to the row it replaces. Leave the Upsert Type as OLake Go resolved it (Positional Deletes in the run on this page).
  6. Click Create Job, then open the job's menu and choose Sync Now for the first run.
OLake UI Streams Selection page with the topics namespace, customers and orders selected, sync mode CDC Only, ingestion mode Upsert, dedup key id and upsert type Positional Deletes on Iceberg format version V2
Each topic: CDC Only, Upsert on the id field, and Positional Deletes as the upsert type. The Iceberg DB name at the top is editable.
OLake UI Job Logs and History for kafka_to_bigquery showing two completed syncs, the first in 44 seconds and the second in 53 seconds
Job history: the 44 s first read of both topics, then the 53 s sync of the new messages.

On this page the first run read 8 customer and 40 order messages (48 records, 9.00 KB) and finished in 44 seconds, container start included. OLake Go names the BigLake namespace after the job and the source namespace.

The namespace for every Kafka topic is topics, so kafka_to_bigquery produced kafka_to_bigquery_topics. The Iceberg DB field at the top of the Streams page changes it before the first sync.

Step 6: Query the tables in BigQuery​

There is no registration step and no external table to declare. A BigLake catalog is a BigQuery data source in the same project: the catalog is the bucket name, the namespace OLake Go created is the dataset, and the tables are the tables. Address them with the four-part name in backticks, and run the query in the bucket's region.

BigQuery SQL editor (location: the bucket region)
SELECT id, name, city, tier
FROM `<project-id>.<bucket>.kafka_to_bigquery_topics.customers`
ORDER BY id;

SELECT status, count(*) AS n, round(sum(amount), 2) AS total
FROM `<project-id>.<bucket>.kafka_to_bigquery_topics.orders`
GROUP BY status ORDER BY status;

From a terminal, bq query --project_id=<project-id> --location=<region> --use_legacy_sql=false "<sql>" runs the same statements. Set the location to the bucket's region (us-central1 on this page); the default US multi-region returns Not found: Dataset for a catalog whose bucket is regional.

OLake Go adds four columns to every table: _olake_id (a hash of the primary key), _op_type, _olake_timestamp and _cdc_timestamp. _op_type is r for a row from the first snapshot, c for an insert, u for an update and d for a delete. Filter them out of dashboards, or use them to see when a row last changed.

BigQuery reads Iceberg v2 tables with positional and equality deletes, which is why the job on this page uses positional deletes. Deletion vectors on v3 tables are a preview feature in BigQuery with per-query limits, so keep the job off deletion vectors while BigQuery is a reader.

BigQuery SQL editor in the Google Cloud console running the customers query on the olake-x2y-lab-bq catalog and returning 10 rows with id, name, city and tier
BigQuery reading the customers table through the BigLake catalog after the second sync: 10 rows, one per key.

Step 7: Produce new messages and sync again​

To see the change path work, the run on this page produced 12 more messages after the first sync. Seven carry new keys; five repeat an existing key with a changed value.

Messages produced between the two syncs (key, then value)
# customers: two new keys, two repeated keys
9   {"id":9,"name":"Maya Patel","email":"maya@example.com","city":"Pune","tier":"silver", ...}
10  {"id":10,"name":"Lucas Silva","email":"lucas@example.com","city":"São Paulo","tier":"bronze", ...}
3   {"id":3,"name":"Liam Carter","email":"liam@example.com","city":"Austin","tier":"gold", ...}
8   {"id":8,"name":"Zara Ali","email":"zara@example.com","city":"Abu Dhabi","tier":"silver", ...}
# orders: five new keys (41 to 45), three repeated keys (1, 4, 7) with status "delivered"
41  {"id":41,"customer_id":9,"product":"Laptop","amount":1299.0,"status":"placed", ...}
1   {"id":1,"customer_id":2,"product":"Headphones","amount":99.19,"status":"delivered", ...}

The second sync read 12 records (2.26 KB) from the two topics and finished in 53 seconds end to end. For customers that meant one new data file with 4 rows: the 2 new keys plus the new versions of the 2 repeated keys.

One small positional delete file retires the 2 old versions. OLake Go's commit report in the sync log shows it directly: addedDataFiles=1, addedRecords=4, addedPositionalDeleteFiles=1, addedPositionalDeletes=2. The orders table has the same shape with 8 rows and 3 deletes.

OLake UI sync log filtered to the Iceberg commit report, showing addedDataFiles 1, addedPositionalDeleteFiles 1, addedRecords and addedPositionalDeletes for the second sync
The second sync in the OLake UI log: one data file and one positional delete file per topic.

BigQuery shows the result on the next query, with no refresh. Liam Carter is gold, Zara Ali moved to Abu Dhabi, and the two new customers are there, with still one row per key. The _op_type column shows how each row arrived (c for a first-seen key, u for a repeated key) and _kafka_offset shows which message it came from.

Schema changes. When a new field appears in the messages, OLake Go adds it as a column on the next sync and commits the new schema to BigLake in the same commit. BigQuery shows the column on the next query.

A field whose type changes in an incompatible way fails the sync rather than corrupt the table. Full rules are on the schema evolution page.

Query the same tables from DuckDB and Spark​

This is the point of writing Iceberg instead of loading BigQuery tables. Nothing is exported, copied or refreshed: both engines read the files OLake Go wrote, through the same BigLake catalog.

DuckDB attaches BigLake as an Iceberg REST catalog with a Google access token. The catalog on this page is in end-user credential mode, so DuckDB also needs its own Cloud Storage credentials to read the files: an HMAC key for the service account (Cloud Storage, Settings, Interoperability, Create a key for a service account).

DuckDB 1.5.5
INSTALL iceberg; LOAD iceberg;
INSTALL httpfs;  LOAD httpfs;

-- gcloud auth print-access-token, or a token minted for the service account
CREATE SECRET biglake_catalog (
TYPE iceberg,
TOKEN '<access token>',
EXTRA_HTTP_HEADERS MAP {'x-goog-user-project': '<project-id>'}
);
-- the HMAC key pair for the bucket
CREATE SECRET biglake_files (TYPE gcs, KEY_ID '<hmac access id>', SECRET '<hmac secret>');

ATTACH 'gs://<bucket>' AS biglake (
TYPE iceberg,
ENDPOINT 'https://biglake.googleapis.com/iceberg/v1/restcatalog',
SECRET biglake_catalog
);

SHOW ALL TABLES;
SELECT id, name, city, tier FROM biglake.kafka_to_bigquery_topics.customers ORDER BY id;

The access token lives an hour; CREATE OR REPLACE SECRET with a fresh one when a query fails with 401. If the catalog is in vended-credentials mode instead, drop the gcs secret and add ACCESS_DELEGATION_MODE 'vended_credentials' to the ATTACH: BigLake then hands DuckDB a short-lived storage token per table. DuckDB reads positional deletes, so the rows match BigQuery after every sync.

Google Cloud console Cloud Storage Interoperability settings with the Select a service account dialog, the OLake service account selected and the Create key button
The key for DuckDB: Cloud Storage, Settings, Interoperability, then a key for the same service account OLake Go uses.

DuckDB 1.5.5 returned the same 10 customers and the same orders roll-up as BigQuery in the run on this page. It read the current metadata file of each table through the catalog and the data files through the hash-based message authentication code (HMAC) key.

An orders roll-up matched the latest message per key in all three engines. It gave 16 delivered orders for 8659.68, 18 placed for 10522.26, 11 shipped for 6397.25.

Data types: Kafka JSON to Iceberg to BigQuery​

A Kafka message has no schema of its own, so OLake Go infers one from a sample of messages at discover time and maps it to Iceberg types.

BigQuery then maps Iceberg types to its own when it reads the catalog. Four Kafka columns are added to every row. This is what the run on this page produced:

In the JSON valueIceberg (written by OLake Go)BigQuery showsNotes
Integer ("id": 3)longINT64
Decimal ("amount": 99.19)doubleFLOAT64The orders.amount sums on this page matched the messages to the cent in every engine; round at query time when you need exact decimal arithmetic.
ISO 8601 timestamp string ("2026-10-29T15:22:04+00:00")timestamptz (UTC)TIMESTAMPStrings that parse as timestamps are stored as timestamps and shown as UTC instants.
Other stringsstringSTRING
_kafka_keystringSTRINGThe message key, base64-encoded (3 arrives as Mw==).
_kafka_partition, _kafka_offsetint, longINT64Where the row's latest message sat on the topic.
_kafka_timestamptimestamptzTIMESTAMPThe message timestamp: produce time or broker append time, depending on the topic's message.timestamp.type.

Types on the left come from the Kafka connector reference. The BigQuery side comes from the BigQuery Iceberg tables page (checked 2026-10-30) and from the table schemas of this run. With Normalization on, which is the default, top-level fields become columns.

Cost and maintenance​

  • Storage is your bucket: you pay Cloud Storage rates for the Parquet and delete files. The BigLake catalog itself has no per-table charge.
  • Compute. OLake Go runs wherever you run Docker. BigQuery bills on-demand queries by bytes scanned, or by slot time on an edition; a query over the catalog reads the Parquet files in the bucket, so filter on the columns you need. DuckDB and Spark cost whatever machine they run on.
  • Maintenance. A topic synced every minute adds a small file and a delete file per run, and BigLake keeps every snapshot OLake Go commits in the table's metadata.json. BigLake rejects a metadata.json above 1 MB, which a busy table reaches after a few thousand syncs. Expire old snapshots and compact on a schedule with OLake Fusion or with Spark's expire_snapshots and rewrite_data_files procedures through the same catalog.
  • Retention disk. Seven days of a busy topic is real disk on the brokers. Size for it, or shorten retention once the job runs reliably every hour.
  • Key rotation. The service account key is what OLake Go writes with. Rotate it on your schedule from the service account's Keys tab and paste the new JSON into the destination.

Troubleshooting​

1. The source test cannot reach the brokers​

failed to ping kafka brokers: unable to dial: dial tcp 192.168.65.254:19999: connect: connection refused

The address in Bootstrap Servers is not reachable from inside the OLake Go container. For a broker on the same machine use host.docker.internal, not localhost.

Make sure the broker also advertises a listener the container can resolve; Kafka's advertised.listeners decides that. On a managed cluster, run OLake Go on a network that can reach the brokers' advertised addresses.

2. The Streams page is empty​

Skipping topic customers (does not match topic_pattern: ^nothing_here$)

The topic pattern is a full regular expression anchored by you. ^orders$ matches one topic, ^orders matches every topic that starts with it, and a pattern with a typo matches nothing. Fix the pattern on the source and run discovery again; the sync log names every topic it skipped and why.

3. The destination test fails on a catalog in vended-credentials mode​

failed to test destination: failed to create or get table: rpc error: code = Internal desc = Failed to process request: Malformed request: X-Iceberg-Access-Delegation header must be present and contain `vended-credentials` when credential mode is `CREDENTIAL_MODE_VENDED_CREDENTIALS`.

The catalog was created, or switched, with --credential-mode=vended-credentials, and OLake Go 1.1.0 does not send the header BigLake wants in that mode (olake#1369). Switch the catalog back with gcloud beta biglake iceberg catalogs update <bucket> --credential-mode=end-user, which is the default for a catalog OLake Go created itself. With the CLI, "rest_access_delegation": "vended-credentials" in destination.json makes the same test pass; the UI has no field for it yet.

4. BigQuery cannot find the dataset​

Not found: Dataset <project>:<bucket>.kafka_to_bigquery_topics was not found in location US

The query ran in a location other than the bucket's region. Set the query location to the bucket's region in the editor's More, Query settings panel, or pass --location=<region> to bq. Leaving the location unset lets BigQuery pick it from the table.

5. A sync ends early after a consumer-group rebalance​

A rebalance in OLake Go's consumer group, usually because another process joined it, makes the sync stop cleanly with what it has read. Nothing is lost: the messages read so far are committed, and the next sync resumes from the committed offsets.

Give each job its own consumer group and never point another consumer at it. If a group's offsets are damaged, create the job again with a new group id. The group name cannot be edited on an existing source in the UI.

How this compares with other ways to move Kafka data to BigQuery
MethodFreshnessUpdates and deletesWhere the data landsWhat you run
Dataflow Kafka to BigQuery templateSeconds, streamingNo; appends through the Storage Write APINative BigQuery tables; BigQuery is the only readerA Dataflow streaming job per topic set, billed per vCPU-hour
Kafka Connect with the BigQuery sinkSeconds to minutesUpsert and delete in its upsert mode, with an intermediate table and mergeNative BigQuery tablesA Kafka Connect cluster and the sink connector
Confluent Cloud managed BigQuery sinkSeconds to minutesUpsert and delete in its upsert modeNative BigQuery tablesNothing; a managed connector billed per task and per GB
Managed ELT (Fivetran, Estuary, Airbyte Cloud)Minutes, by planVaries by toolBigQuery tables, a second copy you pay to move and storeNothing; priced per row, per GB or per connector
OLake Go to Iceberg on BigLake (this guide)On a schedule down to one minuteYes, upsert on a key with Iceberg row-level deletesApache Iceberg tables that BigQuery, Spark, DuckDB, Trino and Flink all readOne Docker Compose stack, open source; your bucket plus your own compute

The Dataflow template is the simpler choice when you need seconds of latency, append-only is fine and BigQuery is the only reader. Writing Iceberg once, with one row per key, avoids paying to move and store a second copy. That matters as soon as Spark, DuckDB or a notebook needs the same rows, or you want to own the files.

When not to use this​

  • You need seconds of latency. OLake Go drains the topic on a schedule, one minute at the shortest. Use a streaming Dataflow job or the Storage Write API for a continuous feed.
  • Messages are not JSON or Avro. Protobuf, plain text and binary payloads cannot be mapped to columns.
  • Deletes must propagate and the key is in the payload. Tombstones delete a row only when _kafka_key is the single deduplication key; on a topic whose dedup key is a payload field, a tombstone fails the sync. Key the messages by the entity id and use the key as the deduplication key, or run the topic in Append mode and filter deletes downstream.
  • The partition count will change while the job runs in Upsert mode. The same key would then hash to a different partition, and concurrent partition readers could leave a stale row behind. Finish the repartition, then create the job.

FAQs​

How do I get Kafka topics into BigQuery without Kafka Connect or Dataflow?

Run OLake Go (open source, Apache 2.0) with the Kafka cluster as the source and a BigLake catalog with a Cloud Storage bucket as the Iceberg destination. Each sync reads the topics from the last committed offset, upserts the messages on a deduplication key, and commits Iceberg tables that BigQuery queries through the catalog with a four-part name. No Kafka Connect cluster, no Dataflow job and no load job sit in the path.

Does OLake Go keep one row per key, or one row per message?

One row per key when the stream runs in Upsert mode with a deduplication key, which is what this page uses: a later message with the same key replaces the earlier row. In Append mode every message becomes a row, with the Kafka partition, offset and timestamp kept in columns, which suits event logs that are never updated.

Where does the first sync start reading a Kafka topic?

A new consumer group has no committed offset, so the first sync reads every message the broker still retains in every partition of every selected topic. The run on this page read all 48 messages on its first sync. Each later sync resumes from the offsets OLake Go committed in its consumer group, so retention is the replay window.

Does BigQuery read Iceberg tables with row-level deletes?

Yes. BigQuery reads Iceberg v2 merge-on-read tables with positional and equality deletes. The run on this page used positional deletes, which is also the only upsert type OLake Go offers for Kafka, and BigQuery returned one row per key after the repeated messages.

Do I need to create a BigQuery dataset or an external table?

No. A BigLake catalog is a data source BigQuery reads directly: the bucket name is the catalog, the namespace OLake Go creates is the dataset, and the tables appear under it. The query uses the four-part name project.bucket.namespace.table, and there is no CREATE EXTERNAL TABLE and no metadata refresh.

Which message formats does OLake Go read from Kafka?

JSON values, and Avro values when a schema registry is configured on the source. Field types are inferred from a sample of messages at discover time: integers become INT64 in BigQuery, decimals FLOAT64, ISO 8601 timestamp strings TIMESTAMP and other strings STRING. Protobuf and plain-text messages are not supported.

Does this work with Confluent Cloud or Amazon MSK?

Yes. OLake Go speaks the Kafka protocol with PLAINTEXT, SASL_PLAINTEXT or SASL_SSL and the PLAIN or SCRAM-SHA-512 mechanisms, which covers Confluent Cloud, Amazon Managed Streaming for Apache Kafka (MSK), Redpanda and self-hosted clusters. The run on this page used Apache Kafka 4.3.1 in KRaft mode.

Kafka to SnowflakeSame source, read from Snowflake.Kafka to Amazon RedshiftSame source, read from Amazon Redshift.Kafka to DatabricksSame source, read from Databricks.Kafka to Apache IcebergSame source, read from Apache Iceberg.Kafka to ClickHouseSame source, read from ClickHouse.Postgres to BigQuerySame engine, replicated from Postgres.Oracle to BigQuerySame engine, replicated from Oracle.MongoDB to BigQuerySame engine, replicated from MongoDB.MySQL to BigQuerySame engine, replicated from MySQL.MariaDB to BigQuerySame engine, replicated from MariaDB.S3 to BigQuerySame engine, replicated from S3.DB2 to BigQuerySame engine, replicated from DB2.SQL Server to BigQuerySame engine, replicated from SQL Server.Kafka connector referenceEvery field, sync mode and troubleshooting note for the source.Query engine compatibilityWhich engines read which catalogs and delete formats.All integrationsEvery source and engine pair with a tested guide.

Deeper reading on this site: