Module azure_cosmosdb

ballerinax/azure_cosmosdb Ballerina library

2.1.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. It also needs a unique ID to identify it.. In this example, the document ID is my_document


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

cosmosdb:Document documentResult = azureCosmosClient-> createDocument("my_database", "my_container", 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_document.
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 new document to create is represented as record {|string id; json...;|}. The json... represent key-value pairs where the values are of type boolean, int, float, decimal, string, json[], or map<json>

Use bal run command to compile and run the Ballerina program

You can find a list of samples here

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 cosmosdbConfig, ClientConfiguration httpClientConfig)

cosmosdbConfig ConnectionConfig - Configurations required to initialize the Client endpoint

httpClientConfig ClientConfiguration {} - HTTP configuration

createDocument

Isolated FunctionRemote Function

function createDocument(string databaseId, string containerId, record { id string,  json... } document, int|float|decimal|string partitionKey, DocumentCreateOptions? documentCreateOptions) returns Document|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

document record { id string, 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

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

Return Type

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

replaceDocument

Isolated FunctionRemote Function

function replaceDocument(string databaseId, string containerId, record { id string,  json... } document, int|float|decimal|string partitionKey, DocumentReplaceOptions? documentReplaceOptions) returns Document|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

document record { id string, 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

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

Return Type

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

getDocument

Isolated FunctionRemote Function

function getDocument(string databaseId, string containerId, string documentId, int|float|decimal|string partitionKey, ResourceReadOptions? resourceReadOptions) returns Document|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

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

Return Type

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

getDocumentList

Isolated FunctionRemote Function

function getDocumentList(string databaseId, string containerId, DocumentListOptions? documentListOptions) returns stream<Document, 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

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

Return Type

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

deleteDocument

Isolated FunctionRemote Function

function deleteDocument(string databaseId, string containerId, string documentId, int|float|decimal|string partitionKey, ResourceDeleteOptions? resourceDeleteOptions) returns DeleteResponse|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

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.

queryDocuments

Isolated FunctionRemote Function

function queryDocuments(string databaseId, string containerId, string sqlQuery, ResourceQueryOptions? resourceQueryOptions) returns stream<Document, 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

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

Return Type

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

createStoredProcedure

Isolated FunctionRemote Function

function createStoredProcedure(string databaseId, string containerId, string storedProcedureId, string storedProcedure) returns StoredProcedure|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

Return Type

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

replaceStoredProcedure

Isolated FunctionRemote Function

function replaceStoredProcedure(string databaseId, string containerId, string storedProcedureId, string storedProcedure) returns StoredProcedure|Error

Replaces a stored procedure with new one.

Parameters

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

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

storedProcedureId string - The ID of the stored procedure to be replaced

storedProcedure string - A JavaScript function which will replace the existing one

Return Type

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

listStoredProcedures

Isolated FunctionRemote Function

function listStoredProcedures(string databaseId, string containerId, ResourceReadOptions? resourceReadOptions) 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

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

Return Type

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

deleteStoredProcedure

Isolated FunctionRemote Function

function deleteStoredProcedure(string databaseId, string containerId, string storedProcedureId, ResourceDeleteOptions? resourceDeleteOptions) returns DeleteResponse|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

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.

executeStoredProcedure

Isolated FunctionRemote Function

function executeStoredProcedure(string databaseId, string containerId, string storedProcedureId, StoredProcedureExecuteOptions storedProcedureExecuteOptions) returns json|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

storedProcedureExecuteOptions StoredProcedureExecuteOptions - A record cosmos_db:StoredProcedureExecuteOptions to specify the additional parameters

Return Type

json|Error - If successful, returns json with the output from the executed function. Else returns cosmos_db: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 (ConnectionConfig azureConfig, ClientConfiguration httpClientConfig)

azureConfig ConnectionConfig -

httpClientConfig ClientConfiguration {} - HTTP configuration

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 - Reads might lag behind writes behind at most K updates of an item or by T time interval

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

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

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: 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: DeleteResponse

Closed record

Metadata headers which will return for a delete request.

Fields

sessionToken string - Session token from the response

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: DocumentCreateOptions

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

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: ExcludedPath

Closed record

Parameters representing excluded path type.

Fields

path string - Path that is excluded from indexing

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: 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: 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

partitionKey int|float|decimal|string? - The value of partition key of documents that the stored procedure is tagrgetted at

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: almost 3 years ago

Version: 2.1.0

License: Apache-2.0

Compatibility

Platform: java11

Ballerina version: slbeta6

Pull count

Total: 3030

Current verison: 25

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

ballerina/regex/1.1.0 ballerina/url/2.1.0 ballerina/time/2.1.0

Cookie policy

Delete policy

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

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

replaceStoredProcedure

Parameters

Return Type

listStoredProcedures

Parameters

Return Type

deleteStoredProcedure

Parameters

Return Type

executeStoredProcedure

Parameters

Return Type

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

Parameters

Return Type

deleteContainer

Parameters

Return Type