Cosmos DB Connector for SSIS

Connect to your Azure Cosmos DB databases to read, query, create, update, and delete documents and more!
You can use this connector to integrate Cosmos DB data inside SSIS and SQL Server. Let's take a look at the steps below to see how exactly to accomplish that.

Download Documentation

If you are new with SSIS and ZappySys SSIS PowerPack then check below links to get started.

How to get started with SSIS and SSIS PowerPack. it covers how to install necessary tools to design/debug SSIS Packages, deploy to SSIS catalog and last Schedule SSIS Package to run using SQL Agent. It will also cover how to secure SSIS package and Parameterize values (e.g. Password, Hostname, etc).
SSIS API Source Help File
SSIS API Destination Help File

Connect to Cosmos DB in other apps

Connect to Cosmos DB in SQL Server

Connect to Cosmos DB in Power BI

Connect to Cosmos DB in SSRS

Connect to Cosmos DB in Informatica

Connect to Cosmos DB in MS Access

Connect to Cosmos DB in MS Excel

Connect to Cosmos DB in SSAS

Connect to Cosmos DB in C#

Connect to Cosmos DB in Python

Connect to Cosmos DB in JAVA

Connect to Cosmos DB in Tableau

Connect to Cosmos DB in SAP Crystal Reports

Connect to Cosmos DB in Azure Data Factory (Pipeline)

Connect to Cosmos DB in Azure Data Factory (SSIS)

Connect to Cosmos DB in Talend Studio

Connect to Cosmos DB in UiPath

Connect to Cosmos DB in PowerShell

Connect to Cosmos DB in ODBC

Video Tutorial - Integrate Cosmos DB data in SSIS

This video covers following and more so watch carefully. After watching this video follow the steps described in this article.

How to download / install required driver for Cosmos DB integration in SSIS
How to configure connection for Cosmos DB
Features about API Source (Authentication / Query Language / Examples / Driver UI)
Using Cosmos DB Connection in SSIS

Watch this video on YouTube

Prerequisites

Before we perform steps listed in this article, you will need to make sure following prerequisites are met:

SSIS designer installed. Sometimes it is referred as BIDS or SSDT (download it from Microsoft site).
Basic knowledge of SSIS package development using Microsoft SQL Server Integration Services.
Make sure ZappySys SSIS PowerPack is downloaded and installed (download it). Check Getting started section for more information.
Optional (If you want to Deploy and Schedule ) - Deploy and Schedule SSIS Packages

How to read data from Cosmos DB in SSIS (Export data)

In this section we will learn how to configure and use Cosmos DB Connector in API Source to extract data from Cosmos DB.

Begin with opening Visual Studio and Create a New Project.
Select Integration Service Project and in new project window set the appropriate name and location for project. And click OK.
In the new SSIS project screen you will find the following:
1. SSIS ToolBox on left side bar
2. Solution Explorer and Property Window on right bar
3. Control flow, data flow, event Handlers, Package Explorer in tab windows
4. Connection Manager Window in the bottom
Note: If you don't see ZappySys SSIS PowerPack Task or Components in SSIS Toolbox, please refer to this help link.
Now, Drag and Drop SSIS Data Flow Task from SSIS Toolbox. Double click on the Data Flow Task to see Data Flow designer.
From the SSIS toolbox drag and API Source (Predefined Templates) on the data flow designer surface, and double click on it to edit it:
Select New Connection to create a new connection:
Use a preinstalled Cosmos DB Connector from Popular Connector List or press Search Online radio button to download Cosmos DB Connector. Once downloaded simply use it in the configuration:

Cosmos DB

Proceed with selecting the desired Authentication Type. Then select API Base URL (in most cases default one is the right one). Finally, fill in all the required parameters and set optional parameters if needed. You may press a link Steps to Configure which will help set certain parameters. More info is available in Authentication section.

ApiKey [Http]

Steps to get Cosmos DB Credentials : ApiKey [Http]
Connecting to your Azure Cosmos DB data requires you to authenticate your REST API access. Follow the instructions below:

