dart_azure_cosmosdb

Description:

dart azure cosmosdb

Dart package for the Azure Cosmos Database #






Table of content #

1 Features
2 Getting started

2.1 Android settings
2.2 iOS settings
2.3 macOS settings
2.4 Windows settings
2.5 Linux settings


3 Usage

3.1 CosmosDB instance creation and configuration
3.2 Databases

3.2.1 List Databases
3.2.2 Get a Database
3.2.3 Create a Database
3.2.4 Delete a Database
3.2.5 The CosmosDatabase model


3.3 Collections

3.3.1 List Collections
3.3.2 Get a Collection
3.3.3 Create a Collection
3.3.4 Delete a Collection
3.3.5 The Collection model


3.4 Documents

3.4.1 List Documents
3.4.2 Get a Document
3.4.3 Create a Document
3.4.4 Replace a Document
3.4.5 Delete a Document
3.4.6 Query documents
3.4.7 The CosmosDocument model


3.5 Stored Procedures

3.5.1 List Stored Procedures
3.5.2 Create a Stored Procedure
3.5.3 Replace a Stored Procedure
3.5.4 Delete a Stored Procedure
3.5.5 Execute a Stored Procedure
3.5.6 The Stored Procedure model


3.6 User Defined Functions

3.6.1 List User Defined Functions
3.6.2 Create a User Defined Function
3.6.3 Replace a User Defined Function
3.6.4 Delete a User Defined Function
3.6.5 The User Defined Function model


3.7 Triggers

3.7.1 List Triggers
3.7.2 Create a Trigger
3.7.3 Replace a Trigger
3.7.4 Delete a Trigger
3.7.5 The Trigger model


3.8 Users

3.8.1 List Users
3.8.2 Get a User
3.8.3 Create a User
3.8.4 Replace a User
3.8.5 Delete a User
3.8.6 The Trigger model


3.9 Permissions

3.9.1 List Permissions
3.9.2 Get a Permission
3.9.3 Create a Permission
3.9.4 Replace a Permission
3.9.5 Delete a Permission
3.9.6 The Permission model




4 Where to go from here
5 Bugs and issues

1 Features #
dart_azure_cosmosdb offers interaction with the Azure CosmosDB SQL-API.
For more information, check out the Microsoft CosmosDB documentation.
2 Getting started #
2.1 Android settings #
This package uses the HTTP-package and needs access to the internet, networking needs to be enabled in the AndroidManifest.xml.
<manifest xmlns:android...>
...
<uses-permission android:name="android.permission.INTERNET" />
<application ...
</manifest>
copied to clipboard
2.2 iOS settings #
No steps are necessary for iOS.
2.3 macOS settings #
This package uses the HTTP-package and needs access to the internet, networking needs to be enabled in the .entitlements.
<key>com.apple.security.network.client</key>
<true/>
copied to clipboard
2.4 Windows settings #
No steps are necessary for Windows.
2.5 Linux settings #
No steps are necessary for Linux.
3 Usage #
3.1 CosmosDB instance creation and configuration #
First, you need to create an instance of the CosmosDB-class, as follows:
final cosmosDb = CosmosDb(
// REQUIRED -> URI to the Azure Cosmos Database.
connectionUri: 'https://<COSMOS_DB_NAME>.documents.azure.com:443/',
// REQUIRED -> Primary key to the Cosmos Database.
primaryKey: '<COSMOS_DB_KEY>',
// OPTIONAL -> Authorization type of the provided token.
// Default: master
authorizationType: 'master',
// OPTIONAL -> Version of the provided authorization.
// Default: 1.0
authorizationVersion: '1.0',
// OPTIONAL -> The supported REST API versions of the Azure Cosmos DB service.
// Default: 2018-12-31
xmsVersion: '2018-12-31',
);
copied to clipboard
3.2 Databases #
Each Azure Cosmos DB account supports multiple independently named databases. A database is a logical namespace for collections, users, and permissions.
3.2.1 List Databases
List the databases under the database account, performs a GET on the databases resource.
The database-list operation returns a Future<CosmosDatabaseList> with a list of CosmosDatabase or an error object.
See 3.2.5 The CosmosDatabase model for information on the returned model and its variables.
final CosmosDatabaseList databaseList = await cosmosDb.database.list();

if(databaseList.error.isEmpty) {
// If the error is empty, continue....
}
copied to clipboard
3.2.2 Get a Database
Retrieve a database resource, performs a GET on the database resource.
The database-get operation returns a Future<CosmosDatabase>.
See 3.2.5 The CosmosDatabase model for information on the returned model and its variables.
final CosmosDatabase database = await cosmosDb.database.get(
// REQUIRED -> User generated name/id of the database.
dbId: '<DB_ID>',
);

if (database.error.isEmpty) {
// If the error is empty, continue....
}
copied to clipboard
3.2.3 Create a Database
The create-operation creates a new database in the database account.
The database-create operation returns a Future<CosmosDatabase>.
See 3.2.5 The CosmosDatabase model for information on the returned model and its variables.
final CosmosDatabase database = await cosmosDb.database.create(
// REQUIRED -> User generated name/id of the database to be created.
dbId: '<DB_ID>',
);

if (database.error.isEmpty) {
// If the error is empty, continue....
}
copied to clipboard
3.2.4 Delete a Database
The delete-operation deletes an existing database in the database account.
The database-delete operation returns a Future<CosmosDatabase>.
See 3.2.5 The CosmosDatabase model for information on the returned model and its variables.
final CosmosDatabase database = await cosmosDb.database.delete(
// REQUIRED -> User generated name/id of the database to be deleted.
dbId: '<DB_ID>',
);

if (database.error.isEmpty) {
// If the error is empty, continue....
}
copied to clipboard
3.2.5 The CosmosDatabase model
CosmosDatabase
Methods
CosmosDatabase.toMap() -> Transforms the model to a Map for the CosmosDB API.
CosmosDatabase.toMap(Map<String, dynamic> map) -> Transforms a Map from the CosmosDB API to the model.
Variables



