Zero-copy ambar segmenti
Müşteri verinizi Pushizo'ya kopyalamadan, BigQuery, Snowflake veya Databricks ambarınızdaki tablolarla kitle tanımlayın. Yazdığınız SELECT sorgusu sizin ambarınızda çalışır; Pushizo'ya yalnızca seçtiğiniz kimlik kolonu…
Müşteri verinizi Pushizo'ya kopyalamadan, BigQuery, Snowflake veya Databricks ambarınızdaki tablolarla kitle tanımlayın.
Yazdığınız SELECT sorgusu sizin ambarınızda çalışır; Pushizo'ya yalnızca seçtiğiniz kimlik kolonu gelir ve bu
kimlikler kişilerinizle eşleştirilerek statik segment üyeliğine yazılır. Segment zamanlanmış veya elle yenilenir ve
kampanya, journey ve in-app kitlelerinde diğer segmentler gibi kullanılır. Growth ve üzeri planlarda açıktır (plan
özelliği warehouse_segments, ADR-0091).
Nasıl çalışır
- Panelde Segmentler → Ambar sorgusu sayfasında bir ambar bağlantısı eklenir (kimlik bilgisi şifreli saklanır).
- Sorgu, kimlik kolonu ve maliyet tavanı girilir; Maliyet tahmini ile sorgu çalıştırılmadan denetlenir.
- Segment kaydedilince ilk yenileme arka planda (worker) çalışır. Sorgu bir dış sorguyla sarılır:
SELECT DISTINCT CAST(hs_src.`external_id` AS STRING) AS hs_identity
FROM (<sizin sorgunuz>) AS hs_src
WHERE hs_src.`external_id` IS NOT NULL
LIMIT <en çok kişi + 1>Sorgunuz başka kolonlar döndürse de ambardan yalnızca hs_identity çıkar. Kimlikler yalnız bu app'in kişileriyle
eşleştirilir (external_id veya user_id); birleştirilmiş kişi hedef kişiye çevrilir, eşleşmeyen kimlik atlanır.
Üyelik tek işlemde değiştirilir: yenileme başarısız olursa önceki üyelik korunur.
Bağlantılar
| Ambar | Ayarlar | Kimlik bilgisi | API |
|---|---|---|---|
| BigQuery | project_id, isteğe bağlı location | Servis hesabı JSON'u (service_account_json) | jobs.query + getQueryResults, servis hesabı JWT ile OAuth2 |
| Snowflake | account, user, warehouse, isteğe bağlı database, schema, role | Anahtar çifti özel anahtarı (private_key, şifresiz PKCS#8 PEM) | SQL API v2, anahtar çifti JWT |
| Databricks | host, warehouse_id, isteğe bağlı catalog, schema | Kişisel erişim belirteci (access_token) | SQL Statement Execution API |
- Kimlik bilgisi zarf şifrelemeyle saklanır, yanıtlarda ve loglarda yer almaz; yalnız ipucu (servis hesabı e-postası veya maskeli belirteç) gösterilir.
- Ambar hesabına yalnız okuma yetkisi verin. Pushizo ayrıca sorguyu doğrular, ancak asıl güvence ambardaki yetkidir.
- Bağlantıyı dene: BigQuery'de ücretsiz dry-run, Snowflake'te
SELECT CURRENT_VERSION(), Databricks'teSELECT 1. - App başına en çok 10 bağlantı. Segmentlerin kullandığı bağlantı silinemez.
Sorgu kuralları
- Tek ifade,
SELECTveyaWITHile başlar; sondaki tek;kabul edilir. - Yorum (
--,/* */,#), dolar tırnaklı metin, birden çok ifade ve yazma/oturum komutları (INSERT,UPDATE,DELETE,MERGE,CREATE,DROP,COPY,CALL,EXECUTE,INTO…) reddedilir. SnowflakeSYSTEM$ve Databricksreflect/java_methodfonksiyonları kullanılamaz. Tırnak içindeki metin denetimi etkilemez. - Kimlik kolonu sorgu sonucundaki bir kolon adıdır (harf veya alt çizgiyle başlar, en çok 128 karakter). Snowflake'te tırnaksız adlar büyük harfe çevrilir; kolonu sorguda tırnaksız yazın.
- Reddedilen sorgular da sorgu kaydına yazılır (
status = rejected,reason).
Maliyet tavanı
| Sınır | Varsayılan | Aralık | Uygulama |
|---|---|---|---|
| Zaman aşımı | 120 sn | 10–600 sn | BigQuery: süre dolunca jobs.cancel; Snowflake: timeout (STATEMENT_TIMEOUT_IN_SECONDS); Databricks: süre dolunca cancel |
| En çok kişi | 1.000.000 | 1–1.000.000 | Dış sorgunun LIMIT değeri; aşılırsa yenileme hata verir, üyelik kesilmez |
| BigQuery faturalanan bayt | 10 GiB | 10 MiB–10 TiB | maximumBytesBilled: tavanı aşan iş hiç çalışmaz (cost_limit_exceeded) |
| Snowflake ambar boyutu | yok | X-Small … 6X-Large | Önce SHOW WAREHOUSES ile denetlenir; büyükse sorgu çalışmaz (warehouse_too_large) |
| Databricks satır sınırı | en çok kişi + 1 | — | Statement Execution API row_limit |
Önizleme
- Maliyet tahmini (
dry_run): sorgu çalıştırılmaz. BigQuery dry-run tahmini (ücretsiz) bayt olarak döner ve tavanla karşılaştırılır; Snowflake'teEXPLAIN USING JSONile atanan bayt ve ambar boyutu denetimi; Databricks'teEXPLAINile sorgu derlenir (bayt tahmini yoktur). - Örnek getir (
sample): önce maliyet tahmini yapılır, tavan aşılmıyorsa sorgu en çok 20 kimlikle çalışır ve kişilerinizle eşleşen sayı gösterilir. BigQuery'deLIMITtaranan baytı azaltmaz; örnek sorgu ücretlendirilebilir.
Yenileme
- Aralık: elle, 1, 6, 12 veya 24 saatte bir. Worker zamanlayıcısı dakikada bir zamanı gelen segmentleri kuyruğa alır.
- Elle yenileme ve sorgu, bağlantı, kimlik kolonu veya kimlik türü değişikliği yenilemeyi kuyruğa alır (yanıt
202). Kuyrukta bekleyen istek varken ikinci iş eklenmez; 30 dakikadan eski bekleyen istek yeniden istenebilir. - Yenileme işi yeniden denenmez (her deneme ücretli sorgudur); hata kodu segmentin
last_erroralanına, ayrıntı sorgu kaydına yazılır. Planı kapalı org'un segmentleri zamanlayıcıda atlanır. - Segment durumu (
refresh_state):queued,ok,failed,never.
| Hata kodu | Anlamı |
|---|---|
cost_limit_exceeded | BigQuery maximumBytesBilled tavanı aşıldı |
warehouse_too_large | Snowflake ambarı izin verilen boyuttan büyük |
timeout | Zaman aşımı; ifade/iş iptal edildi |
too_many_members | En çok kişi sınırı aşıldı |
auth_failed, permission_denied | Kimlik bilgisi veya yetki sorunu |
rejected | Ambar sorguyu reddetti (ör. kolon veya tablo yok) |
connection_missing, plan_feature_disabled | Bağlantı yok veya plan özelliği kapalı |
API
Panel uçları /internal/v1/apps/{app}/warehouse-segments/..., public uçlar /v1/apps/{app}/warehouse-segments/...
altındadır. Public API'de okuma segments:read, bağlantı, önizleme ve yazma admin kapsamı ister.
| Yöntem | Yol | Açıklama |
|---|---|---|
GET | /options | Ambarlar, kimlik türleri, Snowflake boyutları, yenileme aralıkları, sınırlar |
GET, POST | /connections | Bağlantıları listele, oluştur |
GET, PATCH, DELETE | /connections/{connectionId} | Bağlantı ayrıntısı, güncelleme, silme |
POST | /connections/{connectionId}/test | Bağlantıyı dene |
POST | /preview | dry_run veya sample önizleme |
GET, POST | /segments | Ambar segmentlerini listele, oluştur |
PATCH | /segments/{segmentId} | Ad, sorgu, bağlantı, kimlik kolonu, sınırlar, yenileme aralığı |
POST | /segments/{segmentId}/refresh | Yenilemeyi kuyruğa al |
GET | /runs | Ambar sorgu kaydı |
curl -X POST https://api.pushizo.com/v1/apps/$APP_ID/warehouse-segments/segments \
-H "Authorization: Bearer $PUSHIZO_API_KEY" -H "Content-Type: application/json" \
-d '{"name":"Yüksek değerli müşteriler","connection_id":"whc_...","query":"select external_id from analytics.customers where lifetime_value > 500","id_column":"external_id","id_type":"external_id","refresh_interval_minutes":1440,"limits":{"timeout_seconds":300,"max_bytes_billed":5368709120}}'Node SDK: pushizo.warehouseSegments.createConnection(...), .preview(...), .createSegment(...),
.refreshSegment(id), .runs(...).
Kural uçları (PATCH /segments/{id} tanım/tür, POST /segments/{id}/refresh) ambar segmentinde HS_BAD_REQUEST
(details.code = warehouse_segment) döner; ad, açıklama ve silme ortaktır.
Yerel geliştirme ve doğrulama
PROVIDER_MODE=mock iken ambar istekleri ağa çıkmaz: mock sürücü sorgunuzdaki tek tırnaklı dizgeleri kimlik satırı
olarak döner (... where external_id in ('u-1', 'u-2')), BigQuery dry-run tahmini 20 MiB'dir. Gerçek hesaplarla
doğrulama (BigQuery servis hesabı, Snowflake anahtar çifti, Databricks belirteci) ortamınızda yapılmalıdır.