Module azure_cosmosdb

ballerinax/azure_cosmosdb Ballerina library

4.2.0

Overview

It provides the capability to connect to Azure Cosmos DB and execute CRUD (Create, Read, Update, and Delete) operations for databases and containers, to execute SQL queries to query containers, etc. In addition, it allows the special features provided by Cosmos DB such as operations on JavaScript language-integrated queries, management of users and permissions, etc.

This module supports Azure Cosmos DB(SQL) API version 2018-12-31.

Prerequisites

Before using this connector in your Ballerina application, complete the following:

Create a Microsoft Account with Azure Subscription
Create an Azure Cosmos DB account
Obtain tokens
1. Go to your Azure Cosmos DB account and click Keys.
2. Copy the URI and PRIMARY KEY in the Read-write Keys tab.

Quickstart

To use the Azure Cosmos DB connector in your Ballerina application, update the .bal file as follows:

Step 1 - Import connector

Import the ballerinax/azure_cosmosdb module into the Ballerina project.


import ballerinax/azure_cosmosdb as cosmosdb;

Step 2 - Create a new connector instance

You can now add the connection configuration with the Master-Token or Resource-Token, and the resource URI to the Cosmos DB Account.


cosmosdb:ConnectionConfig configuration = {
    baseUrl: <URI>,
    primaryKeyOrResourceToken: <PRIMARY_KEY>
};
cosmosdb:DataPlaneClient azureCosmosClient = check new (configuration);

Step 3 - Invoke connector operation

Create a document
Once you follow the above steps. you can create a new document inside the Cosmos container as shown below. Cosmos DB is designed to store and query JSON-like documents. Therefore, the document you create must be of the JSON type. In this example, the document ID is my_document


map<json> document = {
        "FirstName": "Alan",
        "FamilyName": "Turing",
        "Parents": [{
            "FamilyName": "Turing",
            "FirstName": "Julius"
        }, {
            "FamilyName": "Stoney",
            "FirstName": "Ethel"
        }],
        "gender": 0
};
int valueOfPartitionKey = 0;
string id = "my_document";

cosmosdb:DocumentResponse response = check azureCosmosClient-> createDocument("my_database", "my_container", id, document, valueOfPartitionKey);

Note:

This document is created inside an already existing container with ID my_container and the container was created inside a database with ID my_database.
As this container have selected path /gender as the partition key path. The document you create should include that path with a valid value.
The document is represented as map<json>

Use bal run command to compile and run the Ballerina program

You can find a list of samples here

Classes

azure_cosmosdb: CosmosResultIterator

Represents CosmosResultIterator.

nextResult

Isolated Function

function nextResult(ResultIterator iterator) returns record {}|Error?

Parameters

iterator ResultIterator -

azure_cosmosdb: ResultIterator

Represents ResultIterator.

Isolated Function

function next() returns record {| value record {} |}|Error?

Clients

azure_cosmosdb: DataPlaneClient

Isolated

This is the Azure Cosmos DB SQL API, a fast NoSQL database servic offers rich querying over diverse data, helps deliver configurable and reliable performance, is globally distributed, and enables rapid development.

Constructor

Gets invoked to initialize the connector. The connector initialization requires setting the API credentials. Create an Azure Cosmos DB account and obtain tokens following this guide.

init (ConnectionConfig config)

config ConnectionConfig -

createDocument

Isolated FunctionRemote Function

function createDocument(string databaseId, string containerId, string documemtId, map<json> document, int|float|decimal|string partitionKey, RequestOptions? requestOptions) returns DocumentResponse|error

Creates a document.

Parameters

databaseId string - ID of the database to which the container belongs to

containerId string - ID of the container where, document is created

documemtId string - ID of the document

document map<json> - A JSON document to be saved in the database

partitionKey int|float|decimal|string - The specific value related to the partition key field of the container

requestOptions RequestOptions? (default ()) - The cosmos_db:RequestOptions which can be used to add additional capabilities that can override client configuration provided in the inilization

Return Type

DocumentResponse|error - Error if failed

replaceDocument

Isolated FunctionRemote Function

function replaceDocument(string databaseId, string containerId, string documentId, map<json> document, int|float|decimal|string partitionKey, RequestOptions? requestOptions) returns DocumentResponse|error

Replaces a document.

Parameters

databaseId string - ID of the database to which the container belongs to

containerId string - ID of the container which contains the existing document

documentId string - Current ID of the document

document map<json> - A JSON document which will replace the existing document

partitionKey int|float|decimal|string - The specific value related to the partition key field of the container

requestOptions RequestOptions? (default ()) - The cosmos_db:RequestOptions which can be used to add additional capabilities that can override client configuration provided in the inilization

Return Type

DocumentResponse|error - Error if failed

getDocument

Isolated FunctionRemote Function

function getDocument(string databaseId, string containerId, string documentId, int|float|decimal|string partitionKey, RequestOptions? requestOptions, typedesc<record {}> returnType) returns returnType|error

Gets information about a document.

Parameters

databaseId string - ID of the database to which the container belongs to

containerId string - ID of the container which contains the document

documentId string - ID of the document

partitionKey int|float|decimal|string - The value of partition key field of the container

requestOptions RequestOptions? (default ()) - The cosmos_db:RequestOptions which can be used to add additional capabilities that can override client configuration provided in the inilization

returnType typedesc<record {}> (default <>) - Type need to be inferred.

Return Type

returnType|error - If successful, returns given target record. Else returns error.

getDocumentList

Isolated FunctionRemote Function

function getDocumentList(string databaseId, string containerId, int|float|decimal|string partitionKey, QueryOptions? queryOptions, typedesc<record {}> returnType) returns stream<returnType, error?>|error

Lists information of all the documents .

Parameters

databaseId string - ID of the database to which the container belongs to

containerId string - ID of the container which contains the document

partitionKey int|float|decimal|string - The value of partition key field of the container

queryOptions QueryOptions? (default ()) - The cosmos_db:QueryOptions which can be used to add additional capabilities that can override client configuration provided in the inilization

returnType typedesc<record {}> (default <>) - Type need to be inferred.

Return Type

stream<returnType, error?>|error - If successful, returns stream<returnType, error>. Else, returns error.

deleteDocument

Isolated FunctionRemote Function

function deleteDocument(string databaseId, string containerId, string documentId, int|float|decimal|string partitionKey, RequestOptions? requestOptions) returns DocumentResponse|error