Go to your Azure portal homepage: https://portal.azure.com/
In the search bar at the top of the homepage, enter Azure Cosmos DB. In the dropdown that appears, select Azure Cosmos DB.
Click on the name of the database account you want to connect to. (Also copy and paste the name of the database account for later use.)
On the next page where you can see all of the database account information, look along the left side and select Keys.
On the Keys page, you will have two tabs: Read-write Keys and Read-only Keys. If you are going to write data to your database, you need to remain on the Read-write Keys tab. If you are only going to read data from your database, you should select the Read-only Keys tab.
On the Keys page, copy the PRIMARY KEY value and paste it somewhere for later use. (The SECONDARY KEY value may also be copied and pasted instead of PRIMARY KEY.)
Back at the connector screen, enter the primary or secondary key you recorded in step 6 into the Primary or Secondary Key field.
Enter the database account you recorded in step 3 into the Database Account field.
Enter or select the default database you want to connect to using the Defualt Database field.
Enter or select the default table (i.e. container/collection) you want to connect to using the Default Table (Container/Collection) field.
Select the Test Connection button at the bottom of the window to verify proper connectivity with your Azure Devops account.
If the connection test succeeds, select OK.

Cosmos DB

ApiKey [Http]

https://[$Account$].documents.azure.com

Required Parameters
Primary or Secondary Key	Fill in the parameter...
Account Name (Case-Sensitive)	Fill in the parameter...
Database Name (keep blank to use default) Case-Sensitive	Fill in the parameter...
API Version	Fill in the parameter...
Optional Parameters
Default Table (needed to invoke #DirectSQL)	Fill in the parameter...

Select the desired endpoint, change/pass the properties values, and click on Preview Data button to make the API call.

API Source - Cosmos DB

Connect to your Azure Cosmos DB databases to read, query, create, update, and delete documents and more!
That's it! We are done! Just in a few clicks we configured the call to Cosmos DB using Cosmos DB Connector.

You can load the source data into your desired destination using the Upsert Destination, which supports SQL Server, PostgreSQL, and Amazon Redshift. We also offer other destinations such as CSV, Excel, Azure Table, Salesforce, and more. You can check out our SSIS PowerPack Tasks and components for more options. (*loaded in Trash Destination)

Load Cosmos DB data in SQL Server using Upsert Destination (Insert or Update)

Once you read data from the desired source, now let's see how to Load Cosmos DB data in SQL Server using Upsert Destination. Upsert Destination can Merge/Synchronize data from source to target for Microsoft SQL Server, PostgreSql and Redshift. It supports very fast Bulk Upsert (Update or Insert) operation along and Bulk delete.

From the SSIS toolbox drag and drop Upsert Destination on the dataflow designer surface
Connect our Source component to Upsert Destination
Double click on Upsert Destination component to configure it.
Select the desired Microsoft SQL Server/PostgreSql/Redshift Target Connection or click NEW to create new connection. Select Target Table or click NEW to create new table based on source columns.

Configure SSIS Upsert Destination Connection - Loading data (REST / SOAP / JSON / XML /CSV) into SQL Server or other target using SSIS
Set Action to Upsert => (insert if not matching in target else update). Select Target Connection and Target Table. Check on Insert and Update. Click on Map All to Mappings all columns and check on Only Primary Key columns.
Click on OK to save Upsert Destination settings UI.
That's it. Run the SSIS Package and it will read the data from the Cosmos DB and load the data in the SQL Server/PostgreSql/Redshift using Upsert Destination.

Video Tutorial - Write or lookup data to Cosmos DB using SSIS

This video covers following and more so watch carefully. After watching this video follow the steps described in this article.

How to download SSIS PowerPack for Cosmos DB integration in SSIS
How to configure connection for Cosmos DB
How to Write or lookup data to Cosmos DB
Features about SSIS API Destination
Using Cosmos DB Connector in SSIS

Watch this video on YouTube

How to write or lookup data to Cosmos DB in SSIS (Import data)

In upper section we learned how to read data, now in this section we will learn how to configure Cosmos DB in the API Source to Post data to the Cosmos DB.

Read the data from the source, being any desired source component. In example we will use ZappySys Dummy Data Source component.
From the SSIS Toolbox drag and drop API Destination (Predefined Templates) on the Data Flow Designer surface and connect source component with it, and double click to edit it.
Select New Connection to create a new connection:

API Destination - Cosmos DB

Connect to your Azure Cosmos DB databases to read, query, create, update, and delete documents and more!
Use a preinstalled Cosmos DB Connector from Popular Connector List or press Search Online radio button to download Cosmos DB Connector. Once downloaded simply use it in the configuration:

Cosmos DB

ApiKey [Http]

Steps to get Cosmos DB Credentials : ApiKey [Http]
Connecting to your Azure Cosmos DB data requires you to authenticate your REST API access. Follow the instructions below:

Go to your Azure portal homepage: https://portal.azure.com/
In the search bar at the top of the homepage, enter Azure Cosmos DB. In the dropdown that appears, select Azure Cosmos DB.
Click on the name of the database account you want to connect to. (Also copy and paste the name of the database account for later use.)
On the next page where you can see all of the database account information, look along the left side and select Keys.
On the Keys page, you will have two tabs: Read-write Keys and Read-only Keys. If you are going to write data to your database, you need to remain on the Read-write Keys tab. If you are only going to read data from your database, you should select the Read-only Keys tab.
On the Keys page, copy the PRIMARY KEY value and paste it somewhere for later use. (The SECONDARY KEY value may also be copied and pasted instead of PRIMARY KEY.)
Back at the connector screen, enter the primary or secondary key you recorded in step 6 into the Primary or Secondary Key field.
Enter the database account you recorded in step 3 into the Database Account field.
Enter or select the default database you want to connect to using the Defualt Database field.
Enter or select the default table (i.e. container/collection) you want to connect to using the Default Table (Container/Collection) field.
Select the Test Connection button at the bottom of the window to verify proper connectivity with your Azure Devops account.
If the connection test succeeds, select OK.

Cosmos DB

ApiKey [Http]

https://[$Account$].documents.azure.com

Required Parameters
Primary or Secondary Key	Fill in the parameter...
Account Name (Case-Sensitive)	Fill in the parameter...
Database Name (keep blank to use default) Case-Sensitive	Fill in the parameter...
API Version	Fill in the parameter...
Optional Parameters
Default Table (needed to invoke #DirectSQL)	Fill in the parameter...

Select the desired endpoint, change/pass the properties values, and go to the Mappings tab to map the columns.

API Destination - Cosmos DB

Connect to your Azure Cosmos DB databases to read, query, create, update, and delete documents and more!
Finally, map the desired columns:

API Destination - Cosmos DB

Connect to your Azure Cosmos DB databases to read, query, create, update, and delete documents and more!
That's it; we successfully configured the POST API Call. In a few clicks we configured the Cosmos DB API call using ZappySys Cosmos DB Connector

Advanced topics

Actions supported by Cosmos DB Connector

Cosmos DB Connector support following actions for REST API integration. If some actions are not listed below then you can easily edit Connector file and enhance out of the box functionality.

Get List of Databases

Gets a list of the databases in the current database account. [Read more...]

Get Database Information by Id or Name

Gets a database by its Id. [Read more...]

Parameter	Description
Database Name (keep blank to use default) Case-Sensitive	Leave blank to use default DB set on connection screen

Get List of Tables

Gets a list of the tables in the database. (Tables are also called 'containers' or 'collections') [Read more...]

Parameter	Description
Database Name (keep blank to use default) Case-Sensitive	Leave blank to use default DB set on connection screen

Get table information by Id or Name

Gets a table by its Id. (Tables are also called 'containers' or 'collections') [Read more...]

Parameter	Description
Table Name (Case-Sensitive)
Database Name (keep blank to use default) Case-Sensitive	Leave blank to use default DB set on connection screen

Get table partition key ranges

Gets Partition Key Ranges for a table. This is useful for query if you want to minimize scan to specific partition (Tables are also called 'containers' or 'collections') [Read more...]

Parameter	Description
Table Name (Case-Sensitive)
Database Name (keep blank to use default) Case-Sensitive	Leave blank to use default DB set on connection screen

Query documents using Cosmos DB SQL query language

Gets data based on the specified SQL query. [Read more...]

Parameter

Description

Table Name (Case-Sensitive)

SQL Query

Query for Cosmos DB

Database Name (keep blank to use default) Case-Sensitive

Leave blank to use default DB set on connection screen

Allow Query Scan

Option	Value
true	true
false	false

Allow Cross Partition Query

Option	Value
true	true
false	false

Cross Partition Key Range Id

Get All Documents for a Table

Gets all documents for a Table. [Read more...]

Parameter	Description
Table Name (Case-Sensitive)
Database Name (keep blank to use default) Case-Sensitive	Leave blank to use default DB set on connection screen

Get Document by Id

Gets Document by Id. [Read more...]

Parameter

Description

Document Id

Table Name (Case-Sensitive)

Database Name (keep blank to use default) Case-Sensitive

Leave blank to use default DB set on connection screen

EnableCrossPartition

Option	Value
true	true
false	false

Partition Key Value (default is supplied Id)

The partition key value for the document. Must be included if and only if the collection is created with a partitionKey definition

Option	Value
Default	.
SingleKeyValue	["someValue1"]
MultiKeyValue	["some_value1","some_value2" ]

ConsistencyLevel

This is the consistency level override. The valid values are: Strong, Bounded, Session, or Eventual (in order of strongest to weakest). The override must be the same or weaker than the account’s configured consistency level.

Option	Value
Strong	Strong
Bounded	Bounded
Session	Session
Eventual	Eventual

Delete a Document by Id

Deletes a Document by Id. [Read more...]

Parameter

Description

Document Id

Table Name (Case-Sensitive)

Database Name (keep blank to use default) Case-Sensitive

Leave blank to use default DB set on connection screen

EnableCrossPartition

Option	Value
true	true
false	false

Partition Key Value (default is supplied Id)

The partition key value for the document. Must be included if and only if the collection is created with a partitionKey definition

Option	Value
Default	.
SingleKeyValue	["someValue1"]
MultiKeyValue	["some_value1","some_value2" ]

Get All Users for a Database

Gets all users for a Database. [Read more...]

Parameter	Description
Database Name (keep blank to use default) Case-Sensitive	Leave blank to use default DB set on connection screen

Get User by Id or Name

Gets database user information for a specific Id [Read more...]

Parameter	Description
User Name (Case-Sensitive)
Database Name (keep blank to use default) Case-Sensitive	Leave blank to use default DB set on connection screen

Create User for Database

Create a new user which you can later use to create permission set and obtain resource token. [Read more...]

Parameter	Description
Database Name (keep blank to use default) Case-Sensitive	Leave blank to use default DB set on connection screen
RequestBody

Create a document in the container

Insert JSON document in Cosmos DB Container. [Read more...]

Upsert a document in the container

Insert JSON document in Cosmos DB Container. [Read more...]

Parameter	Description
Upsert

Update Document in the Container

Update full or part of the document in Cosmos DB Container. [Read more...]

Create Permission Token for a User (One Table)

Create a new user which you can later use to create permission set and obtain resource token. [Read more...]

Parameter

Description

Permission Name (e.g. read_orders)

Database Name (keep blank to use default) Case-Sensitive

Leave blank to use default DB set on connection screen

User Name (Case-Sensitive)

PermissionMode

Option	Value
All	All
Read	Read
Write	Write
Delete	Delete

Table (Add Permission for this)

ExpiresInSecond

The validity period of the resource token returned by the operation. By default, a resource token is valid for one hour. To override the default, set this header with the desired validity period in seconds. The max override value is 18000, which is five hours.

Generic Request

This is generic endpoint. Use this endpoint when some actions are not implemented by connector. Just enter partial URL (Required), Body, Method, Header etc. Most parameters are optional except URL. [Read more...]

Parameter	Description
Url	API URL goes here. You can enter full URL or Partial URL relative to Base URL. If it is full URL then domain name must be part of ServiceURL or part of TrustedDomains
Body	Request Body content goes here
IsMultiPart	Set this option if you want to upload file(s) (i.e. POST RAW file data) or send data using Multi-Part encoding method (i.e. Content-Type: multipart/form-data). Multi-Part request allows you to mix key/value and upload files in same request. On the other hand raw upload allows only single file upload (without any key/value) ==== Raw Upload (Content-Type: application/octet-stream) ===== To upload single file in raw mode check this option and specify full file path starting with @ sign in the Body (e.g. @c:\data\myfile.zip ) ==== Form-Data / Multipart Upload (Content-Type: multipart/form-data) ===== To treat your Request data as multi part fields you must specify key/value pairs separated by new lines into RequestData field (i.e. Body). Each key value pair is entered on new-line and key/value are separated using equal sign (=). Preceding and trailing spaces are ignored also blank lines are ignored. If field value has some any special character(s) then use escape sequence (e.g. For NewLine: \r\n, For Tab: \t, For at (@): \@). When value of any field starts with at sign (@) its automatically treated as File you want to upload. By default file content type is determined based on extension however you can supply content type manually for any field using this way [ YourFileFieldName.Content-Type=some-content-type ]. By default File Upload Field always includes Content-Type in the request (non file fields do not have content-type by default unless you supply manually). For some reason if you dont want to use Content-Type header in your request then supply blank Content-Type to exclude this header altogather [e.g. SomeFieldName.Content-Type= ]. In below example we have supplied Content-Type for file2 and SomeField1, all other fields are using default content-type. See below Example of uploading multiple files along with additional fields. If some API requires you to pass Content-Type: multipart/form-data rather than multipart/form-data then manually set Request Header => Content-Type: multipart/mixed (it must starts with multipart/ else will be ignored). file1=@c:\data\Myfile1.txt file2=@c:\data\Myfile2.json file2.Content-Type=application/json SomeField1=aaaaaaa SomeField1.Content-Type=text/plain SomeField2=12345 SomeFieldWithNewLineAndTab=This is line1\r\nThis is line2\r\nThis is \ttab \ttab \ttab SomeFieldStartingWithAtSign=\@MyTwitterHandle
Filter	Enter filter to extract array from response. Example: $.rows[] --OR-- $.customers[].orders[*]. Check your response document and find out hierarchy you like to extract
Headers	Headers for Request. To enter multiple headers use double pipe or new line after each {header-name}:{value} pair

Conclusion

In this article we discussed how to connect to Cosmos DB in SSIS and integrate data without any coding. Click here to Download Cosmos DB Connector for SSIS and try yourself see how easy it is. If you still have any question(s) then ask here or simply click on live chat icon below and ask our expert (see bottom-right corner of this page).

Download Cosmos DB Connector for SSIS Documentation

More integrations

Other application integration scenarios for Cosmos DB

SQL Server

Power BI

SSRS

Informatica

MS Access

MS Excel

SSAS

Python

JAVA

Tableau

SAP Crystal Reports

Azure Data Factory (Pipeline)

Azure Data Factory (SSIS)

Talend Studio

UiPath

PowerShell

ODBC

Other connectors for SSIS

Amazon Ads

Amazon MWS

Amazon Selling Partner (SP-API)

Asana

Azure DevOps

Cosmos DB

DropBox

FastSpring

Google Drive

Hubspot

Jira

Mailchimp

ManagedEngine ServiceDesk Plus (Zoho)

Nativo

OData

OneDrive

Outlook Mail (Office 365)

Power BI

ServiceNow

SharePoint Online

Shopify

Smartsheet

Stripe

YouTube

Zendesk

Zoho CRM

Zoho SalesIQ

Zoom

REST API

JSON

JSON File

XML

SOAP

XML File

JDBC-ODBC Bridge

Salesforce

CSV

Amazon S3 JSON File

Amazon S3 XML File

Amazon S3 CSV File

Azure Blob JSON File

Azure Blob XML File

Azure Blob CSV File

FTP/SFTP JSON File

FTP/SFTP XML File

FTP/SFTP CSV File

Build your own Custom API Connector

Download Cosmos DB Connector for SSIS Documentation

Common Searches:

How to connect Cosmos DB in SSIS?
How to get Cosmos DB data in SSIS?
How to read Cosmos DB data in SSIS?
How to load Cosmos DB data in SSIS?
How to import Cosmos DB data in SSIS?
How to pull Cosmos DB data in SSIS?
How to push data to Cosmos DB in SSIS?
How to write data to Cosmos DB in SSIS?
How to POST data to Cosmos DB in SSIS?
Call Cosmos DB API in SSIS
Consume Cosmos DB API in SSIS
Cosmos DB SSIS Automate
Cosmos DB SSIS Integration
Integration Cosmos DB in SSIS
Consume real-time Cosmos DB data in SSIS
Consume real-time Cosmos DB API data in SSIS
Cosmos DB ODBC Driver | ODBC Driver for Cosmos DB | ODBC Cosmos DB Driver | SSIS Cosmos DB Source | SSIS Cosmos DB Destination
Connect Cosmos DB in SSIS
Load Cosmos DB in SSIS
Load Cosmos DB data in SSIS
Read Cosmos DB data in SSIS
Cosmos DB API Call in SSIS