Before You Connect

You can either create your own custom role definitions, or assign one of the built-in role definitions:

• CosmosDB Built-in Data Reader
• CosmosDB Built-in Data Contributor

You must also set the scope of the role assignment, where "/" means that the identity has access to all the databases.

For details, see Configure role-based access control for your Azure Cosmos DB account with Azure AD.

This page provides a guide to Establishing a Connection to Azure Cosmos DB in CData Cloud, as well as information on the available resources, and a reference to the available connection properties.

Connecting to Azure Cosmos DB

Establishing a Connection shows how to authenticate to Azure Cosmos DB and configure any necessary connection properties to create a database in CData Cloud

Accessing Data from CData Cloud Services

Accessing data from Azure Cosmos DB through the available standard services and CData Cloud administration is documented in further details in the CData Cloud Documentation.

Connect to Azure Cosmos DB by selecting the corresponding icon in the Database tab. Required properties are listed under Settings. The Advanced tab lists connection properties that are not typically required.

Connecting to Azure Cosmos DB

Account Key

Log in to the Azure Portal, select Azure Cosmos DB, and select your account.

Set the following to authenticate:

• AccountEndpoint: The Cosmos DB account URL. Set this to the URI value found in the Settings > Keys blade of the Cosmos DB account.
• AccountKey: A master key token or a resource token for connecting to Azure Cosmos DB. Set this to the PRIMARY KEY value found in the Settings > Keys blade of the Cosmos DB account.
• TokenType: (optional). Set this to "master" (the default value) if you are using a Master Token, which is a full permissions token generated during account creation. Otherwise, set this property to "resource" if you are using a Resource Token, which is a custom permissions token generated when a database user is set up.

Azure AD

Authentication to Azure AD over a Web application always requires the creation of a custom OAuth application .

For details about creating a custom OAuth application, see Creating an Azure AD Application.

Azure Service Principal

Azure Service Principal is role-based application-based authentication. This means that authentication is done per application, rather than per user. All tasks taken on by the application are executed without a default user context, but based on the assigned roles. The application access to the resources is controlled through the assigned roles' permissions.

For information about how to set up Azure Service Principal authentication, see Creating an Azure AD App with Service Principal.

Fine Tuning Data Access

You can use the following properties to gain greater control over Azure Cosmos DB API features and the strategies the Cloud uses to surface them:

• RowScanDepth: This property determines the number of rows that will be scanned to detect column data types when generating table metadata.
• TypeDetectionScheme: This property allows more control over the strategy implemented by the RowScanDepth property.

• GenerateSchemaFiles: This property enables you to persist table metadata in static schema files that are easy to customize, to persist your changes to column data types, for example.
  You can set this property to "OnStart" to generate schema files for all tables in your database at connection. Or, you can generate schemas as you execute SELECT queries to tables.
  The resulting schemas are based on the connection properties you use to configure Automatic Schema Discovery
  To use the resulting schema files, set the Location property to the folder containing the schemas.

Just as described in the SQL Compliance the Cloud supports batch CUD (Create, Update, Delete) operations. Batch processing is achieved by issuing multiple requests simultaneously. Even though this method greatly improves the performance for write operations, the cost of these operations is relatively high, thus the Request Units (RU) budget per second for a certain container or database may be exceeded. Depending on your Azure Cosmos DB Service Quotas, exceeding the RU budgets may incur in extra costs, or it may even temporary throttle or interrupt the Azure Cosmos DB usage for other workloads.

In order to avoid exceeding the RU budget per second, the Cloud dynamically adjusts the number of concurrent requests per second depending on the set WriteThroughputBudget and the constantly adjusted average RU cost per statement. The user can utilize the WriteThroughputBudget connection property to define the RU budged per second, that batch write operations should not exceed. Another important factor in batch write operations is the MaxThreads connection property, which specifies the maximum number of concurrent requests. If using a low MaxThreads value, the Cloud might not be able to efficiently use the available budget.

Since the requests throttling logic is applied client-side, in a few cases the RU/s budged may be exceeded by a relatively small amount. These cases include inserting, updating and deleting records with highly variable column count and input value length per column.

Note: By default, the WriteThroughputBudget property is set 1000 RU/s and the MaxThreads property is set to 200 threads.

Azure Cosmos DB is a schemaless, document database that provides high performance, availability, and scalability. These features are not necessarily incompatible with a standards-compliant query language like SQL-92. In this section we will show various schemes that the Cloud offers to bridge the gap with relational SQL and a document database.

Working with Azure Cosmos DB Objects as Tables

The Cloud models the schemaless Azure Cosmos DB objects into relational tables and translates SQL queries into Azure Cosmos DB queries to get the requested data. See Query Mapping (Sql API) for more details on how various Azure Cosmos DB operations are represented as SQL.

Discovering Schemas Automatically

The Automatic Schema Discovery scheme automatically finds the data types in a Azure Cosmos DB object by scanning a configured number of rows of the object. You can use RowScanDepth, FlattenArrays, and FlattenObjects to control the relational representation of the collections in Azure Cosmos DB. You can also write Free-Form Queries not tied to the schema.

Customizing Schemas

Optionally, you can use Custom Schema Definitions to project your chosen relational structure on top of a Azure Cosmos DB object. This allows you to define your chosen names of columns, their data types, and the location of their values in the collection.