Deletes a document.

Parameters

databaseId string - ID of the database to which the container belongs to

containerId string - ID of the container which contains the document

documentId string - ID of the document

partitionKey int|float|decimal|string - The specific value related to the partition key field of the container

requestOptions RequestOptions? (default ()) - The cosmos_db:RequestOptions which can be used to add additional capabilities that can override client configuration provided in the inilization

Return Type

DocumentResponse|error - Error if failed

queryDocuments

Isolated FunctionRemote Function

function queryDocuments(string databaseId, string containerId, string sqlQuery, QueryOptions? queryOptions, typedesc<record {}> returnType) returns stream<returnType, error?>|error

Queries documents.

Parameters

databaseId string - ID of the database to which the container belongs to

containerId string - ID of the container to query

sqlQuery string - A string containing the SQL query

queryOptions QueryOptions? (default ()) - The cosmos_db:QueryOptions which can be used to add additional capabilities that can override client configuration provided in the inilization

returnType typedesc<record {}> (default <>) - Type need to be inferred.

Return Type

stream<returnType, error?>|error - If successful, returns a stream<returnType, error>. Else returns error.

createStoredProcedure

Isolated FunctionRemote Function

function createStoredProcedure(string databaseId, string containerId, string storedProcedureId, string storedProcedure, CosmosStoredProcedureRequestOptions? options) returns StoredProcedureResponse|error

Creates a new stored procedure.

Parameters

databaseId string - ID of the database to which the container belongs to

containerId string - ID of the container where, stored procedure will be created

storedProcedureId string - A unique ID for the newly created stored procedure

storedProcedure string - A JavaScript function represented as a string

options CosmosStoredProcedureRequestOptions? (default ()) - The cosmos_db:CosmosStoredProcedureRequestOptions which can be used to add additional capabilities that can override client configuration provided in the inilization

Return Type

StoredProcedureResponse|error - If successful, returns a cosmos_db:StoredProcedure. Else returns error.

listStoredProcedures

Isolated FunctionRemote Function

function listStoredProcedures(string databaseId, string containerId) returns stream<StoredProcedure, error?>|error

Lists information of all stored procedures.

Parameters

databaseId string - ID of the database to which the container belongs to

containerId string - ID of the container which contains the stored procedures

Return Type

stream<StoredProcedure, error?>|error - If successful, returns a stream<cosmos_db:StoredProcedure, error>. Else returns error.

deleteStoredProcedure

Isolated FunctionRemote Function

function deleteStoredProcedure(string databaseId, string containerId, string storedProcedureId) returns StoredProcedureResponse|error

Deletes a stored procedure.

Parameters

databaseId string - ID of the database to which the container belongs to

containerId string - ID of the container which contains the stored procedure

storedProcedureId string - ID of the stored procedure to delete

Return Type

StoredProcedureResponse|error - Error if failed

executeStoredProcedure

Isolated FunctionRemote Function

function executeStoredProcedure(string databaseId, string containerId, string storedProcedureId, int|float|decimal|string patitionKey, StoredProcedureExecuteOptions? storedProcedureExecuteOptions) returns StoredProcedureResponse|error

Executes a stored procedure.

Parameters

databaseId string - ID of the database to which the container belongs to

containerId string - ID of the container which contains the stored procedure

storedProcedureId string - ID of the stored procedure to execute

patitionKey int|float|decimal|string - The specific value related to the partition key field of the container

storedProcedureExecuteOptions StoredProcedureExecuteOptions? (default ()) - A record cosmos_db:StoredProcedureExecuteOptions to specify the additional parameters

Return Type

StoredProcedureResponse|error - error if failed

close

Isolated FunctionRemote Function

function close() returns error?

azure_cosmosdb: ManagementClient

Isolated

Constructor

Gets invoked to initialize the connector. The HTTP client initialization requires setting the API credentials. Create an Azure Cosmos DB account and obtain tokens following this guide.

init (ManagementClientConfig config)

config ManagementClientConfig -

createDatabase

Isolated FunctionRemote Function

function createDatabase(string databaseId, (int|record {| maxThroughput int |})? throughputOption) returns Database|Error

Creates a database.

Parameters

databaseId string - ID of the new database. Must be a unique value.

throughputOption (int|record {| maxThroughput int |})? (default ()) - Throughput parameter of type int or json.

Return Type

Database|Error - If successful, returns cosmos_db:Database. Else returns cosmos_db:Error.

createDatabaseIfNotExist

Isolated FunctionRemote Function

function createDatabaseIfNotExist(string databaseId, (int|record {| maxThroughput int |})? throughputOption) returns Database?|Error

Creates a database only if the specified database ID does not exist already.

Parameters

databaseId string - ID of the new database. Must be a unique value.

throughputOption (int|record {| maxThroughput int |})? (default ()) - Throughput parameter of type int or json.

Return Type

Database?|Error - If successful, returns cosmos_db:Database or () if database already exists. Else returns cosmos_db:Error.

getDatabase

Isolated FunctionRemote Function

function getDatabase(string databaseId, ResourceReadOptions? resourceReadOptions) returns Database|Error

Gets information of a given database.

Parameters

databaseId string - ID of the database

resourceReadOptions ResourceReadOptions? (default ()) - The cosmos_db:ResourceReadOptions which can be used to add additional capabilities to the request

Return Type

Database|Error - If successful, returns cosmos_db:Database. Else returns cosmos_db:Error.

listDatabases

Isolated FunctionRemote Function

function listDatabases() returns stream<Database, error?>|Error

Lists information of all databases.

Return Type

stream<Database, error?>|Error - If successful, returns stream<cosmos_db:Database, error>. else returns cosmos_db:Error.

deleteDatabase

Isolated FunctionRemote Function

function deleteDatabase(string databaseId, ResourceDeleteOptions? resourceDeleteOptions) returns DeleteResponse|Error

Deletes a given database.

Parameters

databaseId string - ID of the database to delete

resourceDeleteOptions ResourceDeleteOptions? (default ()) - The cosmos_db:ResourceDeleteOptions which can be used to add additional capabilities to the request

Return Type

DeleteResponse|Error - If successful, returns cosmos_db:DeleteResponse. Else returns cosmos_db:Error.

createContainer

Isolated FunctionRemote Function

function createContainer(string databaseId, string containerId, PartitionKey partitionKey, IndexingPolicy? indexingPolicy, (int|record {| maxThroughput int |})? throughputOption) returns Container|Error

