<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Stories by Nur Dadak Tomakin on Medium]]></title>
        <description><![CDATA[Stories by Nur Dadak Tomakin on Medium]]></description>
        <link>https://medium.com/@nurdadak?source=rss-ecd6ae87103d------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/1*Z7zIb_q3A0pXJveROCSN0g.jpeg</url>
            <title>Stories by Nur Dadak Tomakin on Medium</title>
            <link>https://medium.com/@nurdadak?source=rss-ecd6ae87103d------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Thu, 19 Nov 2026 23:06:08 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@nurdadak/feed" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[BigQuery Schema Design and Data Validation]]></title>
            <link>https://medium.com/google-cloud/bigquery-schema-design-and-data-validation-e663b73ad2cb?source=rss-ecd6ae87103d------2</link>
            <guid isPermaLink="false">https://medium.com/p/e663b73ad2cb</guid>
            <category><![CDATA[data-pipeline]]></category>
            <category><![CDATA[data]]></category>
            <category><![CDATA[bigquery]]></category>
            <category><![CDATA[google-cloud-platform]]></category>
            <category><![CDATA[claude-code]]></category>
            <dc:creator><![CDATA[Nur Dadak Tomakin]]></dc:creator>
            <pubDate>Thu, 12 Nov 2026 14:39:51 GMT</pubDate>
            <atom:updated>2026-11-12T14:39:51.903Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/630/0*Kl17AAPKSSsyzNR4.png" /><figcaption><em>Photo by the author</em></figcaption></figure><p><strong>What should you test before moving data into BigQuery?</strong></p><p>You design the table and write the columns. Then you find out the API rejects that metric and dimension combination. Now you rebuild the table, reload the data and rewrite part of the fetch code. You could have caught the same error before writing the schema, with a single query.</p><p>So what actually changes when you run this test with Claude Code next to you?</p><p>Picking up from <a href="https://medium.com/google-cloud/how-to-design-a-bigquery-architecture-decisions-and-token-management-with-claude-code-3e294f932ed9">the second article</a>, this article builds the data layer of the “Agentic Data Pipeline” series. I walk through how I moved YouTube and Google Ads data into BigQuery, from testing the APIs in the terminal to the schema.py file, the backfill and the QA script.</p><h3>Schema Design Principle: Test in the Terminal First</h3><p>Before writing any schema, ask the API about every dimension and metric combination, live. In the YouTube Analytics API, not every dimension works with every metric. The same goes for segments and metrics in the Google Ads API. I mentioned this validation in Part 2. Here is how I actually ran it. The rule is simple: if the terminal returns OK, the combination goes into the schema. If it returns 400, I look for an alternative.</p><pre># Ask the live API about a single combination (svc: YouTube Analytics client)<br>r = svc.reports().query(<br>    ids=f&quot;channel=={CHANNEL}&quot;,<br>    startDate=&quot;2025-01-01&quot;,<br>    endDate=&quot;2025-01-07&quot;,<br>    dimensions=&quot;day,creatorContentType&quot;,<br>    metrics=&quot;views,engagedViews,estimatedMinutesWatched,&quot;<br>            &quot;averageViewDuration,averageViewPercentage,&quot;<br>            &quot;subscribersGained,subscribersLost,likes,comments,shares&quot;,<br>).execute()</pre><p>This query returned 28 rows, which is exactly what I expected: 7 days times 4 creatorContentType values. An HTTP 200 alone is not enough, so check the row count too. For video-level traffic sources I tried dimensions=video,insightTrafficSourceType. The API answered with HTTP 400 and The query is not supported. video,day was rejected as well. In both cases the fix was filters=video==VIDEO_ID. With that filter, dimensions=day was accepted for the daily metrics and dimensions=insightTrafficSourceType for traffic sources.</p><p>day,country and day,ageGroup,gender returned 400 as well. The official documentation does not list day among the dimensions of these two reports. So instead of day, I keep a snapshot_date column. It holds the report&#39;s end date.</p><h3>The prompt → test → fix loop with Claude Code</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*jWMl8SF3XvfZFWeZlZLk-g.png" /><figcaption><em>API combination testing</em></figcaption></figure><p>I turned these tests into a loop with Claude. In the prompt, I listed the combinations to try. Claude prepared the test commands. I ran them in the terminal and gave Claude every 400 back, together with its output. For each 400, Claude proposed an alternative, and I made the final call. Then I had Claude Code write the alternatives I picked into schema.py and the fetch scripts.</p><p>No combination reached the schema without passing a test. The country and demographics reports are a good example. They returned 400 because they do not support the day dimension, so the loop turned them into two separate tables based on snapshot_date. This is the table definition I gave Claude Code:</p><pre>channel_geography:<br>  dimensions=country<br>  metrics=views,estimatedMinutesWatched<br>  startDate = endDate = yesterday<br>  snapshot_date = endDate<br>  WRITE_APPEND<br><br>channel_demographics:<br>  dimensions=ageGroup,gender<br>  metrics=viewerPercentage<br>  startDate = endDate = yesterday<br>  snapshot_date = endDate<br>  WRITE_APPEND</pre><p>This definition contains two date decisions. The first is the end date. endDate is yesterday&#39;s date on every run, and it is written as snapshot_date. YouTube Analytics calculates dates in Pacific time, so yesterday in your time zone and yesterday for the API can be different days. The second is the start date. A snapshot has to say which window it represents, because a 28-day total and a channel&#39;s entire history do not mean the same thing in the same column. That is why startDate is always the same day as endDate.</p><h3>The schema.py Structure: Schema, Partitioning, Clustering and Lineage</h3><p>schema.py is the single source of truth for the YouTube tables. The Ads tables follow the same structure in schema_ads.py. Schemas, partitioning and clustering settings, and descriptions all live in one TABLE_REGISTRY, and setup.py builds the tables from that registry. There is one rule: BigQuery must always match schema.py.</p><p>I partitioned the daily tables on the date column and the snapshot tables on snapshot_date. The video tables are also clustered by video_id. A partition column must have a time type, such as DATE or TIMESTAMP. You cannot turn an existing table into a partitioned one in place. Instead, create a new partitioned table and move the data over with SQL. That way you do not have to backfill from the API again.</p><pre>&quot;video_daily_metrics&quot;: {<br>    &quot;schema&quot;:          VIDEO_DAILY_METRICS_SCHEMA,<br>    &quot;partition_field&quot;: &quot;date&quot;,<br>    &quot;clustering&quot;:      [&quot;video_id&quot;],<br>},<br><br># inside ensure_table()<br>table.time_partitioning = bigquery.TimePartitioning(<br>    type_=bigquery.TimePartitioningType.DAY, field=cfg[&quot;partition_field&quot;]<br>)<br>table.clustering_fields = cfg[&quot;clustering&quot;]</pre><figure><img alt="" src="https://cdn-images-1.medium.com/max/630/0*jW0NrsMpDO25bWrF.png" /><figcaption><em>Table Details screen</em></figcaption></figure><p>Every data table carries the same seven lineage columns. They record when a row was fetched, from which API, in which run, and with which code, schema and API version. All of them are REQUIRED, while the metric columns are NULLABLE. A row with a NULL metric value can be written to the table. A row with a NULL or missing lineage column is rejected by BigQuery. etl_run_id also ties each row to its pipeline_runs record.</p><pre>LINEAGE_FIELDS = [<br>    bigquery.SchemaField(n, &quot;TIMESTAMP&quot; if n == &quot;fetched_at&quot; else &quot;STRING&quot;, mode=&quot;REQUIRED&quot;)<br>    for n in (&quot;schema_version&quot;, &quot;etl_run_id&quot;, &quot;etl_job&quot;, &quot;etl_version&quot;,<br>              &quot;fetched_at&quot;, &quot;api_surface&quot;, &quot;api_version&quot;)<br>]</pre><h3>Fetch Scripts: Every API Has Its Own Limits</h3><p>I wrote a separate fetch module for each API. The Data API pulls video metadata and public statistics, the Analytics API pulls channel and video metrics, and the Ads API pulls campaign metrics. A single entry point runs the modules in sequence. If one module fails, the others keep running.</p><p>The API limits shaped the structure of these modules. The YouTube Data API only returns the current state, so tables like video_public_stats get a new snapshot row every day. In the Analytics API, a filter takes at most 500 IDs, and in traffic source reports the number of videos multiplied by the number of days cannot exceed 50,000. For dimensions=video, maxResults=200 was accepted in the terminal and 201 returned HTTP 400.</p><p>Daily video metrics need separate API calls per video. On a channel with thousands of videos, I did not pull every video and every date in one run during the backfill. I used chunked backfill instead. I split the videos into groups and the date range into windows, and each ETL run processed one chunk.</p><p>The Google Ads API returns fixed-value (enum) fields such as campaign type as numeric codes. Instead of labeling these codes with a hand-written map, I used the enum name the client library provides (row.campaign.advertising_channel_sub_type.name). A hand-written map that gets one code wrong labels the sub type incorrectly, and nothing warns you. There is one exception. If the library falls behind the API, values it does not recognize come back as UNKNOWN. Keep the library version current and raise a warning whenever UNKNOWN shows up.</p><p>Documentation changes affect your data too. On March 31, 2025, YouTube changed how Shorts views are counted: play starts and replays now count. The old counting method is available in the Analytics API as the engagedViews metric.</p><h3>Pushing to BigQuery and the First Check</h3><p>Before running the fetch scripts, I created the tables with setup.py. That way the structure matched schema.py from the start.</p><pre>python src/bigquery/setup.py</pre><p>TEST_MODE was on for the first push, so the script processed only 10 videos. Because the lineage columns are REQUIRED, a row with missing source information cannot be written anyway. I still opened the tables in BigQuery and checked that the column values looked right. I also checked that the partition and clustering fields showed up in the Details tab. Nothing looked wrong, so I turned TEST_MODE off and loaded the full data.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*dC0nlaniu3kHN09eJDihvg.png" /><figcaption>video_daily_metrics table design (schema, config, and lineage)</figcaption></figure><h3>Comparing Against YouTube Studio, and the QA Script</h3><p>Once the tables were full, I compared the data against an independent reference. First I picked a few random days and date ranges and put the YouTube Studio values next to the BigQuery values. When the samples matched, I checked channel-level totals from January 1, 2022 to the last fully processed day. I used the metrics I rely on most, views and watch time. I did this right after the first load, before any duplicate rows appeared in the tables.</p><p>A manual comparison happens once, and it does not catch every problem. When I ran the pipeline a few times, the same rows were added again on every run. The row count of channel_daily_metrics grew to roughly four times its size.</p><p>I added UPSERT to the daily tables, so running the same day again is safe. BigQuery has no built-in UPSERT, so I do it with MERGE. Snapshot tables carry the same risk, because WRITE_APPEND can write the same snapshot_date twice. I added the same protection there. I also moved the checks into a QA script. It checks the row count, data freshness, NULL ratio and duplicate keys. It also re-fetches a given date range and set of metrics from the API and compares them with what is in BigQuery. The result is saved as a JSON report.</p><h3>Backfill Strategy: History First, Then a Daily Window</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*6SOvMVWRJ2vAect-jly5pQ.png" /><figcaption><em>Backfill and daily window</em></figcaption></figure><p>The pipeline runs in two modes: backfill and daily. With BACKFILL_MODE on, I pulled channel, video and Ads data from January 1, 2022 up to today. The daily video table on YouTube and the placement table in Ads are very large, so I loaded those two with chunked backfill. After the backfill, the QA script verified every table, and I turned the mode off. The daily run now re-fetches only the last 72 hours of the daily metric tables and writes them with UPSERT.</p><p>The reason for re-fetching the last 72 hours is the Analytics processing delay. According to the documentation, data is processed with a delay of 48 to 72 hours, and the API sets the end date to the last fully processed day. Days that arrive incomplete are filled in on the next run, and UPSERT keeps the re-written rows from piling up as duplicates.</p><p>You can backfill history for reports without a day dimension too. If startDate and endDate are the same day, the report returns the values for that day. You can try this method for the country and age-gender tables.</p><h3>pipeline_runs: A Record of Every Run</h3><p>The pipeline_runs table records every run of every module as a single row. Its columns answer four questions:</p><ul><li>Which run? etl_run_id</li><li>Which code and schema version? etl_job, etl_version, schema_version</li><li>When? started_at, completed_at</li><li>What happened? status, rows_written, and error_type and error_message if something failed</li></ul><p>Every row in the data tables links to this record through etl_run_id. fetched_at tells you when a row was fetched, and etl_run_id tells you which run fetched it. That link lets you trace the source of any anomaly, from the row all the way to the error record.</p><p>The modules run independently, so when one fails, the others carry on. pipeline_runs shows which one failed and why.</p><h3>After the First Step</h3><p>In this article, I built the data layer. The next step is to run this flow on its own every day. The .env file moves to Secret Manager, the pipeline gets packaged into a Docker container, and it runs on a Cloud Run Job triggered by Cloud Scheduler.</p><p>This article is part 3 of the “Agentic Data Pipeline” series. In part 4, I will cover Docker, Cloud Run and daily automation.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=e663b73ad2cb" width="1" height="1" alt=""><hr><p><a href="https://medium.com/google-cloud/bigquery-schema-design-and-data-validation-e663b73ad2cb">BigQuery Schema Design and Data Validation</a> was originally published in <a href="https://medium.com/google-cloud">Google Cloud - Community</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[BigQuery Şema Tasarımı ve Veri Doğrulama]]></title>
            <link>https://medium.com/@nurdadak/bigquery-schema-tasar%C4%B1m%C4%B1-ve-veri-do%C4%9Frulama-06ca7432d2ad?source=rss-ecd6ae87103d------2</link>
            <guid isPermaLink="false">https://medium.com/p/06ca7432d2ad</guid>
            <category><![CDATA[bigquery]]></category>
            <category><![CDATA[data-pipeline]]></category>
            <category><![CDATA[claude-code]]></category>
            <category><![CDATA[google-cloud-platform]]></category>
            <category><![CDATA[data-engineering]]></category>
            <dc:creator><![CDATA[Nur Dadak Tomakin]]></dc:creator>
            <pubDate>Thu, 12 Nov 2026 12:11:25 GMT</pubDate>
            <atom:updated>2026-11-13T06:57:24.868Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*aC5qvV7BJJSPE-G_mLnOGg.png" /><figcaption>Fotoğraf yazar tarafından çekilmiştir</figcaption></figure><p><strong>Veriyi BigQuery’e taşımadan önce neyi test etmelisin?</strong></p><p>Tabloyu tasarlayıp kolonları yazdıktan sonra API’nin o metrik ve dimension kombinasyonunu reddettiğini öğrenmek, süreci başa sarman gereken ciddi bir zaman kaybı yaratır. Tablo yeniden kurulur, veri yeniden yüklenir ve fetch kodunun bir kısmı değişir. Oysa aynı hatayı şema yazılmadan önce, tek bir sorguyla yakalayabilirsin.</p><p>Peki bu testi Claude Code ile yapmak neyi değiştiriyor?</p><p><a href="https://medium.com/@nurdadak/bigquery-mimarisi-nas%C4%B1l-kurulur-claude-code-ile-karar-alma-ve-token-y%C3%B6netimi-df9d03ec9ab4">İkinci makalenin</a> ardından, bu makale “Agentic Data Pipeline” serisinin veri katmanını kuruyor. API’yi terminalde test etmekten schema.py dosyasına, backfill ve QA script’ine kadar YouTube ve Google Ads verilerini BigQuery’e nasıl taşıdığımı adım adım anlatacağım.</p><h3>Şema Tasarım Prensibi: Önce Terminalde Test Et</h3><p>Şema yazmadan önce yapılacak ilk iş, her dimension ve metrik kombinasyonunu API’ye canlı olarak sormaktır. YouTube Analytics API’de her dimension, Google Ads API’de ise her segment her metrikle birlikte çalışmaz. Makale 2&#39;de bu doğrulamaya değinmiştim, burada nasıl yaptığımı anlatıyorum. Kural basit: Terminalde OK dönerse kombinasyon şemaya girer, 400 dönerse alternatif aranır.</p><pre># Tek bir kombinasyonu canlı API&#39;ye sor (svc: YouTube Analytics client)<br>r = svc.reports().query(<br>    ids=f&quot;channel=={CHANNEL}&quot;,<br>    startDate=&quot;2025-01-01&quot;,<br>    endDate=&quot;2025-01-07&quot;,<br>    dimensions=&quot;day,creatorContentType&quot;,<br>    metrics=&quot;views,engagedViews,estimatedMinutesWatched,&quot;<br>            &quot;averageViewDuration,averageViewPercentage,&quot;<br>            &quot;subscribersGained,subscribersLost,likes,comments,shares&quot;,<br>).execute()</pre><p>Bu sorgu 28 satır döndürdü; beklenen sayı da buydu (7 gün × 4 creatorContentType değeri). HTTP 200 tek başına yetmez, satır sayısını da kontrol etmek gerekir. Video bazlı trafik kaynağı için dimensions=video,insightTrafficSourceType denediğimde ise API, HTTP 400 ile The query is not supported yanıtını verdi. video,day de reddedildi.</p><p>İkisinde de çözüm filters=video==VIDEO_ID oldu: Günlük metrik için dimensions=day, trafik kaynağı için dimensions=insightTrafficSourceType kabul edildi.</p><p>day,country ve day,ageGroup,gender kombinasyonları da 400 döndürdü. Resmi dokümanda bu iki raporun dimension listesinde day yer almıyor. Ben de day yerine snapshot_date kolonunu tuttum. Bu kolon raporun bitiş tarihini taşıyor.</p><h3>Claude Code ile prompt → test → fix döngüsü</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*NgjtERoieGcjCETO5RKazg.png" /><figcaption>API kombinasyon testi</figcaption></figure><p>Bu testleri Claude ile bir döngüye çevirdim. Prompt’ta denenecek kombinasyonları listeledim, ardından Claude test komutlarını hazırladı. Komutları terminalde çalıştırıp 400 dönenleri çıktısıyla birlikte geri verdim. Claude her 400 için bir alternatif önerdi ve kararı ben verdim. Seçtiğim alternatifi Claude Code ile schema.py ve fetch script&#39;lerine işledi.</p><p>Claude Code bu döngüyü kendi başına yürütmedi, her turda ben devreye girdim. Veri analisti olarak şemanın kalite kontrolünü ben yaptım. Her tablonun metrik ve dimension kombinasyonuna, hangi metriklerin gerekli olduğuna tablo tablo karar verip denetledim.</p><p>Ülke ve yaş-cinsiyet raporları ise bu döngüden snapshot_date kullanan iki tablo olarak ortaya çıktı. Claude Code&#39;a verdiğim tanım şöyleydi:</p><pre>channel_geography:<br>  dimensions=country<br>  metrics=views,estimatedMinutesWatched<br>  startDate = endDate = yesterday<br>  snapshot_date = endDate<br>  WRITE_APPEND<br><br>channel_demographics:<br>  dimensions=ageGroup,gender<br>  metrics=viewerPercentage<br>  startDate = endDate = yesterday<br>  snapshot_date = endDate<br>  WRITE_APPEND</pre><p>Bu tanımda iki tarih kararı var.</p><p>Birincisi bitiş tarihi: endDate her çalıştırmada dünün tarihidir ve snapshot_date olarak yazılır. YouTube Analytics tarihleri Pasifik saatine göre hesaplar, bu yüzden İstanbul&#39;daki dün ile API&#39;nin dünü farklı olabilir.</p><p>İkincisi başlangıç tarihi: Snapshot&#39;ın temsil ettiği pencere belli olmalı, çünkü son 28 günün toplamı ile kanalın tüm geçmişi aynı kolonda aynı anlama gelmez. Bu yüzden startDate her zaman endDate ile aynı gündür.</p><h3>schema.py Yapısı: Şema, Partition, Cluster ve Lineage</h3><p>schema.py, YouTube tablolarının tek kaynağıdır. Ads tabloları aynı yapıyla schema_ads.py dosyasında durur. Şemalar, partition ve cluster ayarları ve açıklamalar bir TABLE_REGISTRY içinde toplanır, setup.py de tabloları bu registry&#39;den oluşturur. Kural tek: schema.py ile BigQuery her zaman eşleşmeli.</p><p>Günlük tablolara date, snapshot tablolarına snapshot_date kolonu üzerinden partition ekledim. Video tablolarına ayrıca video_id ile cluster ekledim. Partition kolonu DATE ya da TIMESTAMP gibi bir zaman tipinde olmalı. Var olan bir tabloyu yerinde partition&#39;lı hale getiremezsin. Partitionlı olarak tabloyu yeniden kurup SQL ile veriyi taşımak gerekir, böylelikle API’den yeniden backfill gerekmez.</p><pre>&quot;video_daily_metrics&quot;: {<br>    &quot;schema&quot;:          VIDEO_DAILY_METRICS_SCHEMA,<br>    &quot;partition_field&quot;: &quot;date&quot;,<br>    &quot;clustering&quot;:      [&quot;video_id&quot;],<br>},<br><br># ensure_table() içinde<br>table.time_partitioning = bigquery.TimePartitioning(<br>    type_=bigquery.TimePartitioningType.DAY, field=cfg[&quot;partition_field&quot;]<br>)<br>table.clustering_fields = cfg[&quot;clustering&quot;]</pre><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*evZyF_CIcjaHyk7B3BakLQ.png" /><figcaption>Tablo Detaylar ekranı</figcaption></figure><p>Her veri tablosu aynı yedi lineage kolonunu taşır. Bu kolonlar bir satırın ne zaman, hangi API’den, hangi çalıştırmada ve hangi kod, şema ve API sürümüyle çekildiğini kaydeder. etl_run_id ayrıca satırı pipeline_runs kaydına bağlar.</p><p>Lineage kolonlarının hepsi REQUIRED, metrik kolonları ise NULLABLE. Metrik değeri NULL olan bir satır tabloya yazılabilir. Lineage kolonlarından biri NULL ya da eksik olan satırı ise BigQuery reddeder.</p><pre>LINEAGE_FIELDS = [<br>    bigquery.SchemaField(n, &quot;TIMESTAMP&quot; if n == &quot;fetched_at&quot; else &quot;STRING&quot;, mode=&quot;REQUIRED&quot;)<br>    for n in (&quot;schema_version&quot;, &quot;etl_run_id&quot;, &quot;etl_job&quot;, &quot;etl_version&quot;,<br>              &quot;fetched_at&quot;, &quot;api_surface&quot;, &quot;api_version&quot;)<br>]</pre><h3>Fetch Scriptleri: Her API’nin Kendi Sınırı Var</h3><p>Her API için ayrı bir fetch modülü yazdım. Data API video metadata ve public istatistikleri, Analytics API kanal ve video metriklerini, Ads API kampanya metriklerini çeker. Tek bir giriş noktası modülleri sırayla çalıştırır.</p><p>Modüllerin yapısını API sınırları belirledi. YouTube Data API yalnızca anlık durumu verir, bu yüzden video_public_stats gibi tablolara her gün yeni bir snapshot satırı eklenir. Analytics API’de bir filtre en fazla 500 ID alır ve trafik kaynağı raporlarında video sayısı ile gün sayısının çarpımı 50.000&#39;i geçemez. Terminalde dimensions=video için maxResults=200 kabul edildi, 201 ise HTTP 400 döndürdü.</p><p>Google Ads API, kampanya tipi gibi sabit değerli (enum) alanları sayı kodu olarak döndürür. Bu kodları elle yazılmış bir haritayla etiketlemek yerine kütüphanenin verdiği enum adını kullandım (row.campaign.advertising_channel_sub_type.name). Elle yazılmış haritada tek bir yanlış eşleşme alt tipi sessizce yanlış etiketler. Tek istisna: Kütüphane API’nin gerisinde kalırsa tanımadığı değerler UNKNOWN döner. Bu yüzden sürümü güncel tutup UNKNOWN için uyarı üretmek gerekir.</p><p>Dokümantasyon değişiklikleri de veriyi etkiler. Analytics API’de Mart 2025&#39;ten itibaren Shorts views oynatma başlangıçlarını ve tekrarları da saymaya başladı; eski sayım için engagedViews metriği eklendi.</p><h3>BigQuery’e Push ve İlk Doğrulama</h3><p>Fetch script’lerini çalıştırmadan önce tabloları setup.py ile oluşturdum, böylece yapı baştan schema.py ile aynı oldu.</p><pre>python src/bigquery/setup.py</pre><p>İlk push’ta TEST_MODE açıktı ve script yalnızca 10 video işledi. Lineage kolonları REQUIRED olduğu için kaynak bilgisi eksik bir satır zaten tabloya yazılamaz. Ben yine de BigQuery&#39;de tabloları açıp kolonlardaki değerlerin doğru geldiğine, Details sekmesinde de partition ve cluster alanlarının göründüğüne baktım. Sorun görünmediği için TEST_MODE&#39;u kapatıp tam veriyi yükledim.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*foRsej-tLNuBa9qZDLh7hQ.png" /><figcaption>video_daily_metrics tablo tasarımı</figcaption></figure><h3>YouTube Studio ile Karşılaştırma ve QA Script’i</h3><p>Tablolar dolunca veriyi bağımsız bir referansla karşılaştırdım. Önce rastgele seçtiğim birkaç gün ve tarih aralığı için YouTube Studio’daki değerleri BigQuery’dekilerle yan yana koydum. Örneklem tuttuktan sonra 1 Ocak 2022&#39;den son tam işlenmiş güne kadar kanal seviyesindeki toplamları da en çok kullandığım izlenme ve izlenme süresi metrikleriyle kontrol ettim. Bunu, tabloda yinelenen satırlar oluşmadan, ilk yüklemenin hemen ardından yaptım.</p><p>Elle karşılaştırma tek seferliktir ve her sorunu yakalamaz. Pipeline’ı birkaç kez çalıştırdığımda aynı satırlar her seferinde yeniden eklendi ve channel_daily_metrics tablosundaki satır sayısı yaklaşık dört katına çıktı.</p><p>Günlük tablolara UPSERT ekleyerek aynı günün tekrar çalıştırılmasını güvenli hale getirdim. BigQuery&#39;de yerleşik UPSERT yok, bunu MERGE ile yapıyorum. Snapshot tablolarında da aynı risk var, çünkü WRITE_APPEND aynı snapshot_date&#39;i iki kez yazabilir, onlara da aynı korumayı ekledim. Kontrolleri de bir QA script&#39;ine taşıdım. Script satır sayısını, verinin tazeliğini, NULL oranını ve tekrar eden anahtarları kontrol eder. Ayrıca belirlenen tarih aralığı ve metrikleri API&#39;den yeniden çekip BigQuery&#39;dekilerle karşılaştırır. Sonucu JSON raporu olarak tutar.</p><h3>Backfill Stratejisi: Önce Geçmiş, Sonra Günlük Pencere</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*g5thzyN6rHmd4lHLaDuNmw.png" /><figcaption>Backfill ve günlük pencere</figcaption></figure><p>Pipeline iki modda çalışır: backfill ve günlük çalıştırma. BACKFILL_MODE açıkken kanal, video ve Ads verisini 1 Ocak 2022&#39;den bugüne kadar çektim. YouTube’daki günlük video tablosu ile Ads’teki placement tablosu çok büyük olduğu için bu ikisini chunked backfill (parçalı backfill) ile yükledim. Videolar gruplara, tarih aralığı da pencerelere bölündü ve her ETL çalıştırmasında bir chunk işledi. Backfill sonrası QA script’i tüm tabloları doğruladı, ardından modu kapattım.</p><p>Günlük çalıştırma artık günlük metrik tablolarında yalnızca son 72 saati yeniden çekiyor ve UPSERT ile yazıyor.</p><p>Son 72 saatin yeniden çekilmesinin nedeni Analytics verisinin işlenme gecikmesidir. Dokümana göre veri 48 ila 72 saat gecikmeyle işlenir ve API bitiş tarihini son tam işlenmiş güne göre ayarlar. Bu nedenle eksik gelen günler sonraki çalıştırmada tamamlanır, UPSERT ise tekrar yazımda satırların çoğalmasını engeller.</p><p>day boyutu olmayan raporlarda da geçmişi doldurmak mümkün: startDate ile endDate aynı gün verildiğinde rapor o günün değerini döndürüyor. Ülke ve yaş-cinsiyet tabloları için bu yöntemi deneyebilirsiniz.</p><h3>pipeline_runs: Her Çalıştırmanın Kaydı</h3><p>pipeline_runs tablosu her modülün her çalıştırmasını tek satır olarak kaydeder. Kolonlar dört soruyu cevaplar:</p><ul><li>Hangi çalıştırma? etl_run_id</li><li>Hangi kod ve şema sürümüyle? etl_job, etl_version, schema_version</li><li>Ne zaman? started_at, completed_at</li><li>Sonuç ne? status, rows_written, hata varsa error_type ve error_message</li></ul><p>Veri tablolarındaki her satır bu kayda etl_run_id ile bağlanır. fetched_at satırın ne zaman, etl_run_id ise hangi çalıştırmayla çekildiğini söyler. Bu bağ sayesinde herhangi bir anomalinin kaynağını, satırdan hata kaydına kadar kolayca takip edebilirsin.</p><p>Modüller birbirinden bağımsız çalıştığı için bir modül düştüğünde diğerleri devam eder. Hangisinin neden düştüğünü pipeline_runs gösterir.</p><h3>İlk Adımdan Sonra</h3><p>Bu makalede veri katmanını kurdum. Sıradaki adım bu akışı her gün kendiliğinden çalıştırmak: .env dosyası Secret Manager&#39;a taşınacak, pipeline bir Docker container&#39;ına paketlenecek ve Cloud Run Job ile Cloud Scheduler üzerinde çalışacak.</p><p>Bu makale, “Agentic Data Pipeline” serisinin üçüncü bölümü. Dördüncü bölümde Docker, Cloud Run ve günlük otomasyonu ele alacağım.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=06ca7432d2ad" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[BigQuery Mimarisi Nasıl Kurulur? Claude Code ile Karar Alma ve Token Yönetimi]]></title>
            <link>https://medium.com/@nurdadak/bigquery-mimarisi-nas%C4%B1l-kurulur-claude-code-ile-karar-alma-ve-token-y%C3%B6netimi-df9d03ec9ab4?source=rss-ecd6ae87103d------2</link>
            <guid isPermaLink="false">https://medium.com/p/df9d03ec9ab4</guid>
            <category><![CDATA[claude-code]]></category>
            <category><![CDATA[google-cloud-platform]]></category>
            <category><![CDATA[agentic-ai]]></category>
            <category><![CDATA[bigquery]]></category>
            <category><![CDATA[data-engineering]]></category>
            <dc:creator><![CDATA[Nur Dadak Tomakin]]></dc:creator>
            <pubDate>Mon, 27 Jul 2026 09:02:22 GMT</pubDate>
            <atom:updated>2026-08-03T05:26:44.861Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*udNA_M6ZSewoqZmqexRw1Q.png" /><figcaption>Fotoğraf yazar tarafından çekilmiştir</figcaption></figure><p><strong>Veri modelini kurmadan önce hangi soruları cevaplarsan, veriyi güvenle taşımaya başlarsın?</strong></p><p>Serinin <a href="https://medium.com/@nurdadak/gcpde-data-pipeline-%C4%B1-kurmak-claude-code-bu-s%C3%BCre%C3%A7te-ne-yap%C4%B1yor-d315ed51a036">ilk makalesinde pipeline’ın iskeletini</a> kurmuştuk. GCP projesi hazır, servis hesabı devrede, credential yönetimi yapılandırılmış durumda. Şimdi elinde boş bir dataset var ve içinde ilk tabloyu oluşturmak üzeresin. Ama tam burada durup birkaç soruyu cevaplaman gerekiyor. Cevaplamadan devam edersen kod ilk gün çalışır, eksik kararlar ise birkaç hafta sonra pipeline canlıdayken karşına çıkar. Yanlış kurgulanmış bir veri yapısını sonradan düzeltmek, en baştan temiz bir sayfa açıp doğru tasarlamaktan çok daha maliyetli olur.</p><p>Serinin bu makalesinde, pipeline türü seçimi ve BigQuery dataset hiyerarşisini ele alıyorum. Ardından tablo tasarımının arkasındaki mantığa, plan mode ile mimari karar almaya ve YouTube&amp;Google Ads API’lerinin token yönetimine geçiyorum. Agentic Data Pipeline serisinin ikinci bölümünde odak noktası kod yazmak değil, kodun arkasındaki stratejiyi Claude Code ile birlikte kurmak.</p><h3>Neden Batch Pipeline? Neden Airflow veya dbt Değil?</h3><p>İlk mimari karar pipeline türüyle ilgiliydi. Veri kaynakları günde yalnızca bir kez güncelleniyor; dolayısıyla anlık (real-time) bir veri akışına ihtiyacım yoktu. Bu yüzden, günde bir defa tetiklenip veriyi çeken ve BigQuery’e yazdıktan sonra kapanan batch bir yapı yeterli.</p><p>Buradaki asıl soru şu: Neden araya Airflow veya dbt gibi bir orkestrasyon aracı koymadım? Cevap tamamen maliyet ve sadelik dengesinde gizli. Airflow’u canlıda tutmak, sürekli çalışan bir servis altyapısı demek. Bu da hem operasyonel bakım yükü hem de sabit maliyet getiriyor. dbt ise daha ağır dönüşüm senaryolarında anlam kazanıyor. Projenin bu aşamasında ise işim, ham veriyi kaynaktan alıp doğrudan BigQuery’e aktarmaktan ibaret.</p><p>Dolayısıyla bu adımda Claude Code ve Python ikilisinden fazlasına ihtiyacım olmadı. Gerçek bir orkestrasyon ihtiyacı ise serinin ilerleyen bölümlerinde, projeyi Cloud Run ile production ortamına taşırken ortaya çıkacak.</p><h3>BigQuery Dataset Hiyerarşisi</h3><p>Kurduğum pipeline üç farklı API’den veri çekiyor: YouTube Data, YouTube Analytics ve Google Ads. Bu üç kaynağı, iki bağımsız dataset altında topladım: youtube_analytics ve google_ads_analytics. İlk ikisi aynı dataset altında birleşiyor, Google Ads ise kendine ait ayrı bir alanda duruyor. Pipeline bu üç API&#39;yi sırayla çağırıyor ama her kaynağın verisini kendi datasetine ayrı yazıyor.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*jP5VZ_ozTmioBr69QzmNFw.png" /><figcaption>Pipeline mimarisi</figcaption></figure><p>Tüm kaynakları tek bir dataset altında toplamak başlangıçta pratik görünebilir. Ama veri hacmi ve tablo sayısı arttıkça bu yaklaşım yönetilmesi zor bir veri yığınına dönüşür. İki kaynağı en baştan ayırmamın başlıca üç teknik gerekçesi var:</p><ul><li><strong>Bağımsız yaşam döngüleri:</strong> İki kaynak farklı script’lerle besleniyor ve farklı ritimde güncelleniyor. Birinin çekim sıklığı ya da olası bir API kesintisi diğerini bağlamıyor.</li><li><strong>Şema uyumsuzluğu:</strong> YouTube ve Google Ads API’lerinin veri modelleri yapısal olarak kesişmiyor. Bu tabloların aynı datasette yan yana durması için sağlam bir zemin yok.</li><li><strong>Pipeline seviyesinde izolasyon:</strong> Veri çekilip yazılırken iki dataset birbirine hiç join edilmiyor. Her kaynak kendi tablolarına bağımsız yazılıyor.</li></ul><p>Veriyi kaynaktan çekerken iki dataseti birbirine bağlamak, pipeline üzerinde gereksiz bir bağımlılık yaratırdı. Bu yüzden birleştirme ve zenginleştirme işini pipeline’ın sorumluluğu olmaktan çıkardım ve analiz katmanına bıraktım. BigQuery Console’da sorgu yazıp gerekli tabloları join ediyorum, ya da tabloları BigQuery Data Agent’a bağlayıp verileri doğal dilde sorguluyorum. İhtiyaç tekrar ederse bu sorguları View veya Materialized View olarak saklayıp kalıcı hale de getirebilirim.</p><h3>Tablo Tasarım Mantığı</h3><p>youtube_analytics datasetini iki farklı API besliyor ve aralarındaki fark tablo tasarımını doğrudan belirliyor. YouTube Data API video metadatası, kanal bilgisi, playlist ve toplam görüntülenme gibi herkese açık verileri getiriyor. YouTube Analytics API ise yalnızca kanal sahibinin görebildiği özel performans verilerini sunuyor. Trafik kaynağı, demografi ve cihaz tipi gibi veriler de Analytics API üzerinden geliyor.</p><p>Erişim tipindeki bu ayrımın bir de veri tarafında karşılığı var. Data API her çağrıda o güne kadarki kümülatif toplamı verirken, Analytics API yalnızca o günün kendi net değerini raporluyor. Aynı metriği iki API üzerinden sorguladığımda farklı sonuç almamın temel sebebi de bu.</p><p>YouTube tablolarını iki eksende kurguladım:</p><ul><li><strong>Seviye Ekseni:</strong> Channel, video ve playlist kırılımlarını ayrı tablolarda oluşturdum.</li><li><strong>Zaman Ekseni:</strong> Bir tablo kümülatif toplamı ele alırken, bir başkası ise yalnızca ilgili günün değerini tutuyor.</li></ul><p>Zaman ekseni tek başına karışıklık yaratıyor, çünkü bir satıra bakınca değerin kümülatif mi yoksa o güne mi ait olduğu belli olmuyor. Çözüm olarak her tablo şemasına bir fetched_at kolonu ekledim. Bu kolon verinin hangi anda çekildiğini yazıyor ve iki tür satırı birbirinden ayırıyor.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*jIe5cqxg9oJwC80BGwOBUA.png" /></figure><p>Google Ads tarafında bu eksenler tümden değişiyor ve veri kampanya odağında dönüyor. Tablolar da kampanya ekseninde düzenleniyor ve günlük performans, coğrafi dağılım, yaş kırılımı ve reklam alanları gibi ayrı tablolarda yer alıyor.</p><p>Son bir kısıt her iki tarafı da bağlıyor. Bu API’ler her dimension’ı her metrikle birlikte vermiyor, bazı kombinasyonlara hata veriyor. Bu yüzden tabloları kurmadan önce API’yi terminalde çağırıyorum. Önce dimension’ı belirliyorum, sonra o dimension’la hangi metriklerin geldiğini kontrol ediyorum. Cevap geliyorsa kombinasyon şemaya ekleniyor, hata veriyorsa o zaman da alternatif arıyorum. Bu doğrulama sürecine ve şema koduna serinin üçüncü yazısında daha detaylı olarak yer vereceğim.</p><h3>Claude Code ile Mimari Karar Alma: Plan Mode</h3><p>Plan Mode çalışırken Claude Code projedeki dosyalara veya kod tabanına müdahale etmez. Önceden uygulanacak adımları bir plan halinde sunar ve geliştiriciden onay alana kadar hiçbir dosyayı değiştirmez. Mimari kararları değerlendirirken ihtiyacım olan da tam olarak buydu: Doğrudan kod çıktısına odaklanmak yerine, kararın arkasındaki teknik mantığı ve alternatiflerin getireceği yükleri analiz edebilmek.</p><p>Ancak bu modun bir maliyeti var; Plan Mode yüksek miktarda token harcıyor. Bu yüzden geniş kapsamlı ön araştırmaları ve genel yol haritasını web arayüzündeki Claude üzerinde netleştirdim. Claude Code tarafındaki Plan Mode’u kullanmaya başladığımda sormam gereken mimari sorular hazırdı.</p><p>Burada Claude Code’u yalnızca kod üreten bir araç olarak değil, mimari seçenekleri benimle birlikte tartışan bir çalışma ortağı olarak konumlandırdım. Kullandığım prompt’lardan biri şöyleydi:</p><pre>&gt; **Prompt:**<br>&gt; BigQuery&#39;de iki YouTube API&#39;si için channel seviyesinde tablo tasarlıyorum.<br>&gt; Data API kümülatif toplam, Analytics API günlük değer döndürüyor.<br>&gt; Veri günlük batch ile yükleniyor, sorgular çoğunlukla tarih aralığı filtresiyle çalışıyor.<br>&gt;<br>&gt; Kod yazma. Şu iki seçeneği karşılaştır:<br>&gt; 1. Tek tablo, değer tipini ayrı bir kolonda tutmak<br>&gt; 2. API başına ayrı tablo<br>&gt;<br>&gt; Her seçenek için şunları değerlendir:<br>&gt; - partition davranışı ve sorgu maliyeti<br>&gt; - schema değiştiğinde backfill maliyeti<br>&gt; - kümülatif ve günlük satırların karışma riski<br>&gt;<br>&gt; Birini öner, hangi tavizi verdiğini ve hangi varsayımlara dayandığını yaz.</pre><p>Modelden gelen yanıt bir kod bloğu değil, doğrudan teknik bir değerlendirmeydi. İki API’nin farklı zaman ekseninde veri sunduğunu vurguladı. Verilerin tek bir tabloda toplanmasının kümülatif ve günlük satırları karıştıracağını, şema değişikliklerinde ise tüm geçmiş verinin yeniden yüklenmesini gerektireceğini belirtti. Bu yüzden ayrı tablo yapısı önerdi. Kararı ona bırakmıyorum, ama mimari alternatifleri bu şekilde tartışmak kendi kararımı çok daha sağlam bir zemine oturtmamı sağlıyor.</p><p>Plan Mode bu değerlendirmeyi bir karar dokümanı olarak dosyaya yazıyor. İskeleti şöyle:</p><pre># Channel seviyesi tablo tasarımı: tek tablo vs API başına ayrı tablo<br><br>## Context<br>## Seçenek 1 - Tek tablo, değer tipini ayrı kolonda tutmak<br>## Seçenek 2 - API başına ayrı tablo<br>## Öneri<br>## Dayandığım varsayımlar<br>## Doğrulama</pre><p>Planı doğrudan uygulamaya geçmiyorum. Önce okuyup düzeltiyorum, ctrl+g ile plan üzerinde manuel değişiklik yapabiliyorum. Plan netleştikten sonra /clear ile yeni bir oturum açıp uygulamaya geçiyorum.</p><p>Kararı verdikten sonra partitioning ve clustering stratejisini CLAUDE.md dosyasına yazdırdım. Tablolar tarih kolonuna göre ayrılıyor, sık filtrelediğim kolonlara göre de gruplanıyor. Bu ikisi birlikte BigQuery sorgu maliyetini doğrudan düşürüyor. CLAUDE.md projenin hafızası gibi çalışıyor. Bir kuralı oraya tanımladığımda, başlattığım her yeni oturum bu kuralı bilerek çalışmaya başlıyor.</p><h3>Token Yönetimi: OAuth Prensibi ve API Farkları</h3><p>Üç API’nin kimlik doğrulama yöntemi dışarıdan bakıldığında birbirinden farklı görünüyor. Ancak hepsinin altında aynı OAuth mantığı çalışıyor.</p><p>Bu mantık iki nesne üzerine kurulu. Client, Console üzerinde bir kez oluşturulan sabit kimliği temsil ediyor. Token ise geçici bir erişim anahtarı olarak görev yapıyor. Token’ın süresi dolduğunda refresh token devreye giriyor ve yeni bir token üretiyor. Client hiçbir zaman değişmiyor, sürekli yenilenen bileşen token oluyor.</p><p>Bu aşamada beni uğraştıran konulardan biri tokenin beklenmedik biçimde geçersiz olmasıydı. Sorunun kaynağı OAuth consent screen’in yayın durumuydu. Ekran “Testing” modunda kaldığında refresh token yaklaşık yedi gün sonra geçerliliğini yitiriyordu. Hata mesajı da sorunun kaynağını doğrudan göstermedi. Consent screen’i Production’a aldıktan sonra revoke sorunu ortadan kalktı ve token uzun ömürlü hale geldi.</p><p>Bu ortak mantığın üzerine her API kendi kimlik doğrulama katmanını ekliyor ve aradaki fark üç noktada toplanıyor:</p><ul><li><strong>YouTube Data API:</strong> Public veri döndürdüğü için token gerektirmiyor, API Key yeterli oluyor. Key’i yalnızca bu API ile kısıtladım. Günlük kota proje bazlı tanımlanıyor, ek key oluşturmak limiti artırmıyor.</li><li><strong>YouTube Analytics API:</strong> Private veri döndürdüğü için OAuth zorunlu. Read-only scope’larla çalışıyor. Gelir metriklerini takip etmek istiyorsan da monetary scope eklemen gerekiyor.</li><li><strong>Google Ads API:</strong> OAuth’a ek olarak developer token istiyor. Hesapları MCC üzerinden merkezi olarak yönetiyorum, böylece her hesap için ayrı yetkilendirme kurmam gerekmiyor.</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*1aT6ZC-7unGyPqWf1Lz7Gg.png" /><figcaption>Credential ve API eşleşmesi</figcaption></figure><h3>.env Yapısı ve Smoke Test</h3><p>Farklı tipteki credential’ları tek bir .env dosyasında topladım. API Key gibi tekil değerleri doğrudan bu dosyada sakladım, OAuth ve servis hesabı JSON dosyalarını ise dosya yolu referansı olarak tanımladım. Kod her şeyi .env üzerinden okuduğu için hiçbir script&#39;in içinde sabit bir yol ya da anahtar bulunmuyor. JSON dosyalarının kendisi repo&#39;ya girmiyor, .gitignore bunları dışarıda bırakıyor.</p><p>Bu yapı ilerleyen aşamada işimi kolaylaştırdı. Pipeline’ı Cloud Run’a taşıdığımda değerleri Secret Manager üzerinden tanımlamam yeterli oldu ve koda müdahale etmem gerekmedi.</p><p>Proje yapısı bu aşamada şöyle görünüyordu:</p><pre>youtube-analytics-pipeline/<br>├── .claude/<br>│   ├── plans/<br>│   └── skills/<br>├── CLAUDE.md<br>├── README.md<br>├── main.py<br>├── .env<br>├── .gitignore<br>├── requirements.txt<br>├── credentials/<br>│   ├── youtube_analytics_token.json<br>│   ├── google_ads_token.json<br>│   └── service_account.json<br>├── src/<br>│   ├── bigquery/<br>│   ├── youtube_data/<br>│   ├── youtube_analytics/<br>│   ├── google_ads/<br>│   └── utils/<br>└── tests/<br>    └── smoke.sh</pre><p>İlk fetch script’ini yazmadan önce süreci bir smoke test ile doğruladım. Bu test Python interpreter’ının doğru ortamı gösterdiğini, gerekli paketlerin kurulu olduğunu, credential dosyalarının okunabildiğini ve CLI’ın hatasız çalıştığını teyit ediyordu.</p><p>Buradaki amacım, ortam kaynaklı sorunları API kaynaklı sorunlardan ayırmaktı. Bu kontrolü yapmadan veri çekmeye başlasaydım, karşılaştığım hataların kaynağını bulmam zorlaşırdı. Sorun kimlik doğrulamadan da kaynaklanabilirdi, eksik bir kütüphaneden de. Test başarıyla tamamlandığında API’den veriyi çeken ilk script’i yazmaya geçtim.</p><h3>Mimari Kurulduktan Sonra</h3><p>Veri mimarisi hazır: Dataset hiyerarşisi kurgulandı, tablolar seviye ve zaman ekseninde tasarlandı, üç API’nin de kimlik doğrulama mekanizması sorunsuz çalışıyor. Artık şema tanımlarını koda dökmeye, veriyi BigQuery’ye taşımaya ve veri bütünlüğünü doğrulamaya geçebiliriz.</p><p>Bu makale, Agentic Data Pipeline serisinin ikinci bölümü. Üçüncü bölümde şema tasarımı ve veri doğrulama süreçlerini ele alacağım.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=df9d03ec9ab4" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[How to Design a BigQuery Architecture: Decisions and Token Management with Claude Code]]></title>
            <link>https://medium.com/google-cloud/how-to-design-a-bigquery-architecture-decisions-and-token-management-with-claude-code-3e294f932ed9?source=rss-ecd6ae87103d------2</link>
            <guid isPermaLink="false">https://medium.com/p/3e294f932ed9</guid>
            <category><![CDATA[data-engineering]]></category>
            <category><![CDATA[claude-code]]></category>
            <category><![CDATA[google-cloud-platform]]></category>
            <category><![CDATA[bigquery]]></category>
            <category><![CDATA[agentic-ai]]></category>
            <dc:creator><![CDATA[Nur Dadak Tomakin]]></dc:creator>
            <pubDate>Sun, 26 Jul 2026 06:12:07 GMT</pubDate>
            <atom:updated>2026-07-26T06:12:07.835Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*udNA_M6ZSewoqZmqexRw1Q.png" /><figcaption>Photo by the author</figcaption></figure><p><strong>Which questions do you need to answer before you build the data model, so you can start moving data with confidence?</strong></p><p>In <a href="https://medium.com/towards-data-engineering/setting-up-a-data-pipeline-on-gcp-what-claude-code-actually-does-4d6ffd1e8561">the first article in this series</a>, we set up the skeleton of the pipeline. The GCP project is ready, the service account is live, and credential management is configured. Now you have an empty dataset in front of you and you’re about to create the first table inside it. This is where you stop and answer a few questions. Skip them and the code still runs on day one. The missing decisions show up weeks later, with the pipeline already live. Fixing a badly designed data structure after the fact costs far more than getting it right on a clean page.</p><p>This article covers the pipeline type decision and the BigQuery dataset hierarchy. From there I move to the logic behind table design, making architecture decisions in Plan Mode, and token management for the YouTube and Google Ads APIs. In this second part of the Agentic Data Pipeline series, the focus is not on writing code. It’s on building the strategy behind it, together with Claude Code.</p><h3>Why a Batch Pipeline? Why Not Airflow or dbt?</h3><p>The first architecture decision was the pipeline type. My data sources refresh once a day, so there’s no need for a real-time stream. A batch setup that triggers once daily, pulls the data, writes it to BigQuery, and shuts down is enough.</p><p>The real question is this: why didn’t I put an orchestration tool like Airflow or dbt in between? The answer sits in the balance between cost and simplicity. Keeping Airflow alive means running a service around the clock, which brings both operational maintenance and a fixed bill. dbt earns its place in heavier transformation scenarios. At this stage, my job is to pull raw data from the source and write it straight to BigQuery.</p><p>So Claude Code and Python were all I needed here. Real orchestration comes later in the series, when the project moves to production on Cloud Run.</p><h3>The BigQuery Dataset Hierarchy</h3><p>The pipeline I built pulls data from three different APIs: YouTube Data, YouTube Analytics, and Google Ads. I collected these three sources under two independent datasets: youtube_analytics and google_ads_analytics. The first two share a dataset, while Google Ads sits in its own space. The pipeline calls the three APIs in sequence but writes each source to its own dataset separately.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*zz8AZ5xZklv9u_28AKtILA.png" /><figcaption><em>Pipeline architecture</em></figcaption></figure><p>Putting everything under a single dataset looks practical at first. But as data volume and table count grow, that approach turns into a pile of tables nobody can manage. I had three technical reasons for separating the two sources from the start:</p><ul><li><strong>Independent lifecycles:</strong> The two sources are fed by different scripts and refresh on different rhythms. Neither the fetch frequency nor a possible API outage on one side affects the other.</li><li><strong>Schema mismatch:</strong> The data models behind the YouTube and Google Ads APIs don’t overlap structurally. There’s no solid reason for these tables to sit side by side in the same dataset.</li><li><strong>Isolation at the pipeline level:</strong> Nothing joins the two datasets while data is being pulled and written. Each source writes to its own tables independently.</li></ul><p>Wiring the two datasets together at the extraction stage would create an unnecessary dependency inside the pipeline. So I took joining and enrichment out of the pipeline’s job description and handed it to the analysis layer. I write queries in the BigQuery Console to join the tables I need, or I connect the tables to a BigQuery Data Agent and query them in natural language. When a query keeps coming back, I can save it as a View or a Materialized View.</p><h3>Table Design Strategy</h3><p>Two different APIs feed the youtube_analytics dataset, and the difference between them shapes the table design directly. The YouTube Data API returns public data: video metadata, channel information, playlists, and total view counts. The YouTube Analytics API returns performance data only the channel owner can see. Traffic source, demographics, and device type all come through the Analytics API.</p><p>That access difference has a counterpart on the data side. The Data API returns the cumulative total up to that day on every call, while the Analytics API reports only that day’s own net value. This is exactly why the same metric gives me different numbers depending on which API I ask.</p><p>I organized the YouTube tables along two axes:</p><ul><li><strong>Level axis:</strong> channel, video, and playlist each get their own tables.</li><li><strong>Time axis:</strong> one table holds the cumulative total, another holds only the value for that specific day.</li></ul><p>The time axis creates confusion on its own, because looking at a single row tells you nothing about whether the value is cumulative or belongs to that day. To solve this I added a fetched_at column to every table schema. The column records the moment the data was pulled and keeps the two kinds of rows apart.</p><p>On the Google Ads side these axes change completely, and the data revolves around campaigns. The tables follow that same axis: daily performance, geographic distribution, age breakdown, and ad group performance live in separate tables like campaign_daily, campaign_geography, age_range, and ad_group_ads.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*p00nyFBYXFCpswfvrDHXEw.png" /></figure><p>One last constraint ties both sides together: these APIs don’t return every dimension with every metric, and some combinations come back as errors. So before I create the tables, I call the API from the terminal. I pick the dimension first, then check which metrics come back with it. If the response arrives, the combination goes into the schema. If it errors, I look for an alternative. The third article in the series covers this validation process and the schema code in detail.</p><h3>Making Architecture Decisions with Claude Code: Plan Mode</h3><p>While Plan Mode is running, Claude Code touches nothing in the project files or the codebase. It presents the steps it plans to take and changes no file until the developer approves. That’s exactly what I needed while weighing architecture decisions: instead of jumping to code output, I could look at the technical reasoning behind the decision and the cost each alternative would carry.</p><p>This mode comes at a price, though. Plan Mode burns through a lot of tokens. So I did the broad research and the general roadmap on the Claude web interface. By the time I started using Plan Mode inside Claude Code, I already knew which architecture questions I needed to ask.</p><p>Here I treated Claude Code not as a tool that generates code, but as a working partner that debates architectural options with me. One of the prompts I used looked like this:</p><pre>&gt; **Prompt:**<br>&gt; I&#39;m designing channel-level tables in BigQuery for two YouTube APIs.<br>&gt; The Data API returns cumulative totals, the Analytics API returns daily values.<br>&gt; Data loads in a daily batch, and queries mostly filter on a date range.<br>&gt;<br>&gt; Don&#39;t write code. Compare these two options:<br>&gt; 1. A single table with the value type in a separate column<br>&gt; 2. A separate table per API<br>&gt; <br>&gt; For each option, evaluate:<br>&gt; - partition behavior and query cost<br>&gt; - backfill cost when the schema changes<br>&gt; - the risk of mixing cumulative and daily rows<br>&gt; <br>&gt; Recommend one, state the trade-off you&#39;re accepting, and name your assumptions.</pre><p>What came back wasn’t a block of code, it was a technical assessment. It pointed out that the two APIs deliver data on different time axes. Collecting them in a single table would mix cumulative and daily rows, and any schema change would force a reload of the entire history. It recommended separate tables. I don’t hand the decision over to the model. But debating architectural alternatives this way puts my own decision on much firmer ground.</p><p>Plan Mode writes that assessment to a file as a decision document. The skeleton looks like this:</p><pre># Channel-level table design: single table vs separate table per API<br><br>## Context<br>## Option 1 - Single table with a value-type column<br>## Option 2 - Separate table per API<br>## Recommendation<br>## Assumptions<br>## Verification</pre><p>After the decision, I had Claude Code write the partitioning and clustering strategy into CLAUDE.md. The tables are partitioned on the date column and clustered on the columns I filter most often. Together these two bring BigQuery query costs down directly. CLAUDE.md works like the project&#39;s memory. Once I define a rule there, every new session I start already knows it.</p><h3>Token Management: The OAuth Principle and API Differences</h3><p>The authentication method for the three APIs looks different from the outside. Underneath, they all run on the same OAuth logic.</p><p>That logic rests on two objects. The client represents a fixed identity you create once in the Console. The token acts as a temporary access key. When the token expires, the refresh token steps in and produces a new one. The client never changes. The token is the part that keeps getting renewed.</p><p>One thing that cost me time at this stage was the token becoming invalid without warning. The source turned out to be the publishing status of the OAuth consent screen. While the screen stays in “Testing” mode, the refresh token expires after about seven days. The pipeline ran without a hitch for seven days, then stopped on the eighth. The error message didn’t point to the cause either. Once I moved the consent screen to Production, the revoke problem disappeared and the token became long-lived.</p><p>On top of that shared logic, each API adds its own authentication layer, and the differences come down to three points:</p><ul><li><strong>YouTube Data API:</strong> It returns public data, so it needs no token at all. An API Key is enough. I restricted the key to this API only. The daily quota is defined at the project level, so creating extra keys doesn’t raise the limit.</li><li><strong>YouTube Analytics API:</strong> It returns private data, so OAuth is required. It works with read-only scopes. If you want to track revenue metrics, you also need to add the monetary scope.</li><li><strong>Google Ads API:</strong> On top of OAuth, it asks for a developer token. I manage the accounts centrally through an MCC, which saves me from setting up separate authorization for each one.</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*_ghgvkIUy92EFZQfHhpK0A.png" /><figcaption><em>Credentials and API mapping</em></figcaption></figure><h3>The .env Structure and a Smoke Test</h3><p>I collected credentials of every type into a single .env file. Single values like the API Key I stored directly in the file, while the OAuth and service account JSON files are defined as path references. Since the code reads everything through .env, no script carries a hardcoded path or key. The JSON files themselves never enter the repo, and .gitignore keeps them out from the start.</p><p>This structure paid off later. When I moved the pipeline to Cloud Run, defining the values through Secret Manager was enough, and the code needed no changes.</p><p>Here’s how the project structure looked at this stage:</p><pre>youtube-analytics-pipeline/<br>├── .claude/<br>│   ├── plans/<br>│   └── skills/<br>├── CLAUDE.md<br>├── README.md<br>├── main.py<br>├── .env<br>├── .gitignore<br>├── requirements.txt<br>├── credentials/<br>│   ├── youtube_analytics_token.json<br>│   ├── google_ads_token.json<br>│   └── service_account.json<br>├── src/<br>│   ├── bigquery/<br>│   ├── youtube_data/<br>│   ├── youtube_analytics/<br>│   ├── google_ads/<br>│   └── utils/<br>└── tests/<br>    └── smoke.sh</pre><p>Before writing the first fetch script, I validated the setup with a smoke test. The test confirms that the Python interpreter points to the right environment, the required packages are installed, the credential files are readable, and the CLI runs without errors. What I wanted was to separate environment problems from API problems. Without that check, tracking down the source of an error gets harder. The problem could be authentication, or it could be a missing library. Once the test passed, I moved on to writing the first script that pulls data from the API.</p><h3>After the Architecture Is in Place</h3><p>The data architecture is ready: the dataset hierarchy is designed, the tables are laid out along the level and time axes, and authentication works for all three APIs. Now we can move on to writing the schema definitions in code, loading data into BigQuery, and validating its integrity.</p><p>This is part two of the Agentic Data Pipeline series. Part three covers schema design and the data validation process.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=3e294f932ed9" width="1" height="1" alt=""><hr><p><a href="https://medium.com/google-cloud/how-to-design-a-bigquery-architecture-decisions-and-token-management-with-claude-code-3e294f932ed9">How to Design a BigQuery Architecture: Decisions and Token Management with Claude Code</a> was originally published in <a href="https://medium.com/google-cloud">Google Cloud - Community</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Setting Up a Data Pipeline on GCP: What Claude Code Actually Does]]></title>
            <link>https://medium.com/towards-data-engineering/setting-up-a-data-pipeline-on-gcp-what-claude-code-actually-does-4d6ffd1e8561?source=rss-ecd6ae87103d------2</link>
            <guid isPermaLink="false">https://medium.com/p/4d6ffd1e8561</guid>
            <category><![CDATA[claude-code]]></category>
            <category><![CDATA[agentic-ai]]></category>
            <category><![CDATA[google-cloud-platform]]></category>
            <category><![CDATA[data-engineering]]></category>
            <category><![CDATA[data-pipeline]]></category>
            <dc:creator><![CDATA[Nur Dadak Tomakin]]></dc:creator>
            <pubDate>Fri, 17 Jul 2026 13:52:57 GMT</pubDate>
            <atom:updated>2026-07-17T13:52:57.433Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*cXyyORt-gFE0faTa.jpeg" /><figcaption><em>(Photo by the author)</em></figcaption></figure><p><strong>What would this project look like if an AI assistant had been in the room from day one?</strong></p><p>The most critical decisions on a data project happen before you write a single line of code: architecture, service connections, security layers, data modeling. On the cloud, each one becomes a layer you have to get right. Service accounts, OAuth flow, API authorization, and BigQuery configuration all affect each other. Get the order wrong and it won’t show up until the pipeline is already running, usually as an authorization error. By then you’re retracing steps to find it.</p><p>So what changes when you make these calls with Claude Code next to you?</p><p>This is part one of the Agentic Data Pipeline series: how Claude Code fits in at each stage, from data infrastructure through automation to agentic systems. We start with setup.</p><h3>Google Cloud: Why GCP, Why BigQuery?</h3><p>YouTube and Google Ads already run on Google’s infrastructure. You could process this data on another cloud, but every extra hop adds a layer in between: more complex authentication, extra transfer configuration, higher maintenance cost.</p><p>On GCP, these integrations stay inside one ecosystem. Nothing has to leave its source to get processed, access control sits in one place, and you always know where the data is.</p><p>BigQuery alone justifies the choice. It’s serverless, so there’s no cluster to manage, and storage, processing, ML, and visualization all live under one roof. Later in the series, Gemini Enterprise Agent Platform (formerly Vertex AI), the Gemini models it hosts in Model Garden, and BigQuery ML come into the picture. Building on GCP from the start makes that move a straighter line.</p><h3>Connecting Claude Code to the Project</h3><p>I ran Claude Code through the extension inside the Antigravity IDE. Install it from the Extensions tab and open it directly. You get a session with access to the file system, the terminal, and version control.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/727/0*Xec2p8__I0SfSIv5.png" /><figcaption><em>The Antigravity Extensions tab</em></figcaption></figure><p>I used skill-creator to build the skills this project needed. Claude Code’s skill system packages repeated workflows into a /command, covered under Creating a Skill below.</p><h3>Starting the Project with Claude Code</h3><p>I opened an empty folder and ran /init. Claude Code scanned it, saw it was empty, and created a minimal CLAUDE.md:</p><pre># CLAUDE.md  <br>This file provides guidance to Claude Code when working in this repository.</pre><p>Then it asked what I was building. That question matters. Claude Code resets its memory every session and starts like someone who has never seen the project. CLAUDE.md fills the gap: Claude reads it at the start of every session, and it carries the project’s context, technical constraints, and architecture decisions.</p><p>Two rules kept it useful. Keep it under 200 lines, since longer files eat into the context window and drag response quality down. And split it up: general context stays in CLAUDE.md, while security rules or API behavior move to separate rule files that Claude loads only when relevant.</p><p>Then I built the first folder structure with Claude Code:</p><pre>youtube-analytics-pipeline/  <br>├── CLAUDE.md  <br>├── .gitignore  <br>├── .env  <br>├── README.md  <br>├── .claude/  <br>│   └── skills/  <br>├── src/  <br>├── data/  <br>└── outputs/</pre><p>Credential files live outside the repo. The .env file holds the paths and sits in the repo root, but .gitignore keeps it untracked, so it never gets committed.</p><p>Claude Code has different edit-permission modes. During setup I used Edit automatically to move fast, since nothing was critical yet. For production code, especially scripts that write to BigQuery, I switched to Ask before edits, which asks for approval before every change.</p><h3>Creating a Skill</h3><p>Skills let you call repeated workflows with a /command, and this was one of the features I got the most out of. I kept the skill files under the project&#39;s .claude folder.</p><p>To install skill-creator, run /manage plugins, then search for skill-creator@claude-plugins-official in the marketplace and add it. Restart Claude Code.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/617/0*YP6ma3BToR1_g3le.png" /><figcaption><em>The manage plugins command in Claude Code (1)</em></figcaption></figure><p>Once it’s back, check that skill-creator is active, then start with something like “I want to create a BigQuery-GCP skill for this project.” It asks when the skill should trigger, what steps to follow, and what the output should look like, then builds SKILL.md from your answers.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/603/0*wMaGBWxXJQ19NJfA.png" /><figcaption><em>The manage plugins command in Claude Code (2)</em></figcaption></figure><p>Save it with the “commit this” command. From then on, /bigquery-gcp loads every instruction in SKILL.md plus the project context. The /eval command compares the skill&#39;s output with and without it active and suggests updates. I still read the outputs myself to confirm it behaved the way I expected.</p><h3>Setting Up the GCP Infrastructure</h3><p>With the project started, I moved to GCP. The order matters.</p><p><strong>1. Create a project.</strong> I created one at console.cloud.google.com/projectcreate and chose EU for the region, since the data location has to stay consistent with the BigQuery dataset later.</p><p><strong>2. Enable the APIs.</strong> Through the API library I enabled three: YouTube Data API v3, YouTube Analytics API, and Google Ads API.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*S9wLUNk_4pbvtACm.png" /><figcaption><em>Google Cloud API Library</em></figcaption></figure><p>Clicking Enable is all it takes, but decide your authentication method first. That determines whether you need OAuth or a service account.</p><p><strong>3. Create a service account and assign roles.</strong> From IAM &amp; Admin, use + CREATE SERVICE ACCOUNT. The pipeline needs two roles to write to BigQuery: BigQuery Data Editor and BigQuery Job User. Without Data Editor you can&#39;t write tables; without Job User you can&#39;t run queries.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/340/0*5VpI7hQuE2k4ZgPQ.png" /><figcaption><em>Google Cloud IAM screen</em></figcaption></figure><p>Then download the JSON key. This file never goes into the repo.</p><p><strong>4. OAuth consent screen and Client ID.</strong> YouTube Analytics and Google Ads both need OAuth 2.0, so set up the consent screen first. I set it to External and added the account that needed access under Test users. Skip that and the authorization screen still opens, but access gets denied. Then I created a separate OAuth client per API, with Desktop app as the type since the pipeline runs as a Python script, and downloaded each client secret.</p><h3>Keeping Credentials Secure</h3><p>That leaves three credential files: the service account JSON key and two OAuth client secrets. All three stay outside the repo, with their paths defined in .env:</p><pre>GOOGLE_APPLICATION_CREDENTIALS=/path/to/credentials/youtube-pipeline-sa.json  <br>YOUTUBE_OAUTH_CLIENT=/path/to/credentials/youtube-oauth-client.json  <br>GOOGLE_ADS_OAUTH_CLIENT=/path/to/credentials/google-ads-oauth-client.json</pre><p>Scripts read the paths from .env, so no real path or key ever appears in the code. GOOGLE_APPLICATION_CREDENTIALS is also the variable Google&#39;s client libraries check by default, so service-account authentication works through it automatically.</p><p>The .gitignore:</p><pre># Python  <br>__pycache__/  <br>*.pyc  <br><br># Credentials  <br>.env  <br>*.json  <br><br># Outputs  <br>data/  <br>outputs/  <br><br># macOS  <br>.DS_Store</pre><p>The .env and *.json rules do different jobs. .env carries the paths, so it can&#39;t be committed. *.json is a second layer: as a project grows, a stray key file or a test API response saved as JSON can slip in, and this rule is the last line of defense.</p><p><strong>The code stays the same, only the source changes</strong></p><p>This pays off the moment you move to production. Locally, the variables come from .env. On Cloud Run, they come from Secret Manager instead. The names stay the same, so the code doesn&#39;t change.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*sqfFppQRUOOs5otyncXrZw.png" /><figcaption>Same variable, different source: local vs production</figcaption></figure><p>The code reading the credentials never has to know which environment it’s in:</p><pre>from dotenv import load_dotenv  <br>import os  <br><br>load_dotenv()  <br><br>creds_path = os.environ[&quot;GOOGLE_APPLICATION_CREDENTIALS&quot;]</pre><p>load_dotenv() never overwrites a variable that&#39;s already set. Locally it reads from .env; on Cloud Run it leaves the value Secret Manager already injected in place. The only thing to check on the way to production is that the variable names match across environments.</p><p><strong>One step further in production</strong></p><p>For local development, the JSON key and .env setup is a solid start. In production, a downloaded JSON key is a risk by most enterprise security standards: rotation is manual, and the audit trail is fragile if it leaks. Cloud Run can reach GCP resources through its own service identity, and Workload Identity Federation makes authentication work with no key at all. The series moves to that in Article 4. The local setup stays as it is here.</p><h3>After the First Step</h3><p>The environment is ready: Claude Code knows the project, the GCP infrastructure is up, and credentials are configured securely. Next comes the BigQuery dataset hierarchy, table design decisions, and token setup for the YouTube and Google Ads APIs.</p><p>This is part one of the Agentic Data Pipeline series. The next articles build on this infrastructure.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=4d6ffd1e8561" width="1" height="1" alt=""><hr><p><a href="https://medium.com/towards-data-engineering/setting-up-a-data-pipeline-on-gcp-what-claude-code-actually-does-4d6ffd1e8561">Setting Up a Data Pipeline on GCP: What Claude Code Actually Does</a> was originally published in <a href="https://medium.com/towards-data-engineering">Towards Data Engineering</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[GCP’de Data Pipeline’ı Kurmak: Claude Code Bu Süreçte Ne Yapıyor?]]></title>
            <link>https://medium.com/@nurdadak/gcpde-data-pipeline-%C4%B1-kurmak-claude-code-bu-s%C3%BCre%C3%A7te-ne-yap%C4%B1yor-d315ed51a036?source=rss-ecd6ae87103d------2</link>
            <guid isPermaLink="false">https://medium.com/p/d315ed51a036</guid>
            <category><![CDATA[claude-code]]></category>
            <category><![CDATA[google-cloud-platform]]></category>
            <category><![CDATA[data-engineering]]></category>
            <category><![CDATA[agentic-ai]]></category>
            <category><![CDATA[data-pipeline]]></category>
            <dc:creator><![CDATA[Nur Dadak Tomakin]]></dc:creator>
            <pubDate>Tue, 16 Jun 2026 19:30:52 GMT</pubDate>
            <atom:updated>2026-11-18T06:49:18.377Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*wWlNietWhmO3B1k-cDXsmw.jpeg" /><figcaption>(Fotoğraf yazar tarafından çekilmiştir)</figcaption></figure><p><strong>Fikir aşamasından itibaren bir AI asistan seninle birlikte çalışsaydı, proje nasıl şekillenirdi?</strong></p><p>Bir data projesinin en kritik kararları kod yazılmadan önce alınıyor. Mimari seçimler, servis bağlantıları, güvenlik katmanları, data modelleme. Cloud üzerinde bir data pipeline kurarken bunların her biri ayrı bir katman olarak değerlendirilir. Servis hesapları, OAuth akışı, API yetkilendirmeleri ve BigQuery yapılandırması birbirini doğrudan etkiler. Bu katmanların doğru sırayla kurulması kritik; çünkü kurulumda atlanan bir adım, pipeline çalışmaya başladığında yetki hatası ya da erişim problemi olarak geri dönüyor ve çoğu zaman birkaç adım geriye dönmeyi gerektiriyor.</p><p>Peki bu kararları Claude Code ile almak neyi değiştiriyor?</p><p>Serinin ilerleyen aşamalarında Gemini Enterprise Agent Platform, Gemini ve BigQuery ML de devreye girecek; altyapıyı baştan GCP üzerinde kurmak, bu bileşenlere geçişi çok daha düz bir çizgiye indirmemizi sağlayacak.</p><h3>Google Cloud: Neden GCP, Neden BigQuery?</h3><p>YouTube ve Google Ads, Google’ın kendi altyapısını kullanıyor. Bu verileri başka bir cloud sağlayıcısında işlemek mümkün ama her ekstra adım ek bir ara katman demek. Kimlik doğrulama karmaşıklaşır, veri aktarımı için ek yapılandırma gerekir veya bakım maliyeti artar.</p><p>GCP’de ise bu entegrasyonlar aynı ekosistem içinde kuruluyor. Bunun güvenlik ve data governance tarafında da doğrudan bir karşılığı var: veri kaynağından ayrılmadan işlendiği için dışarıya taşınması gerekmiyor, erişim kontrolü tek noktadan yönetiliyor ve verinin nerede durduğu her aşamada net kalıyor.</p><p>BigQuery özelinde bakıldığında: serverless bir veri ambarı olması, yani cluster yönetmene gerek kalmaması, başlı başına bir tercih sebebi. Ama daha somut bir neden var: tüm veri depolama, işleme, ML ve görselleştirmeyi tek bir ekosistemde yönetmek. Bu noktada BigQuery tüm katmanlarla doğrudan konuşabiliyor.</p><p>Serinin ilerleyen aşamalarında Vertex AI Agent Builder, Gemini ve BigQuery ML de devreye girecek; altyapıyı baştan GCP üzerinde kurmak, bu bileşenlere geçişi çok daha düz bir çizgiye indirmemizi sağlayacak.</p><h3>Claude Code’u Projeye Bağlamak</h3><p>Bu projede Claude Code’u Antigravity IDE’si içindeki extension üzerinden kullandım. Extensions sekmesinden Claude Code’u yükleyip doğrudan açmak yeterli.</p><figure><img alt="Antigravity extensions sekmesi" src="https://cdn-images-1.medium.com/max/727/1*QjKkvTDCd3bLSHVoSw24DA.png" /><figcaption>Antigravity extensions sekmesi</figcaption></figure><p>Claude Code açıldığında dosya sistemine, terminale ve versiyon sistemine erişimi olan bir oturum başlıyor. Bu oturumu mevcut bir klasörde başlatabilir ya da terminal üzerinde sıfırdan bir klasör açıp oradan devam edebilirsin.</p><p>Bu projede skill-creator aracını kullanarak proje için gerekli skilleri oluşturdum. Claude Code’un skill sistemi, tekrarlayan iş akışlarını /komut şeklinde paketlemeyi sağlıyor. Kurulum adımlarının detaylarını &quot;Skill Oluşturmak&quot; başlığı altında bulabilirsiniz.</p><h3>Projeyi Claude Code ile Başlatmak</h3><p><strong>/init ile projeyi tanıtmak</strong></p><p>Boş bir klasör açtım ve Claude Code içinde ilk komutu çalıştırdım:</p><pre>/init</pre><p>Claude Code klasörü taradı, boş olduğunu gördü ve birkaç satırlık minimal bir CLAUDE.md oluşturdu:</p><pre># CLAUDE.md<br><br>This file provides guidance to Claude Code when working in this repository.</pre><p>Sonra şunu sordu: “Ne inşa ediyorsun?”</p><p>Bu soru önemli. Claude Code her yeni oturumda hafızasını sıfırlar. Projeyi tanımayan biri gibi başlar. CLAUDE.md tam bu aşamada devreye giriyor: rehber oluyor. Her oturumun başında Claude’un okuduğu, projenin bağlamını, teknik kısıtlarını ve mimari kararlarını taşıyor.</p><p><strong>CLAUDE.md için iki pratik kural:</strong></p><p>Birincisi, dosyayı 200 satırın altında tut. Daha uzun dosyalar Claude’un bağlam penceresini doldurmaya başlıyor ve bu durum yanıt kalitesini doğrudan etkiliyor.</p><p>İkincisi, her şeyi tek dosyada tutmak yerine parçalara böl. Genel proje bağlamı CLAUDE.md’de kalırken, güvenlik kuralları veya API davranışları gibi konular ayrı rule dosyalarına taşınabilir. Claude bu dosyaları yalnızca ilgili oldukları durumlarda yükler.</p><p><strong>Klasör yapısını kurmak</strong></p><p>CLAUDE.md oluşturduktan sonra projenin ilk klasör yapısını Claude Code ile birlikte kurdum. İlk versiyon şu şekildeydi:</p><pre>youtube-analytics-pipeline/<br>├── CLAUDE.md<br>├── .gitignore<br>├── .env<br>├── README.md<br>├── .claude/<br>│   └── skills/<br>├── src/<br>├── data/<br>└── outputs/</pre><p>Credential dosyaları repo dışında güvenli bir konumda tutuldu. Path tanımlarını taşıyan .env dosyası ise repo kök dizininde duruyor ama .gitignore ile takip dışı bırakıldığı için repo&#39;ya hiçbir zaman girmiyor. Bu, credential yönetiminde yaygın kullanılan bir yapı: dosyalar dışarıda, path&#39;ler .env içinde, .env ise git&#39;in görmediği bir dosyada.</p><p>Claude Code ile dosyaları oluşturduktan sonra klasör yapısını ve dosya içeriklerini kontrol etmek önemli; her dosyanın amacına uygun oluşturulduğundan emin olmak gerekiyor.</p><p>Claude Code’da dosya düzenleme izinleri farklı modlarda yönetiliyor, ben bu projede genel olarak iki mod kullandım. Proje kurulum aşamasında, dosya oluşturma sürecinin hızlı ilerlemesi için Edit automatically modunu seçtim; bu aşamadaki dosyalar henüz kritik değildi ve her adımı tek tek onaylamak süreci yavaşlatacaktı. Production kod yazarken, özellikle BigQuery’e veri yazan kritik scriptlerde ise Ask before edits moduna geçtim; bu modda Claude Code her değişiklik öncesinde onay istiyor.</p><p>Python environment kurulu değilse bu aşamada Claude Code üzerinden de kurulumu tamamlayabilirsin; tüm paketlerin hazır olması ilerleyen adımlarda gerekli olacak.</p><h3>Skill Oluşturmak</h3><p>Skill’ler, Claude Code’da tekrarlayan iş akışlarını /komut şeklinde çağırmayı sağlıyor. Bu projede en çok yararlandığım özelliklerden biri oldu. Oluşturduğum skill dosyalarını da projedeki .claude klasörü altında tuttum.</p><p><strong>Skill creator kurulumu</strong></p><p>Skill oluşturmak için önce skill creator’ı yüklemen gerekir. Claude Code içine aşağıdaki komutu yaz:</p><pre>/manage plugins</pre><p>Açılan marketplace ekranında skill-creator@claude-plugins-official arat ve ardından ekle.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/617/1*b9m7uHmFkvifYKSpBd41Cg.png" /><figcaption>Claude Code ekranı — manage plugins komutu (1)</figcaption></figure><p>Ekledikten sonra Claude Code’u yeniden başlat.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/603/1*Qq7HV3pGE2Y43aTukZe0BQ.png" /><figcaption>Claude Code ekranı — manage plugins komutu (2)</figcaption></figure><p>Yeniden başlattıktan sonra Claude Code’a “skill creator skill aktif mi?” diye sorabilirsin. Aktifse, “Bu proje için BigQuery-GCP skill’i oluşturmak istiyorum” gibi bir mesajla süreci başlatabilirsin. Skill creator sana sorular soruyor: skill ne zaman devreye girsin, hangi adımları izlesin, çıktı formatı nasıl olsun. Cevapladıkça SKILL.md dosyasını otomatik oluşturuyor.</p><p>Skill oluşturulduktan sonra “commit this” komutu ile skilli kaydedebilirsin. Artık Claude Code ekranına /bigquery-gcp yazmak yeterli; bu komutu yazdığında SKILL.md içindeki tüm talimatlar ve proje bağlamı otomatik olarak yüklenir.</p><p>/eval komutu ise skill&#39;in aktif olduğu ve olmadığı versiyonları karşılaştırıp gerekirse güncelleme öneriyor; çıktıları kendin de kontrol ederek skill&#39;in beklediğin gibi çalışıp çalışmadığını doğrulayabilirsin.</p><h3>GCP Altyapısını Kurmak</h3><p>Claude Code ile projeyi başlattıktan sonra GCP tarafına geçtim. Adımların sırası burada önemli.</p><p><strong>1. Proje oluştur</strong></p><p>console.cloud.google.com/projectcreate adresinden yeni bir proje oluşturdum. Bölge seçiminde EU tercih ettim; veri lokasyonu ilerleyen aşamalarda BigQuery dataset’i ile tutarlı olmalı.</p><p><strong>2. API’leri aktif et</strong></p><p>API library üzerinden 3 API’yi aktif hale getirdim:</p><ul><li>YouTube Data API v3</li><li>YouTube Analytics API</li><li>Google Ads API</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*e_LLAghKoyvjnRb6Bygh_g.png" /><figcaption>Google Cloud — Api Library</figcaption></figure><p>Her biri için “Enable” butonuna tıklamak yeterli. Ama aktif etmeden önce hangi kimlik doğrulama yöntemini kullanacağını bilmek gerekiyor; bu OAuth ve servis hesabı arasındaki farkı doğrudan etkiliyor.</p><p><strong>3. Servis hesabı oluştur ve rol ata</strong></p><p>IAM &amp; Admin bölümünden “+ CREATE SERVICE ACCOUNT” ile servis hesabını oluştur. Pipeline’ın BigQuery’e yazabilmesi için iki rol gerekiyor:</p><ul><li>BigQuery Data Editor</li><li>BigQuery Job User</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/340/1*OkSvjzLmT6Hk_FCJnPUFKA.png" /><figcaption>Google Cloud-IAM ekranı</figcaption></figure><p>BigQuery Data Editor olmadan tablo yazmak mümkün değil. Job User olmadan ise sorgu çalıştırmak mümkün değil. İkisi birlikte çalışıyor.</p><p>Servis hesabı oluşturulduktan sonra JSON key indir. Bu dosyayı repo içine koymayacağız; credential yönetimi bir sonraki bölümde ele alınıyor.</p><p><strong>4. OAuth consent screen ve Client ID</strong></p><p>YouTube Analytics API ve Google Ads API için OAuth 2.0 gerekiyor. Önce consent screen kurulmalı, bu zorunlu bir ön adım.</p><p>Consent screen’de “External” seçtim. Sonrasında “Test users” bölümüne yetkilendirilmesi gereken Google hesabını ekledim. Bu adımı atlarsan OAuth akışı çalışmıyor; yetkilendirme ekranı açılıyor ama erişim reddediliyor.</p><p>Consent screen tamamlandıktan sonra her API için ayrı OAuth client oluşturdum. Pipeline, Python script olacağı için application type olarak “Desktop app” seçmek gerekiyor. Son adımda ise her biri için client secret JSON dosyasını indirmemiz gerekli.</p><h3>Credentials’ları Güvenli Tutmak</h3><p>Bu kurulumun sonunda elimizde üç credential dosyası var: BigQuery servis hesabının JSON key’i ve iki API için oluşturulan OAuth client secret dosyaları. Üçü de repo dışında tutulmalı.</p><p>Credential dosyaları repo dışında, güvenli bir konumda. Kod tarafında bu dosyalara giden path’ler .env dosyasında tanımlanıyor:</p><pre>GOOGLE_APPLICATION_CREDENTIALS=/path/to/credentials/youtube-pipeline-sa.json<br>YOUTUBE_OAUTH_CLIENT=/path/to/credentials/youtube-oauth-client.json<br>GOOGLE_ADS_OAUTH_CLIENT=/path/to/credentials/google-ads-oauth-client.json</pre><p>Script’ler credential path’lerini .env üzerinden okuyor; kodun içinde hiçbir yerde gerçek path veya key bilgisi geçmiyor. GOOGLE_APPLICATION_CREDENTIALS ayrıca Google&#39;ın client kütüphanelerinin varsayılan olarak kontrol ettiği değişken; servis hesabı ile kimlik doğrulama bu değişken üzerinden otomatik çalışıyor.</p><p>Repo kök dizinindeki .gitignore:</p><pre># Python<br>__pycache__/<br>*.pyc<br><br># Credentials<br>.env<br>*.json<br><br># Outputs<br>data/<br>outputs/<br><br># macOS<br>.DS_Store</pre><p>.env ve *.json kuralları burada iki ayrı amaca hizmet ediyor. .env dosyası credential path&#39;lerini taşıdığı için repo&#39;ya girmemeli. *.json kuralı ise ekstra bir güvenlik katmanı: credential dosyaları zaten repo dışında tutuluyor, ama proje büyüdükçe bir API yanıtının test amaçlı JSON olarak kaydedilmesi ya da yanlış klasörde oluşturulmuş bir key dosyası gibi durumlar ortaya çıkabiliyor. Bu kural o senaryolarda son savunma hattı olarak devreye giriyor.</p><p><strong>Kod değişmez, sadece kaynak değişir</strong></p><p>Bu yapının prod ortamına taşınırken asıl değeri ortaya çıkıyor. Local’de .env dosyasından okunan değişkenler, Cloud Run&#39;da Secret Manager&#39;dan inject ediliyor. İkisinde de değişken isimleri aynı; kod tarafında hiçbir şey değişmiyor.</p><pre>from dotenv import load_dotenv<br>import os<br><br>load_dotenv()  <br><br>creds_path = os.environ[&quot;GOOGLE_APPLICATION_CREDENTIALS&quot;]</pre><p>load_dotenv() zaten set edilmiş bir ortam değişkenini ezmez. Local&#39;de .env&#39;den okur, Cloud Run&#39;da Secret Manager&#39;dan gelen değeri korur. Production geçişinde kontrol edilmesi gereken tek şey değişken isimlerinin her iki ortamda birebir eşleşmesi. Koda dokunulmaz.</p><p><strong>Production’da bir adım ötesi</strong></p><p>Local geliştirme için JSON key ve .env yapısı işlevsel bir başlangıç noktası. Ancak production ortamında JSON key indirmek kurumsal güvenlik standartlarında bir risk olarak değerlendirilir: dosya rotasyonu manueldir, sızma durumunda denetim izi kırılgandır.</p><p>Cloud Run, kendi servis kimliğiyle GCP kaynaklarına erişebilir. GCP Workload Identity Federation ise servis hesabı JSON key kullanmadan kimlik doğrulamayı mümkün kılıyor. Bu seride production geçiş aşamasında (Makale 4) bu yapıya geçeceğiz; local kurulum ise bu makalede olduğu gibi kalacak.</p><h3>İlk Adımdan Sonra</h3><p>Bu noktada ortam hazır: Claude Code projeyi tanıyor, GCP altyapısı kurulu, credential’lar güvenli şekilde yapılandırılmış durumda. <a href="https://medium.com/@nurdadak/bigquery-mimarisi-nas%C4%B1l-kurulur-claude-code-ile-karar-alma-ve-token-y%C3%B6netimi-df9d03ec9ab4">Sıradaki adımda</a> BigQuery dataset hiyerarşisi, tablo tasarım kararları ve Youtube ve Google Ads API için token kurulumu var.</p><p>Bu makale “Agentic Data Pipeline” serisinin ilk bölümü. Sonraki makalelerde bu altyapının üzerine inşa etmeye devam edeceğiz.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=d315ed51a036" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Natural Language Analytics: How I Built a Google Analytics and Google Ads Assistant]]></title>
            <link>https://medium.com/design-bootcamp/natural-language-analytics-how-i-built-a-google-analytics-and-google-ads-assistant-bac0359c87e7?source=rss-ecd6ae87103d------2</link>
            <guid isPermaLink="false">https://medium.com/p/bac0359c87e7</guid>
            <category><![CDATA[data-engineering]]></category>
            <category><![CDATA[mcps]]></category>
            <category><![CDATA[google-analytics]]></category>
            <category><![CDATA[google-cloud-platform]]></category>
            <category><![CDATA[chatbots]]></category>
            <dc:creator><![CDATA[Nur Dadak Tomakin]]></dc:creator>
            <pubDate>Tue, 10 Mar 2026 09:13:50 GMT</pubDate>
            <atom:updated>2026-03-23T12:03:37.428Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*1Btw8vpXtPIjdOdU17vedw.png" /><figcaption>(Image by author)</figcaption></figure><p><strong>What if anyone on your team could query GA4 and Google Ads data in plain language, without opening a single dashboard?</strong></p><p>Most analytics workflows have a hidden bottleneck that nobody talks about openly. Dashboards are powerful, but they carry a silent assumption: the person looking at them knows what they’re looking for, knows how to read them, and has the time to dig through multiple views to find a single answer.</p><p>In practice, this rarely holds. A marketing manager wants to know which campaign drove the most engaged new users last quarter, not just clicks or sessions, but users who came back. A content team wants to compare two articles across traffic source, device type, and conversion behavior simultaneously. These are not exotic requests. But they almost never live in a pre-built dashboard, and building one for each question isn’t sustainable. The result: someone opens a ticket, a data analyst builds an ad hoc report, and the answer arrives two days later.</p><p>Interfaces change and dashboards evolve, but the gap between a question and its answer stays stubbornly wide. The analyst still needs to know which report to open, which filters to apply, and which platform holds which piece of data. To close that gap, I connected GA4 and Google Ads data directly to a conversational AI interface using MCP (Model Context Protocol). The result: any team member can ask a question in plain language and get an accurate answer in seconds, without opening a dashboard.</p><h3>What Is MCP and Why Does It Matter for Analytics?</h3><p>Model Context Protocol (MCP) is an open standard developed to let large language models connect directly to external data sources and tools in a structured, reliable way. Instead of copy-pasting data into a chat window or building custom API wrappers, MCP provides a clean protocol layer that sits between the LLM and the underlying data APIs.</p><p>For analytics, this is significant. The LLM doesn’t need to know SQL or the specifics of the GA4 Data API. It receives a natural language query, maps it to the right MCP tool, calls the API with the correct parameters, and returns a human-readable response. The complexity is abstracted away.</p><p>The architecture is straightforward:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*TNeSbk6yVR-Wy-NlCf0V5w.png" /></figure><p>Both MCP servers run locally and authenticate via Google Cloud’s Application Default Credentials (ADC), which means the same identity and permission model your organization already uses for GCP services.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*n376vKtYUwr5RmvwbsIIQA.png" /><figcaption>Gemini CLI — the interface used to query both MCP servers (Image by author)</figcaption></figure><h3>The Technical Stack</h3><p>The implementation uses two official MCP servers:</p><p><strong>analytics-mcp</strong> (Google Analytics MCP, experimental) provides six tools:</p><ul><li>run_report — standard analytics reports via the GA4 Data API</li><li>run_realtime_report — live visitor data</li><li>get_property_details — returns details about a specific GA4 property</li><li>list_google_ads_links — returns linked Google Ads accounts for a property</li><li>get_account_summaries — account and property overview</li><li>get_custom_dimensions_and_metrics — custom definitions for a property</li></ul><p><strong>google-ads-mcp</strong> (Google Ads MCP, experimental) provides:</p><ul><li>search — query Google Ads data using GAQL (Google Ads Query Language), abstracted through natural language</li><li>list_accessible_customers — enumerate accessible accounts under a manager account</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*lLqHQytSTs2G9r66PsVSOQ.png" /><figcaption>Both MCP servers running simultaneously (Image by author)</figcaption></figure><p>Authentication is handled through ADC with the appropriate OAuth scopes:</p><pre>{<br>  &quot;mcpServers&quot;: {<br>    &quot;analytics-mcp&quot;: {<br>      &quot;command&quot;: &quot;pipx&quot;,<br>      &quot;args&quot;: [&quot;run&quot;, &quot;analytics-mcp&quot;],<br>      &quot;env&quot;: {<br>        &quot;GOOGLE_APPLICATION_CREDENTIALS&quot;: &quot;/path/to/credentials.json&quot;,<br>        &quot;GOOGLE_PROJECT_ID&quot;: &quot;your-project-id&quot;<br>      }<br>    },<br>    &quot;google-ads-mcp&quot;: {<br>      &quot;command&quot;: &quot;pipx&quot;,<br>      &quot;args&quot;: [&quot;run&quot;, &quot;google-ads-mcp&quot;],<br>      &quot;env&quot;: {<br>        &quot;GOOGLE_APPLICATION_CREDENTIALS&quot;: &quot;/path/to/credentials.json&quot;,<br>        &quot;GOOGLE_PROJECT_ID&quot;: &quot;your-project-id&quot;,<br>        &quot;GOOGLE_ADS_DEVELOPER_TOKEN&quot;: &quot;your-developer-token&quot;<br>      }<br>    }<br>  }<br>}</pre><p>If accessing Google Ads through a manager account, add &quot;GOOGLE_ADS_LOGIN_CUSTOMER_ID&quot;: &quot;your-manager-account-id&quot; to the credentials.</p><p>Both servers load simultaneously in Gemini CLI, which means a single conversation can draw on both GA4 and Google Ads data and even correlate between them.</p><h3>What You Can Actually Do: Beyond the Dashboard</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*UqNyRILG5_lRGO0DUIcWZw.png" /><figcaption>The same question that took two days now takes seconds</figcaption></figure><p>This is where the real value becomes clear. The use cases that matter most aren’t the ones you could solve with a filter on an existing dashboard. They’re the questions that currently require a data analyst to step in.</p><p><strong>Multi-dimensional, comparative queries without pre-built views</strong></p><p>Consider this question: <em>“Compare the conversion funnel performance of our top two organic landing pages for users who arrived via paid search in the last 90 days, segmented by new vs. returning users.”</em></p><p>This query touches at least four dimensions simultaneously: landing page, acquisition channel, user type, and conversion behavior, across a 90-day window. No standard dashboard accommodates this without custom configuration. With the chatbot, it’s a single prompt. The MCP layer handles the report construction, and Gemini synthesizes the response into a coherent analysis.</p><p><strong>Cross-platform correlation</strong></p><p>Because both MCP servers run in the same session, you can ask questions that bridge GA4 and Google Ads data directly:</p><p><em>“Which campaigns generated the most sessions that converted, and how did those users behave on-site compared to organic visitors over the same period?”</em></p><p>Previously, answering this meant exporting from two platforms, aligning on date ranges and attribution windows, and stitching the data together manually. Here it’s conversational.</p><p><strong>What surprised me: accessing data that dashboards can never show</strong></p><p>The most unexpected capability wasn’t the reporting flexibility. It was the GA4 Admin API access through analytics-mcp. Beyond standard reporting, this exposes property configuration data and account summaries that don&#39;t appear anywhere in the GA4 interface or Looker Studio- things like custom dimension definitions, property structure, and linked account details. For teams responsible for tracking governance, it means you can audit your setup in the same session where you&#39;re querying your data.</p><p>Then I started pushing it further. I prompted the assistant to conduct a hypothesis-driven bot traffic analysis based on observed anomalies, and it returned a structured investigation that would have taken hours to produce manually:</p><ul><li><em>“We’re seeing unusual traffic from specific geographies with overwhelming desktop dominance, near-identical browser/OS combinations, and outdated screen resolutions like 800×600 and 1280×1200. What does this fingerprint suggest about the traffic source?”</em> The chatbot identified the pattern as consistent with headless browser environments (Puppeteer, Playwright) running in virtualized cloud infrastructure, distinguishing between AI training crawlers, commercial scrapers, and malicious bots based on behavioral signatures.</li><li><em>“How do bots report screen resolutions that no real user device would have?”</em> The response explained that headless browsers default to legacy viewport sizes because they’re not rendering on physical monitors, and that virtualized display drivers report generic resolutions unless explicitly configured.</li><li><em>“What behavioral metrics definitively separate this traffic from genuine users?”</em> The analysis mapped specific GA4 signals: near-100% bounce rate, session duration of 0–1 seconds, exactly 1.0 pages per session, and 24/7 request patterns with no circadian rhythm. Individually explainable, but collectively conclusive.</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*00rgO6TrgdPpQlx6BdeOYg.png" /><figcaption>This is the kind of investigation no dashboard can conduct.</figcaption></figure><p>For anyone responsible for data quality, tracking governance, or ad measurement integrity, this represents a genuinely different category of capability.</p><p><strong>100+ language support out of the box</strong></p><p>Because the interface is powered by Gemini, the natural language layer supports over 100 languages with no additional configuration. A user can query in Turkish, Spanish, or Japanese and receive a response in the same language. For international teams, this removes a coordination layer that usually requires building localized dashboards or relying on translation intermediaries.</p><p><strong>AI-assisted summarization and trend analysis</strong></p><p>GA4 queries through analytics-mcp benefit directly from Gemini’s reasoning capabilities. Rather than returning raw numbers, the model can summarize trends, flag anomalies, and provide contextual interpretation. Asking <em>“What’s notable about traffic patterns over the last 30 days?”</em> returns an actual analytical narrative, not just a table.</p><h3>Deployment Flexibility</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*MA2V23bMz-rsuIfeMssHXw.png" /></figure><p>One of the practical advantages of this architecture is that it isn’t tied to a single interface. Gemini CLI is the development and testing environment, but the MCP servers themselves can be connected to any compatible LLM host.</p><p>For production deployment, the natural path is Google Cloud Run, containerizing both MCP servers behind a web interface (Flask or FastAPI) that any team member can access through a browser. The same authentication model carries over via service accounts.</p><p>From a deployment perspective, this means the chatbot can be embedded wherever your team already works: an internal analytics portal, a Slack integration, or a standalone web app. There’s no requirement to send users to a separate tool.</p><p>Role-based access is also straightforward to implement at the service account level. For example, giving marketing teams GA4 and Google Ads access, while limiting other groups to GA4 only.</p><p>It’s also worth noting that analytics-mcp and google-ads-mcp can be unified into a single interface. Running both in the same Gemini session is already the architecture described here — a single conversation that spans both data sources. Whether to expose them as one or two user-facing tools is an interface decision, not a technical constraint.</p><h3><strong>Key Takeaways</strong></h3><p>A few outcomes from the implementation were worth noting beyond what the documentation covers.</p><p>I didn’t expect the Admin API to be this useful. I went in expecting reporting capabilities, and that part worked as expected. What caught me off guard was being able to pull property configuration data directly: account structure, custom dimension definitions, linked services. Most GA4 implementations ignore the Admin API entirely because the Data API handles the reporting side. But if you’ve ever had to manually verify tracking setups across multiple properties, or spent an afternoon clicking through the GA4 interface to check whether a custom dimension was actually configured the way someone said it was, you know how tedious that gets. Having that accessible through a prompt is a different experience.</p><p>The natural language layer held up better than I assumed it would. I expected to iterate on prompts for complex queries, the kind where you’re crossing three or four dimensions at once. Most of them worked on the first try. The MCP tools give the model enough structure to figure out the right API call without much guidance. That changes things. The usual cycle of someone filing a request, an analyst building a one-off report, and the answer arriving two days later… this setup turns that into a single conversation. Not for every query, but for a surprisingly large share of them.</p><p>Cross-platform queries need some attention to how you phrase things. Combining GA4 and Google Ads in one response works, but the two platforms handle attribution differently and their time windows don’t always align cleanly. I ran into a few cases early on where the numbers looked reasonable but weren’t actually comparable because of mismatched lookback windows. Once you know to watch for that, it’s manageable. But it’s the kind of thing that can quietly produce misleading answers if you don’t.</p><p>One more thing worth mentioning: this runs outside a local terminal. With Cloud Run and a lightweight web framework, the same setup becomes something anyone on the team can use from a browser. That matters because the point isn’t that I can query data faster from my own machine. The point is that a marketing lead or a content strategist can ask a question and get an answer without waiting for someone on the analytics team to prioritize it.</p><p>If you’re a data analyst or analytics engineer looking to reduce the volume of ad hoc report requests while giving your team more independent access to data, MCP is worth exploring. The official repositories for both analytics-mcp and google-ads-mcp are public and actively maintained by Google.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=bac0359c87e7" width="1" height="1" alt=""><hr><p><a href="https://medium.com/design-bootcamp/natural-language-analytics-how-i-built-a-google-analytics-and-google-ads-assistant-bac0359c87e7">Natural Language Analytics: How I Built a Google Analytics and Google Ads Assistant</a> was originally published in <a href="https://medium.com/design-bootcamp">Bootcamp</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
    </channel>
</rss>