Name
Azure API key name
Example
Description




id
id
myId1
The unique user generated name for the resource, max 255 chars.


rid
_rid
qicAAA==
System generated property. The resource ID (_rid) is a unique identifier. It is used internally for placement of and navigation to the resource.


ts
_ts
1446192371
System generated property. It specifies the last updated timestamp of the resource. The value is a timestamp.


self
_self
dbs\/qicAAA==\/
System generated property. It is the unique addressable URI for the resource.


etag
_etag
00001800-...
System generated property representing the resource etag required for optimistic concurrency control.


error
code,message
{"code": "...","message": "..."}
An empty Map in case of a successful transaction, else a map with a code and a message.


colls
_colls
colls/
It is a system generated property that specifies the addressable path of the collections resource.


users
_users
users/
It is a system generated property that specifies the addressable path of the users resource.



CosmosDatabaseList
Methods
CosmosDatabaseList.toMap() -> Transforms the model to a Map for the CosmosDB API.
CosmosDatabaseList.toMap(Map<String, dynamic> map) -> Transforms a Map from the CosmosDB API to the model.
Variables



Name
Azure API key name
Example
Description




rid
_rid
qicAAA==
System generated property. The resource ID (_rid) is a unique identifier. It is used internally for placement of and navigation to the resource.


count
_count
3
This property shows the number of resources returned as part of list operation.


error
code,message
{"code": "...","message": "..."}
An empty Map in case of a successful transaction, else a map with a code and a message.


databases
Databases
[]
A list of CosmosDB databases. List<CosmosDatabase>



3.3 Collections #
A collection is a container of JSON documents and associated JavaScript application logic, i.e. stored procedures, triggers and user-defined functions.
3.3.1 List Collections
Performing a GET on the collections resource of a particular database, i.e. the colls URI path, returns a list of the collections in the database.
The collection-list operation returns a Future<CollectionList> with a list of Collection or an error object.
See 3.3.5 The Collection model for information on the returned model and its variables.
final CollectionList collectionList = await cosmosDb.collection.list(
// REQUIRED -> User generated name/id of the database in which the collections are located.
dbId: '<DB_ID>',
);

if (collectionList.error.isEmpty) {
// If the error is empty, continue....
}
copied to clipboard
3.3.2 Get a Collection
Performing a GET on a specific collection resource retrieves the properties for the collection.
The collection-get operation returns a Future<Collection>.
See 3.3.5 The Collection model for information on the returned model and its variables.
final Collection collection = await cosmosDb.collection.get(
// REQUIRED -> User generated name/id of the database in which the collection is located.
dbId: '<DB_ID>',
// REQUIRED -> Name of the existing collection.
collectionId: '<COLLECTION_ID>',
);

if (collection.error.isEmpty) {
// If the error is empty, continue....
}
copied to clipboard
3.3.3 Create a Collection
The create-operation creates a new collection in a database.
The collection-create operation returns a Future<Collection>.
See 3.3.5 The Collection model for information on the returned model and its variables.
final Collection collection = await cosmosDb.collection.create(
// REQUIRED -> User generated name/id of the database in which the collections are saved.
dbId: '<DB_ID>',
// REQUIRED -> Name of the collection to be created.
collectionId: '<COLLECTION_ID>',
// REQUIRED -> The partition key to be used for partitioning data into multiple partitions.
partitionKey: '/id',
// REQUIRED -> Set this value to 2, to use a large partition key, else set it to 1.
version: 1,
);

if (collection.error.isEmpty) {
// If the error is empty, continue....
}
copied to clipboard
3.3.4 Delete a Collection
The delete-operation deletes an existing collection in a database.
The collection-delete operation returns a Future<Collection>.
See 3.3.5 The Collection model for information on the returned model and its variables.
final Collection collection = await cosmosDb.collection.delete(
// REQUIRED -> User generated name/id of the database in which the collection is located.
dbId: '<DB_ID>',
// REQUIRED -> Name of the collection to be deleted.
collectionId: '<COLLECTION_ID>',
);

if (collection.error.isEmpty) {
// If the error is empty, continue....
}
copied to clipboard
3.3.5 The Collection model
Collection
Methods
Collection.toMap() -> Transforms the model to a Map for the CosmosDB API.
Collection.toMap(Map<String, dynamic> map) -> Transforms a Map from the CosmosDB API to the model.
Variables



Name
Azure API key name
Example
Description




id
id
myId1
The unique user generated name for the resource, max 255 chars.


rid
_rid
qicAAA==
System generated property. The resource ID (_rid) is a unique identifier. It is used internally for placement of and navigation to the resource.


ts
_ts
1446192371
System generated property. It specifies the last updated timestamp of the resource. The value is a timestamp.


self
_self
dbs\/qicAAA==\/
System generated property. It is the unique addressable URI for the resource.


etag
_etag
00001800-...
System generated property representing the resource etag required for optimistic concurrency control.


error
code,message
{"code": "...","message": "..."}
An empty Map in case of a successful transaction, else a map with a code and a message.


docs
_docs
docs/
It is a system generated property that specifies the addressable path of the documents resource.


sprocs
_sprocs
sprocs/
It is a system generated property that specifies the addressable path of the stored procedures (sprocs) resource.


triggers
_triggers
triggers/
It is a system generated property that specifies the addressable path of the triggers resource.


udfs
_udfs
udfs/
It is a system generated property that specifies the addressable path of the user-defined functions (udfs) resource.


conflicts
_conflicts
conflicts/
It is a system generated property that specifies the addressable path of the conflicts resource.


partitionKey
partitionKey
{"paths": [ "/AccountNumber" ],"kind": "Hash","Version": 2}
This value is used to configure the partition key to be used for partitioning data into multiple partitions.


indexingPolicy
indexingPolicy
[{"path": "/*","indexes": [{ "dataType": "String","precision": -1, "kind": "Range" }]}]
This value is used to configure indexing policy. By default, the indexing is automatic for all document paths within the collection.