Creates a container inside the given database.

Parameters

databaseId string - ID of the database to which the container belongs to

containerId string - ID of the new container. Must be a unique value.

partitionKey PartitionKey - A record cosmos_db:PartitionKey

indexingPolicy IndexingPolicy? (default ()) - A record cosmos_db:IndexingPolicy.

throughputOption (int|record {| maxThroughput int |})? (default ()) - Throughput parameter of type int or json.

Return Type

Container|Error - If successful, returns cosmos_db:Container. Else returns cosmos_db:Error.

createContainerIfNotExist

Isolated FunctionRemote Function

function createContainerIfNotExist(string databaseId, string containerId, PartitionKey partitionKey, IndexingPolicy? indexingPolicy, (int|record {| maxThroughput int |})? throughputOption) returns Container?|Error

Creates a container only if the specified container ID does not exist already.

Parameters

databaseId string - ID of the database to which the container belongs to

containerId string - ID of the new container

partitionKey PartitionKey - A record of cosmos_db:PartitionKey

indexingPolicy IndexingPolicy? (default ()) - A record of cosmos_db:IndexingPolicy.

throughputOption (int|record {| maxThroughput int |})? (default ()) - Throughput parameter of type int or json.

Return Type

Container?|Error - If successful, returns cosmos_db:Container if a new container is created or () if container already exists. Else returns cosmos_db:Error.

getContainer

Isolated FunctionRemote Function

function getContainer(string databaseId, string containerId, ResourceReadOptions? resourceReadOptions) returns Container|Error

Gets information about a container.

Parameters

databaseId string - ID of the database to which the container belongs to

containerId string - ID of the container

resourceReadOptions ResourceReadOptions? (default ()) - The cosmos_db:ResourceReadOptions which can be used to add additional capabilities to the request

Return Type

Container|Error - If successful, returns cosmos_db:Container. Else returns cosmos_db:Error.

listContainers

Isolated FunctionRemote Function

function listContainers(string databaseId) returns stream<Container, error?>|Error

Lists information of all containers.

Parameters

databaseId string - ID of the database to which the containers belongs to

Return Type

stream<Container, error?>|Error - If successful, returns stream<cosmos_db:Container, error>. Else returns cosmos_db:Error.

deleteContainer

Isolated FunctionRemote Function

function deleteContainer(string databaseId, string containerId, ResourceDeleteOptions? resourceDeleteOptions) returns DeleteResponse|Error

Deletes a container.

Parameters

databaseId string - ID of the database to which the container belongs to

containerId string - ID of the container to delete

resourceDeleteOptions ResourceDeleteOptions? (default ()) - The cosmos_db:ResourceDeleteOptions which can be used to add additional capabilities to the request

Return Type

DeleteResponse|Error - If successful, returns cosmos_db:DeleteResponse. Else returns cosmos_db:Error.

listPartitionKeyRanges

Isolated FunctionRemote Function

function listPartitionKeyRanges(string databaseId, string containerId) returns stream<PartitionKeyRange, error?>|Error

Retrieves a list of partition key ranges for the container.

Parameters

databaseId string - ID of the database to which the container belongs to

containerId string - ID of the container where the partition key ranges are related to

Return Type

stream<PartitionKeyRange, error?>|Error - If successful, returns stream<cosmos_db:PartitionKeyRange, error>. Else returns cosmos_db:Error.

createUserDefinedFunction

Isolated FunctionRemote Function

function createUserDefinedFunction(string databaseId, string containerId, string userDefinedFunctionId, string userDefinedFunction) returns UserDefinedFunction|Error

Creates a new User Defined Function.

Parameters

databaseId string - ID of the database to which the container belongs to

containerId string - ID of the container where, User Defined Function is created

userDefinedFunctionId string - A unique ID for the newly created User Defined Function

userDefinedFunction string - A JavaScript function represented as a string

Return Type

UserDefinedFunction|Error - If successful, returns a cosmos_db:UserDefinedFunction. Else returns cosmos_db:Error.

replaceUserDefinedFunction

Isolated FunctionRemote Function

function replaceUserDefinedFunction(string databaseId, string containerId, string userDefinedFunctionId, string userDefinedFunction) returns UserDefinedFunction|Error

Replaces an existing User Defined Function.

Parameters

databaseId string - ID of the database to which the container belongs to

containerId string - ID of the container which contains the existing User Defined Function

userDefinedFunctionId string - The ID of the User Defined Function to replace

userDefinedFunction string - A JavaScript function represented as a string

Return Type

UserDefinedFunction|Error - If successful, returns a cosmos_db:UserDefinedFunction. Else returns cosmos_db:Error.

listUserDefinedFunctions

Isolated FunctionRemote Function

function listUserDefinedFunctions(string databaseId, string containerId, ResourceReadOptions? resourceReadOptions) returns stream<UserDefinedFunction, error?>|Error

Gets a list of existing user defined functions.

Parameters

databaseId string - ID of the database to which the container belongs to

containerId string - ID of the container which contains the user defined functions

resourceReadOptions ResourceReadOptions? (default ()) - The cosmos_db:ResourceReadOptions which can be used to add additional capabilities to the request

Return Type

stream<UserDefinedFunction, error?>|Error - If successful, returns a stream<cosmos_db:UserDefinedFunction, error>. Else returns cosmos_db:Error.

deleteUserDefinedFunction

Isolated FunctionRemote Function

function deleteUserDefinedFunction(string databaseId, string containerId, string userDefinedFunctionid, ResourceDeleteOptions? resourceDeleteOptions) returns DeleteResponse|Error

Deletes an existing User Defined Function.

Parameters

databaseId string - ID of the database to which the container belongs to

containerId string - ID of the container which contains the User Defined Function

userDefinedFunctionid string - ID of UDF to delete

resourceDeleteOptions ResourceDeleteOptions? (default ()) - The cosmos_db:ResourceDeleteOptions which can be used to add additional capabilities to the request

Return Type

DeleteResponse|Error - If successful, returns cosmos_db:DeleteResponse. Else returns cosmos_db:Error.

createTrigger

Isolated FunctionRemote Function

function createTrigger(string databaseId, string containerId, string triggerId, string trigger, TriggerOperation triggerOperation, TriggerType triggerType) returns Trigger|Error

Creates a trigger.

Parameters

databaseId string - ID of the database to which the container belongs to

