Netsis INCKEYNO ile Artımlı Veri Çekme: Entegrasyon SQL Deseni

Netsis'te entegrasyon yaparken tüm tabloyu her seferinde çekmek yerine yalnızca yeni veya değişen kayıtları almak hem performans hem de kaynak kullanımı açısından kritiktir. Bu amaçla Netsis'in hemen tüm hareket tablolarında bulunan artan sıra numarası (INCKEYNO veya INC_KEY_NUMBER) kullanılarak "watermark" tabanlı artımlı veri çekme (incremental extraction) yöntemi uygulanır. Bu yazıda, TBLSTHAR ve TBLCAHAR özelinde INCKEYNO ile nasıl sadece yeni kayıtların çekileceğini, dikkat edilmesi gereken limitasyonları ve pratik SQL desenlerini paylaşıyoruz.

INCKEYNO ve INC_KEY_NUMBER Nedir?

Netsis hareket tablolarında her satıra otomatik olarak atanan, tekil ve sürekli artan bir sıra numarası bulunur. Bu numara:

İki isim farklı olsa da işlev aynıdır: tabloya kayıt eklendikçe değer monoton artar. Daha önce girilmiş bir kaydın INCKEYNO değeri asla küçülmez veya tekrar kullanılmaz (kolon tipik olarak IDENTITY'dir). Bu özellik, "son alınan ID'den büyük olanları getir" mantığıyla yeni kayıtları yakalamak için idealdir.

Artımlı Veri Çekme Mantığı

Entegrasyon uygulamanızda aşağıdaki akışı uygulayabilirsiniz:

1. İlk çalıştırmada tüm tabloyu çekin ve en büyük INCKEYNO'yu bir watermark tablosuna kaydedin.
2. Sonraki çalışmalarda WHERE INCKEYNO > @son_inc filtresiyle yalnızca yeni eklenen kayıtları alın.
3. Çektiğiniz maksimum INCKEYNO'yu tekrar watermark'a yazın.

Bu yöntem ekleme (INSERT) işlemlerini güvenle yakalar. Ancak güncelleme (UPDATE) ve silme (DELETE) işlemleri INCKEYNO değişikliğine neden olmadığı için artımlı sorguda görünmez. Bu nedenle eğer sisteminizde var olan kayıtların güncellenmesi veya silinmesi söz konusuysa, periyodik tam yükleme (full refresh) veya alternatif değişiklik yakalama yöntemleri uygulanmalıdır.

TBLSTHAR İçin İlk Yükleme ve Artımlı SQL

Aşağıdaki örneklerde @son_inc değişkeni bir önceki çalışmadan alınan en yüksek INCKEYNO'yu temsil eder. İlk yükleme için 0 olarak varsayılır.

İlk yükleme (veya watermark sıfırlandığında):

-- TBLSTHAR'daki tüm kayıtları sırayla al ve watermark'ı belirle
SELECT TOP 100000 INCKEYNO, STHAR_TARIH, FISNO, STOK_KODU,
       STHAR_GCKOD, STHAR_GCMIK, STHAR_NF, STHAR_FTIRSIP, STHAR_HTUR,
       DEPO_KODU, STHAR_CARIKOD, SUBE_KODU
FROM TBLSTHAR
ORDER BY INCKEYNO;
-- Sonuçtaki en büyük INCKEYNO'yu watermark olarak sakla.

Eğer büyük veri setiyle çalışıyorsanız, sayfa sayfa almak için OFFSET-FETCH veya WHERE INCKEYNO > @son_inc AND INCKEYNO <= @son_inc + 10000 gibi aralık sorguları yapabilirsiniz.

Sonraki artımlı yükleme:

-- @son_inc: bir önceki çalışmadan alınan max INCKEYNO
DECLARE @son_inc INT = 54231; -- örnek

SELECT INCKEYNO, STHAR_TARIH, FISNO, STOK_KODU,
       STHAR_GCKOD, STHAR_GCMIK, STHAR_NF, STHAR_FTIRSIP, STHAR_HTUR,
       DEPO_KODU, STHAR_CARIKOD, SUBE_KODU
FROM TBLSTHAR
WHERE INCKEYNO > @son_inc
ORDER BY INCKEYNO;

Yukarıdaki sorgu yalnızca INCKEYNO 54231'den büyük olan satırları getirir. İşlem sonrası, çektiğiniz en büyük INCKEYNO'yu güncellemeyi unutmayın.

TBLCAHAR İçin Artımlı SQL

Aynı prensip INC_KEY_NUMBER ile uygulanır:

-- @son_key: önceki max INC_KEY_NUMBER
DECLARE @son_key INT = 12345;

SELECT INC_KEY_NUMBER, TARIH, VADE_TARIHI, CARI_KOD, BELGE_NO, ACIKLAMA,
       BORC, ALACAK, BAKIYE, HAREKET_TURU, DOVIZ_TURU, DOVIZ_TUTAR,
       PLASIYER_KODU, PROJE_KODU, SUBE_KODU
FROM TBLCAHAR
WHERE INC_KEY_NUMBER > @son_key
ORDER BY INC_KEY_NUMBER;

Bu sorgu son kayıttan sonra eklenen cari hareketleri verir.

Büyük Veri İçin Sayfalama (Batching) Stratejisi

Arayüz veya toplu işlem sırasında bellek tüketimini kontrol altında tutmak için sorguyu küçük gruplara bölebilirsiniz. Örneğin TBLSTHAR için:

DECLARE @son INT = 0, @batch_size INT = 5000;

WHILE EXISTS (SELECT 1 FROM TBLSTHAR WHERE INCKEYNO > @son)
BEGIN
    -- Batch veriyi geçici tabloya al
    CREATE TABLE #batch (
        INCKEYNO INT,
        STHAR_TARIH DATETIME,
        FISNO VARCHAR(15),
        STOK_KODU VARCHAR(35),
        STHAR_GCKOD CHAR(1),
        STHAR_GCMIK DECIMAL(18,6),
        STHAR_NF DECIMAL(18,6)
    );

    INSERT INTO #batch
    SELECT TOP (@batch_size) INCKEYNO, STHAR_TARIH, FISNO, STOK_KODU,
           STHAR_GCKOD, STHAR_GCMIK, STHAR_NF
    FROM TBLSTHAR
    WHERE INCKEYNO > @son
    ORDER BY INCKEYNO;

    -- Burada batch veriyi işleyin (export, API gönderimi vs.)
    -- SELECT * FROM #batch;

    -- Watermark'ı güncelle
    SELECT @son = ISNULL(MAX(INCKEYNO), @son) FROM #batch;

    DROP TABLE #batch;