Set GenerateSchemaFiles to save the detected schemas as simple configuration files that are easy to extend. You can persist schemas for all collections in the database or for the results of SELECT queries.

Limitations of the RawValue TypeDetectionScheme

If the TypeDetectionScheme is set to RawValue, the Cloud will push each document as single aggregate value on a column named JsonData, along with its resource identifier on the separate Primary Key column. The JSON documents are not processed, and as a result, the below functionalities are NOT supported with this configuration.

• Automatic Schema Discovery
• Free-Form Queries
• Vertical Flattening
• SQL API Built-In Functions
• SQL API GROUP BY
• Almost all server side supported filters apart from WHERE clause conditions built with the resource identifier.

The Cloud automatically infers a relational schema by inspecting a series of Azure Cosmos DB documents in a collection. You can use the RowScanDepth property to define the number of documents the Cloud will scan to do so. The columns identified during the discovery process depend on the FlattenArrays and FlattenObjects properties.

Flattening Objects

If FlattenObjects is set, all nested objects will be flattened into a series of columns. For example, consider the following document:

{
  id: 12,
  name: "Lohia Manufacturers Inc.",
  address: {street: "Main Street", city: "Chapel Hill", state: "NC"},
  offices: ["Chapel Hill", "London", "New York"],
  annual_revenue: 35,600,000
}

If FlattenObjects is not set, then the address.street, address.city, and address.state columns will not be broken apart. The address column of type string will instead represent the entire object. Its value would be {street: "Main Street", city: "Chapel Hill", state: "NC"}. See JSON Functions for more details on working with JSON aggregates.

You can change the separator character in the column name from a dot by setting SeparatorCharacter.

Flattening Arrays

The FlattenArrays property can be used to flatten array values into columns of their own. This is only recommended for arrays that are expected to be short, for example the coordinates below:

"coord": [ -73.856077, 40.848447 ]

It is best to leave other unbounded arrays as they are and piece out the data for them as needed using JSON Functions.

As discussed in Automatic Schema Discovery, intuited table schemas enable SQL access to unstructured Azure Cosmos DB data. JSON Functions enable you to use standard JSON functions to summarize Azure Cosmos DB data and extract values from any nested structures. Custom Schema Definitions enable you to define static tables and give you more granular control over the relational view of your data; for example, you can write schemas defining parent/child tables or fact/dimension tables. However, you are not limited to these schemes.

After connecting you can query any nested structure without flattening the data. Any relations that you can access with FlattenArrays and FlattenObjects can also be accessed with an ad hoc SQL query.

Let's consider an example document from the following Restaurant data set:

 
{
  "address": {
    "building": "1007",
    "coord": [
      -73.856077,
      40.848447
    ],
    "street": "Morris Park Ave",
    "zipcode": "10462"
  },
  "borough": "Bronx",
  "cuisine": "Bakery",
  "grades": [
    {
      "grade": "A",
      "score": 2,
      "date": {
        "$date": "1393804800000"
      }
    },
    {
      "date": {
        "$date": "1378857600000"
      },
      "grade": "B",
      "score": 6
    },
    {
      "score": 10,
      "date": {
        "$date": "1358985600000"
      },
      "grade": "C"
    }
  ],
  "name": "Morris Park Bake Shop",
  "restaurant_id": "30075445"
} 

SELECT [address.building], [grades.1.grade] FROM restaurants WHERE restaurant_id = '30075445'

It is possible to retrieve an array of documents as if it were a separate table. Take the following JSON structure from the restaurants collection for example:

{
  "_id" : ObjectId("568c37b748ddf53c5ed98932"),
  "address" : {
    "building" : "1007",
    "coord" : [-73.856077, 40.848447],
    "street" : "Morris Park Ave",
    "zipcode" : "10462"
  },
  "borough" : "Bronx",
  "cuisine" : "Bakery",
  "grades" : [{
      "date" : ISODate("2014-03-03T00:00:00Z"),
      "grade" : "A",
      "score" : 2
    }, {
      "date" : ISODate("2013-09-11T00:00:00Z"),
      "grade" : "A",
      "score" : 6
    }, {
      "date" : ISODate("2013-01-24T00:00:00Z"),
      "grade" : "A",
      "score" : 10
    }, {
      "date" : ISODate("2011-11-23T00:00:00Z"),
      "grade" : "A",
      "score" : 9
    }, {
      "date" : ISODate("2011-03-10T00:00:00Z"),
      "grade" : "B",
      "score" : 14
    }],
  "name" : "Morris Park Bake Shop",
  "restaurant_id" : "30075445"
}

SELECT * FROM [restaurants.grades]

You may also want to include information from the base restaurants table. You can do this with a join. Flattened arrays can only be joined with the root document. The Cloud expects the left part of the join is the array document you want to flatten vertically. Disable SupportEnhancedSQL to join nested Azure Cosmos DB documents -- this type of query is supported through the Azure Cosmos DB API.

SELECT [restaurants].[restaurant_id], [restaurants.grades].* FROM [restaurants.grades] JOIN [restaurants] WHERE [restaurants].name = 'Morris Park Bake Shop'

The Cloud can return JSON structures as column values. The Cloud enables you to use standard SQL functions to work with these JSON structures. The examples in this section use the following array:

[
     { "grade": "A", "score": 2 },
     { "grade": "A", "score": 6 },
     { "grade": "A", "score": 10 },
     { "grade": "A", "score": 9 },
     { "grade": "B", "score": 14 }
]