uniqueKeyPolicy
uniqueKeyPolicy
[]
With unique keys, you make sure that one or more values within a logical partition is unique. By default, the unique key policy is an empty array or null as an object.


geospatialConfig
geospatialConfig
{"type": "Geography"}
The Geospatial Configuration specifies how the spatial data will be indexed. Specify one Geospatial Configuration per container: geography or geometry.



CollectionList
Methods
CollectionList.toMap() -> Transforms the model to a Map for the CosmosDB API.
CollectionList.toMap(Map<String, dynamic> map) -> Transforms a Map from the CosmosDB API to the model.
Variables



Name
Azure API key name
Example
Description




rid
_rid
qicAAA==
System generated property. The resource ID (_rid) is a unique identifier. It is used internally for placement of and navigation to the resource.


count
_count
3
This property shows the number of resources returned as part of list operation.


error
code,message
{"code": "...","message": "..."}
An empty Map in case of a successful transaction, else a map with a code and a message.


collections
DocumentCollections
[]
A list of CosmosDB collections. List<Collection>



3.4 Documents #
A document consists of user-defined content in JSON format. Aside from the required ID property, users can define any arbitrary elements, structures, and hierarchies for the content. The ID element is a unique string that is user-settable and must not exceed 255 characters. You can insert, replace, delete, read, enumerate, and query arbitrary JSON documents in a collection.
3.4.1 List Documents
Performing a GET on the documents resource of a particular collection, i.e. the docs URI path, returns a list of documents under the collection.
The document-list operation returns a Future<CosmosDocumentList> with a list of CosmosDocument or an error object.
See 3.4.6 The CosmosDocument model for information on the returned model and its variables.
final CosmosDocumentList documentList = await cosmosDb.document.list(
// REQUIRED -> User generated name/id of the database.
dbId: '<DB_ID>',
// REQUIRED -> Id/name of the collection.
collectionId: '<COLLECTION_ID>',
);

if (documentList.error.isEmpty) {
// If the error is empty, continue....
}
copied to clipboard
3.4.2 Get a Document
The get-operation retrieves a document by its partition key and document key.
The collection-get operation returns a Future<CosmosDocument>.
See 3.4.6 The CosmosDocument model for information on the returned model and its variables.
final CosmosDocument document = await cosmosDb.document.get(
// REQUIRED -> User generated name/id of the database.
dbId: '<DB_ID>',
// REQUIRED -> Id/name of the collection.
collectionId: '<COLLECTION_ID>',
// REQUIRED -> Id of the document to be retrieved.
documentId: '<DOCUMENT_ID>',
// REQUIRED -> Partition key value for the document to be received.
partitionKey: '<DOCUMENT_PARTITION_KEY>',
);

if (document.error.isEmpty) {
// If the error is empty, continue....
}
copied to clipboard
3.4.3 Create a Document
The create-operation creates a new document in a collection.
The collection-create operation returns a Future<CosmosDocument>.
See 3.4.6 The CosmosDocument model for information on the returned model and its variables.

// Example: Create an instance of a Person to write to the document.
final Person person = Person(
id: '01',
name: 'Jane',
familyName: 'Doe',
birthDate: '01.01.1970',
);

final CosmosDocument document = await cosmosDb.document.create(
// REQUIRED -> User generated name/id of the database.
dbId: '<DB_ID>',
// REQUIRED -> Id/name of the collection.
collectionId: '<COLLECTION_ID>',
// REQUIRED -> Partition key value for the document to be created.
// In this example the partition-key /id is used.
partitionKey: person.id,
// REQUIRED -> Any map with Strings as keys and dynamic values that will be added to the document.
// In this example the Person-instance is transformed into a map.
body: person.toMap(),
);

if (document.error.isEmpty) {
// If the error is empty, continue....
}
copied to clipboard
3.4.4 Replace a Document
The replace-operation replaces the entire content of a document.
The collection-replace operation returns a Future<CosmosDocument>.
See 3.4.6 The CosmosDocument model for information on the returned model and its variables.
// Example: Create an instance of a Person to overwrite.
final Person personUpdated = Person(
id: '02',
name: 'Jane',
familyName: 'Doe',
birthDate: '01.01.1970',
);

final CosmosDocument document = await cosmosDb.document.replace(
// REQUIRED -> User generated name/id of the database.
dbId: '<DB_ID>',
// REQUIRED -> Id/name of the collection.
collectionId: '<COLLECTION_ID>',
// REQUIRED -> Partition key value for the document to be created.
// In this example the partition-key /id is used.
partitionKey: person.id,
// REQUIRED -> Id of the document to be replaced.
documentId: '01',
// REQUIRED -> Any map with Strings as keys and dynamic values that will replace the previous body.
// In this example the Person-instance is transformed into a map.
body: person.toMap(),
);

if (document.error.isEmpty) {
// If the error is empty, continue....
}
copied to clipboard
3.4.5 Delete a Document
The delete-operation deletes an existing document in a collection.
The collection-replace operation returns a Future<CosmosDocument>.
See 3.4.6 The CosmosDocument model for information on the returned model and its variables.
final CosmosDocument document = await cosmosDb.document.delete(
// REQUIRED -> User generated name/id of the database.
dbId: '<DB_ID>',
// REQUIRED -> Id/name of the collection.
collectionId: '<COLLECTION_ID>',
// REQUIRED -> Partition key value for the document to be deleted.
partitionKey: '<DOCUMENT_PARTITION_KEY>',
// REQUIRED -> Id of the document to be deleted.
documentId: '01',
);

if (document.error.isEmpty) {
// If the error is empty, continue....
}
copied to clipboard
3.4.6 Query documents
3.4.7 The CosmosDocument model
CosmosDocument
Methods
CosmosDocument.toMap() -> Transforms the model to a Map for the CosmosDB API.
CosmosDocument.toMap(Map<String, dynamic> map) -> Transforms a Map from the CosmosDB API to the model.
Variables



Name
Azure API key name
Example
Description




id
id
myId1
The unique user generated name for the resource, max 255 chars.