containerId string - ID of the container where trigger is created

triggerId string - A unique ID for the newly created trigger

trigger string - A JavaScript function represented as a string

triggerOperation TriggerOperation - The specific operation in which trigger will be executed can be All, Create, Replace or Delete

triggerType TriggerType - The instance in which trigger will be executed Pre or Post

Return Type

Trigger|Error - If successful, returns a cosmos_db:Trigger. Else returns cosmos_db:Error.

replaceTrigger

Isolated FunctionRemote Function

function replaceTrigger(string databaseId, string containerId, string triggerId, string trigger, TriggerOperation triggerOperation, TriggerType triggerType) returns Trigger|Error

Replaces an existing trigger.

Parameters

databaseId string - ID of the database to which the container belongs to

containerId string - ID of the container which contains the trigger

triggerId string - The ID of the trigger to be replaced

trigger string - A JavaScript function represented as a string

triggerOperation TriggerOperation - The specific operation in which trigger will be executed

triggerType TriggerType - The instance in which trigger will be executed Pre or Post

Return Type

Trigger|Error - If successful, returns a cosmos_db:Trigger. Else returns cosmos_db:Error.

listTriggers

Isolated FunctionRemote Function

function listTriggers(string databaseId, string containerId, ResourceReadOptions? resourceReadOptions) returns stream<Trigger, error?>|Error

Lists existing triggers.

Parameters

databaseId string - ID of the database to which the container belongs to

containerId string - ID of the container which contains the triggers

resourceReadOptions ResourceReadOptions? (default ()) - The cosmos_db:ResourceReadOptions which can be used to add additional capabilities to the request

Return Type

stream<Trigger, error?>|Error - If successful, returns a stream<cosmos_db:Trigger, error>. Else returns cosmos_db:Error.

deleteTrigger

Isolated FunctionRemote Function

function deleteTrigger(string databaseId, string containerId, string triggerId, ResourceDeleteOptions? resourceDeleteOptions) returns DeleteResponse|Error

Deletes an existing trigger.

Parameters

databaseId string - ID of the database to which the container belongs to

containerId string - ID of the container which contains the trigger

triggerId string - ID of the trigger to be deleted

resourceDeleteOptions ResourceDeleteOptions? (default ()) - The cosmos_db:ResourceDeleteOptions which can be used to add additional capabilities to the request

Return Type

DeleteResponse|Error - If successful, returns cosmos_db:DeleteResponse. Else returns cosmos_db:Error.

createUser

Isolated FunctionRemote Function

function createUser(string databaseId, string userId) returns User|Error

Creates a user for a given database.

Parameters

databaseId string - ID of the database where the user is created.

userId string - ID of the new user. Must be a unique value.

Return Type

User|Error - If successful, returns a cosmos_db:User. Else returns cosmos_db:Error.

replaceUserId

Isolated FunctionRemote Function

function replaceUserId(string databaseId, string userId, string newUserId) returns User|Error

Replaces the ID of an existing user.

Parameters

databaseId string - ID of the database to which, the existing user belongs to

userId string - Old ID of the user

newUserId string - New ID for the user

Return Type

User|Error - If successful, returns a cosmos_db:User. Else returns cosmos_db:Error.

getUser

Isolated FunctionRemote Function

function getUser(string databaseId, string userId, ResourceReadOptions? resourceReadOptions) returns User|Error

Gets information of a user.

Parameters

databaseId string - ID of the database to which, the user belongs to

userId string - ID of user

resourceReadOptions ResourceReadOptions? (default ()) - The cosmos_db:ResourceReadOptions which can be used to add additional capabilities to the request

Return Type

User|Error - If successful, returns a cosmos_db:User. Else returns cosmos_db:Error.

listUsers

Isolated FunctionRemote Function

function listUsers(string databaseId, ResourceReadOptions? resourceReadOptions) returns stream<User, error?>|Error

Lists users of a specific database.

Parameters

databaseId string - ID of the database to which, the user belongs to

resourceReadOptions ResourceReadOptions? (default ()) - The cosmos_db:ResourceReadOptions which can be used to add additional capabilities to the request

Return Type

stream<User, error?>|Error - If successful, returns a stream<cosmos_db:User, error>. Else returns cosmos_db:Error.

deleteUser

Isolated FunctionRemote Function

function deleteUser(string databaseId, string userId, ResourceDeleteOptions? resourceDeleteOptions) returns DeleteResponse|Error

Deletes a user.

Parameters

databaseId string - ID of the database to which, the user belongs to

userId string - ID of the user to delete

resourceDeleteOptions ResourceDeleteOptions? (default ()) - The cosmos_db:ResourceDeleteOptions which can be used to add additional capabilities to the request

Return Type

DeleteResponse|Error - If successful, returns cosmos_db:DeleteResponse. Else returns cosmos_db:Error.

createPermission

Isolated FunctionRemote Function

function createPermission(string databaseId, string userId, string permissionId, PermisssionMode permissionMode, string resourcePath, int? validityPeriodInSeconds) returns Permission|Error

Creates a permission for a user.

Parameters

databaseId string - ID of the database to which, the user belongs to

userId string - ID of user to which, the permission is granted. Must be a unique value.

permissionId string - A unique ID for the newly created permission

permissionMode PermisssionMode - The mode to which the permission is scoped

resourcePath string - The resource this permission is allowing the user to access

validityPeriodInSeconds int? (default ()) - Validity period of the permission in seconds.

Return Type

Permission|Error - If successful, returns a cosmos_db:Permission. Else returns cosmos_db:Error.

replacePermission

Isolated FunctionRemote Function

function replacePermission(string databaseId, string userId, string permissionId, PermisssionMode permissionMode, string resourcePath, int? validityPeriodInSeconds) returns Permission|Error

Replaces an existing permission.

Parameters

databaseId string - ID of the database where the user is created

userId string - ID of user to which, the permission is granted

permissionId string - The ID of the permission to be replaced

permissionMode PermisssionMode - The mode to which the permission is scoped

resourcePath string - The resource this permission is allowing the user to access

validityPeriodInSeconds int? (default ()) - Validity period of the permission in seconds.

Return Type

Permission|Error - If successful, returns a cosmos_db:Permission. Else returns cosmos_db:Error.

getPermission

Isolated FunctionRemote Function

function getPermission(string databaseId, string userId, string permissionId, ResourceReadOptions? resourceReadOptions) returns Permission|Error

