PushizoDocs

SQL sorgu ve SQL segment

Kitlenizi kural oluşturucunun yetmediği durumlarda SQL ile tanımlayın: izinli görünümler üzerinde salt okunur SELECT sorgusu çalıştırın, sonucu tabloda görün ve sonuçtaki kişileri segment olarak kaydedin. SQL segmenti…

Kitlenizi kural oluşturucunun yetmediği durumlarda SQL ile tanımlayın: izinli görünümler üzerinde salt okunur SELECT sorgusu çalıştırın, sonucu tabloda görün ve sonuçtaki kişileri segment olarak kaydedin. SQL segmenti elle veya zamanlanmış olarak 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 sql_segments, ADR-0087).

Görünümler

Sorgular yalnızca aşağıdaki görünümleri okuyabilir. Görünümler her zaman seçili app'in verisini döner; başka app'in satırları görünümde yer almaz. Şemasız (users) veya şemalı (sql_api.users) yazabilirsiniz.

GörünümKolonlar
usersuser_id, external_id, properties, tags, first_seen_at, last_active_at, session_count, usage_seconds, last_sentiment, created_at
subscriptionssubscription_id, user_id, channel, status, os, os_version, app_version, sdk_platform, device_model, locale, timezone, test_device, last_active_at, last_delivered_at, opted_in_at, unsubscribed_at, created_at
eventsevent_id, user_id, name, properties, value, source, occurred_at
deliveriesdelivery_id, message_id, user_id, channel, status, sent_at, delivered_at, opened_at, clicked_at, failed_at, created_at
messagesmessage_id, campaign_id, journey_run_id, source, status, name, category, created_at
campaignscampaign_id, name, type, status, category, labels, send_at, started_at, completed_at, created_at
segment_membershipssegment_id, user_id, computed_at
companiescompany_id, external_id, name, domain, properties, created_at, updated_at
company_memberscompany_id, user_id, role, created_at

Kişisel veri politikası gereği abonelik belirteci (e-posta adresi, telefon numarası, push belirteci), konum, reklam kimliği, IP adresi ve sağlayıcı hata metni görünümlere alınmamıştır.

Kurallar ve sınırlar

  • Tek ifade ve yalnızca SELECT (CTE, alt sorgu, JOIN, UNION, pencere fonksiyonları serbest). INSERT, UPDATE, DELETE, DDL, veri değiştiren CTE, SELECT INTO, FOR UPDATE ve birden çok ifade reddedilir.
  • Sorgu PostgreSQL'in kendi ayrıştırıcısıyla denetlenir. Yalnızca izinli fonksiyonlar (toplama, pencere, metin, sayı, tarih, JSON ve dizi yardımcıları) ve temel tip dönüşümleri kullanılabilir; pg_sleep, pg_read_file, dblink, set_config, current_setting gibi fonksiyonlar ve katalog tabloları (pg_*, information_schema) reddedilir.
  • Sorgu salt okunur bir transaction'da çalışır. Zaman aşımı varsayılan 10 sn, en çok 30 sn; satır sınırı varsayılan 500, en çok 5.000. Sonuç tablosu 2 MB'ı geçerse kesilir ve truncated: true döner.
  • Ret yanıtı 400 HS_VALIDATION_ERROR, details.code = "sql_rejected" ve details.reason (not_select, multiple_statements, forbidden_relation, forbidden_function, forbidden_type, forbidden_construct, syntax, empty, too_long) içerir. Zaman aşımı 422, details.code = "sql_timeout".

Örnek: son 30 günde en az üç satın alma yapan altın üyeler.

with buyers as (
  select user_id, count(*) as orders, sum(value) as total
    from events
   where name = 'purchase' and occurred_at > now() - interval '30 days'
   group by user_id
)
select u.user_id, u.external_id, b.orders, b.total
  from users u
  join buyers b on b.user_id = u.user_id
 where u.properties->>'tier' = 'gold' and b.orders >= 3
 order by b.total desc

Segment olarak kaydetme

Panel → Segmentler → SQL editörü → sorguyu çalıştırın → Segment olarak kaydet. Sorgu sonucunda user_id kolonu bulunmalıdır; bu kolondaki tekil kimlikler segmentin üyeleri olur.

  • Kimlikler yalnızca bu app'in kişileriyle eşleştirilir: sorguya başka bir app'in kimliği yazılsa bile üye olamaz. Birleştirilmiş bir kişinin kimliği hedef kişiye çevrilir.
  • Segment statiktir: üyelik kayıt, sorgu değişikliği ve yenileme anında hesaplanır. En çok 1.000.000 kişi; aşılırsa yenileme hata verir ve önceki üyelik korunur.
  • Yenileme aralığı: elle, 1, 6, 12 veya 24 saat. Zamanlanmış yenilemeyi worker 5 dakikada bir tarar; hata olursa segmentin sql.last_error alanına kod yazılır ve önceki üyelik korunur.
  • SQL segmentinin kural tanımı ve dinamik/statik türü segment uçlarından değiştirilemez; adı ve açıklaması değiştirilebilir, silme her zamanki gibi DELETE /segments/{id} ile yapılır.

API

Sorgu users:read, şema ve kayıt okuma segments:read, segment oluşturma/güncelleme/yenileme admin kapsamı ister.

curl -X POST https://api.pushizo.com/v1/apps/$APP_ID/sql/query \
  -H "Authorization: Bearer $PUSHIZO_API_KEY" -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{"query": "select user_id, external_id from users where properties->>'tier' = 'gold'", "row_limit": 100}
JSON

curl -X POST https://api.pushizo.com/v1/apps/$APP_ID/sql/segments \
  -H "Authorization: Bearer $PUSHIZO_API_KEY" -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{"name": "Altın üyeler", "query": "select user_id from users where properties->>'tier' = 'gold'", "refresh_interval_minutes": 1440}
JSON
UçAçıklama
GET /v1/apps/{app}/sql/schemaGörünümler, kolonlar ve sınırlar
POST /v1/apps/{app}/sql/querySorgu çalıştır (query, row_limit, timeout_ms); satırlar kolon sırasıyla dizi
GET /v1/apps/{app}/sql/runsSorgu kaydı (segment_id, status, limit, cursor)
GET /v1/apps/{app}/sql/segmentsSQL segmentleri
POST /v1/apps/{app}/sql/segmentsSorgudan segment (name, description, query, refresh_interval_minutes)
PATCH /v1/apps/{app}/sql/segments/{id}Ad, açıklama, sorgu veya yenileme aralığı
POST /v1/apps/{app}/sql/segments/{id}/refreshŞimdi yenile

Node SDK: pushizo.sqlSegments.query({ query }), createSegment(...), refreshSegment(id).

Sorgu kaydı ve güvenlik

Panel, API ve zamanlanmış yenileme çalıştırmalarının hepsi — reddedilenler ve zaman aşımına uğrayanlar dahil — sorgu kaydına yazılır: kaynak, kullanıcı/API anahtarı, sorgu metni ve özeti, durum, ret nedeni, satır sayısı ve süre. Kayıt panelde SQL editörünün altında ve GET /sql/runs ucunda görünür.

Savunma katmanları: ayrıştırıcı denetimi, ayrı bağlantıda salt okunur transaction, statement_timeout ve lock_timeout, yalnızca izinli görünümleri bulan arama yolu, app süzgeçli security_barrier görünümleri ve alttaki tablolarda satır düzeyi güvenlik (RLS). Sorgu ve yenileme uçlarında kullanıcı başına dakikada 30, app başına 60 istek sınırı vardır.

Bu sayfada