Skip to main content
Version: 2.0

Azure Cosmos DB Data Source

Introduction​

Azure Cosmos DB is a fully managed database service on Azure that provides low-latency access to globally distributed data. This topic explains how to connect Azure Cosmos DB data sources in your Reveal application to visualize and analyze your data.

Server Configuration​

Installation​

Step 1 - Install the Reveal Azure Cosmos DB connector package.

For ASP.NET applications, you need to install a separate NuGet package to enable Azure Cosmos DB support:

dotnet add package Reveal.Sdk.Data.AzureCosmosDB

Step 2 - Register the Azure Cosmos DB data source in your application.

builder.Services.AddControllers().AddReveal( builder =>
{
    builder.DataSources.RegisterAzureCosmosDB();
});

Connection Configuration​

// Create a data source provider
public class DataSourceProvider : IRVDataSourceProvider
{
    public async Task<RVDataSourceItem> ChangeDataSourceItemAsync(IRVUserContext userContext, string dashboardId,
        RVDataSourceItem dataSourceItem)
    {
        // Required: Update the underlying data source
        await ChangeDataSourceAsync(userContext, dataSourceItem.DataSource);

        if (dataSourceItem is RVAzureCosmosDBDataSourceItem cosmosItem)
        {
            // Configure specific item properties if needed
            if (cosmosItem.Id == "azure_cosmos_orders")
            {
                cosmosItem.Container = "orders";
            }
        }

        return dataSourceItem;
    }

    public Task<RVDashboardDataSource> ChangeDataSourceAsync(IRVUserContext userContext,
        RVDashboardDataSource dataSource)
    {
        if (dataSource is RVAzureCosmosDBDataSource cosmosDataSource)
        {
            // Configure connection properties
            cosmosDataSource.AccountEndpoint = "https://your-account.documents.azure.com:443/";
            cosmosDataSource.Database = "Sales";
            cosmosDataSource.ApplicationRegion = "East US";
            cosmosDataSource.ConnectionMode = "Gateway";
            cosmosDataSource.AcceptAnyServerCertificate = false;
        }

        return Task.FromResult(dataSource);
    }
}
Important

Any changes made to the data source in the ChangeDataSourceAsync method are not carried over into the ChangeDataSourceItemAsync method. You must update the data source properties in both methods. We recommend calling the ChangeDataSourceAsync method within the ChangeDataSourceItemAsync method passing the data source item's underlying data source as the parameter as shown in the examples above.

Authentication​

Authentication for Azure Cosmos DB is handled on the server side using RVKeyPairDataSourceCredential. For Azure Cosmos DB, the credential key maps to your account key. For detailed information on authentication options, see the Authentication topic.

public class AuthenticationProvider: IRVAuthenticationProvider
{
    public Task<IRVDataSourceCredential> ResolveCredentialsAsync(IRVUserContext userContext, RVDashboardDataSource dataSource)
    {
        IRVDataSourceCredential userCredential = null;
        if (dataSource is RVAzureCosmosDBDataSource)
        {
            // Use account key
            userCredential = new RVKeyPairDataSourceCredential(null, "your_account_key");
        }
        return Task.FromResult<IRVDataSourceCredential>(userCredential);
    }
}

Client-Side Implementation​

On the client side, you only need to specify basic properties like ID, title, and subtitle for the data source. The actual connection configuration happens on the server.

Creating Data Sources​

Step 1 - Add an event handler for the RevealView.onDataSourcesRequested event.

const revealView = new RevealView("#revealView");
revealView.onDataSourcesRequested = (callback) => {
    // Add data source here
    callback(new RevealDataSources([], [], false));
};

Step 2 - In the RevealView.onDataSourcesRequested event handler, create a new instance of the RVAzureCosmosDBDataSource object. Set the title and subtitle properties. After you have created the RVAzureCosmosDBDataSource object, add it to the data sources collection.

revealView.onDataSourcesRequested = (callback) => {
    // Create the data source
    const cosmosDS = new RVAzureCosmosDBDataSource();
    cosmosDS.title = "My Azure Cosmos DB Datasource";
    cosmosDS.subtitle = "Azure Cosmos DB";

    callback(new RevealDataSources([cosmosDS], [], false));
};

When the application runs, create a new Visualization and you will see the newly created Azure Cosmos DB data source listed in the "Select a Data Source" dialog.

Creating Data Source Items​

Data source items represent specific datasets within your Azure Cosmos DB data source that users can select for visualization. On the client side, you only need to specify ID, title, and subtitle.

revealView.onDataSourcesRequested = (callback) => {
    // Create the data source
    const cosmosDS = new RVAzureCosmosDBDataSource();
    cosmosDS.title = "My Azure Cosmos DB Datasource";
    cosmosDS.subtitle = "Azure Cosmos DB";

    // Create a data source item
    const cosmosDSI = new RVAzureCosmosDBDataSourceItem(cosmosDS);
    cosmosDSI.title = "My Azure Cosmos DB Datasource Item";
    cosmosDSI.subtitle = "Azure Cosmos DB";

    callback(new RevealDataSources([cosmosDS], [cosmosDSI], false));
};

When the application runs, create a new Visualization and you will see the newly created Azure Cosmos DB data source item listed in the "Select a Data Source" dialog.

Additional Resources​

API Reference​