Gets information of a permission.

Parameters

databaseId string - ID of the database where the user is created

userId string - ID of user to which, the permission is granted

permissionId string - ID of the permission

resourceReadOptions ResourceReadOptions? (default ()) - The cosmos_db:ResourceReadOptions which can be used to add additional capabilities to the request

Return Type

Permission|Error - If successful, returns a cosmos_db:Permission. Else returns cosmos_db:Error.

listPermissions

Isolated FunctionRemote Function

function listPermissions(string databaseId, string userId, ResourceReadOptions? resourceReadOptions) returns stream<Permission, error?>|Error

Lists permissions belong to a user.

Parameters

databaseId string - ID of the database where the user is created

userId string - ID of user to which, the permissions are granted

resourceReadOptions ResourceReadOptions? (default ()) - The cosmos_db:ResourceReadOptions which can be used to add additional capabilities to the request

Return Type

stream<Permission, error?>|Error - If successful, returns a stream<cosmos_db:Permission, error>. Else returns cosmos_db:Error.

deletePermission

Isolated FunctionRemote Function

function deletePermission(string databaseId, string userId, string permissionId, ResourceDeleteOptions? resourceDeleteOptions) returns DeleteResponse|Error

Deletes a permission belongs to a user.

Parameters

databaseId string - ID of the database where the user is created

userId string - ID of user to which, the permission is granted

permissionId string - ID of the permission to delete

resourceDeleteOptions ResourceDeleteOptions? (default ()) - The cosmos_db:ResourceDeleteOptions which can be used to add additional capabilities to the request

Return Type

DeleteResponse|Error - If successful, returns cosmos_db:DeleteResponse. Else returns cosmos_db:Error.

replaceOffer

Isolated FunctionRemote Function

function replaceOffer(Offer offer) returns Offer|Error

Replaces an existing offer.

Parameters

offer Offer - A record cosmos_db:Offer

Return Type

Offer|Error - If successful, returns a cosmos_db:Offer. Else returns cosmos_db:Error.

getOffer

Isolated FunctionRemote Function

function getOffer(string offerId, ResourceReadOptions? resourceReadOptions) returns Offer|Error

Gets information about an offer.

Parameters

offerId string - The ID of the offer

resourceReadOptions ResourceReadOptions? (default ()) - The cosmos_db:ResourceReadOptions which can be used to add additional capabilities to the request

Return Type

Offer|Error - If successful, returns a cosmos_db:Offer. Else returns cosmos_db:Error.

listOffers

Isolated FunctionRemote Function

function listOffers(ResourceReadOptions? resourceReadOptions) returns stream<Offer, error?>|Error

Lists information of offers.

Parameters

resourceReadOptions ResourceReadOptions? (default ()) - The cosmos_db:ResourceReadOptions which can be used to add additional capabilities to the request

Return Type

stream<Offer, error?>|Error - If successful, returns a stream<cosmos_db:Offer, error> Else returns cosmos_db:Error.

queryOffer

Isolated FunctionRemote Function

function queryOffer(string sqlQuery, ResourceQueryOptions? resourceQueryOptions) returns stream<Offer, error?>|Error

Performs queries on offer resources.

Parameters

sqlQuery string - A string value containing SQL query

resourceQueryOptions ResourceQueryOptions? (default ()) - The cosmos_db:ResourceQueryOptions which can be used to add additional capabilities to the request

Return Type

stream<Offer, error?>|Error - If successful, returns a stream<cosmos_db:Offer, error>. Else returns cosmos_db:Error.

Constants

azure_cosmosdb: PARTITION_KEY_VERSION_1

int 1

Version of the partition key if it is smaller than 100 bytes

azure_cosmosdb: PARTITION_KEY_VERSION_2

int 2

Version of the partition key if it is larger than 100 bytes

Enums

azure_cosmosdb: ChangeFeedOption

Incremental changes to documents within the collection.

Members

INCREMENTAL - Provides a sorted list of documents that were changed in the order in which they were modified

azure_cosmosdb: ConsistencyLevel

The Consistency Level Override for document create and update.

Members

STRONG - Users are always guaranteed to read the latest committed write

BOUNDED_STALENESS

SESSION - Reads are guaranteed to honor the consistent-prefix, monotonic reads, monotonic writes, read-your-writes, and write-follows-reads guarantees in a single client session

EVENTUAL - No ordering guarantee for reads. In the absence of any further writes, the replicas eventually converge

CONSISTENT_PREFIX

azure_cosmosdb: IndexDataType

Datatype for which the indexing behavior is applied to.

Members

STRING - Represents a string data type

NUMBER - Represents a numeric data type

POINT - Represents a point data type

POLYGON - Represents a polygon data type

LINESTRING - Represents a line string data type

azure_cosmosdb: IndexingDirective

Whether to include or exclude the document in indexing.

Members

INCLUDE - Adds the document to the index

EXCLUDE - Omits the document from indexing

azure_cosmosdb: IndexingMode

Mode of indexing for the container.

Members

CONSISTENT - The index is updated synchronously as you create, update or delete items

NONE - Indexing is disabled on the container

azure_cosmosdb: IndexType

Type of an Index.

Members

HASH - Useful for equality comparisons

RANGE - Useful for equality, range comparisons and sorting

SPATIAL - Useful for spatial queries

azure_cosmosdb: OfferType

Performance levels for a specific throughput level.
They depend on the Cosmos DB region which the container belongs to and partitioning nature of the container (ie: single partitioned or multiple partitioned).

Members

LEVEL_S1 - Performance level allows a low throughput and predefined amount of storage

LEVEL_S2 - Performance level allows a medium throughput and predefined amount of storage

LEVEL_S3 - Performance level allows a high throughput and predefined amount of storage

INVALID - Performance level should set Invalid for V2, user-defined throughput levels

azure_cosmosdb: OfferVersion

Specific version for a given offer.

Members

PRE_DEFINED - Represents pre-defined throughput levels

USER_DEFINED - Represents user-defined throughput levels

azure_cosmosdb: PermisssionMode

Access mode for the resource.

Members

ALL_PERMISSION - Provides read, write, and delete access to a resource

READ_PERMISSION - Restricts the user to have only read access to the resource

azure_cosmosdb: TriggerOperation

Type of operation that invokes the trigger.

Members

ALL - Trigger fires in all create, replace and delete operations

