Tugas Jalankan SQL
Berlaku untuk: SQL Server SSIS Integration Runtime di Azure Data Factory
Tugas Jalankan SQL menjalankan pernyataan SQL atau prosedur tersimpan dari paket. Tugas dapat berisi satu pernyataan SQL atau beberapa pernyataan SQL yang berjalan secara berurutan. Anda dapat menggunakan tugas Jalankan SQL untuk tujuan berikut:
Memotong tabel atau tampilan dalam persiapan untuk menyisipkan data.
Buat, ubah, dan hapus objek database seperti tabel dan tampilan.
Buat ulang tabel fakta dan dimensi sebelum memuat data ke dalamnya.
Jalankan prosedur yang tersimpan. Jika pernyataan SQL memanggil prosedur tersimpan yang mengembalikan hasil dari tabel sementara, gunakan opsi DENGAN KUMPULAN HASIL untuk menentukan metadata dengan kumpulan hasil.
Simpan himpunan baris yang dikembalikan dari kueri ke dalam variabel.
Tugas Jalankan SQL dapat digunakan dalam kombinasi dengan kontainer Foreach Loop dan For Loop untuk menjalankan beberapa pernyataan SQL. Kontainer ini menerapkan alur kontrol berulang dalam paket dan mereka dapat menjalankan tugas Jalankan SQL berulang kali. Misalnya, menggunakan kontainer Foreach Loop, paket dapat menghitung file dalam folder dan menjalankan tugas Execute SQL berulang kali untuk menjalankan pernyataan SQL yang disimpan di setiap file.
Menyambungkan ke sumber data
Tugas Jalankan SQL dapat menggunakan berbagai jenis manajer koneksi untuk menyambungkan ke sumber data tempat menjalankan pernyataan SQL atau prosedur tersimpan. Tugas dapat menggunakan tipe koneksi yang tercantum dalam tabel berikut ini.
Tipe sambungan | Manajer sambungan |
---|---|
EXCEL | Pengelola Koneksi Excel |
OLE DB | Pengelola Sambungan OLE DB |
ODBC | Pengelola Koneksi ODBC |
ADO | Pengelola Koneksi ADO |
ADO.NET | Pengelola Koneksi ADO.NET |
SQLMOBILE | Pengelola Koneksi SQL Server Edisi Compact |
Membuat pernyataan SQL
Sumber pernyataan SQL yang digunakan oleh tugas ini bisa menjadi properti tugas yang berisi pernyataan, koneksi ke file yang berisi satu atau beberapa pernyataan, atau nama variabel yang berisi pernyataan. Pernyataan SQL harus ditulis dalam dialek sistem manajemen database sumber (DBMS). Untuk informasi selengkapnya, lihat Kueri Integration Services (SSIS).
Jika pernyataan SQL disimpan dalam file, tugas menggunakan manajer koneksi File untuk menyambungkan ke file. Untuk informasi selengkapnya, lihat Pengelola Sambungan file.
Di SSIS Designer, Anda dapat menggunakan kotak dialog Jalankan Editor Tugas SQL untuk mengetik pernyataan SQL, atau menggunakan Query Builder, antarmuka pengguna grafis untuk membuat kueri SQL.
Catatan
Pernyataan SQL yang valid yang ditulis di luar tugas Jalankan SQL mungkin tidak berhasil diurai oleh tugas Jalankan SQL.
Catatan
Tugas Jalankan SQL menggunakan nilai enumerasi RecognizeAll ParseMode. Untuk informasi selengkapnya, lihat Namespace Layanan ManagedBatchParser.
Mengirim beberapa pernyataan dalam batch
Jika Anda menyertakan beberapa pernyataan dalam tugas Jalankan SQL, Anda dapat mengelompokkannya dan menjalankannya sebagai batch. Untuk memberi sinyal akhir batch, gunakan perintah GO. Semua pernyataan SQL antara dua perintah GO dikirim dalam batch ke penyedia OLE DB untuk dijalankan. Perintah SQL dapat menyertakan beberapa batch yang dipisahkan oleh perintah GO.
Ada batasan pada jenis pernyataan SQL yang dapat Anda kelompokkan dalam batch. Untuk informasi selengkapnya, lihat Batch Pernyataan.
Jika tugas Jalankan SQL menjalankan batch pernyataan SQL, aturan berikut berlaku untuk batch:
Hanya satu pernyataan yang dapat mengembalikan tataan hasil dan harus menjadi pernyataan pertama dalam batch.
Jika kumpulan hasil menggunakan pengikatan hasil, kueri harus mengembalikan jumlah kolom yang sama. Jika kueri mengembalikan jumlah kolom yang berbeda, tugas gagal. Namun, meskipun tugas gagal, kueri yang dijalankannya, seperti kueri DELETE atau INSERT, mungkin berhasil.
Jika pengikatan hasil menggunakan nama kolom, kueri harus mengembalikan kolom yang memiliki nama yang sama dengan nama kumpulan hasil yang digunakan dalam tugas. Jika kolom hilang, tugas gagal.
Jika tugas menggunakan pengikatan parameter, semua kueri dalam batch harus memiliki jumlah dan jenis parameter yang sama.
Jalankan perintah SQL berparameter
Pernyataan SQL dan prosedur tersimpan sering menggunakan parameter input, parameter output, dan kode pengembalian. Tugas Jalankan SQL mendukung jenis parameter Input, Output, dan ReturnValue . Anda menggunakan Jenis input untuk parameter input, Output untuk parameter output, dan ReturnValue untuk kode pengembalian.
Catatan
Anda dapat menggunakan parameter dalam tugas Jalankan SQL hanya jika penyedia data mendukungnya.
Tentukan jenis tataan hasil
Bergantung pada jenis perintah SQL, kumpulan hasil mungkin atau mungkin tidak dikembalikan ke tugas Jalankan SQL. Misalnya, pernyataan SELECT biasanya mengembalikan kumpulan hasil, tetapi pernyataan INSERT tidak. Hasil yang ditetapkan dari pernyataan SELECT dapat berisi baris nol, satu baris, atau banyak baris. Prosedur tersimpan juga dapat mengembalikan nilai bilangan bulat, yang disebut kode pengembalian, yang menunjukkan status eksekusi prosedur. Dalam hal ini, kumpulan hasil terdiri dari satu baris.
Mengonfigurasi tugas Jalankan SQL
Anda dapat mengonfigurasi tugas Jalankan SQL dengan cara berikut:
Tentukan tipe manajer koneksi yang akan digunakan untuk menyambungkan ke database.
Tentukan jenis kumpulan hasil yang dikembalikan oleh pernyataan SQL.
Tentukan batas waktu untuk pernyataan SQL.
Tentukan sumber pernyataan SQL.
Menunjukkan apakah tugas melewati fase persiapan untuk pernyataan SQL.
Jika Anda menggunakan jenis koneksi ADO, Anda harus menunjukkan apakah pernyataan SQL adalah prosedur tersimpan. Untuk jenis koneksi lainnya, properti ini bersifat baca-saja dan nilainya selalu salah.
Anda dapat mengatur properti secara terprogram atau melalui SSIS Designer.
Halaman Umum - Jalankan Editor Tugas SQL
Gunakan halaman Umum kotak dialog Jalankan Editor Tugas SQL untuk mengonfigurasi tugas Jalankan SQL dan berikan pernyataan SQL yang dijalankan tugas.
Untuk mempelajari selengkapnya tentang bahasa kueri Transact-SQL, lihat Referensi Transact-SQL (Mesin Database).
Opsi Statis
Nama
Berikan nama unik untuk tugas Jalankan SQL dalam alur kerja. Nama yang disediakan akan ditampilkan dalam SSIS Designer.
Keterangan
Jelaskan tugas Jalankan SQL. Sebagai praktik terbaik, untuk membuat paket mendokumentasikan diri dan lebih mudah dipertahankan, jelaskan tugas dalam hal tujuannya.
Timeout
Tentukan jumlah detik maksimum yang akan dijalankan tugas sebelum waktu habis. Nilai 0 menunjukkan waktu tak terbatas. Defaultnya adalah 0.
Catatan
Prosedur tersimpan tidak kehabisan waktu jika mereka meniru fungsionalitas tidur dengan memberikan waktu agar koneksi dibuat dan transaksi selesai yang lebih besar dari jumlah detik yang ditentukan oleh TimeOut. Namun, prosedur tersimpan yang menjalankan kueri selalu tunduk pada pembatasan waktu yang ditentukan oleh TimeOut.
CodePage
Tentukan halaman kode yang akan digunakan saat menerjemahkan nilai Unicode dalam variabel. Nilai default adalah halaman kode komputer lokal.
Catatan
Saat tugas Jalankan SQL menggunakan manajer koneksi ADO atau ODBC, properti CodePage tidak tersedia. Jika solusi Anda memerlukan penggunaan halaman kode, gunakan OLE DB atau manajer koneksi ADO.NET dengan tugas Jalankan SQL.
TypeConversionMode
Saat Anda mengatur properti ini ke Diizinkan, Tugas Jalankan SQL akan mencoba mengonversi parameter output dan hasil kueri ke jenis data variabel tempat hasil ditetapkan. Ini berlaku untuk jenis tataan hasil baris tunggal.
ResultSet
Tentukan jenis hasil yang diharapkan oleh pernyataan SQL yang sedang dijalankan. Pilih di antara Baris tunggal, Kumpulan hasil lengkap, XML, atau Tidak Ada.
ConnectionType
Pilih jenis manajer koneksi yang akan digunakan untuk menyambungkan ke sumber data. Jenis koneksi yang tersedia termasuk OLE DB, ODBC, ADO, ADO.NET dan SQLMOBILE.
Topik Terkait: OLE DB Pengelola Sambungan, ODBC Pengelola Sambungan, ADO Pengelola Sambungan, ADO.NET Pengelola Sambungan, SQL Server Compact Edition Pengelola Sambungan
Koneksi
Pilih koneksi dari daftar manajer koneksi yang ditentukan. Untuk membuat koneksi baru, pilih <Koneksi baru...>.
SQLSourceType
Pilih jenis sumber pernyataan SQL yang dijalankan tugas.
Bergantung pada jenis manajer koneksi yang digunakan tugas Jalankan SQL, Anda harus menggunakan penanda parameter tertentu dalam pernyataan SQL berparameter.
Properti ini memiliki opsi yang tercantum dalam tabel berikut.
Nilai | Deskripsi |
---|---|
Input langsung | Atur sumber ke pernyataan Transact-SQL. Memilih nilai ini menampilkan opsi dinamis, SQLStatement. |
Koneksi file | Pilih file yang berisi pernyataan Transact-SQL. Pengaturan opsi ini menampilkan opsi dinamis, FileConnection. |
Variabel | Atur sumber ke variabel yang menentukan pernyataan Transact-SQL. Memilih nilai ini menampilkan opsi dinamis, SourceVariable. |
QueryIsStoredProcedure
Menunjukkan apakah pernyataan SQL yang ditentukan yang akan dijalankan adalah prosedur tersimpan. Properti ini baca/tulis hanya jika tugas menggunakan manajer koneksi ADO. Jika tidak, properti bersifat baca-saja dan nilainya false.
BypassPrepare
Menunjukkan apakah pernyataan SQL disiapkan. benar melewati persiapan; false menyiapkan pernyataan SQL sebelum menjalankannya. Opsi ini hanya tersedia dengan koneksi OLE DB yang mendukung persiapan.
Topik Terkait: Eksekusi yang Disiapkan
Ramban
Temukan file yang berisi pernyataan SQL dengan menggunakan kotak dialog Buka . Pilih file untuk menyalin konten file sebagai pernyataan SQL ke dalam properti SQLStatement .
Buat Kueri
Buat pernyataan SQL menggunakan kotak dialog Pembangun Kueri, alat grafis yang digunakan untuk membuat kueri. Opsi ini tersedia saat opsi SQLSourceType diatur ke Input langsung.
Mengurai Kueri
Validasi sintaks pernyataan SQL.
Opsi Dinamis SQLSourceType
SQLSourceType = Input langsung
SQLStatement
Ketik pernyataan SQL untuk dijalankan dalam kotak opsi, atau klik tombol telusuri (...) untuk mengetik pernyataan SQL dalam kotak dialog Masukkan Kueri SQL, atau klik Buat Kueri untuk menyusun pernyataan menggunakan kotak dialog Pembangun Kueri.
Topik Terkait: Penyusun Kueri
SQLSourceType = Koneksi file
Sambungan File
Pilih manajer koneksi File yang sudah ada, atau klik <Koneksi baru...> untuk membuat pengelola koneksi baru.
Topik Terkait: File Pengelola Sambungan, File Pengelola Sambungan Editor
SQLSourceType = Variabel
SourceVariable
Pilih variabel yang sudah ada, atau klik <Variabel baru...> untuk membuat variabel baru.
Topik Terkait: Variabel Integration Services (SSIS), Tambahkan Variabel
Halaman Pemetaan Parameter - Jalankan Editor Tugas SQL
Gunakan halaman Pemetaan Parameter dari kotak dialog Jalankan Editor Tugas SQL untuk memetakan variabel ke parameter dalam pernyataan SQL.
Opsi
Nama Variabel
Setelah Anda menambahkan pemetaan parameter dengan mengklik Tambahkan, pilih sistem atau variabel yang ditentukan pengguna dari daftar atau klik< Variabel baru...> untuk menambahkan variabel baru dengan menggunakan kotak dialog Tambahkan Variabel.
Topik Terkait: Variabel Integration Services (SSIS)
Arah
Pilih arah parameter. Petakan setiap variabel ke parameter input, parameter output, atau kode pengembalian.
Tipe Data
Pilih jenis data parameter. Daftar jenis data yang tersedia khusus untuk penyedia yang dipilih di manajer koneksi yang digunakan oleh tugas.
Nama Parameter
Berikan nama parameter.
Bergantung pada jenis manajer koneksi yang digunakan tugas, Anda harus menggunakan nama angka atau parameter. Beberapa jenis pengelola koneksi mengharuskan karakter pertama dari nama parameter adalah tanda @ , nama tertentu seperti @Param1, atau nama kolom sebagai nama parameter.
Ukuran Parameter
Berikan ukuran parameter yang memiliki panjang variabel, seperti string dan bidang biner.
Pengaturan ini memastikan bahwa penyedia mengalokasikan ruang yang cukup untuk nilai parameter panjang variabel.
Tambahkan
Klik untuk menambahkan pemetaan parameter.
Hapus
Pilih pemetaan parameter dalam daftar lalu klik Hapus.
Halaman Set Hasil - Jalankan Editor Tugas SQL
Gunakan halaman Kumpulan Hasil dari dialog Jalankan Editor Tugas SQL untuk memetakan hasil pernyataan SQL ke variabel baru atau yang sudah ada. Opsi dalam kotak dialog ini dinonaktifkan jika ResultSet pada halaman Umum diatur ke Tidak Ada.
Opsi
Nama Hasil
Setelah Anda menambahkan set pemetaan tataan hasil dengan mengklik Tambahkan, berikan nama untuk hasilnya. Bergantung pada jenis tataan hasil, Anda harus menggunakan nama hasil tertentu.
Jika tipe tataan hasil adalah Baris tunggal, Anda bisa menggunakan nama kolom yang dikembalikan oleh kueri atau angka yang mewakili posisi kolom dalam daftar kolom kolom yang dikembalikan oleh kueri.
Jika jenis tataan hasil adalah Kumpulan hasil lengkap atau XML, Anda harus menggunakan 0 sebagai nama tataan hasil.
Nama Variabel
Petakan hasil yang diatur ke variabel dengan memilih variabel atau klik <Variabel baru...> untuk menambahkan variabel baru dengan menggunakan kotak dialog Tambahkan Variabel.
Tambahkan
Klik untuk menambahkan pemetaan kumpulan hasil.
Hapus
Pilih pemetaan tataan hasil dalam daftar lalu klik Hapus.
Parameter dalam Tugas Jalankan SQL
Pernyataan SQL dan prosedur tersimpan sering menggunakan parameter input , parameter output , dan kode pengembalian. Di Integration Services, tugas Execute SQL mendukung jenis parameter Input, Output, dan ReturnValue . Anda menggunakan Jenis input untuk parameter input, Output untuk parameter output, dan ReturnValue untuk kode pengembalian.
Catatan
Anda dapat menggunakan parameter dalam tugas Jalankan SQL hanya jika penyedia data mendukungnya.
Parameter dalam perintah SQL, termasuk kueri dan prosedur tersimpan, dipetakan ke variabel yang ditentukan pengguna yang dibuat dalam cakupan tugas Execute SQL, kontainer induk, atau dalam cakupan paket. Nilai variabel dapat diatur pada waktu desain atau diisi secara dinamis pada waktu proses. Anda juga dapat memetakan parameter ke variabel sistem. Untuk informasi selengkapnya, lihat Variabel Integration Services (SSIS) dan Variabel Sistem.
Namun, bekerja dengan parameter dan mengembalikan kode dalam tugas Execute SQL lebih dari sekadar mengetahui jenis parameter apa yang didukung tugas dan bagaimana parameter ini akan dipetakan. Ada persyaratan dan panduan penggunaan tambahan untuk berhasil menggunakan parameter dan mengembalikan kode dalam tugas Jalankan SQL. Sisa topik ini mencakup persyaratan dan pedoman penggunaan ini:
Nama dan penanda parameter
Bergantung pada jenis koneksi yang digunakan tugas Jalankan SQL, sintaks perintah SQL menggunakan penanda parameter yang berbeda. Misalnya, jenis pengelola koneksi ADO.NET mengharuskan perintah SQL menggunakan penanda parameter dalam format @varParameter, sedangkan jenis koneksi OLE DB memerlukan penanda parameter tanda tanya (?).
Nama yang dapat Anda gunakan sebagai nama parameter dalam pemetaan antara variabel dan parameter juga bervariasi menurut jenis manajer koneksi. Misalnya, jenis pengelola koneksi ADO.NET menggunakan nama yang ditentukan pengguna dengan awalan @, sedangkan jenis manajer koneksi OLE DB mengharuskan Anda menggunakan nilai numerik ordinal berbasis 0 sebagai nama parameter.
Tabel berikut ini meringkas persyaratan untuk perintah SQL untuk jenis manajer koneksi yang dapat digunakan tugas Jalankan SQL.
Tipe sambungan | Penanda parameter | Nama Parameter | Contoh perintah SQL |
---|---|---|---|
ADO | ? | Param1, Param2, ... | SELECT FirstName, LastName, Title FROM Person.Contact WHERE ContactID = ? |
ADO.NET | @<nama parameter> | @<nama parameter> | SELECT FirstName, LastName, Title FROM Person.Contact WHERE ContactID = @parmContactID |
ODBC | ? | 1, 2, 3, ... | SELECT FirstName, LastName, Title FROM Person.Contact WHERE ContactID = ? |
EXCEL dan OLE DB | ? | 0, 1, 2, 3, ... | SELECT FirstName, LastName, Title FROM Person.Contact WHERE ContactID = ? |
Menggunakan parameter dengan Pengelola Sambungan ADO.NET dan ADO
ADO.NET dan manajer koneksi ADO memiliki persyaratan khusus untuk perintah SQL yang menggunakan parameter:
ADO.NET pengelola koneksi mengharuskan perintah SQL menggunakan nama parameter sebagai penanda parameter. Ini berarti bahwa variabel dapat dipetakan langsung ke parameter. Misalnya, variabel
@varName
dipetakan ke parameter bernama@parName
dan memberikan nilai ke parameter@parName
.Manajer koneksi ADO mengharuskan perintah SQL menggunakan tanda tanya (?) sebagai penanda parameter. Namun, Anda dapat menggunakan nama yang ditentukan pengguna, kecuali untuk nilai bilangan bulat, sebagai nama parameter.
Untuk memberikan nilai ke parameter, variabel dipetakan ke nama parameter. Kemudian, tugas Jalankan SQL menggunakan nilai ordinal nama parameter dalam daftar parameter untuk memuat nilai dari variabel ke parameter.
Menggunakan parameter dengan Pengelola Sambungan EXCEL, ODBC, dan OLE DB
Pengelola koneksi EXCEL, ODBC, dan OLE DB mengharuskan perintah SQL menggunakan tanda tanya (?) sebagai penanda parameter dan nilai numerik berbasis 0 atau 1 sebagai nama parameter. Jika tugas Jalankan SQL menggunakan manajer koneksi ODBC, nama parameter yang memetakan ke parameter pertama dalam kueri diberi nama 1; jika tidak, parameter diberi nama 0. Untuk parameter berikutnya, nilai numerik dari nama parameter menunjukkan parameter dalam perintah SQL tempat nama parameter dipetakan. Misalnya, parameter bernama 3 peta ke parameter ketiga, yang diwakili oleh tanda tanya ketiga (?) dalam perintah SQL.
Untuk memberikan nilai ke parameter, variabel dipetakan ke nama parameter dan tugas Jalankan SQL menggunakan nilai ordinal nama parameter untuk memuat nilai dari variabel ke parameter.
Bergantung pada penyedia yang digunakan manajer koneksi, beberapa jenis data OLE DB mungkin tidak didukung. Misalnya, driver Excel hanya mengenali sekumpulan tipe data terbatas. Untuk informasi selengkapnya tentang perilaku penyedia Jet dengan driver Excel, lihat Sumber Excel.
Menggunakan parameter dengan Pengelola Sambungan OLE DB
Ketika tugas Jalankan SQL menggunakan manajer koneksi OLE DB, properti BypassPrepare tugas tersedia. Anda harus mengatur properti ini ke true jika tugas Jalankan SQL menggunakan pernyataan SQL dengan parameter.
Saat Anda menggunakan manajer koneksi OLE DB, Anda tidak dapat menggunakan subkueri berparameter karena Tugas Jalankan SQL tidak dapat memperoleh informasi parameter melalui penyedia OLE DB. Namun, Anda dapat menggunakan ekspresi untuk menggabungkan nilai parameter ke dalam string kueri dan untuk mengatur properti SqlStatementSource tugas.
Menggunakan parameter dengan jenis data tanggal dan waktu
Gunakan parameter tanggal dan waktu dengan Pengelola Sambungan ADO.NET dan ADO
Saat membaca data jenis, waktu, dan datetimeoffset SQL Server, tugas Jalankan SQL yang menggunakan manajer koneksi ADO.NET atau ADO memiliki persyaratan tambahan berikut:
Untuk data waktu , pengelola koneksi ADO.NET mengharuskan data ini disimpan dalam parameter yang jenis parameternya adalah Input atau Output, dan yang jenis datanya adalah string.
Untuk data datetimeoffset , pengelola koneksi ADO.NET mengharuskan data ini disimpan dalam salah satu parameter berikut:
Parameter yang jenis parameternya adalah Input dan yang jenis datanya adalah string.
Parameter yang jenis parameternya adalah Output atau ReturnValue, dan yang jenis datanya adalah datetimeoffset, string, atau datetime2. Jika Anda memilih parameter yang jenis datanya adalah string atau datetime2, Integration Services mengonversi data menjadi string atau datetime2.
Manajer koneksi ADO mengharuskan data waktu atau datetimeoffset disimpan dalam parameter yang jenis parameternya adalah Input atau Output, dan yang jenis datanya adalah adVarWchar.
Untuk informasi selengkapnya tentang jenis data SQL Server dan bagaimana mereka memetakan ke jenis data Integration Services, lihat Jenis Data (T-SQL) dan Jenis Data Integration Services.
Menggunakan parameter tanggal dan waktu dengan Pengelola Sambungan OLE DB
Saat menggunakan manajer koneksi OLE DB, tugas Jalankan SQL memiliki persyaratan penyimpanan khusus untuk data jenis data SQL Server, tanggal, waktu, tanggalwaktu, tanggalwaktu2, dan datetimeoffset. Anda harus menyimpan data ini di salah satu jenis parameter berikut:
Parameter input dari jenis data NVARCHAR.
Parameter output dengan jenis data yang sesuai, seperti yang tercantum dalam tabel berikut.
Jenis parameter output Jenis data tanggal DBDATE date DBTIME2 time DBTIMESTAMP datetime, datetime2 DBTIMESTAMPOFFSET datetimeoffset
Jika data tidak disimpan dalam parameter input atau output yang sesuai, paket gagal.
Gunakan parameter tanggal dan waktu dengan Pengelola Sambungan ODBC
Saat menggunakan manajer koneksi ODBC, tugas Jalankan SQL memiliki persyaratan penyimpanan khusus untuk data dengan salah satu jenis data SQL Server, tanggal, waktu, tanggalwaktu, tanggalwaktu2, atau datetimeoffset. Anda harus menyimpan data ini di salah satu jenis parameter berikut:
Parameter input dari jenis data SQL_WVARCHAR
Parameter output dengan jenis data yang sesuai, seperti yang tercantum dalam tabel berikut.
Jenis parameter output Jenis data tanggal SQL_DATE date SQL_SS_TIME2 time SQL_TYPE_TIMESTAMP
-atau-
SQL_TIMESTAMPdatetime, datetime2 SQL_SS_TIMESTAMPOFFSET datetimeoffset
Jika data tidak disimpan dalam parameter input atau output yang sesuai, paket gagal.
Menggunakan parameter dalam klausa WHERE
Perintah SELECT, INSERT, UPDATE, dan DELETE sering kali menyertakan klausa WHERE untuk menentukan filter yang menentukan kondisi setiap baris dalam tabel sumber harus memenuhi syarat untuk perintah SQL. Parameter menyediakan nilai filter dalam klausa WHERE.
Anda dapat menggunakan penanda parameter untuk memberikan nilai parameter secara dinamis. Aturan yang penanda parameter dan nama parameternya dapat digunakan dalam pernyataan SQL bergantung pada jenis manajer koneksi yang digunakan Execute SQL.
Tabel berikut ini mencantumkan contoh perintah SELECT menurut jenis manajer koneksi. Pernyataan INSERT, UPDATE, dan DELETE serupa. Contoh menggunakan SELECT untuk mengembalikan produk dari tabel Produk di AdventureWorks2022
yang memiliki ProductID lebih besar dari dan kurang dari nilai yang ditentukan oleh dua parameter.
Tipe sambungan | Sintaks SELECT |
---|---|
EXCEL, ODBC, dan OLEDB | SELECT* FROM Production.Product WHERE ProductId > ? AND ProductID < ? |
ADO | SELECT* FROM Production.Product WHERE ProductId > ? AND ProductID < ? |
ADO.NET | SELECT* FROM Production.Product WHERE ProductId > @parmMinProductID AND ProductID < @parmMaxProductID |
Contohnya akan memerlukan parameter yang memiliki nama berikut:
Pengelola koneksi EXCEL dan OLED DB menggunakan nama parameter 0 dan 1. Jenis koneksi ODBC menggunakan 1 dan 2.
Jenis koneksi ADO dapat menggunakan dua nama parameter, seperti Param1 dan Param2, tetapi parameter harus dipetakan oleh posisi ordinalnya dalam daftar parameter.
Jenis koneksi ADO.NET menggunakan nama parameter @parmMinProductID dan @parmMaxProductID.
Menggunakan parameter dengan prosedur tersimpan
Perintah SQL yang menjalankan prosedur tersimpan juga dapat menggunakan pemetaan parameter. Aturan tentang cara menggunakan penanda parameter dan nama parameter tergantung pada jenis manajer koneksi yang digunakan Execute SQL, sama seperti aturan untuk kueri berparameter.
Tabel berikut ini mencantumkan contoh perintah EXEC menurut jenis manajer koneksi. Contoh menjalankan prosedur tersimpan uspGetBillOfMaterials di AdventureWorks2022
. Prosedur tersimpan @StartProductID
menggunakan parameter input dan @CheckDate
.
Tipe sambungan | Sintaks EXEC |
---|---|
EXCEL dan OLEDB | EXEC uspGetBillOfMaterials ?, ? |
ODBC | {call uspGetBillOfMaterials(?, ?)} Untuk informasi selengkapnya tentang sintaks panggilan ODBC, lihat topik, Parameter Prosedur, di Referensi Programmer ODBC di Pustaka MSDN. |
ADO | Jika IsQueryStoredProcedure diatur ke False, EXEC uspGetBillOfMaterials ?, ? Jika IsQueryStoredProcedure diatur ke True, uspGetBillOfMaterials |
ADO.NET | Jika IsQueryStoredProcedure diatur ke False, EXEC uspGetBillOfMaterials @StartProductID, @CheckDate Jika IsQueryStoredProcedure diatur ke True, uspGetBillOfMaterials |
Untuk menggunakan parameter output, sintaksis mengharuskan kata kunci OUTPUT mengikuti setiap penanda parameter. Misalnya, sintaks parameter output berikut sudah benar: EXEC myStoredProcedure ? OUTPUT
.
Untuk informasi selengkapnya tentang menggunakan parameter input dan output dengan prosedur tersimpan Transact-SQL, lihat EXECUTE (Transact-SQL).
Memetakan parameter kueri ke variabel
Bagian ini menjelaskan cara menggunakan pernyataan SQL berparameter dalam tugas Jalankan SQL dan membuat pemetaan antara variabel dan parameter dalam pernyataan SQL.
Di SQL Server Data Tools (SSDT), buka paket Layanan Integrasi yang ingin Anda kerjakan.
Di Penjelajah Solusi, klik dua kali paket untuk membukanya.
Klik tab Alur Kontrol.
Jika paket belum menyertakan tugas Jalankan SQL, tambahkan paket ke alur kontrol paket. Untuk informasi selengkapnya, lihat Menambahkan atau Menghapus Tugas atau Kontainer dalam Alur Kontrol.
Klik dua kali tugas Jalankan SQL.
Berikan perintah SQL berparameter dengan salah satu cara berikut:
Gunakan input langsung dan ketik perintah SQL di properti SQLStatement.
Gunakan input langsung, klik Buat Kueri, lalu buat perintah SQL menggunakan alat grafis yang disediakan Pembangun Kueri.
Gunakan koneksi file lalu referensikan file yang berisi perintah SQL.
Gunakan variabel lalu referensikan variabel yang berisi perintah SQL.
Penanda parameter yang Anda gunakan dalam pernyataan SQL berparameter bergantung pada jenis koneksi yang digunakan tugas Jalankan SQL.
Tipe sambungan Penanda parameter ADO ? ADO.NET dan SQLMOBILE @<nama parameter> ODBC ? EXCEL dan OLE DB ? Tabel berikut ini mencantumkan contoh perintah SELECT menurut jenis manajer koneksi. Parameter menyediakan nilai filter dalam klausa WHERE. Contoh menggunakan SELECT untuk mengembalikan produk dari tabel Produk di
AdventureWorks2022
yang memiliki ProductID lebih besar dari dan kurang dari nilai yang ditentukan oleh dua parameter.Tipe sambungan Sintaks SELECT EXCEL, ODBC, dan OLEDB SELECT* FROM Production.Product WHERE ProductId > ? AND ProductID < ?
ADO SELECT* FROM Production.Product WHERE ProductId > ? AND ProductID < ?
ADO.NET SELECT* FROM Production.Product WHERE ProductId > @parmMinProductID AND ProductID < @parmMaxProductID
Klik Pemetaan Parameter.
Untuk menambahkan pemetaan parameter, klik Tambahkan.
Berikan nama dalam kotak Nama Parameter.
Nama parameter yang Anda gunakan bergantung pada jenis koneksi yang digunakan tugas Jalankan SQL.
Tipe sambungan Nama Parameter ADO Param1, Param2, ... ADO.NET dan SQLMOBILE @<nama parameter> ODBC 1, 2, 3, ... EXCEL dan OLE DB 0, 1, 2, 3, ... Dari daftar Nama Variabel, pilih variabel. Untuk informasi selengkapnya, lihat Menambahkan, Menghapus, Mengubah Cakupan Variabel yang Ditentukan Pengguna dalam Paket.
Dalam daftar Arah, tentukan apakah parameter adalah input, output, atau nilai pengembalian.
Dalam daftar Jenis Data, atur jenis data parameter.
Penting
Jenis data parameter harus kompatibel dengan jenis data variabel.
Ulangi langkah 8 hingga 11 untuk setiap parameter dalam pernyataan SQL.
Penting
Urutan pemetaan parameter harus sama dengan urutan di mana parameter muncul dalam pernyataan SQL.
Klik OK.
Mendapatkan nilai kode pengembalian
Prosedur tersimpan dapat mengembalikan nilai bilangan bulat, yang disebut kode pengembalian, untuk menunjukkan status eksekusi prosedur. Untuk menerapkan kode pengembalian dalam tugas Jalankan SQL, Anda menggunakan parameter jenis ReturnValue .
Tabel berikut mencantumkan menurut jenis koneksi beberapa contoh perintah EXEC yang menerapkan kode pengembalian. Semua contoh menggunakan parameter input . Aturan tentang cara menggunakan penanda parameter dan nama parameter sama untuk semua parameter type-Input, Output, dan ReturnValue.
Beberapa sintaks tidak mendukung literal parameter. Dalam hal ini, Anda harus memberikan nilai parameter dengan menggunakan variabel.
Tipe sambungan | Sintaks EXEC |
---|---|
EXCEL dan OLEDB | EXEC ? = myStoredProcedure 1 |
ODBC | {? = call myStoredProcedure(1)} Untuk informasi selengkapnya tentang sintaks panggilan ODBC, lihat topik, Parameter Prosedur, di Referensi Programmer ODBC di Pustaka MSDN. |
ADO | Jika IsQueryStoreProcedure diatur ke False, EXEC ? = myStoredProcedure 1 Jika IsQueryStoreProcedure diatur ke True, myStoredProcedure |
ADO.NET | Atur IsQueryStoreProcedure diatur ke True.myStoredProcedure |
Dalam sintaks yang diperlihatkan dalam tabel sebelumnya, tugas Jalankan SQL menggunakan jenis sumber Input Langsung untuk menjalankan prosedur tersimpan . Tugas Jalankan SQL juga dapat menggunakan jenis sumber Koneksi File untuk menjalankan prosedur tersimpan. Terlepas dari apakah tugas Execute SQL menggunakan jenis sumber Input Langsung atau Koneksi File, gunakan parameter jenis ReturnValue untuk mengimplementasikan kode pengembalian.
Untuk informasi selengkapnya tentang menggunakan kode pengembalian dengan prosedur tersimpan Transact-SQL, lihat RETURN (Transact-SQL).
Tataan Hasil dalam Tugas Jalankan SQL
Dalam paket Layanan Integrasi, apakah kumpulan hasil dikembalikan ke tugas Jalankan SQL bergantung pada jenis perintah SQL yang digunakan tugas. Misalnya, pernyataan SELECT biasanya mengembalikan kumpulan hasil, tetapi pernyataan INSERT tidak.
Apa yang dikandung kumpulan hasil juga bervariasi menurut perintah SQL. Misalnya, hasil yang ditetapkan dari pernyataan SELECT dapat berisi baris nol, satu baris, atau banyak baris. Namun, hasil yang ditetapkan dari pernyataan SELECT yang mengembalikan hitungan atau jumlah hanya berisi satu baris.
Bekerja dengan tataan hasil dalam tugas Execute SQL lebih dari sekadar mengetahui apakah perintah SQL mengembalikan tataan hasil dan apa yang dikandung kumpulan hasil tersebut. Ada persyaratan dan panduan penggunaan tambahan untuk berhasil menggunakan tataan hasil dalam tugas Jalankan SQL. Sisa topik ini mencakup persyaratan dan pedoman penggunaan ini:
Tentukan jenis tataan hasil
Tugas Jalankan SQL mendukung jenis kumpulan hasil berikut:
Kumpulan hasil Tidak Ada digunakan saat kueri tidak mengembalikan hasil. Misalnya, tataan hasil ini digunakan untuk kueri yang menambahkan, mengubah, dan menghapus rekaman dalam tabel.
Kumpulan hasil baris tunggal digunakan saat kueri hanya mengembalikan satu baris. Misalnya, kumpulan hasil ini digunakan untuk pernyataan SELECT yang mengembalikan hitungan atau jumlah.
Kumpulan hasil tataan hasil lengkap digunakan saat kueri mengembalikan beberapa baris. Misalnya, tataan hasil ini digunakan untuk pernyataan SELECT yang mengambil semua baris dalam tabel.
Kumpulan hasil XML digunakan saat kueri mengembalikan tataan hasil dalam format XML. Misalnya, kumpulan hasil ini digunakan untuk pernyataan SELECT yang menyertakan klausa FOR XML.
Jika tugas Jalankan SQL menggunakan tataan hasil kumpulan hasil lengkap dan kueri mengembalikan beberapa set baris, tugas hanya mengembalikan set baris pertama. Jika himpunan baris ini menghasilkan kesalahan, tugas melaporkan kesalahan. Jika kumpulan baris lain menghasilkan kesalahan, tugas tidak melaporkannya.
Mengisi variabel dengan kumpulan hasil
Anda dapat mengikat kumpulan hasil yang dikembalikan kueri ke variabel yang ditentukan pengguna, jika jenis tataan hasil adalah satu baris, set baris, atau XML.
Jika jenis tataan hasil adalah Baris tunggal, Anda dapat mengikat kolom dalam hasil pengembalian ke variabel dengan menggunakan nama kolom sebagai nama kumpulan hasil, atau Anda dapat menggunakan posisi ordinal kolom dalam daftar kolom sebagai nama kumpulan hasil. Misalnya, nama kumpulan hasil untuk kueri SELECT Color FROM Production.Product WHERE ProductID = ?
bisa berupa Warna atau 0. Jika kueri mengembalikan beberapa kolom dan Anda ingin mengakses nilai di semua kolom, Anda harus mengikat setiap kolom ke variabel yang berbeda. Jika Anda memetakan kolom ke variabel menggunakan angka sebagai nama kumpulan hasil, angka tersebut mencerminkan urutan kolom muncul dalam daftar kolom kueri. Misalnya, dalam kueri SELECT Color, ListPrice, FROM Production.Product WHERE ProductID = ?
, Anda menggunakan 0 untuk kolom Warna dan 1 untuk kolom ListPrice . Kemampuan untuk menggunakan nama kolom sebagai nama kumpulan hasil bergantung pada penyedia yang tugasnya dikonfigurasi untuk digunakan. Tidak semua penyedia membuat nama kolom tersedia.
Beberapa kueri yang mengembalikan satu nilai mungkin tidak menyertakan nama kolom. Misalnya, pernyataan SELECT COUNT (*) FROM Production.Product
tidak mengembalikan nama kolom. Anda dapat mengakses hasil pengembalian menggunakan posisi ordinal, 0, sebagai nama hasil. Untuk mengakses hasil pengembalian menurut nama kolom, kueri harus menyertakan klausa nama> alias AS <untuk memberikan nama kolom. Pernyataan SELECT COUNT (*)AS CountOfProduct FROM Production.Product
, menyediakan kolom CountOfProduct . Anda kemudian dapat mengakses kolom hasil pengembalian menggunakan nama kolom CountOfProduct atau posisi ordinal, 0.
Jika jenis tataan hasil adalah Kumpulan hasil lengkap atau XML, Anda harus menggunakan 0 sebagai nama tataan hasil.
Saat Anda memetakan variabel ke kumpulan hasil dengan jenis tataan hasil baris tunggal, variabel harus memiliki tipe data yang kompatibel dengan jenis data kolom yang dimuat tataan hasil. Misalnya, kumpulan hasil yang berisi kolom dengan jenis data String tidak dapat memetakan ke variabel dengan jenis data numerik. Saat Anda mengatur properti TypeConversionMode ke Diizinkan, Tugas Jalankan SQL akan mencoba mengonversi parameter output dan hasil kueri ke jenis data variabel tempat hasil ditetapkan.
Kumpulan hasil XML hanya dapat memetakan ke variabel dengan jenis data String atau Objek . Jika variabel memiliki jenis data String , tugas Jalankan SQL mengembalikan string dan sumber XML dapat menggunakan data XML. Jika variabel memiliki jenis data Objek , tugas Jalankan SQL mengembalikan objek Model Objek Dokumen (DOM).
Kumpulan hasil Lengkap harus dipetakan ke variabel jenis data Objek. Hasil yang dikembalikan adalah objek set baris. Anda dapat menggunakan kontainer Foreach Loop untuk mengekstrak nilai baris tabel yang disimpan dalam variabel Objek ke dalam variabel paket, lalu menggunakan Tugas Skrip untuk menulis data yang disimpan dalam variabel paket ke file. Untuk demonstrasi tentang cara melakukan ini menggunakan kontainer Foreach Loop dan Tugas Skrip.
Tabel berikut ini meringkas jenis data variabel yang dapat dipetakan ke kumpulan hasil.
Jenis tataan hasil | Jenis data variabel | Jenis objek |
---|---|---|
Baris tunggal | Jenis apa pun yang kompatibel dengan kolom jenis dalam tataan hasil. | Tidak berlaku |
Tataan hasil lengkap | Objek | Jika tugas menggunakan manajer koneksi asli, termasuk manajer koneksi ADO, OLE DB, Excel, dan ODBC, objek yang dikembalikan adalah ADO Recordset. Jika tugas menggunakan pengelola koneksi terkelola, seperti pengelola koneksi ADO.NET, maka objek yang dikembalikan adalah System.Data.DataSet. Anda dapat menggunakan tugas Skrip untuk mengakses objek System.Data.DataSet , seperti yang ditunjukkan dalam contoh berikut. Dim dt As Data.DataTable Dim ds As Data.DataSet = CType(Dts.Variables("Recordset").Value, DataSet) dt = ds.Tables(0) |
XML | String | String |
XML | Objek | Jika tugas menggunakan manajer koneksi asli, termasuk manajer koneksi ADO, OLE DB, Excel, dan ODBC, objek yang dikembalikan adalah MSXML6. IXMLDOMDocument. Jika tugas menggunakan manajer koneksi terkelola, seperti pengelola koneksi ADO.NET, objek yang dikembalikan adalah System.Xml.XmlDocument. |
Variabel dapat didefinisikan dalam cakupan tugas Execute SQL atau paket. Jika variabel memiliki cakupan paket, kumpulan hasil tersedia untuk tugas dan kontainer lain dalam paket, dan tersedia untuk paket apa pun yang dijalankan oleh tugas Execute Package atau Execute DTS 2000 Package.
Saat Anda memetakan variabel ke kumpulan hasil Baris tunggal, nilai non-string yang dikembalikan pernyataan SQL dikonversi menjadi string saat kondisi berikut terpenuhi:
Properti TypeConversionMode diatur ke true. Anda mengatur nilai properti di jendela Properti atau dengan menggunakan Editor Tugas Jalankan SQL.
Konversi tidak akan mengakibatkan pemotongan data.
Memetakan tataan hasil ke variabel dalam Tugas Jalankan SQL
Bagian ini menjelaskan cara membuat pemetaan antara kumpulan hasil dan variabel dalam tugas Jalankan SQL. Memetakan hasil yang diatur ke variabel membuat tataan hasil tersedia untuk elemen lain dalam paket. Misalnya, skrip dalam tugas Skrip dapat membaca variabel lalu menggunakan nilai dari kumpulan hasil atau sumber XML dapat menggunakan kumpulan hasil yang disimpan dalam variabel. Jika tataan hasil dihasilkan oleh paket induk, kumpulan hasil dapat disediakan untuk paket anak yang dipanggil oleh tugas Jalankan Paket dengan memetakan hasil yang diatur ke variabel dalam paket induk, lalu membuat konfigurasi variabel paket induk dalam paket anak untuk menyimpan nilai variabel induk.
Di SQL Server Data Tools (SSDT), buka proyek Integration Services yang berisi paket yang Anda inginkan.
Di Penjelajah Solusi, klik dua kali paket untuk membukanya.
Klik tab Alur Kontrol.
Jika paket belum menyertakan tugas Jalankan SQL, tambahkan paket ke alur kontrol paket. Untuk informasi selengkapnya, lihat Menambahkan atau Menghapus Tugas atau Kontainer dalam Alur Kontrol.
Klik dua kali tugas Jalankan SQL.
Dalam kotak dialog Jalankan Editor Tugas SQL, pada halaman Umum , pilih baris Tunggal, Kumpulan hasil lengkap, atau jenis tataan hasil XML .
Klik Tataan Hasil.
Untuk menambahkan pemetaan tataan hasil, klik Tambahkan.
Dari daftar Nama Variabel, pilih variabel atau buat variabel baru. Untuk informasi selengkapnya, lihat Menambahkan, Menghapus, Mengubah Cakupan Variabel yang Ditentukan Pengguna dalam Paket.
Di daftar Nama Hasil, secara opsional, ubah nama kumpulan hasil.
Secara umum, Anda dapat menggunakan nama kolom sebagai nama kumpulan hasil, atau Anda bisa menggunakan posisi ordinal kolom dalam daftar kolom sebagai tataan hasil. Kemampuan untuk menggunakan nama kolom sebagai nama kumpulan hasil bergantung pada penyedia yang tugasnya dikonfigurasi untuk digunakan. Tidak semua penyedia membuat nama kolom tersedia.
Klik OK.
Memecahkan masalah tugas Jalankan SQL
Anda dapat mencatat panggilan yang dilakukan tugas Execute SQL ke penyedia data eksternal. Anda dapat menggunakan kemampuan pengelogan ini untuk memecahkan masalah perintah SQL yang dijalankan tugas Jalankan SQL. Untuk mencatat panggilan yang dilakukan tugas Execute SQL ke penyedia data eksternal, aktifkan pengelogan paket dan pilih peristiwa Diagnostik di tingkat paket. Untuk informasi selengkapnya, lihat Alat Pemecahan Masalah untuk Eksekusi Paket.
Terkadang perintah SQL atau prosedur tersimpan mengembalikan beberapa tataan hasil. Kumpulan hasil ini tidak hanya mencakup kumpulan baris yang merupakan hasil kueri SELECT , tetapi nilai tunggal yang merupakan hasil dari kesalahan pernyataan RAISERROR atau PRINT . Apakah tugas mengabaikan kesalahan dalam tataan hasil yang terjadi setelah tataan hasil pertama bergantung pada jenis manajer koneksi yang digunakan:
Saat Anda menggunakan manajer koneksi OLE DB dan ADO, tugas mengabaikan kumpulan hasil yang terjadi setelah tataan hasil pertama. Oleh karena itu, dengan manajer koneksi ini, tugas mengabaikan kesalahan yang dikembalikan oleh perintah SQL atau prosedur tersimpan ketika kesalahan bukan bagian dari tataan hasil pertama.
Saat Anda menggunakan ODBC dan ADO.NET pengelola koneksi, tugas tidak mengabaikan kumpulan hasil yang terjadi setelah tataan hasil pertama. Dengan manajer koneksi ini, tugas akan gagal dengan kesalahan ketika tataan hasil selain kumpulan hasil pertama berisi kesalahan.
Entri Log Kustom
Tabel berikut ini menjelaskan entri log kustom untuk tugas Jalankan SQL. Untuk informasi selengkapnya, lihat Pengelogan Integration Services (SSIS).
Entri log | Deskripsi |
---|---|
ExecuteSQLExecutingQuery | Menyediakan informasi tentang fase eksekusi pernyataan SQL. Entri log ditulis ketika tugas memperoleh koneksi ke database, ketika tugas mulai menyiapkan pernyataan SQL, dan setelah eksekusi pernyataan SQL selesai. Entri log untuk fase persiapan mencakup pernyataan SQL yang digunakan tugas. |