Aracılığıyla paylaş

Tablo değerli parametreleri kullanma

JDBC sürücüsünü indirin

Tablo değerli parametreler, bir istemci uygulamasından SQL Server'a birden çok veri satırını aktarmanın kolay bir yolunu sağlar ve bu işlemi gerçekleştirmek için birden çok gidiş dönüşe veya özel sunucu tarafı mantığına gerek duymaz. Tablo değerli parametreleri kullanarak bir istemci uygulamasındaki veri satırlarını kapsülleyebilir ve verileri tek bir parametreli komutla sunucuya gönderebilirsiniz. Gelen veri satırları, transact-SQL kullanılarak üzerinde çalıştırılabilir bir tablo değişkeninde depolanır.

Tablo değerli parametrelerdeki sütun değerlerine standart Transact-SQL SELECT deyimleri kullanılarak erişilebilir. Tablo değerli parametreler kesin olarak yazılır ve yapıları otomatik olarak doğrulanır. Tablo değerli parametrelerin boyutu yalnızca sunucu belleğiyle sınırlıdır.

Uyarı

Microsoft JDBC Sürücüsü 6.0'dan itibaren SQL Server için Table-Valued Parameters desteği mevcuttur.

Tablo değerli bir parametrede veri döndüremezsiniz. Tablo değerli parametreler yalnızca giriştir; OUTPUT anahtar kelimesi desteklenmiyor.

Tablo değerli parametreler hakkında daha fazla bilgi için aşağıdaki kaynaklara bakın.

Resource Description
SQL Server Books Online'da Tablo Değerli Parametreler (Veritabanı Motoru) Tablo değerli parametrelerin nasıl oluşturulacağını ve kullanılacağını açıklar
SQL Server Books Online'da Kullanıcı Tanımlı Tablo Türleri Tablo değerli parametreleri bildirmek için kullanılan kullanıcı tanımlı tablo türlerini açıklar

SQL Server'ın önceki sürümlerinde birden çok satırın aktarımı

SQL Server 2008'e tablo değerli parametreler tanıtılmadan önce, birden çok veri satırını saklı yordam veya parametreli SQL komutuna aktarma seçenekleri sınırlıydı. Bir geliştirici, sunucuya birden çok satır geçirmek için aşağıdaki seçenekler arasından seçim yapabilir:

  • Birden çok sütundaki ve veri satırındaki değerleri göstermek için bir dizi bağımsız parametre kullanın. Bu yöntem kullanılarak geçirilebilen veri miktarı, izin verilen parametre sayısıyla sınırlıdır. SQL Server yordamlarında en fazla 2100 parametre olabilir. Bu tek tek değerleri işlemek üzere bir tablo değişkenine veya geçici bir tabloya birleştirmek için sunucu tarafı mantığı gereklidir.

  • Birden çok veri değerini sınırlandırılmış dizelerde veya XML belgelerinde paketleyin ve sonra bu metin değerlerini bir yordama veya deyime geçirin. Bunun için yordam veya ifadenin veri yapılarını doğrulamak ve değerlerin çözülmesi için gerekli mantığı içermesi gerekir.

  • Birden çok satırı etkileyen veri değişiklikleri için bir dizi bağımsız SQL deyimi oluşturun. Değişiklikler sunucuya tek tek gönderilebilir veya gruplar halinde toplu olarak oluşturulabilir. Ancak, birden çok deyim içeren toplu olarak gönderildiğinde bile, her deyim sunucuda ayrı olarak yürütülür.

  • Tabloya çok sayıda veri satırı yüklemek için bcp yardımcı programı veya SQLServerBulkCopy kullanın. Bu teknik verimli olsa da, veriler geçici bir tablo veya tablo değişkenine yüklenmediği sürece sunucu tarafı işlemeyi desteklemez.

Tablo türündeki parametreleri oluşturma

Tablo değerli parametreler, Transact-SQL CREATE TYPE deyimleri kullanılarak tanımlanan kesin olarak belirlenmiş tablo yapılarını temel alır. İstemci uygulamalarınızda tablo değerli parametreleri kullanabilmek için önce bir tablo türü oluşturmanız ve SQL Server'da yapıyı tanımlamanız gerekir. Tablo türleri oluşturma hakkında daha fazla bilgi için bkz. SQL Server Books Online'da User-Defined Tablo Türleri .