JSON_EXTRACT

SELECT Name, JSON_EXTRACT(grades,'[0].grade') AS Grade, JSON_EXTRACT(grades,'[0].score') AS Score FROM Students;

JSON_COUNT

SELECT Name, JSON_COUNT(grades,'[x]') AS NumberOfGrades FROM Students;

JSON_SUM

SELECT Name, JSON_SUM(score,'[x].score') AS TotalScore FROM Students;

JSON_MIN

SELECT Name, JSON_MIN(score,'[x].score') AS LowestScore FROM Students;

JSON_MAX

SELECT Name, JSON_MAX(score,'[x].score') AS HighestScore FROM Students;

DOCUMENT

The DOCUMENT function can be used to retrieve the entire document as a JSON string. See the following query and its result as an example:

SELECT DOCUMENT(*) FROM Customers;

{ "id": 12, "name": "Lohia Manufacturers Inc.", "address": { "street": "Main Street", "city": "Chapel Hill", "state": "NC"}, "offices": [ "Chapel Hill", "London", "New York" ], "annual_revenue": 35,600,000 }

Cosmos DB also supports a number of built-in functions for common operations, that can be used inside queries. Here are some example of how can be used as part of select columns or the WHERE clause:

Use Built-in functions as part of SELECT columns

SELECT IS_NUMBER(user_id) AS ISN_ATTR, IS_NUMBER(id) AS ISN_ID FROM [users]
SELECT POWER(user_id, 2) AS POWERSSS, LENGTH(id) AS LENGTH_ID, PI() AS JustThePI FROM [users]

Use Built-in functions as part of WHERE clause

SELECT * FROM [users] WHERE STARTSWITH(middle_name, 'G')
SELECT * FROM [users] WHERE REPLACE(middle_name, 'Chr', '___') = '___istopher'

Mathematical functions

The mathematical functions each perform a calculation, based on input values that are provided as arguments, and return a numeric value. Here's a table of supported built-in mathematical functions.

Type checking functions

The type checking functions allow you to check the type of an expression within SQL queries. Type checking functions can be used to determine the type of properties within documents dynamically when it is variable or unknown. Here's a table of supported built-in type checking functions.

String functions

The following scalar functions perform an operation on a string input value and return a string, numeric or Boolean value. Here's a table of built-in string functions:

Array functions

The following scalar functions perform an operation on an array input value and return numeric, Boolean or array value. Here's a table of built-in array functions:

Nested functions

You can also perform nested built-in functions, which are processed server side as well:

i.e. SELECT TOP 10 CONCAT(SUBSTRING(UPPER(cuisine), 0, 3), '-cuisine') FROM [restaurants]

The GROUP BY clause divides the query's results according to the values of one or more specified properties. This operation is partially done server-side because of some API limitations. We still need to operate a client-side grouping.

GROUP BY Examples

SELECT COUNT(*) AS CNT, gender FROM [users] GROUP BY gender
SELECT COUNT(*) AS CNT, gender, doc_type FROM [users] GROUP BY gender, doc_type

The Cloud maps SQL queries into the corresponding Azure Cosmos DB SQL API queries. A detailed description of all the transformations is out of scope, but we will describe some of the common elements that are used. The Cloud takes advantage of SQL API features such as the aggregation framework to compute the desired results.

SELECT Queries

SELECT id, name FROM Users

SELECT C.id, C.name FROM C

SELECT * FROM Users WHERE name = 'A'

SELECT * FROM C WHERE C.name = 'A'

SELECT * FROM Users WHERE name = 'A' OR email = '[email protected]'

SELECT * FROM C WHERE C.name = 'A' OR C.email = '[email protected]'

SELECT id, grantamt FROM WorldBank WHERE grantamt IN (4500000, 85400000) OR grantamt = 16200000

SELECT C.id, C.grantamt FROM C WHERE C.grantamt IN (4500000, 85400000) OR C.grantamt = 16200000

SELECT * FROM WorldBank WHERE CountryCode = 'A' ORDER BY TotalCommAmt ASC

SELECT * FROM C WHERE C.countrycode = 'AL' ORDER BY C.totalcommamt ASC

SELECT * FROM WorldBank WHERE CountryCode = 'A' ORDER BY TotalCommAmt DESC

SELECT * FROM C WHERE C.countrycode = 'AL' ORDER BY C.totalcommamt DESC

Aggregate Queries

SELECT COUNT(grantamt) AS COUNT_GRAMT FROM WorldBank

SELECT COUNT(C.grantamt) AS COUNT_GRAMT FROM C

SELECT SUM(grantamt) AS SUM_GRAMT FROM WorldBank

SELECT SUM(C.grantamt) AS SUM_GRAMT FROM C

Built-In functions

SELECT IS_NUMBER(grantamt) AS ISN_ATTR, IS_NUMBER(id) AS ISN_ID FROM WorldBank

SELECT IS_NUMBER(C.grantamt) AS ISN_ATTR, IS_NUMBER(C.id) AS ISN_ID FROM C

SELECT POWER(totalamt, 2) AS POWERS_A, LENGTH(id) AS LENGTH_ID, PI() AS ThePI FROM WorldBank

SELECT POWER(C.totalamt, 2) AS POWERS_A, LENGTH(C.id) AS LENGTH_ID, PI() AS ThePI FROM C