rid
_rid
qicAAA==
System generated property. The resource ID (_rid) is a unique identifier. It is used internally for placement of and navigation to the resource.


ts
_ts
1446192371
System generated property. It specifies the last updated timestamp of the resource. The value is a timestamp.


self
_self
dbs\/qicAAA==\/
System generated property. It is the unique addressable URI for the resource.


etag
_etag
00001800-...
System generated property representing the resource etag required for optimistic concurrency control.


error
code,message
{"code": "...","message": "..."}
An empty Map in case of a successful transaction, else a map with a code and a message.


attachments
_attachments
attachments/
It is a system generated property that specifies the addressable path for the attachments resource.


values
...
{"key1": "val1","key2": "val2"}
Any map of key-value pairs to save or retrieve in a document.



CosmosDocumentList
Methods
CosmosDocumentList.toMap() -> Transforms the model to a Map for the CosmosDB API.
CosmosDocumentList.toMap(Map<String, dynamic> map) -> Transforms a Map from the CosmosDB API to the model.
Variables



Name
Azure API key name
Example
Description




rid
_rid
qicAAA==
System generated property. The resource ID (_rid) is a unique identifier. It is used internally for placement of and navigation to the resource.


count
_count
3
This property shows the number of resources returned as part of list operation.


error
code,message
{"code": "...","message": "..."}
An empty Map in case of a successful transaction, else a map with a code and a message.


documents
Documents
[]
A list of CosmosDB documents. List<CosmosDocument>



3.5 Stored Procedures #
A stored procedure is a piece of application logic written in JavaScript that is registered and executed against a collection as a single transaction. In Azure Cosmos DB, JavaScript is hosted in the same memory space as the database. Hence, requests made within stored procedures execute in the same scope as a database session. This process enables Azure Cosmos DB to guarantee ACID for all operations that are part of a single stored procedure.
3.5.1 List Stored Procedures
Performing a GET on the stored procedures resource of a particular database, that is, the sprocs URI path, returns a list of the stored procedures in the collection.
The stored-procedure-list operation returns a Future<StoredProcedureList> with a list of StoredProcedure or an error object.
See 3.5.5 The Stored Procedure model for information on the returned model and its variables.
final StoredProcedureList storedProcedureList = await cosmosDb.storedProcedure.list(
// REQUIRED -> User generated name/id of the database.
dbId: '<DB_ID>',
// REQUIRED -> Name of the collection where the stored procedures reside.
collectionId: '<COLLECTION_ID>',
);

if (storedProcedureList.error.isEmpty) {
// If the error is empty, continue....
}
copied to clipboard
3.5.2 Create a Stored Procedure
The create-operation creates a new stored procedure in a collection.
The stored-procedure-create operation returns a Future<StoredProcedure>.
See 3.5.5 The Stored Procedure model for information on the returned model and its variables.
final StoredProcedure storedProcedure = await cosmosDb.storedProcedure.create(
// REQUIRED -> User generated name/id of the database.
dbId: '<DB_ID>',
// REQUIRED -> Name of the collection where the stored procedure is created.
collectionId: '<COLLECTION_ID>',
// REQUIRED -> The user generated unique name for the stored procedure, max 255 chars.
storedProcedureId: '<SPROC_ID>',
// REQUIRED -> The body of the stored procedure as a String.
function: 'function () { ... }',
);

if (storedProcedure.error.isEmpty) {
// If the error is empty, continue....
}
copied to clipboard
3.5.3 Replace a Stored Procedure
Replaces the entire stored procedure resource.
All user-settable properties, including the ID and the body, must be submitted in the body to perform the replacement.
The stored-procedure-replace operation returns a Future<StoredProcedure>.
See 3.5.5 The Stored Procedure model for information on the returned model and its variables.
final StoredProcedure storedProcedure = await cosmosDb.storedProcedure.replace(
// REQUIRED -> User generated name/id of the database.
dbId: '<DB_ID>',
// REQUIRED -> Name of the collection where the stored procedure is updated.
collectionId: '<COLLECTION_ID>',
// REQUIRED -> The user generated unique name for an existing stored procedure.
storedProcedureId: '<SPROC_ID>',
// REQUIRED -> The body of the stored procedure as a String, will replace the current function.
function: 'function () { ...Updated function... }',
);

if (storedProcedure.error.isEmpty) {
// If the error is empty, continue....
}
copied to clipboard
3.5.4 Delete a Stored Procedure
The delete-operation deletes an existing stored procedure in a collection.
The stored-procedure-delete operation returns a Future<StoredProcedure>.
See 3.5.5 The Stored Procedure model for information on the returned model and its variables.
final StoredProcedure storedProcedure = await cosmosDb.storedProcedure.delete(
// REQUIRED -> User generated name/id of the database.
dbId: '<DB_ID>',
// REQUIRED -> Name of the collection where the stored procedure is deleted from.
collectionId: '<COLLECTION_ID>',
// REQUIRED -> The user generated unique name for an existing stored procedure.
storedProcedureId: '<SPROC_ID>',
);

if (storedProcedure.error.isEmpty) {
// If the error is empty, continue....
}
copied to clipboard
3.5.5 Execute a Stored Procedure
3.5.6 The Stored Procedure model
StoredProcedure
Methods
StoredProcedure.toMap() -> Transforms the model to a Map for the CosmosDB API.
StoredProcedure.toMap(Map<String, dynamic> map) -> Transforms a Map from the CosmosDB API to the model.
Variables



Name
Azure API key name
Example
Description




id
id
myId1
The unique user generated name for the resource, max 255 chars.


rid
_rid
qicAAA==
System generated property. The resource ID (_rid) is a unique identifier. It is used internally for placement of and navigation to the resource.


ts
_ts
1446192371
System generated property. It specifies the last updated timestamp of the resource. The value is a timestamp.


self
_self
dbs\/qicAAA==\/
System generated property. It is the unique addressable URI for the resource.


etag
_etag
00001800-...
System generated property representing the resource etag required for optimistic concurrency control.


error
code,message
{"code": "...","message": "..."}
An empty Map in case of a successful transaction, else a map with a code and a message.


