PushizoDocs

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

  1. Panelde Segmentler → Ambar sorgusu sayfasında bir ambar bağlantısı eklenir (kimlik bilgisi şifreli saklanır).
  2. Sorgu, kimlik kolonu ve maliyet tavanı girilir; Maliyet tahmini ile sorgu çalıştırılmadan denetlenir.
  3. 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

AmbarAyarlarKimlik bilgisiAPI
BigQueryproject_id, isteğe bağlı locationServis hesabı JSON'u (service_account_json)jobs.query + getQueryResults, servis hesabı JWT ile OAuth2
Snowflakeaccount, user, warehouse, isteğe bağlı database, schema, roleAnahtar çifti özel anahtarı (private_key, şifresiz PKCS#8 PEM)SQL API v2, anahtar çifti JWT
Databrickshost, warehouse_id, isteğe bağlı catalog, schemaKiş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'te SELECT 1.
  • App başına en çok 10 bağlantı. Segmentlerin kullandığı bağlantı silinemez.

Sorgu kuralları

  • Tek ifade, SELECT veya WITH ile 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. Snowflake SYSTEM$ ve Databricks reflect/java_method fonksiyonları 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ırVarsayılanAralıkUygulama
Zaman aşımı120 sn10–600 snBigQuery: süre dolunca jobs.cancel; Snowflake: timeout (STATEMENT_TIMEOUT_IN_SECONDS); Databricks: süre dolunca cancel
En çok kişi1.000.0001–1.000.000Dış sorgunun LIMIT değeri; aşılırsa yenileme hata verir, üyelik kesilmez
BigQuery faturalanan bayt10 GiB10 MiB–10 TiBmaximumBytesBilled: tavanı aşan iş hiç çalışmaz (cost_limit_exceeded)
Snowflake ambar boyutuyokX-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'te EXPLAIN USING JSON ile atanan bayt ve ambar boyutu denetimi; Databricks'te EXPLAIN ile 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'de LIMIT taranan 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_error alanı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 koduAnlamı
cost_limit_exceededBigQuery maximumBytesBilled tavanı aşıldı
warehouse_too_largeSnowflake ambarı izin verilen boyuttan büyük
timeoutZaman aşımı; ifade/iş iptal edildi
too_many_membersEn çok kişi sınırı aşıldı
auth_failed, permission_deniedKimlik bilgisi veya yetki sorunu
rejectedAmbar sorguyu reddetti (ör. kolon veya tablo yok)
connection_missing, plan_feature_disabledBağ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öntemYolAçıklama
GET/optionsAmbarlar, kimlik türleri, Snowflake boyutları, yenileme aralıkları, sınırlar
GET, POST/connectionsBağlantıları listele, oluştur
GET, PATCH, DELETE/connections/{connectionId}Bağlantı ayrıntısı, güncelleme, silme
POST/connections/{connectionId}/testBağlantıyı dene
POST/previewdry_run veya sample önizleme
GET, POST/segmentsAmbar segmentlerini listele, oluştur
PATCH/segments/{segmentId}Ad, sorgu, bağlantı, kimlik kolonu, sınırlar, yenileme aralığı
POST/segments/{segmentId}/refreshYenilemeyi kuyruğa al
GET/runsAmbar 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.

Bu sayfada