You can extend the table schemas created with Automatic Schema Discovery by saving them into schema files. The schema files have a simple format that makes the schemas to edit.

Generating Schema Files

Set GenerateSchemaFiles to "OnStart" to persist schemas for all tables when you connect. You can also generate table schemas as needed: Set GenerateSchemaFiles to "OnUse" and execute a SELECT query to the table.

For example, consider a schema for the restaurants data set. This is a sample data set provided by Azure Cosmos DB.

Below is an example document from the collection:

{
  "address":{
    "building":"461",
      "coord":[
        -74.138492,
        40.631136
      ],
      "street":"Port Richmond Ave",
      "zipcode":"10302"
   },
   "borough":"Staten Island",
   "cuisine":"Other",
   "name":"Indian Oven",
   "restaurant_id":"50018994"
}

Customizing a Schema

When GenerateSchemaFiles is set, the Cloud saves schemas into the folder specified by the Location property. You can then change column behavior in the resulting schema.

The following schema uses the other:bsonpath property to define where in the collection to retrieve the data for a particular column. Using this model you can flatten arbitrary levels of hierarchy.

Below are the corresponding column definitions for the restaurants data set. In Custom Schema Example, you will find the complete schema.

<rsb:script xmlns:rsb="http://www.rssbus.com/ns/rsbscript/2">  

  <rsb:info title="StaticRestaurants" description="Custom Schema for the restaurants data set.">  
    <!-- Column definitions -->
    <attr   name="_rid"               xs:type="string"   key="true"   other:collrid="hWdRAKRi3Pg=" other:dbrid="hWdRAA==" other:partitionpath="/name" />
	<attr   name="borough"            xs:type="string"   />
    <attr   name="cuisine"            xs:type="string"   />
    <attr   name="address.building"   xs:type="string"   />
    <attr   name="address.street"     xs:type="string"   />
    <attr   name="address.coord.0"    xs:type="double"   />
    <attr   name="address.coord.1"    xs:type="double"   />
    <input name="rows@next" desc="Internal attribute used for paging through data."  />
  </rsb:info>  

  <rsb:set attr="collection" value="restaurants"/>

</rsb:script>

This section contains a complete schema. The info section enables a relational view of a Azure Cosmos DB object. For more details, see Custom Schema Definitions. The table below allows the SELECT, INSERT, UPDATE, and DELETE commands as implemented in the GET, POST, MERGE, and DELETE sections of the schema below.

Copy the rows@next input as-is into your schema. The operations, such as cosmosdbadoSysData, are internal implementations and can also be copied as is.

Set the Location property to the file directory that will contain the schema file.

When, creating custom schemas, the attr for _rid, shown below, is required.

Also required are three properties for the _rid column definition:

• other:dbrid is found in the _self property of an item in the collection, after "dbs/".
• other:collrid is found in the _self property of an item in the collection, after "/colls/".
• other:partitionpath refers to the name of the partition specified when the collection was created.

<rsb:script xmlns:rsb="http://www.rssbus.com/ns/rsbscript/2">  

  <rsb:info title="StaticRestaurants" description="Custom Schema for the restaurants data set.">  
    <!-- Column definitions -->
	<attr   name="_rid"               xs:type="string"   key="true"   other:collrid="hWdRAKRi3Pg=" other:dbrid="hWdRAA==" other:partitionpath="/name" />
    <attr   name="borough"            xs:type="string"   />
    <attr   name="cuisine"            xs:type="string"   />
    <attr   name="address.building"   xs:type="string"   />
    <attr   name="address.street"     xs:type="string"   />
    <attr   name="address.coord.0"    xs:type="double"   />
    <attr   name="address.coord.1"    xs:type="double"   />
    <input name="rows@next" desc="Internal attribute used for paging through data."  />
  </rsb:info>  

  <rsb:script method="GET">
    <rsb:call op="cosmosdbadoSysData">
      <rsb:push />
    </rsb:call>
  </rsb:script>

  <rsb:script method="POST">
    <rsb:call op="cosmosdbadoSysData">
      <rsb:push />
    </rsb:call>
  </rsb:script>

  <rsb:script method="MERGE">
    <rsb:call op="cosmosdbadoSysData">
      <rsb:push />
    </rsb:call>
  </rsb:script>

  <rsb:script method="DELETE">
    <rsb:call op="cosmosdbadoSysData">
      <rsb:push />
    </rsb:call>
  </rsb:script>

</rsb:script>

You can query the system tables described in this section to access schema information, information on data source functionality, and batch operation statistics.

Schema Tables

The following tables return database metadata for Azure Cosmos DB:

• sys_catalogs: Lists the available databases.
• sys_schemas: Lists the available schemas.
• sys_tables: Lists the available tables and views.
• sys_tablecolumns: Describes the columns of the available tables and views.
• sys_procedures: Describes the available stored procedures.
• sys_procedureparameters: Describes stored procedure parameters.
• sys_keycolumns: Describes the primary and foreign keys.
• sys_indexes: Describes the available indexes.

Data Source Tables

The following tables return information about how to connect to and query the data source:

• sys_connection_props: Returns information on the available connection properties.
• sys_sqlinfo: Describes the SELECT queries that the Cloud can offload to the data source.

Query Information Tables

The following table returns query statistics for data modification queries, including batch operations::

• sys_identity: Returns information about batch operations or single updates.

Lists the available databases.

The following query retrieves all databases determined by the connection string:

SELECT * FROM sys_catalogs

Columns

Lists the available schemas.

The following query retrieves all available schemas:

          SELECT * FROM sys_schemas
          

Columns

Lists the available tables.

The following query retrieves the available tables and views:

          SELECT * FROM sys_tables
          

Columns

Describes the columns of the available tables and views.

The following query returns the columns and data types for the [CData].[Entities].Customers table:

SELECT ColumnName, DataTypeName FROM sys_tablecolumns WHERE TableName='Customers' AND CatalogName='CData' AND SchemaName='Entities'

Columns

Lists the available stored procedures.

The following query retrieves the available stored procedures:

          SELECT * FROM sys_procedures
          

Columns

Describes stored procedure parameters.

The following query returns information about all of the input parameters for the EVAL stored procedure:

SELECT * FROM sys_procedureparameters WHERE ProcedureName='EVAL' AND Direction=1 OR Direction=2

Columns

Describes the primary and foreign keys.

The following query retrieves the primary key for the [CData].[Entities].Customers table:

         SELECT * FROM sys_keycolumns WHERE IsKey='True' AND TableName='Customers' AND CatalogName='CData' AND SchemaName='Entities'
          

Columns

Describes the foreign keys.

The following query retrieves all foreign keys which refer to other tables:

         SELECT * FROM sys_foreignkeys WHERE ForeignKeyType = 'FOREIGNKEY_TYPE_IMPORT'
          

Columns

Describes the primary keys.

The following query retrieves the primary keys from all tables and views:

         SELECT * FROM sys_primarykeys
          

Columns

Describes the available indexes. By filtering on indexes, you can write more selective queries with faster query response times.

The following query retrieves all indexes that are not primary keys:

          SELECT * FROM sys_indexes WHERE IsPrimary='false'
          

Columns

Returns information on the available connection properties and those set in the connection string.

The following query retrieves all connection properties that have been set in the connection string or set through a default value:

SELECT * FROM sys_connection_props WHERE Value <> ''

Columns

Describes the SELECT query processing that the Cloud can offload to the data source.

See SQL Compliance for SQL syntax details.

Discovering the Data Source's SELECT Capabilities

Below is an example data set of SQL capabilities. Some aspects of SELECT functionality are returned in a comma-separated list if supported; otherwise, the column contains NO.

The following query retrieves the operators that can be used in the WHERE clause:

SELECT * FROM sys_sqlinfo WHERE Name = 'SUPPORTED_OPERATORS'

Columns

Returns information about attempted modifications.

The following query retrieves the Ids of the modified rows in a batch operation:

         SELECT * FROM sys_identity
          

Columns

Describes the available system information.

The following query retrieves all columns:

SELECT * FROM sys_information

Columns

Stored procedures are function-like interfaces that extend the functionality of the Cloud beyond simple SELECT/INSERT/UPDATE/DELETE operations with Azure Cosmos DB.

Stored procedures accept a list of parameters, perform their intended function, and then return any relevant response data from Azure Cosmos DB, along with an indication of whether the procedure succeeded or failed.

CData Cloud - Azure Cosmos DB Stored Procedures

Insert entire JSON string to CosmosDB.

Input

Result Set Columns

The connection string properties are the various options that can be used to establish a connection. This section provides a complete list of the options you can configure in the connection string for this provider. Click the links for further details.

Authentication

Azure Authentication

OAuth

JWT OAuth

SSL

Logging

Schema

Miscellaneous

This section provides a complete list of the Authentication properties you can configure in the connection string for this provider.

The type of authentication to use when connecting to Azure Cosmos DB.

Possible Values

Data Type

string

Default Value

"AccountKey"

Remarks

• AccountKey: Set this to perform authentication with AccountKey and AccountEndpoint.
• AzureAD: Set this to perform Azure Active Directory OAuth authentication.
• AzureServicePrincipal: Set this to authenticate as an Azure Service Principal using a Client Secret.
• AzureServicePrincipalCert: Set this to authenticate as an Azure Service Principal using a Certificate.

The value should be the Cosmos DB account URL from the Keys blade of the Cosmos DB account.

Data Type

string

Default Value

""

Remarks

The value should be the Cosmos DB account URL from the Keys blade of the Cosmos DB account.

A master key token or a resource token for connecting to the Azure Cosmos DB REST API.

Data Type

string

Default Value

""

Remarks

In the Azure portal, navigate to the Cosmos DB service and select your Azure Cosmos DB account. From the resource menu, go to the Keys page. Find the PRIMARY KEY value and set Token to this value.

Denotes the type of token: master or resource.

Possible Values

Data Type

string

Default Value

"master"

Remarks

The master key is created during the creation of an account. There are two sets of master keys, the primary key and the secondary key. The administrator of the account can then exercise key rotation using the secondary key. In addition, the account administrator can also regenerate the keys as needed.

Resource tokens are created when users in a database are set up with access permissions for precise access control on a resource, also known as a permission resource. A permission resource contains a hash resource token constructed with the information regarding the resource path and access type a user has access to. The permission resource token is time bound and the validity period can be overridden. When a permission resource is acted upon on (POST, GET, PUT), a new resource token is generated.

This section provides a complete list of the Azure Authentication properties you can configure in the connection string for this provider.

Identifies the Azure Cosmos DB tenant being used to access data, either by name (for example, contoso.omnicrosoft.com) or ID. (Conditional).