CREATE - Trigger fires only in a create operations

REPLACE - Trigger fires only in a replace operations

DELETE - Trigger fires only in a delete operations

azure_cosmosdb: TriggerType

When the trigger is fired.

Members

PRE - Triggers fire before an operation

POST - Triggers fires after an operation

Records

azure_cosmosdb: Commons

Closed record

Common elements representing information.

Fields

resourceId string? - A unique identifier which is used internally for placement and navigation of the resource

selfReference string? - A unique addressable URI for the resource

eTag string? - Resource etag for the resource retrieved

sessionToken string? - Session token of the request

azure_cosmosdb: ConnectionConfig

Closed record

Configuration parameters to create Azure Cosmos DB client.

Fields

baseUrl string - Base URL of the Azure Cosmos DB account

primaryKeyOrResourceToken string - The token used to make the request call authorized

advanceClientConfig CustomClientConfiguration? - Custom parameters for client creation

azure_cosmosdb: Container

Closed record

Parameters representing information about a container.

Fields

id string - User generated unique ID for the container

Fields Included from *Commons

resourceId string
selfReference string
eTag string
sessionToken string

indexingPolicy IndexingPolicy - Record of type IndexingPolicy

partitionKey PartitionKey - Record of type PartitionKey

azure_cosmosdb: CosmosStoredProcedureRequestOptions

Encapsulates options that can be specified for a request issued to cosmos stored procedure.

Fields

ifMatchETag string? - The If-Match (ETag) associated with the request in the Azure Cosmos DB service

ifNoneMatchETag string? - the If-None-Match (ETag) associated with the request in the Azure Cosmos DB service

scriptLoggingEnabled boolean? - Sets whether Javascript stored procedure logging is enabled for the current request in the Azure Cosmos DB database service or not

sessionToken string? - The token for use with session consistency.

azure_cosmosdb: CustomClientConfiguration

Closed record

Custom parameters for client creation

Fields

consistencyLevel ConsistencyLevel - The ConsistencyLevel to be used By default, ConsistencyLevel.SESSION consistency will be used

directMode DirectMode - The default DIRECT connection configuration to be used

connectionSharingAcrossClientsEnabled boolean - Enables connections sharing across multiple Cosmos Clients

contentResponseOnWriteEnabled boolean - The boolean to only return the headers and status code in Cosmos DB response in case of Create, Update and Delete operations on CosmosItem

preferredRegions string[] - The preferred regions for geo-replicated database accounts

userAgentSuffix string - The value of the user-agent suffix

azure_cosmosdb: Database

Closed record

Parameters representing information about a database.

Fields

id string - User generated unique ID for the database

Fields Included from *Commons

resourceId string
selfReference string
eTag string
sessionToken string

azure_cosmosdb: DedicatedGatewayRequestOptions

Dedicated Gateway Request Options

Fields

maxIntegratedCacheStaleness int - The staleness value associated with the request in the Azure CosmosDB service.

azure_cosmosdb: DeleteResponse

Closed record

Metadata headers which will return for a delete request.

Fields

sessionToken string - Session token from the response

azure_cosmosdb: Diagnostics

Diagnostic statistics associated with a request to Azure Cosmos DB.

Fields

regionsContacted string[]? - Regions contacted for this request

duration int - Response Diagnostic String

azure_cosmosdb: DirectConnectionConfig

Represents the direct connection configuration.

Fields

connectTimeout int? - Represents timeout for establishing connections with an endpoint (in seconds)

idleConnectionTimeout int? - The idle connection timeout (in seconds)

idleEndpointTimeout int? - Idle endpoint timeout Default value is 1 hour (in seconds)

maxConnectionsPerEndpoint int? - Max connections per endpoint This represents the size of connection pool for a specific endpoint Default value is 130

maxRequestsPerConnection int? - Mmax requests per connection This represents the number of requests that will be queued on a single connection for a specific endpoint Default value is 30

networkRequestTimeout int? - The network request timeout interval (time to wait for response from network peer).

connectionEndpointRediscoveryEnabled boolean? - Value indicating whether Direct TCP connection endpoint rediscovery should be enabled

azure_cosmosdb: DirectMode

Closed record

Represents DirectMode configuration.

Fields

directConnectionConfig DirectConnectionConfig? - Direct Connection Configuration

gatewayConnectionConfig GatewayConnectionConfig? - Gateway Connection Configuration

azure_cosmosdb: Document

Closed record

Parameters representing information about a document.

Fields

id string - User generated unique ID for the document

Fields Included from *Commons

resourceId string
selfReference string
eTag string
sessionToken string

documentBody map<json> - The document reprsented as a map of json

azure_cosmosdb: DocumentListOptions

Closed record

Optional parameters which can be passed to the function when listing information about the documents.

Fields

consistancyLevel ConsistencyLevel? - The consistency level override
- Allowed values are Strong, Bounded, Session or Eventual.
- The override must be the same or weaker than the Cosmos DB account’s configured consistency level.

sessionToken string? - Echo the latest read value of session token header to acquire session level consistency

changeFeedOption ChangeFeedOption? - Must be set to Incremental feed or omitted otherwise

partitionKeyRangeId string? - The partition key range ID for reading data

azure_cosmosdb: DocumentReplaceOptions

Closed record

Optional parameters which can be passed to the function when replacing a document.

Fields

indexingDirective IndexingDirective? - The option whether to include the document in the index
- Allowed values are 'Include' or 'Exclude'.

azure_cosmosdb: DocumentResponse

Document response.

Fields

activityId string - Activity ID for the request

currentResourceQuotaUsage string - Current size of this entity (in megabytes (MB) for server resources and in count for master resources)

maxResourceQuota string - Maximum size limit for this entity (in megabytes (MB) for server resources and in count for master resources).

etag string? - ETag from the response headers

responseHeaders map<string> - Headers associated with the response.

sessionToken string - Token used for managing client's consistency requirements.

statusCode int - HTTP status code associated with the response

requestCharge float - Request charge as request units (RU) consumed by the operation

duration int - End-to-end request latency for the current request to Azure Cosmos DB service

diagnostics Diagnostics? - Diagnostics information for the current request to Azure Cosmos DB service

item json? - Field Description

azure_cosmosdb: ExcludedPath

Closed record

Parameters representing excluded path type.

Fields

path string - Path that is excluded from indexing

azure_cosmosdb: GatewayConnectionConfig

Represents Gateway Connection Configuration