CREATE TYPE dbo.CategoryTableType AS TABLE  
    ( CategoryID int, CategoryName nvarchar(50) )

Tablo türü oluşturduktan sonra, tablo değerli parametreleri bu türe göre bildirebilirsiniz. Aşağıdaki Transact-SQL parçası, saklı yordam tanımında tablo değerli bir parametrenin nasıl ilan edileceğini göstermektedir. Bir tablo READONLY değerli parametre bildirmek için anahtar sözcük gereklidir.

CREATE PROCEDURE usp_UpdateCategories
    (@tvpNewCategories dbo.CategoryTableType READONLY)

Tablo değerli parametrelerle verileri değiştirme (Transact-SQL)

Tablo değerli parametreler, tek bir deyim yürütülerek birden çok satırı etkileyen küme tabanlı veri değişikliklerinde kullanılabilir. Örneğin, tablo değerli bir parametredeki tüm satırları seçip bir veritabanı tablosuna ekleyebilir veya güncelleştirmek istediğiniz tabloya tablo değerli bir parametre ekleyerek bir update deyimi oluşturabilirsiniz.

Aşağıdaki Transact-SQL UPDATE deyimi, tablo değerli bir parametreyi Kategoriler tablosuna birleştirerek nasıl kullanılacağını gösterir. FROM yan tümcesinde JOIN ile tablo değerli bir parametre kullandığınızda, burada belirtildiği gibi, tablo değerli parametreyi "ec" olarak adlandırmanız gerekir.

UPDATE dbo.Categories  
    SET Categories.CategoryName = ec.CategoryName  
    FROM dbo.Categories INNER JOIN @tvpEditedCategories AS ec  
    ON dbo.Categories.CategoryID = ec.CategoryID;

Bu Transact-SQL örneği, tek bir set tabanlı işlemde INSERT gerçekleştirmek için tablo değerli bir parametreden nasıl satır seçileceğini gösterir.

INSERT INTO dbo.Categories (CategoryID, CategoryName)  
    SELECT nc.CategoryID, nc.CategoryName FROM @tvpNewCategories AS nc;

Tablo değerli parametrelerin sınırlamaları

Tablo değerli parametrelerle ilgili çeşitli sınırlamalar vardır:

  • Tablo değerli parametreleri kullanıcı tanımlı işlevlere geçiremezsiniz.

  • Tablo değerli parametreler yalnızca UNIQUE veya PRIMARY KEY kısıtlamalarını desteklemek için dizinlenebilir. SQL Server, tablo değerli parametrelerle ilgili istatistikleri korumaz.

  • Tablo değerli parametreler Transact-SQL kodunda salt okunurdur. Tablo değerli bir parametrenin satırlarındaki sütun değerlerini güncelleştiremez ve satır ekleyemez veya silemezsiniz. Tablo değerli bir parametrede saklı yordam veya parametreli ifadeye geçirilecek verileri değiştirmek için,bu verileri geçici bir tabloya veya tablo değişkenine eklemeniz gerekir.

  • Tablo değerli parametrelerin tasarımını değiştirmek için ALTER TABLE deyimlerini kullanamazsınız.

  • Tablo değerli bir parametrede büyük nesnelerin akışını yapabilirsiniz.

Tablo değerli parametre yapılandırma

Microsoft JDBC Driver 6.0’dan itibaren SQL Server için, tablo değerli parametreler parametreli bir ifade veya parametreli bir saklı prosedür ile desteklenir. Tablo değerli parametreler SQLServerDataTable'dan, ResultSet'ten veya kullanıcı tarafından sağlanan ISQLServerDataRecord arabiriminin uygulamasından doldurulabilir. Hazırlanan sorgu için tablo değerli bir parametre ayarlarken, daha önce sunucuda oluşturulan uyumlu bir türün adıyla eşleşmesi gereken bir tür adı belirtmeniz gerekir.