END

Bu döngü her seferinde 5000’er kayıt getirir ve son ID’yi takip ederek ilerler.

Sık yapılan hatalar

• INCKEYNO ile birlikte tarih filtresi kullanmamak: Artımlı çekimde WHERE INCKEYNO > @son yeterlidir; ayrıca tarih filtresi eklenirse, daha sonra eski tarihe girilmiş ancak yüksek INCKEYNO'lu kayıtları kaçırabilirsiniz. Watermark yönteminde tarih karıştırılmamalıdır.
• Silinen kayıtları beklemek: INCKEYNO silme sonucu değişmez. Silinen bir kaydı tespit edemezsiniz. Bunun için tam karşılaştırma (full diff) veya tetikleyici tabanlı yöntem gerekir.
• Güncellemeleri INCKEYNO ile yakalamaya çalışmak: Güncelleme varsa ve eski kayıt ID'si korunuyorsa, bu değişiklik artımlı sorguda görünmez. Mecburen tam yenileme yapmalısınız.
• Watermark değerini işlem tamamlanmadan güncellemek: İşlem sırasında hata alınırsa, watermark güncellenmediği için aynı kayıtları tekrar çekebilirsiniz (idempotent olmalı). Ancak watermark'ı erken güncellerseniz arada kalan veriler kaybolur. Daima başarılı işlemeden sonra güncelleyin.
• INCKEYNO'nun tablolar arası benzersiz olduğunu varsaymak: Her tablonun kendi bağımsız INCKEYNO serisi vardır. TBLSTHAR ve TBLCAHAR'daki değerler birbiriyle ilişkili değildir. Entegrasyonda her tablo için ayrı watermark tutmalısınız.

Sık sorulanlar

INCKEYNO sıfırlanır mı? Hayır, tipik kurulumlarda IDENTITY olduğu için değer sürekli artar. Veritabanı bakımı veya veri aktarımı sırasında bir müdahale olmadıkça sıfırlanmaz.

En yüksek INCKEYNO'dan sonra yeni kayıt gelmezse ne olur? Sorgu boş döner, sorun olmaz. Watermark değişmez.

Çok büyük miktarda veri birikmişse ilk yükleme nasıl yapılır? İlk defada WHERE INCKEYNO > 0 ile tüm tabloyu küçük batch'lerle çekmeniz önerilir; yukarıdaki döngü yöntemini kullanabilirsiniz.

Farklı tablolardan gelen verileri INCKEYNO'ya göre birleştirebilir miyim? Hayır, her tablonun serisi bağımsızdır. TBLSTHAR ve TBLCAHAR ancak iş mantığı (örn. FISNO) ile birleştirilir.

Netsis entegrasyonunuzda artımlı veri çekme desenini uygulamak, raporlama ve dış sistem besleme süreçlerinizi hızlandıracak. Daha fazla hazır sorgu için Netsis Hazır SQL Sorguları sayfasına göz atabilir; entegrasyon altyapısını sıfırdan kurmak isterseniz Özel Entegrasyon: Kendi Veritabanınızı Bağlama rehberimizi inceleyebilirsiniz. Hepsi bir yana, SQL yazmadan doğal dille sorgu üretmek için Erp Asistanı'nı ücretsiz kullanmaya başlayın.

Ücretsiz üye olun, istediğiniz sorguyu doğal dille alın →