Data Type

string

Default Value

""

Remarks

A tenant is a digital representation of your organization, primarily associated with a domain (for example, microsoft.com). The tenant is managed through a Tenant ID (also known as the directory ID), which is specified whenever you assign users permissions to access or manage Azure resources.

To locate the directory ID in the Azure Portal, navigate to Azure Active Directory > Properties.

Specifying AzureTenant is required when AuthScheme = either AzureServicePrincipal or AzureServicePrincipalCert, or if AuthScheme = AzureAD and the user belongs to more than one tenant.

A tenant is a digital representation of your organization, primarily associated with a domain (for example, microsoft.com). The tenant is managed through a Tenant ID (also known as the directory ID), which is specified whenever you assign users permissions to access or manage Azure resources.

To locate the directory ID in the Azure Portal, navigate to Azure Active Directory > Properties.

Specifying AzureTenant is required when AuthScheme = either AzureServicePrincipal or AzureServicePrincipalCert, or if AuthScheme = AzureAD and the user belongs to more than one tenant.

Specifies the Azure network environment to which you will connect. Must be the same network to which your Azure account was added.

Possible Values

Data Type

string

Default Value

"GLOBAL"

Remarks

Required if your Azure account is part of a different network than the Global network, such as China, USGOVT, or USGOVTDOD.

This section provides a complete list of the OAuth properties you can configure in the connection string for this provider.

Specifies the client Id that was assigned the custom OAuth application was created. (Also known as the consumer key.) This ID registers the custom application with the OAuth authorization server.

Data Type

string

Default Value

""

Remarks

OAuthClientId is one of a handful of connection parameters that need to be set before users can authenticate via OAuth. For details, see Establishing a Connection.

Specifies the client secret that was assigned when the custom OAuth application was created. (Also known as the consumer secret ). This secret registers the custom application with the OAuth authorization server.

Data Type

string

Default Value

""

Remarks

OAuthClientSecret is one of a handful of connection parameters that need to be set before users can authenticate via OAuth. For details, see Establishing a Connection.

Specifies the grant type for the chosen OAuth flow. This value should be the same as the grant_type that was set during OAuth custom application creation.

Possible Values

Data Type

string

Default Value

"CODE"

Remarks

In most cases, the default grant type should not be modified. For information about the most common OAuth grant types and the trade-offs between them, see https://oauth.net/2/grant-types/.

This section provides a complete list of the JWT OAuth properties you can configure in the connection string for this provider.

The JWT Certificate store.

Data Type

string

Default Value

""

Remarks

The name of the certificate store for the client certificate.

The OAuthJWTCertType field specifies the type of the certificate store specified by OAuthJWTCert. If the store is password protected, specify the password in OAuthJWTCertPassword.

OAuthJWTCert is used in conjunction with the OAuthJWTCertSubject field in order to specify client certificates. If OAuthJWTCert has a value, and OAuthJWTCertSubject is set, a search for a certificate is initiated. Please refer to the OAuthJWTCertSubject field for details.

Designations of certificate stores are platform-dependent.

The following are designations of the most common User and Machine certificate stores in Windows:

In Java, the certificate store normally is a file containing certificates and optional private keys.

When the certificate store type is PFXFile, this property must be set to the name of the file. When the type is PFXBlob, the property must be set to the binary contents of a PFX file (i.e. PKCS12 certificate store).

The type of key store containing the JWT Certificate.

Possible Values

Data Type

string

Default Value

"PEMKEY_BLOB"

Remarks

This property can take one of the following values:

The password for the OAuth JWT certificate used to access a certificate store that requires a password. If the certificate store does not require a password, leave this property blank.

Data Type

string

Default Value

""

Remarks

This property specifies the password needed to open the certificate store, but only if the store type requires one. To determine if a password is necessary, refer to the documentation or configuration for your specific certificate store.

The subject of the OAuth JWT certificate used to locate a matching certificate in the store. Supports partial matches and the wildcard '*' to select the first certificate.

Data Type

string

Default Value

"*"

Remarks

The value of this property is used to locate a matching certificate in the store. The search process works as follows:

• If an exact match for the subject is found, the corresponding certificate is selected.
• If no exact match is found, the store is searched for certificates whose subjects contain the property value.
• If no match is found, no certificate is selected.

You can set the value to '*' to automatically select the first certificate in the store. The certificate subject is a comma-separated list of distinguished name fields and values. For example: CN=www.server.com, OU=test, C=US, [email protected]. Common fields include:

If a field value contains a comma, enclose it in quotes. For example: "O=ACME, Inc.".

This section provides a complete list of the SSL properties you can configure in the connection string for this provider.

Specifies the TLS/SSL client certificate store for SSL Client Authentication (2-way SSL). This property works in conjunction with other SSL-related properties to establish a secure connection.

Data Type

string

Default Value

""

Remarks

This property specifies the client certificate store for SSL Client Authentication. Use this property alongside SSLClientCertType, which defines the type of the certificate store, and SSLClientCertPassword, which specifies the password for password-protected stores. When SSLClientCert is set and SSLClientCertSubject is configured, the driver searches for a certificate matching the specified subject.

Certificate store designations vary by platform. On Windows, certificate stores are identified by names such as MY (personal certificates), while in Java, the certificate store is typically a file containing certificates and optional private keys.

The following are designations of the most common User and Machine certificate stores in Windows:

For PFXFile types, set this property to the filename. For PFXBlob types, set this property to the binary contents of the file in PKCS12 format.

Specifies the type of key store containing the TLS/SSL client certificate for SSL Client Authentication. Choose from a variety of key store formats depending on your platform and certificate source.

Possible Values

Data Type

string

Default Value

"PEMKEY_BLOB"

Remarks

This property determines the format and location of the key store used to provide the client certificate. Supported values include platform-specific and universal key store formats. The available values and their usage are:

Specifes the password required to access the TLS/SSL client certificate store. Use this property if the selected certificate store type requires a password for access.

Data Type

string

Default Value

""

Remarks

This property provides the password needed to open a password-protected certificate store. This property is necessary when using certificate stores that require a password for decryption, as is often recommended for PFX or JKS type stores.

If the certificate store type does not require a password, for example USER or MACHINE on Windows, this property can be left blank. Ensure that the password matches the one associated with the specified certificate store to avoid authentication errors.

Specifes the subject of the TLS/SSL client certificate to locate it in the certificate store. Use a comma-separated list of distinguished name fields, such as CN=www.server.com, C=US. The wildcard * selects the first certificate in the store.

Data Type

string

Default Value

"*"

Remarks

This property determines which client certificate to load based on its subject. The Cloud searches for a certificate that exactly matches the specified subject. If no exact match is found, the Cloud looks for certificates containing the value of the subject. If no match is found, no certificate is selected.

The subject should follow the standard format of a comma-separated list of distinguished name fields and values. For example, CN=www.server.com, OU=Test, C=US. Common fields include the following:

Note: If any field contains special characters, such as commas, the value must be quoted. For example: CN="Example, Inc.", C=US.

Specifies the certificate to be accepted from the server when connecting using TLS/SSL.

Data Type

string

Default Value

""

Remarks

If using a TLS/SSL connection, this property can be used to specify the TLS/SSL certificate to be accepted from the server. Any other certificate that is not trusted by the machine is rejected.

This property can take the following forms:

If not specified, any certificate trusted by the machine is accepted.

Use '*' to signify to accept all certificates. Note that this is not recommended due to security concerns.

This section provides a complete list of the Logging properties you can configure in the connection string for this provider.

Specifies the verbosity level of the log file, which controls the amount of detail logged. Supported values range from 1 to 5.

Data Type

string

Default Value

"1"

Remarks

This property defines the level of detail the Cloud includes in the log file. Higher verbosity levels increase the detail of the logged information, but may also result in larger log files and slower performance due to the additional data being captured.

The default verbosity level is 1, which is recommended for regular operation. Higher verbosity levels are primarily intended for debugging purposes. For more information on each level, refer to Logging.

When combined with the LogModules property, Verbosity can refine logging to specific categories of information.

This section provides a complete list of the Schema properties you can configure in the connection string for this provider.

Optional setting that restricts the schemas reported to a subset of all available schemas. For example, BrowsableSchemas=SchemaA,SchemaB,SchemaC .

Data Type

string

Default Value

""

Remarks

Listing all available database schemas can take extra time, thus degrading performance. Providing a list of schemas in the connection string saves time and improves performance.

Specify the Azure Cosmos DB database you want to work with.

Data Type

string

Default Value

""

Remarks

Specify the Azure Cosmos DB database you want to work with.

This section provides a complete list of the Miscellaneous properties you can configure in the connection string for this provider.

Specifies whether will return the calculated value of the aggregates or grouped by partiton range.

Data Type

bool

Default Value

true

Remarks

Specifies whether will return the calculated value of the aggregates or grouped by partiton range.

Denotes the type of token: master or resource.

Possible Values

Data Type

string

Default Value

"SESSION"

Remarks

The consistency level override for read options against documents and attachments. 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.

The consistency level override for read options against documents and attachments. 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.

By default, nested arrays are returned as strings of JSON. The FlattenArrays property can be used to flatten the elements of nested arrays into columns of their own. Set FlattenArrays to the number of elements you want to return from nested arrays.

Data Type

string

Default Value

"0"

Remarks

By default, nested arrays are returned as strings of JSON. The FlattenArrays property can be used to flatten the elements of nested arrays into columns of their own. This is only recommended for arrays that are expected to be short.

Set FlattenArrays to the number of elements you want to return from nested arrays. The specified elements are returned as columns. The zero-based index is concatenated to the column name. Other elements are ignored.

For example, you can return an arbitrary number of elements from an array of strings:

["FLOW-MATIC","LISP","COBOL"]

Setting FlattenArrays to -1 will flatten all the elements of nested arrays.

Set FlattenObjects to true to flatten object properties into columns of their own. Otherwise, objects nested in arrays are returned as strings of JSON.

Data Type

bool

Default Value

true

Remarks

Set FlattenObjects to true to flatten object properties into columns of their own. Otherwise, objects nested in arrays are returned as strings of JSON. The property name is concatenated onto the object name with a dot to generate the column name.

For example, you can flatten the nested objects below at connection time:

[
     { "grade": "A", "score": 2 },
     { "grade": "A", "score": 6 },
     { "grade": "A", "score": 10 },
     { "grade": "A", "score": 9 },
     { "grade": "B", "score": 14 }
]

Force the use of an index scan to process the query if indexing is disabled or the right index path is not available.

Data Type

bool

Default Value

false

Remarks