Fields

maxConnectionPoolSize int? - Max Connection Pool Size

idleConnectionTimeout int? - Idle Connection Timeout

azure_cosmosdb: HttpDetail

Extra HTTP status code detail of an error.

Fields

status int - The HTTP status code of the error

azure_cosmosdb: IncludedPath

Closed record

Parameters representing included path type.

Fields

path string - Path to which the indexing behavior applies to

indexes Index[](default []) - Array of type Index, representing index values

azure_cosmosdb: Index

Closed record

Parameters representing an index.

Fields

kind IndexType(default HASH) - Type of index
- Can be Hash, Range or Spatial.

dataType IndexDataType(default STRING) - Datatype for which the indexing behavior is applied to
- Can be String, Number, Point, Polygon or LineString.

precision int(default MAX_PRECISION) - Precision of the index
- Can be either set to -1 for maximum precision or between 1-8 for Number, and 1-100 for String
- Not applicable for Point, Polygon, and LineString data types. Default is -1.

azure_cosmosdb: IndexingPolicy

Closed record

Parameters necessary to create an indexing policy when creating a container.

Fields

indexingMode IndexingMode? - Mode of indexing. Can be consistent or none

automatic boolean(default true) - Specify whether indexing is done automatically or not
- Must be true if indexing must be automatic and false otherwise.

includedPaths IncludedPath[]? - Array of type IncludedPath representing included paths

excludedPaths ExcludedPath[]? - Array of type IncludedPath representing excluded paths

azure_cosmosdb: ManagementClientConfig

Closed record

CosmosDB Management Client configurations.

Fields

Fields Included from *ConnectionConfig

auth AuthConfig
httpVersion HttpVersion
http1Settings ClientHttp1Settings
http2Settings ClientHttp2Settings
timeout decimal
forwarded string
poolConfig PoolConfiguration
cache CacheConfig
compression Compression
circuitBreaker CircuitBreakerConfig
retryConfig RetryConfig
responseLimits ResponseLimitConfigs
secureSocket ClientSecureSocket
proxy ProxyConfig
validation boolean
anydata...

auth never? - Excluded auth configurations (Provide primaryKey or ResourceToken instead)

baseUrl string - Base URL of the Azure Cosmos DB account

primaryKeyOrResourceToken string - The token used to make the request call authorized

httpVersion HttpVersion(default http:HTTP_1_1) - The HTTP version understood by the client

azure_cosmosdb: Offer

Closed record

Parameters representing an offer.

Fields

id string - User generated unique ID for the offer

Fields Included from *Commons

resourceId string
selfReference string
eTag string
sessionToken string

offerVersion OfferVersion - Offer version
- This value can be V1 for pre-defined throughput levels and V2 for user-defined throughput levels

offerType OfferType - Performance level for V1 offer version, allows S1, S2 and S3.

content map<json> - Information about the offer
- For V2 offers, it contains the throughput of the collection.

resourceResourceId string - The resource id(_rid) of the collection

resourceSelfLink string - The self-link(_self) of the collection

azure_cosmosdb: PartitionKey

Closed record

Parameters representing a partition key.

Fields

paths string[](default []) - Array of paths using which, data within the collection can be partitioned. The array must contain only a single value.

kindreadonly string(default PARTITIONING_ALGORITHM_TYPE_HASH) - Algorithm used for partitioning
- Only Hash is supported.

keyVersion PartitionKeyVersion(default PARTITION_KEY_VERSION_1) - Version of partition key. Default is 1. To use a large partition key, set the version to 2.

azure_cosmosdb: PartitionKeyRange

Closed record

Parameters representing a partition key range.

Fields

id string - ID for the partition key range

Fields Included from *Commons

resourceId string
selfReference string
eTag string
sessionToken string

minInclusive string - Minimum partition key hash value for the partition key range

maxExclusive string - Maximum partition key hash value for the partition key range

azure_cosmosdb: Permission

Closed record

Parameters representing a permission.

Fields

id string - User generated unique ID for the permission

Fields Included from *Commons

resourceId string
selfReference string
eTag string
sessionToken string

permissionMode PermisssionMode - Access mode for the resource, Should be All or Read

resourcePath string - Full addressable path of the resource associated with the permission

token string - System generated Resource-Token for the particular resource and user

azure_cosmosdb: QueryOptions

Query Options

Fields

consistencyLevel ConsistencyLevel? - Consistency level required for the request

dedicatedGatewayRequestOptions DedicatedGatewayRequestOptions? - Dedicated Gateway Request Options

indexMetricsEnabled boolean? - Used to obtain the index metrics to understand how the query engine used existing indexes and could use potential new indexes.

maxBufferedItemCount int? - Number of items that can be buffered client side during parallel query execution

maxDegreeOfParallelism int? - Number of concurrent operations run client side during parallel query execution

partitionKey int|float|decimal|string? - Used to identify the current request's target partition.

queryMetricsEnabled boolean? - Option to enable/disable getting metrics relating to query execution on item query requests

limitInKb int? - Option for item query requests in the Azure Cosmos DB service

scanInQueryEnabled boolean? - Option to allow scan on the queries which couldn't be served as indexing was opted out on the requested paths

sessionToken string? - Session token for use with session consistency

thresholdForDiagnosticsOnTracer int? - If latency on query operation is greater than this diagnostics will be send to open telemetry exporter as events in tracer span of end to end CRUD api.

throughputControlGroupName string? - Throughput control group name.

azure_cosmosdb: RequestOptions

Closed record

Optional parameters which can be passed to the function when creating a document.

Fields

indexingDirective IndexingDirective? - The option whether to include the document in the index
- Allowed values are Include or Exclude.

isUpsertRequest boolean(default false) - A boolean value which specify whether the request is an upsert request

consistancyLevel ConsistencyLevel? - Consistency level required for the request

contentResponseOnWriteEnabled boolean? - The boolean to only return the headers and status code in Cosmos DB response in case of Create, Update and Delete operations on CosmosItem

dedicatedGatewayRequestOptions DedicatedGatewayRequestOptions? - The Dedicated Gateway Request Options

ifMatchETag string? - The If-Match (ETag) associated with the request in the Azure Cosmos DB service

ifNoneMatchETag string? - The If-None-Match (ETag) associated with the request in the Azure Cosmos DB service

postTriggerInclude string[]? - Triggers to be invoked after the operation