Aşağıdaki iki kod parçası, veri eklemek için SQLServerPreparedStatement ve SQLServerCallableStatement ile tablo türündeki bir parametrenin nasıl yapılandırıldığını gösterir. Burada sourceTVPObject bir SQLServerDataTable, ResultSet veya ISQLServerDataRecord nesnesi olabilir. Örneklerde bağlantının etkin bir Connection nesnesi olduğu varsayılır.

// Using table-valued parameter with a SQLServerPreparedStatement.  
SQLServerPreparedStatement pStmt =
    (SQLServerPreparedStatement) connection.prepareStatement("INSERT INTO dbo.Categories SELECT * FROM ?");  
pStmt.setStructured(1, "dbo.CategoryTableType", sourceTVPObject);  
pStmt.execute();  

// Using table-valued parameter with a SQLServerCallableStatement.  
SQLServerCallableStatement pStmt =
    (SQLServerCallableStatement) connection.prepareCall("exec usp_InsertCategories ?");
pStmt.setStructured(1, "dbo.CategoryTableType", sourceTVPObject);;  
pStmt.execute();

Uyarı

Tablo değerli parametreyi ayarlamak için kullanılabilecek API'lerin tam listesi için aşağıdaki JDBC Sürücüsü için Tablo Değerli Parametre API'si Bölümüne bakın.

Tablo değerli bir parametreyi SQLServerDataTable nesnesi olarak gönderme

SQL Server için Microsoft JDBC Driver 6.0 sürümünden başlayarak, SQLServerDataTable sınıfı ilişkisel verilerin bellek içi tablosunu temsil eder. Bu örnek, SQLServerDataTable nesnesini kullanarak bellek içi verilerden tablo değerli bir parametrenin nasıl yapılandırıldığını gösterir. İlk olarak, kod bir SQLServerDataTable nesnesi oluşturur, şemasını tanımlar ve tabloyu verilerle doldurur. Kod daha sonra bu veri tablosunu SQL Server'a "tablo değerli parametre" olarak ileten bir SQLServerPreparedStatement'i yapılandırır.

/* Assumes connection is an active Connection object. */

// Create an in-memory data table.  
SQLServerDataTable sourceDataTable = new SQLServerDataTable();
  
// Define metadata for the data table.  
sourceDataTable.addColumnMetadata("CategoryID" ,java.sql.Types.INTEGER);
sourceDataTable.addColumnMetadata("CategoryName" ,java.sql.Types.NVARCHAR);
  
// Populate the data table.  
sourceDataTable.addRow(1, "CategoryNameValue1");
sourceDataTable.addRow(2, "CategoryNameValue2");
  
// Pass the data table as a table-valued parameter using a prepared statement.  
SQLServerPreparedStatement pStmt =
        (SQLServerPreparedStatement) connection.prepareStatement(  
            "INSERT INTO dbo.Categories SELECT * FROM ?;");  
pStmt.setStructured(1, "dbo.CategoryTableType", sourceDataTable);  
pStmt.execute();

Bu örnek, öncekine benzer. Tek fark, PreparedStatement'i SQLServerPreparedStatement'ya dönüştürerek setStructured yöntemini kullanmaya güvenmek yerine TVP Adı'nı SQLServerDataTable üzerinde ayarlamasıdır.

/* Assumes connection is an active Connection object. */

// Create an in-memory data table.
SQLServerDataTable sourceDataTable = new SQLServerDataTable();
sourceDataTable.setTvpName("dbo.CategoryTableType");

// Define metadata for the data table.
sourceDataTable.addColumnMetadata("CategoryID" ,java.sql.Types.INTEGER);
sourceDataTable.addColumnMetadata("CategoryName" ,java.sql.Types.NVARCHAR);

// Populate the data table.
sourceDataTable.addRow(1, "CategoryNameValue1");
sourceDataTable.addRow(2, "CategoryNameValue2");

// Pass the data table as a table-valued parameter using a prepared statement.
PreparedStatement pStmt =
        connection.prepareStatement(
            "INSERT INTO dbo.Categories SELECT * FROM ?;");
pStmt.setObject(1, sourceDataTable);
pStmt.execute();

Uyarı

