Hacking: changing Cosmos DB Portal experience from Graph to SQL

In the last article, we looked at how we could access a graph using the SQL (aka DocumentDB) API.

Here we’ll explore how we can switch the Portal experience from one to the other.

Portal Experience

The Portal Experience refers to the way the portal lets us interact with Cosmos DB Data.  It’s basically the Data Explorer experience.

Here we have the Cosmos DB Graph experience:


The Data Explorer lets us access the Graph using Gremlin and displays results in a Graph UI experience (i.e. showing vertices & edges).

Let’s compare this to the Cosmos DB SQL (aka DocumentDB) experience:


Here we query collections using SQL queries and results are shown as JSON documents.

CosmosDB in ARM

The schema for JSON ARM template of CosmosDB Database Account is documented here.

There are two important properties for Cosmos DB model (i.e. SQL, Graph, Table or MongoDB):  kind and defaultExperience (on fourth and seventh line respectively).

  "apiVersion": "2015-04-08",
  "type": "Microsoft.DocumentDB/databaseAccounts",
  "kind": "[parameters('kind')]",
  "name": "[parameters('databaseAccountName')]",
  "tags": {
    "defaultExperience": "[parameters('experience')]"
  "location": "[resourceGroup().location]",
  "properties": {
    "name": "[parameters('databaseAccountName')]",
    "databaseAccountOfferType": "[variables('offerType')]",
    "consistencyPolicy": {
      "defaultConsistencyLevel": "[parameters('consistencyLevel')]",
      "maxStalenessPrefix": "[parameters('maxStalenessPrefix')]",
      "maxIntervalInSeconds": "[parameters('maxIntervalInSeconds')]"

Kind takes the following values:  GlobalDocumentDB, MongoDB & Parse.  It defines how the database engine is configured.  This property must be supplied at creation time and can’t be changed after.

DefaultExperience takes the following values:  DocumentDB, MongoDB, Graph & Table.  It influences only how the portal behaves.  This property is optional and can be changed in any update deployments.

When creating a Cosmos DB account in the Portal, here is the mapping of the values.  The left-hand side column API refers to the drop down value selected in the portal at the account creation.

API Kind Default Experience
SQL (DocumentDB) GlobalDocumentDB DocumentDB
MongoDB MongoDB MongoDB
Gremlin (graph) GlobalDocumentDB Graph
Table (key-value) GlobalDocumentDB Table

We notice the Kind value Parse isn’t yet used with any model.  It is used for the Parse Server offering.

Changing the experience

With all that said, we can easily change the default experience from one ARM Deployment to another.  Template is available in GitHub.

Also, since the experience is a simple tag, it can be changed using PowerShell or even the Portal.



Although the fundamental database engine is set at the creation of the account, the portal experience can be changed.

Therefore, if it is convenient to change the experience in order to execute some tasks, it is possible to do so without impacting the underlying database.

4 responses

  1. Razvan Goga (@WhiteRGR) 2017-11-02 at 09:41

    Would you happen to know if there is there an official public documentation of any sort detailing this?

    I’ve asked the same question about the role of the API switchin this context to the CosmosDB support guys (askcosmosdb@microsoft.com / askcosmosdbgraphapi@microsoft.com) and got basically the same vague eplination that the msdn docs give.

    Thanks, Razvan

  2. Vincent-Philippe Lauzon 2017-11-02 at 09:43

    To my knowledge there isn’t. This is why I wrote that article.

  3. Razvan Goga (@WhiteRGR) 2017-11-02 at 09:55

    Was pretty much expecting this but I hoped I had missed something :)

    Thank you

  4. Viola 2021-04-08 at 14:30

    Thank you for this post. It helps a lot!

Leave a comment