body
body
function() { ... }
A user settable property. It is the body of the stored procedure.



StoredProcedureList
Methods
StoredProcedureList.toMap() -> Transforms the model to a Map for the CosmosDB API.
StoredProcedureList.toMap(Map<String, dynamic> map) -> Transforms a Map from the CosmosDB API to the model.
Variables



Name
Azure API key name
Example
Description




rid
_rid
qicAAA==
System generated property. The resource ID (_rid) is a unique identifier. It is used internally for placement of and navigation to the resource.


count
_count
3
This property shows the number of resources returned as part of list operation.


error
code,message
{"code": "...","message": "..."}
An empty Map in case of a successful transaction, else a map with a code and a message.


storedProcedures
StoredProcedures
[]
A list of CosmosDB stored procedures. List<StoredProcedure>



3.6 User Defined Functions #
A user-defined function (UDF) is a side effect free piece of application logic written in JavaScript. It allows developers to construct a query operator, thus extending the core of the Cosmos DB query language. Like stored procedures, UDFs live in the confines of a collection, thus confining the application logic to the collection.
3.6.1 List User Defined Functions
Performing a GET on the triggers resource of a particular database returns a list of the triggers in the collection.
The user-defined-function-list operation returns a Future<UserDefinedFunctionList> with a list of UserDefinedFunction or an error object.
See 3.6.5 The User Defined Function model for information on the returned model and its variables.
final UserDefinedFunctionList userDefinedFunctionList = await cosmosDb.userDefinedFunctions.list(
// REQUIRED -> User generated name/id of the database.
dbId: '<DB_ID>',
// REQUIRED -> Id/name of the collection where the user defined functions reside.
collectionId: '<COLLECTION_ID>',
);

if (userDefinedFunctionList.error.isEmpty) {
// If the error is empty, continue....
}
copied to clipboard
3.6.2 Create a User Defined Function
The create-operation creates a new stored procedure in a collection.
The user-defined-function-create operation returns a Future<UserDefinedFunction>.
See 3.6.5 The User Defined Function model for information on the returned model and its variables.
final UserDefinedFunction userDefinedFunction = await cosmosDb.userDefinedFunctions.create(
// REQUIRED -> User generated name/id of the database.
dbId: '<DB_ID>',
// REQUIRED -> Id/name of the collection where the user defined function is created.
collectionId: '<COLLECTION_ID>',
// REQUIRED -> Unique name to identify the user defined function, max 255 chars.
userDefinedFunctionId: '<UDFS_ID>',
// REQUIRED -> The body of the user defined function.
function: 'function updateMetadata() { ... }',
);

if (userDefinedFunction.error.isEmpty) {
// If the error is empty, continue....
}
copied to clipboard
3.6.3 Replace a User Defined Function
Performing a PUT operation on a specific UDF resource replaces the entire UDF resource.
All user-settable properties, including the id and the body, must be submitted in the body to perform the replacement.
The user-defined-function-replace operation returns a Future<UserDefinedFunction>.
See 3.6.5 The User Defined Function model for information on the returned model and its variables.
final UserDefinedFunction userDefinedFunction = await cosmosDb.userDefinedFunctions.replace(
// REQUIRED -> User generated name/id of the database.
dbId: '<DB_ID>',
// REQUIRED -> Id/name of the collection where the user defined function is replaced.
collectionId: '<COLLECTION_ID>',
// REQUIRED -> Id/name of the user defined function to be replaced.
userDefinedFunctionId: '<UDFS_ID>',
// REQUIRED -> The body of the user defined function, will replace the current function.
function: 'function updateMetadata() { ...Updated function... }',
);

if (userDefinedFunction.error.isEmpty) {
// If the error is empty, continue....
}
copied to clipboard
3.6.4 Delete a User Defined Function
The delete-operation deletes an existing user-defined function in a collection.
The user-defined-function-delete operation returns a Future<UserDefinedFunction>.
See 3.6.5 The User Defined Function model for information on the returned model and its variables.
final UserDefinedFunction userDefinedFunction = await cosmosDb.userDefinedFunctions.delete(
// REQUIRED -> User generated name/id of the database.
dbId: '<DB_ID>',
// REQUIRED -> Id/name of the collection where the user defined function is deleted from.
collectionId: '<COLLECTION_ID>',
// REQUIRED -> Id/name of the user defined function to be deleted.
userDefinedFunctionId: '<UDFS_ID>',
);

if (userDefinedFunction.error.isEmpty) {
// If the error is empty, continue....
}
copied to clipboard
3.6.5 The User Defined Function model
UserDefinedFunction
Methods
UserDefinedFunction.toMap() -> Transforms the model to a Map for the CosmosDB API.
UserDefinedFunction.toMap(Map<String, dynamic> map) -> Transforms a Map from the CosmosDB API to the model.
Variables



Name
Azure API key name
Example
Description




id
id
myId1
The unique user generated name for the resource, max 255 chars.


rid
_rid
qicAAA==
System generated property. The resource ID (_rid) is a unique identifier. It is used internally for placement of and navigation to the resource.


ts
_ts
1446192371
System generated property. It specifies the last updated timestamp of the resource. The value is a timestamp.


self
_self
dbs\/qicAAA==\/
System generated property. It is the unique addressable URI for the resource.


etag
_etag
00001800-...
System generated property representing the resource etag required for optimistic concurrency control.


error
code,message
{"code": "...","message": "..."}
An empty Map in case of a successful transaction, else a map with a code and a message.


body
body
function() { ... }
A user settable property. It is the body of the UDF.



UserDefinedFunctionList
Methods
UserDefinedFunctionList.toMap() -> Transforms the model to a Map for the CosmosDB API.
UserDefinedFunctionList.toMap(Map<String, dynamic> map) -> Transforms a Map from the CosmosDB API to the model.
Variables



Name
Azure API key name
Example
Description




rid
_rid
qicAAA==
System generated property. The resource ID (_rid) is a unique identifier. It is used internally for placement of and navigation to the resource.