Tablo değerli parametreyi ayarlamak için kullanılabilecek API'lerin tam listesi için aşağıda JDBC Sürücüsü için Tablo-Değerli Parametre API'si Bölümüne bakın.

Tablo değerli bir parametreyi ResultSet objesi olarak aktarımı

Bu örnekte, bir ResultSet'ten tablo değerli bir parametreye veri satırlarının nasıl akışla aktarıldığı gösterilmektedir. İlk olarak, kod SQLServerDataTable nesnesindeki bir kaynak tablodan veri alır, şemasını tanımlar ve tabloyu verilerle doldurur. Daha sonra kod, bu veri tablosunu tablo değeri olarak SQL Server'a ileten bir SQLServerPreparedStatement yapılandırır.

/* Assumes connection is an active Connection object. */

// Create the source ResultSet object. Here SourceCategories is a table defined with the same schema as Categories table.
ResultSet sourceResultSet = connection.createStatement().executeQuery("SELECT * FROM SourceCategories");  

// Pass the source result set as a table-valued parameter using a prepared statement.  
SQLServerPreparedStatement pStmt =
        (SQLServerPreparedStatement) connection.prepareStatement(  
                "INSERT INTO dbo.Categories SELECT * FROM ?;");  
pStmt.setStructured(1, "dbo.CategoryTableType", sourceResultSet);  
pStmt.execute();

Uyarı

JDBC Sürücüsü için Tablo Değerli Parametre API'si bölümüne aşağıda bakarak tablo değerli parametreyi ayarlamak için kullanılabilecek API'lerin tam listesini görebilirsiniz.

Tablo değerli bir parametreyi ISQLServerDataRecord nesnesi olarak geçirme

SQL Server için Microsoft JDBC Driver 6.0'den başlayarak, tablo değerli bir parametre kullanarak akış verileri için yeni bir ISQLServerDataRecord arabirimi (kullanıcının uygulamayı nasıl sağladığına bağlı olarak) kullanılabilir. Aşağıdaki örnek, ISQLServerDataRecord arabiriminin nasıl uygulanacağı ve tablolu değerli bir parametre olarak nasıl geçirileceği üzerine bir gösterim sunmaktadır. Kolaylık olması için aşağıdaki örnek, sabit kodlanmış değerleri olan tek bir satırı tablo değerli parametresine geçirir. İdeal olarak, kullanıcı herhangi bir kaynaktan(örneğin metin dosyalarından) satır akışı yapmak için bu arabirimi uygular.

class MyRecords implements ISQLServerDataRecord  
{  
    int currentRow = 0;  
    Object[] row = new Object[2];  
  
    MyRecords(){  
        // Constructor. This implementation has just one row.
        row[0] = new Integer(1);  
        row[1] = "categoryName1";  
    }  
  
    public int getColumnCount(){  
        // Return the total number of columns, for this example it is 2.  
        return 2;  
    }  
  
    public SQLServerMetaData getColumnMetaData(int columnIndex) {  
        // Return the column metadata.  
        if (1 == columnIndex)  
            return new SQLServerMetaData("CategoryID", java.sql.Types.INTEGER);  
        else  
            return new SQLServerMetaData("CategoryName", java.sql.Types.NVARCHAR);  
    }  
  
    public Object[] getRowData(){  
        // Return the columns in the current row as an array of objects. This implementation has just one row.  
        return row;
    }  
  
    public boolean next(){  
        // Move to the next row. This implementation has just one row, after processing the first row, return false.  
        currentRow++;  
        if (1 == currentRow)  
            return true;  
        else  
            return false;  
    }
}

// Following code demonstrates how to pass MyRecords object as a table-valued parameter.  
MyRecords sourceRecords = new MyRecords();  
SQLServerPreparedStatement pStmt =
        (SQLServerPreparedStatement) connection.prepareStatement(  
                "INSERT INTO dbo.Categories SELECT * FROM ?;");  
pStmt.setStructured(1, "dbo.CategoryTableType", sourceRecords);  
pStmt.execute();

Uyarı

Aşağıda, tablo değerli parametreyi ayarlamak için kullanılabilecek API'lerin tam listesini bulabileceğiniz JDBC sürücüsü için Tablo Değerli Parametre API'si Bölümü'ne bakın.