Queries against containers where indexing is disabled or paths are excluded may fail. Set this property to true to force the use of indexing on the server so the query is processed successfully. By default, queries that require the use of indexing on containers where IndexingMode=None are handled client-side.

Specifies the maximum rows returned for queries without aggregation or GROUP BY.

Data Type

int

Default Value

-1

Remarks

This property sets an upper limit on the number of rows the Cloud returns for queries that do not include aggregation or GROUP BY clauses. This limit ensures that queries do not return excessively large result sets by default.

When a query includes a LIMIT clause, the value specified in the query takes precedence over the MaxRows setting. If MaxRows is set to "-1", no row limit is enforced unless a LIMIT clause is explicitly included in the query.

This property is useful for optimizing performance and preventing excessive resource consumption when executing queries that could otherwise return very large datasets.

Specifies the maximum number of concurrent requests for Batch CUD (Create, Update, Delete) operations.

Data Type

int

Default Value

200

Remarks

This property should be used in conjunction with the WriteThroughputBudget connection property. The Cloud may execute less parallel requests than the configured MaxThreads value, since it always aims to not exceed the WriteThroughputBudget limit. The number of concurrent requests will also depend on the running machine's resources.

Note: This property is applicable only when executing batch CUD operations.

Aggregate queries in partitioned collections will require parallel requests for different partition ranges. Set this to the number of parallel request to be issued in the same time.

Data Type

string

Default Value

"5"

Remarks

Aggregate queries in partitioned collections will require parallel requests for different partition ranges. Set this to the number of parallel request to be issued in the same time.

Specifies the maximum number of results to return from Azure Cosmos DB, per page. This setting overrides the default page size set by the datasource, which is optimized for most use cases.

Data Type

int

Default Value

1000

Remarks

You may want to adjust the default pagesize to optimize results for a particular object or service endpoint you are querying. Be aware that increasing the page size may improve performance, but it could also result in higher memory consumption per page.

Specifies the pseudocolumns to expose as table columns. Use the format 'TableName=ColumnName;TableName=ColumnName'. The default is an empty string, which disables this property.

Data Type

string

Default Value

""

Remarks

This property allows you to define which pseudocolumns the Cloud exposes as table columns.

To specify individual pseudocolumns, use the following format: "Table1=Column1;Table1=Column2;Table2=Column3"

To include all pseudocolumns for all tables use: "*=*"

Specifies the priority level for requests sent to Azure Cosmos DB when the number of requests exceeds the configured RU/s within a second.

Possible Values

Data Type

string

Default Value

"None"

Remarks

• None: Sends requests with the default priority.
• Low: Sends requests with low priority.
• High: Sends requests with high priority.

The maximum number of rows to scan to look for the columns available in a table.

Data Type

int

Default Value

100

Remarks

The columns in a table must be determined by scanning table rows. This value determines the maximum number of rows that will be scanned.

Setting a high value may decrease performance. Setting a low value may prevent the data type from being determined properly, especially when there is null data.

The character or characters used to denote hierarchy.

Data Type

string

Default Value

"."

Remarks

In order to flatten out hierarchical structures, the Cloud needs some specifier that states the path to a column through the hierarchy. If this value is "." and a column comes back with the name address.city, this indicates that there is a mapped attribute with a child called city. If your data has columns that already use a single period within the attribute name, set the SeparatorCharacter to a different character or characters.

Whether or not to use the collection's Partition Key field as part of composite Primary Key for the corresponding exposed table.

Data Type

bool

Default Value

true

Remarks

By default, this is set to TRUE, and the collection's Partition Key is used as part of the table's composite Primary Key along with the _rid column. If this is set to FALSE, only the _rid column will serve as the Primary Key for the exposed table.

Specifies the maximum time, in seconds, that the provider waits for a server response before throwing a timeout error. The default is 60 seconds. Set to 0 to disable the timeout.

Data Type

int

Default Value

60

Remarks

This property controls the maximum time, in seconds, that the Cloud waits for an operation to complete before canceling it. If the timeout period expires before the operation finishes, the Cloud cancels the operation and throws an exception.

The timeout applies to each individual communication with the server rather than the entire query or operation. For example, a query could continue running beyond 60 seconds if each paging call completes within the timeout limit.

Setting this property to 0 disables the timeout, allowing operations to run indefinitely until they succeed or fail due to other conditions such as server-side timeouts, network interruptions, or resource limits on the server. Use this property cautiously to avoid long-running operations that could degrade performance or result in unresponsive behavior.

Comma-separated options for how the provider will scan the data to determine the fields and datatypes in each document collection.

Data Type

string

Default Value

"RowScan,Recent"

Remarks

Set this property to false to switch using the id column as primary key instead the default _rid.

Data Type

bool

Default Value

true

Remarks

Since CosmosDB allows you to use both _rid and id fields as unique values for retrieving resource data, you can set this property to false to switch using the id column as primary key instead the default _rid.

Defines the Requests Units (RU) budget per Second that the Batch CUD (Create, Update, Delete) operations should not exceed.

Data Type

int

Default Value

1000

Remarks

The Cloud will dynamically adjust the maximum number of requests per second depending on the configured RU budget. Although the Cloud always aims to not exceed the RU budget, since the requests throttling logic is applied client-side, it may be exceeded by a relatively small amount in a few cases. These cases include inserting, updating and deleting records with highly variable column count and input value length per column.

Note: This property is applicable only when executing batch CUD operations.