count
_count
3
This property shows the number of resources returned as part of list operation.


error
code,message
{"code": "...","message": "..."}
An empty Map in case of a successful transaction, else a map with a code and a message.


userDefinedFunctions
UserDefinedFunctions
[]
A list of CosmosDB stored procedures. List<UserDefinedFunction>



3.7 Triggers #
Triggers are pieces of application logic that can be executed before (pre-triggers) and after (post-triggers) creation, deletion, and replacement of a document. Triggers are written in JavaScript. Both pre and post triggers do not take parameters. Like stored procedures, triggers live within the confines of a collection, thus confining the application logic to the collection.
3.7.1 List Triggers
Performing a GET on the triggers resource of a particular database returns a list of the triggers in the collection.
The trigger-list operation returns a Future<TriggerList> with a list of Trigger or an error object.
See 3.7.5 The Trigger model for information on the returned model and its variables.
final TriggerList triggerList = await cosmosDb.trigger.list(
// REQUIRED -> User generated name/id of the database.
dbId: '<DB_ID>',
// REQUIRED -> Id/name of the collection where the triggers reside.
collectionId: '<COLLECTION_ID>',
);

if (triggerList.error.isEmpty) {
// If the error is empty, continue....
}
copied to clipboard
3.7.2 Create a Trigger
The create-operation creates a new trigger in a collection.
The trigger-create operation returns a Future<Trigger>.
See 3.7.5 The Trigger model for information on the returned model and its variables.
final Trigger trigger = await cosmosDb.trigger.create(
// REQUIRED -> User generated name/id of the database.
dbId: '<DB_ID>',
// REQUIRED -> Id/name of the collection where the triggers is created.
collectionId: '<COLLECTION_ID>',
// REQUIRED -> Unique name used to identify the trigger, max 255 chars.
triggerId: '<TRIGGER_ID>',
// REQUIRED -> The function of the trigger.
function: 'function updateMetadata() { ... }',
// REQUIRED -> Type of operation that invokes the trigger.
// The acceptable values are: TriggerOperation.all, TriggerOperation.create, TriggerOperation.replace, and TriggerOperation.delete.
triggerOperation: TriggerOperation.all,
// REQUIRED -> This value specifies when the trigger is fired.
// The acceptable values are: TriggerType.pre and TriggerType.post.
// Pre triggers fire before an operation while Post triggers after an operation.
triggerType: TriggerType.post,
);

if (trigger.error.isEmpty) {
// If the error is empty, continue....
}
copied to clipboard
3.7.3 Replace a Trigger
Performing a PUT operation on a specific trigger resource replaces the entire trigger resource.
All user-settable properties, including the ID, the body, the triggerOperation, and the triggerType, must be submitted in the body to perform the replacement.
The trigger-replace operation returns a Future<Trigger>.
See 3.7.5 The Trigger model for information on the returned model and its variables.
final Trigger trigger = await cosmosDb.trigger.replace(
// REQUIRED -> User generated name/id of the database.
dbId: '<DB_ID>',
// REQUIRED -> Id/name of the collection where the triggers is replaced.
collectionId: '<COLLECTION_ID>',
// REQUIRED -> Id/name of the trigger to replace.
triggerId: '<TRIGGER_ID>',
function: 'function updateMetadata() { ...Updated function... }',
// REQUIRED -> Type of operation that invokes the trigger.
// The acceptable values are: TriggerOperation.all, TriggerOperation.create, TriggerOperation.replace, and TriggerOperation.delete.
triggerOperation: TriggerOperation.all,
// REQUIRED -> This value specifies when the trigger is fired.
// The acceptable values are: TriggerType.pre and TriggerType.post.
// Pre triggers fire before an operation while Post triggers after an operation.
triggerType: TriggerType.post,
);

if (trigger.error.isEmpty) {
// If the error is empty, continue....
}
copied to clipboard
3.7.4 Delete a Trigger
The delete-operation deletes an existing trigger in a collection.
The trigger-delete operation returns a Future<Trigger>.
See 3.7.5 The Trigger model for information on the returned model and its variables.
final Trigger trigger = await cosmosDb.trigger.delete(
// REQUIRED -> User generated name/id of the database.
dbId: '<DB_ID>',
// REQUIRED -> Id/name of the collection where the triggers is deleted from.
collectionId: '<COLLECTION_ID>',
// REQUIRED -> Id/name of the trigger to delete.
triggerId: '<TRIGGER_ID>',
);

if (trigger.error.isEmpty) {
// If the error is empty, continue....
}
copied to clipboard
3.7.5 The Trigger model
Trigger
Methods
Trigger.toMap() -> Transforms the model to a Map for the CosmosDB API.
Trigger.toMap(Map<String, dynamic> map) -> Transforms a Map from the CosmosDB API to the model.
Variables



Name
Azure API key name
Example
Description




id
id
myId1
The unique user generated name for the resource, max 255 chars.


rid
_rid
qicAAA==
System generated property. The resource ID (_rid) is a unique identifier. It is used internally for placement of and navigation to the resource.


ts
_ts
1446192371
System generated property. It specifies the last updated timestamp of the resource. The value is a timestamp.


self
_self
dbs\/qicAAA==\/
System generated property. It is the unique addressable URI for the resource.


etag
_etag
00001800-...
System generated property representing the resource etag required for optimistic concurrency control.


error
code,message
{"code": "...","message": "..."}
An empty Map in case of a successful transaction, else a map with a code and a message.


body
body
function() { ... }
A user settable property. It is the body of the trigger.


triggerOperation
triggerOperation
TriggerOperation.all
It is the type of operation that invokes the trigger.The acceptable values are: TriggerOperation.all, TriggerOperation.insert, TriggerOperation.replace and TriggerOperation.delete.


triggerType
triggerType
TriggerType.post
This specifies when the trigger is fired. The acceptable values are: TriggerType.pre and TriggerType.post.Pre triggers fire before an operation while Post triggers after an operation.