JDBC sürücüsü için tablo değerli parametreler API'si

SQLServerMetaData

Bu sınıf bir sütunun meta verilerini temsil eder. IsQLServerDataRecord arabiriminde sütun meta verilerini tablo değerli parametresine geçirmek için kullanılır. Bu sınıftaki yöntemler şunlardır:

İsim Description
public SQLServerMetaData(String columnName, int sqlType, int precision, int scale, boolean useServerDefault, boolean isUniqueKey, SQLServerSortOrder sortOrder, int sortOrdinal) Belirtilen sütun adı, sql türü, duyarlık, ölçek ve sunucu varsayılanı ile sqlServerMetaData'nın yeni bir örneğini başlatır. Bu oluşturucu biçimi, tablo değerli parametrede sütunun benzersiz olup olmadığını, sütunun sıralama düzenini ve sıralama sütununun sırasını belirtmenize olanak tanıyarak tablo değerli parametreleri destekler.

useServerDefault - Bu sütunun varsayılan sunucu değerini kullanıp kullanmaması gerektiğini belirtir; Varsayılan değer false'tur.
isUniqueKey - tablo değerli parametredeki sütunun benzersiz olup olmadığını gösterir; Varsayılan değer false'tur.
sortOrder - bir sütunun sıralama düzenini gösterir; Varsayılan değer SQLServerSortOrder.Unspecified değeridir.
sortOrdinal - sıralama sütununun sırasını belirtir; sortOrdinal 0'dan başlar; Varsayılan değer -1'dir.
public SQLServerMetaData(String columnName, int sqlType) Sütun adını ve sql türünü kullanarak sqlServerMetaData'nın yeni bir örneğini başlatır.
public SQLServerMetaData(String columnName, int sqlType, int length) Sütun adını, sql türünü ve uzunluğunu (Dize verileri için) kullanarak sqlServerMetaData'nın yeni bir örneğini başlatır. Uzunluk, büyük dizeleri uzunluğu 4000 karakterden az olan dizelerden ayırmak için kullanılır. JDBC sürücüsünün 7.2 sürümünde kullanıma sunulmuştur.
public SQLServerMetaData(String sütünIsmi, int sqlTipi, int duyarlılık, int ölçek) Sütun adı, SQL türü, kesinlik ve ölçek kullanarak SQLServerMetaData'nın yeni bir örneğini başlatır.
Public SQLServerMetaData(SQLServerMetaData sqlServerMetaData) Başka bir SQLServerMetaData nesnesinden yeni bir SQLServerMetaData örneği başlatır.
public String getColumName() Sütun adını alır.
public int getSqlType() JAVA SQL türünü alır.
public int getPrecision() Sütuna geçirilen türün kesinliği alınır.
public int getScale() Kolona geçirilen türün ölçeğini alır.
public SQLServerSortOrder getSortOrder() Sıralama düzenini alır.
public int getSortOrdinal() Sıralama sırasını alır.
public boolean isUniqueKey() Bir sütunun benzersiz olup olmadığını belirler.
public boolean useServerDefault() Sütunun varsayılan sunucu değerini kullanıp kullanmadığını döndürür.

SQLServerSortOrder

Bir sıralama sırasını tanımlayan bir Enum. Olası değerler Artan, Azalan ve Belirtilmeyen değerlerdir.

SQLServerDataTable

Bu sınıf, tablo değerli parametrelerle kullanım için tasarlanan bellek içi bir veri tablosunu temsil eder. Bu sınıftaki yöntemler şunlardır:

İsim Description
Public SQLServerDataTable() SQLServerDataTable'ın yeni bir örneğini başlatır.
public İteratör<Giriş<Tamsayı, Object[]>> getIterator() Veri tablosunun satırları üzerinde bir yineleyiciyi elde eder.
public void addColumnMetadata(String columnName, int sqlType) Belirtilen sütun için meta veriler ekler.
public void addColumnMetadata(SQLServerDataColumn sütunu) Belirtilen sütun için meta veriler ekler.
public void addRow(Object... değerler) Veri tablosuna bir veri satırı ekler.
public Map<Integer, SQLServerDataColumn> getColumnMetadata() Bu veri tablosunun sütun meta verilerini alır.
public void clear() Bu veri tablosunu temizler.