preTriggerInclude string[]? - Triggers to be invoked before the operation

sessionToken string? - The token for use with session consistency

thresholdForDiagnosticsOnTracer int? - ThresholdForDiagnosticsOnTracer, if latency on CRUD operation is greater than this diagnostics will be sent to open telemetry exporter as events in tracer span of end to end CRUD api

throughputControlGroupName string? - The throughput control group name

azure_cosmosdb: ResourceDeleteOptions

Closed record

Optional parameters which can be passed to the function when deleting other resources in Cosmos DB.

Fields

sessionToken string? - Echo the latest read value of sessionToken to acquire session level consistency

azure_cosmosdb: ResourceQueryOptions

Closed record

Optional parameters which can be passed to the function when querying containers.

Fields

consistancyLevel ConsistencyLevel? - The consistency level override
- Allowed values are Strong, Bounded, Session or Eventual.
- The override must be the same or weaker than the account’s configured consistency level.

sessionToken string? - Echo the latest read value of sessionToken to acquire session level consistency

enableCrossPartition boolean(default true) - Boolean value specifying whether to allow cross partitioning <br/> Default is true where, it allows to query across all logical partitions.

partitionKey (int|float|decimal|string)?(default ()) - Optional. The value of partition key field of the container.

azure_cosmosdb: ResourceReadOptions

Closed record

Optional parameters which can be passed to the function when reading the information about other resources in Cosmos DB such as Containers, StoredProcedures, Triggers, User Defined Functions, etc.

Fields

consistancyLevel ConsistencyLevel? - The consistency level override
- Allowed values are Strong, Bounded, Session or Eventual.
- The override must be the same or weaker than the account’s configured consistency level.

sessionToken string? - Echo the latest read value of sessionToken to acquire session level consistency

azure_cosmosdb: StoredProcedure

Closed record

Parameters representing a stored procedure.

Fields

id string - User generated unique ID for the stored procedure

Fields Included from *Commons

resourceId string
selfReference string
eTag string
sessionToken string

storedProcedure string - A JavaScript function, respresented as a string

azure_cosmosdb: StoredProcedureExecuteOptions

Closed record

The options which can be passed for execution of stored procedures.

Fields

parameters string[](default []) - An array of parameters which has values match the function parameters of a stored procedure

cosmosStoredProcedureRequestOptions CosmosStoredProcedureRequestOptions? -

azure_cosmosdb: StoredProcedureResponse

Stored procedure response.

Fields

activityId string - Activity ID for the request

requestCharge float - Request charge as request units (RU) consumed by the operation

responseAsString string? - Response of the stored procedure as a string

scriptLog string? - Output from stored procedure console.log() statements

sessionToken string - Token used for managing client's consistency requirements

statusCode int - HTTP status code associated with the response

azure_cosmosdb: Trigger

Closed record

Parameters representing a trigger.

Fields

id string - User generated unique ID for the trigger

Fields Included from *Commons

resourceId string
selfReference string
eTag string
sessionToken string

triggerFunction string - A JavaScript function, respresented as a string

triggerOperation TriggerOperation(default ALL) - Type of operation that invokes the trigger
- Can be All, Create, Replace or Delete.

triggerType TriggerType(default PRE) - When the trigger is fired, Pre or Post

azure_cosmosdb: User

Closed record

Parameters representing a user.

Fields

id string - User generated unique ID for the user

Fields Included from *Commons

resourceId string
selfReference string
eTag string
sessionToken string

permissions string - A system generated property that specifies the addressable path of the permissions resource

azure_cosmosdb: UserDefinedFunction

Closed record

Parameters representing a user defined function.

Fields

id string - User generated unique ID for the user defined function

Fields Included from *Commons

resourceId string
selfReference string
eTag string
sessionToken string

userDefinedFunction string - A JavaScript function, respresented as a string

Errors

azure_cosmosdb: DbOperationError

HttpDetail

The payload access errors where the error detail contains the HTTP status.

azure_cosmosdb: Error

PayloadValidationError|DbOperationError|InputValidationError|error

The union of all types of errors in the connector.

azure_cosmosdb: InputValidationError

Distinct

The errors which occur when providing an invalid value.

azure_cosmosdb: PayloadValidationError

Distinct

The errors which will come from the Azure API call itself.

Union types

azure_cosmosdb: PartitionKeyVersion

PARTITION_KEY_VERSION_1|PARTITION_KEY_VERSION_2

PartitionKeyVersion

Version of the partition key.

Import

import ballerinax/azure_cosmosdb;

Metadata

Released date: over 1 year ago

Version: 4.2.0

License: Apache-2.0

Compatibility

Platform: java11

Ballerina version: 2201.7.0

GraalVM compatible: Yes

Pull count

Total: 3030

Current verison: 292

Weekly downloads

Source repository

Keywords

IT Operations/Databases

Cost/Paid

Vendor/Microsoft

Contributors

Other versions

4.2.0

4.1.1 4.1.0 4.0.0 3.0.1

Dependencies

ballerinax/client.config/1.0.1 ballerina/regex/1.4.3 ballerina/url/2.3.0

Cookie policy

Delete policy

classes

clients

constants

enums

records

errors

unionTypes

ballerinax/azure_cosmosdb Ballerina library

Overview

Prerequisites

Quickstart

Step 1 - Import connector

Step 2 - Create a new connector instance

Step 3 - Invoke connector operation

Classes

azure_cosmosdb: CosmosResultIterator

nextResult

Parameters

azure_cosmosdb: ResultIterator

next

Clients

azure_cosmosdb: DataPlaneClient

Constructor

createDocument

Parameters

Return Type

replaceDocument

Parameters

Return Type

getDocument

Parameters

Return Type

getDocumentList

Parameters

Return Type

deleteDocument

Parameters

Return Type

queryDocuments

Parameters

Return Type

createStoredProcedure

Parameters

Return Type

listStoredProcedures

Parameters

Return Type

deleteStoredProcedure

Parameters

Return Type

executeStoredProcedure

Parameters

Return Type

close

azure_cosmosdb: ManagementClient

Constructor

createDatabase

Parameters

Return Type

createDatabaseIfNotExist

Parameters

Return Type

getDatabase

Parameters

Return Type

listDatabases

Return Type

deleteDatabase

Parameters

Return Type

createContainer

Parameters

Return Type

createContainerIfNotExist

Parameters

Return Type

getContainer

Parameters

Return Type

listContainers