TriggerList
Methods
TriggerList.toMap() -> Transforms the model to a Map for the CosmosDB API.
TriggerList.toMap(Map<String, dynamic> map) -> Transforms a Map from the CosmosDB API to the model.
Variables



Name
Azure API key name
Example
Description




rid
_rid
qicAAA==
System generated property. The resource ID (_rid) is a unique identifier. It is used internally for placement of and navigation to the resource.


count
_count
3
This property shows the number of resources returned as part of list operation.


error
code,message
{"code": "...","message": "..."}
An empty Map in case of a successful transaction, else a map with a code and a message.


triggers
Triggers
[]
A list of CosmosDB triggers. List<Trigger>



3.8 Users #
A user is a logical namespace for scoping permissions on collections, documents, attachments, stored procedures, triggers, and user-defined functions. The user construct lives under a database resource and thus cannot cross the database boundary it is under. The user resource is represented by users in the Azure Cosmos DB REST resource model. It is a system resource, and thus contains a fixed schema.
3.8.1 List Users
Performing a GET operation on the users resource of a particular database, i.e. the users URI path.
The user-list operation returns a Future<UserList> with a list of User or an error object.
See 3.8.6 The Trigger model for information on the returned model and its variables.
final UserList userList = await cosmosDb.user.list(
// REQUIRED -> User generated name/id of the database.
dbId: '<DB_ID>',
);

if (userList.error.isEmpty) {
// If the error is empty, continue....
}
copied to clipboard
3.8.2 Get a User
Performing a GET operation on a single user with his id/name.
The user-get operation returns a Future<User>.
See 3.8.6 The Trigger model for information on the returned model and its variables.
final User user = await cosmosDb.user.get(
// REQUIRED -> User generated name/id of the database.
dbId: '<DB_ID>',
// REQUIRED -> The id/name of the user.
userId: '<USER_ID>',
);

if (user.error.isEmpty) {
// If the error is empty, continue....
}
copied to clipboard
3.8.3 Create a User
The create-operation creates a new user in a database.
The user-create operation returns a Future<User>.
See 3.8.6 The Trigger model for information on the returned model and its variables.
final User user = await cosmosDb.user.create(
// REQUIRED -> User generated name/id of the database.
dbId: '<DB_ID>',
// REQUIRED -> The user generated unique name for the user.
userId: '<USER_ID>',
);

if (user.error.isEmpty) {
// If the error is empty, continue....
}
copied to clipboard
3.8.4 Replace a User
PUT operation on the specific user resource to replace the entire user resource.
The only replaceable property is the id of the user. This replace operation does not impact the permissions of the user.
The user-replace operation returns a Future<User>.
See 3.8.6 The Trigger model for information on the returned model and its variables.
final User user = await cosmosDb.user.replace(
// REQUIRED -> User generated name/id of the database.
dbId: '<DB_ID>',
// REQUIRED -> The id/name of the user to replace.
userId: '<USER_ID>',
// REQUIRED -> The new unique id/name of the user.
newUserId: '<NEW_USER_ID>',
);

if (user.error.isEmpty) {
// If the error is empty, continue....
}
copied to clipboard
3.8.5 Delete a User
The delete-operation deletes an existing user in a database.
The user-delete operation returns a Future<User>.
See 3.8.6 The Trigger model for information on the returned model and its variables.
final User user = await cosmosDb.user.delete(
// REQUIRED -> User generated name/id of the database.
dbId: '<DB_ID>',
// REQUIRED -> The id/name of the user to delete.
userId: '<USER_ID>',
);

if (user.error.isEmpty) {
// If the error is empty, continue....
}
copied to clipboard
3.8.6 The User model
User
Methods
User.toMap() -> Transforms the model to a Map for the CosmosDB API.
User.toMap(Map<String, dynamic> map) -> Transforms a Map from the CosmosDB API to the model.
Variables



Name
Azure API key name
Example
Description




id
id
myId1
The unique user generated name for the resource, max 255 chars.


rid
_rid
qicAAA==
System generated property. The resource ID (_rid) is a unique identifier. It is used internally for placement of and navigation to the resource.


ts
_ts
1446192371
System generated property. It specifies the last updated timestamp of the resource. The value is a timestamp.


self
_self
dbs\/qicAAA==\/
System generated property. It is the unique addressable URI for the resource.


etag
_etag
00001800-...
System generated property representing the resource etag required for optimistic concurrency control.


error
code,message
{"code": "...","message": "..."}
An empty Map in case of a successful transaction, else a map with a code and a message.


permissions
_permissions
permissions\/
System generated property denoting the addressable path of the feed of permissions resource.



UserList
Methods
UserList.toMap() -> Transforms the model to a Map for the CosmosDB API.
UserList.toMap(Map<String, dynamic> map) -> Transforms a Map from the CosmosDB API to the model.
Variables



Name
Azure API key name
Example
Description




rid
_rid
qicAAA==
System generated property. The resource ID (_rid) is a unique identifier. It is used internally for placement of and navigation to the resource.


count
_count
3
This property shows the number of resources returned as part of list operation.


error
code,message
{"code": "...","message": "..."}
An empty Map in case of a successful transaction, else a map with a code and a message.


users
Users
[]
A list of CosmosDB users. List<User>



3.9 Permissions #
Permission is an authorization token associated with a user for authorized access to a specific resource. It is used to manage access to collections, documents, attachments, stored procedures, triggers, and user-defined functions for a particular user.
3.9.1 List Permissions
GET operation on the permissions URI path, which returns a list of permissions for the user.
All of the resource tokens are recreated for the respective permissions returned as part of the response.
The new tokens have the default validity period (one hour) unless it is overridden.
The permission-list operation returns a Future<PermissionList> with a list of Permission or an error object.
See 3.9.6 The Permission model for information on the returned model and its variables.
final PermissionList permissionList = await cosmosDb.permission.list(
// REQUIRED -> User generated name/id of the database.
dbId: '<DB_ID>',
// REQUIRED -> Name/id of the user, the permissions are assigned to.
userId: '<USER_ID>',
);