SQLServerDataColumn (SQL Sunucu Veri Sütunu)

Bu sınıf, SQLServerDataTable tarafından temsil edilen bellek içi veri tablosunun sütununu temsil eder. Bu sınıftaki yöntemler şunlardır:

İsim Description
public SQLServerDataColumn(String columnName, int sqlType) Sütun adı ve türüyle yeni bir SQLServerDataColumn örneği başlatır.
public String getColumnName() Sütun adını alır.
public int getColumnType() Sütun türünü alır.

ISQLServerDataRecord

Bu sınıf, kullanıcıların tablo değerli bir parametreye veri akışı yapmak için uygulayabileceği bir arabirimi temsil eder. Bu arabirimdeki yöntemler şunlardır:

İsim Description
public SQLServerMetaData getColumnMetaData(int sütunu); Verilen sütun indeksinin meta verilerini alır.
public int getColumnCount(); Toplam sütun sayısını alır.
public Object[] getRowData(); Geçerli satırın verilerini bir Nesneler dizisi olarak alır.
public boolean next(); Sonraki satıra geçer. Eğer taşıma başarılıysa ve sonraki satır varsa True döndürür, aksi takdirde false döndürür.

SQLServerPreparedStatement (SQL Server Hazır Beyanı)

Tablo değerli parametrelerin geçirilmesini desteklemek için aşağıdaki yöntemler bu sınıfa eklenmiştir.

İsim Description
public final void setStructured(int parameterIndex, String tvpName, SQLServerDataTable tvpDataTable) Tablo değerli bir parametreyi veri tablosuyla doldurur. parameterIndex parametre dizinidir, tvpName tablo değerli parametrenin adıdır ve tvpDataTable da kaynak veri tablosu nesnesidir.
public final void setStructured(int parameterIndex, String tvpName, ResultSet tvpResultSet) Tablo değerli bir parametreyi başka bir tablodan alınan ResultSet ile doldurur. parameterIndex parametre dizinidir, tvpName tablo değerli parametrenin adıdır ve tvpResultSet de kaynak sonuç kümesi nesnesidir.
public final void setStructured(int parameterIndex, String tvpName, ISQLServerDataRecord tvpDataRecord) Tablo değeri olan bir parametreyi ISQLServerDataRecord nesnesi ile doldurur. ISQLServerDataRecord, akış verileri için kullanılır ve bunun nasıl kullanılacağına kullanıcı karar verir. parameterIndex parametre dizinidir, tvpName tablo değerli parametrenin adıdır ve tvpDataRecord bir ISQLServerDataRecord nesnesidir.

SQLServerCallableStatement

Tablo değerli parametrelerin geçirilmesini desteklemek için aşağıdaki yöntemler bu sınıfa eklenmiştir.

İsim Description
public final void setStructured(String parametreAdı, String tvpAdı, SQLServerDataTable tvpVeriTablosu) Saklı yordamda kullanılan tablo değerli bir parametreyi bir veri tablosuyla doldurur. parameterName parametresinin adı, tvpName, TVP türünün adı ve tvpDataTable ise veri tablosu nesnesidir.
public final void setStructured(String parameterName, String tvpName, ResultSet tvpResultSet) Saklı yordama geçirilen tablo değerli parametreyi başka bir tablodan alınan ResultSet ile doldurur. parameterName parametresinin adıdır, tvpName TVP türünün adıdır ve tvpResultSet de kaynak sonuç kümesi nesnesidir.
public final void setStructured(String parameterName, String tvpName, ISQLServerDataRecord tvpDataRecord) Saklı yordama geçirilen tablo değerli bir parametreyi ISQLServerDataRecord nesnesiyle doldurur. ISQLServerDataRecord, akış verileri için kullanılır ve bunun nasıl kullanılacağına kullanıcı karar verir. parameterName parametresinin adıdır, tvpName, TVP türünün adıdır ve tvpDataRecord bir ISQLServerDataRecord nesnesidir.

Ayrıca bakınız

JDBC sürücüsüne genel bakış

  • Last updated on