if (permissionList.error.isEmpty) {
// If the error is empty, continue....
}
copied to clipboard
3.9.2 Get a Permission
Performing a GET operation on a specific permission resource retrieves the permission properties, including the token, for the particular permission.
A new resource token is created every time a GET is invoked on the permission resource.
The new tokens have the default validity period (one hour) unless it is overridden.
The permission-get operation returns a Future<Permission>.
See 3.9.6 The Permission model for information on the returned model and its variables.
final Permission permission = await cosmosDb.permission.get(
// REQUIRED -> User generated name/id of the database.
dbId: '<DB_ID>',
// REQUIRED -> Name/id of the user, the permission is assigned to.
userId: '<USER_ID>',
// REQUIRED -> Name/id of the permission to be retrieved.
permissionId: '<PERMISSION_ID>',
);

if (permission.error.isEmpty) {
// If the error is empty, continue....
}
copied to clipboard
3.9.3 Create a Permission
The create-operation creates a new permission in a database.
The permission-create operation returns a Future<Permission>.
See 3.9.6 The Permission model for information on the returned model and its variables.
final Permission permission = await cosmosDb.permission.create(
// REQUIRED -> User generated name/id of the database.
dbId: '<DB_ID>',
// REQUIRED -> Name/id of the user, the permission will be assigned to.
userId: '<USER_ID>',
// REQUIRED -> The full addressable path of the resource associated with the permission.
// For example, dbs/volcanodb/colls/volcano1.
collectionId: '<COLLECTION_ID>',
// REQUIRED -> Name/id of the permission to be created.
permissionId: '<PERMISSION_ID>',
// REQUIRED -> The access mode for the resource: All or Read. All provides read, write, and delete access to a resource.
// The acceptable values are: PermissionMode.all, PermissionMode.read
permissionMode: PermissionMode.all,
);

if (permission.error.isEmpty) {
// If the error is empty, continue....
}
copied to clipboard
3.9.4 Replace a Permission
Performing a PUT operation on a specific permission resource replaces the entire user resource.
All user-settable properties, the id, permissionMode, and resource, must be submitted in the body to perform the replacement.
The permission-replace operation returns a Future<Permission>.
See 3.9.6 The Permission model for information on the returned model and its variables.
final Permission permission = await cosmosDb.permission.replace(
// REQUIRED -> User generated name/id of the database.
dbId: '<DB_ID>',
// REQUIRED -> Name/id of the user, the permission is assigned to.
userId: '<USER_ID>',
// REQUIRED -> The full addressable path of the resource associated with the permission.
// For example, dbs/volcanodb/colls/volcano1.
collectionId: '<COLLECTION_ID>',
// REQUIRED -> Name/id of the permission to be replaced.
permissionId: '<PERMISSION_ID>',
// REQUIRED -> The new name/id of the permission.
newPermissionId: '<NEW_PERMISSION_ID>',
// REQUIRED -> The access mode for the resource: All or Read. All provides read, write, and delete access to a resource.
// The acceptable values are: PermissionMode.all, PermissionMode.read
permissionMode: PermissionMode.all,
);

if (permission.error.isEmpty) {
// If the error is empty, continue....
}
copied to clipboard
3.9.5 Delete a Permission
The delete-operation deletes an existing permission in a database.
The permission-delete operation returns a Future<Permission>.
See 3.9.6 The Permission model for information on the returned model and its variables.
final Permission permission = await cosmosDb.permission.delete(
// REQUIRED -> User generated name/id of the database.
dbId: '<DB_ID>',
// REQUIRED -> Name/id of the user, the permission is assigned to.
userId: '<USER_ID>',
// REQUIRED -> Name/id of the permission to be deleted.
permissionId: '<PERMISSION_ID>',
);

if (permission.error.isEmpty) {
// If the error is empty, continue....
}
copied to clipboard
3.9.6 The Permission model
Permission
Methods
Permission.toMap() -> Transforms the model to a Map for the CosmosDB API.
Permission.toMap(Map<String, dynamic> map) -> Transforms a Map from the CosmosDB API to the model.
Variables



Name
Azure API key name
Example
Description




id
id
myId1
The unique user generated name for the resource, max 255 chars.


rid
_rid
qicAAA==
System generated property. The resource ID (_rid) is a unique identifier. It is used internally for placement of and navigation to the resource.


ts
_ts
1446192371
System generated property. It specifies the last updated timestamp of the resource. The value is a timestamp.


self
_self
dbs\/qicAAA==\/
System generated property. It is the unique addressable URI for the resource.


etag
_etag
00001800-...
System generated property representing the resource etag required for optimistic concurrency control.


error
code,message
{"code": "...","message": "..."}
An empty Map in case of a successful transaction, else a map with a code and a message.


token
_token
type=resource&ver=1&sig=m32...
System generated resource token for the particular resource and user.


permissionMode
permissionMode
PermissionMode.all
The access mode on the resource for the user: PermissionMode.all or PermissionMode.read.All provides read, write, and delete access to a resource.


resource
resource
dbs/ruJjAA==/colls/ruJjAM9UnAA=/
The full addressable path of the resource associated with the permission.



PermissionList
Methods
PermissionList.toMap() -> Transforms the model to a Map for the CosmosDB API.
PermissionList.toMap(Map<String, dynamic> map) -> Transforms a Map from the CosmosDB API to the model.
Variables



Name
Azure API key name
Example
Description




rid
_rid
qicAAA==
System generated property. The resource ID (_rid) is a unique identifier. It is used internally for placement of and navigation to the resource.


count
_count
3
This property shows the number of resources returned as part of list operation.


error
code,message
{"code": "...","message": "..."}
An empty Map in case of a successful transaction, else a map with a code and a message.


permissions
Permissions
[]
A list of CosmosDB permissions. List<Permission>



4 Where to go from here #
While you could use this package for creating your own CosmosDB editor, in case of an app that will save and receive data from users, it is advisable to use a user and its key.
Check out the Microsoft CosmosDB documentation for more information on the CosmosDB SQL-API.
5 Bugs and issues #
Please file feature requests and bugs at the issue tracker