Kom igång med Azure Cosmos DB

Lite kort Cosmos DB

Azure Cosmos DB är en globalt distribuerad databas som erbjuder låg latens, hög tillgänglighet, elastisk skalning och automatisk indexering för olika datamodeller (dokument, nyckel-värde, graf och kolumnorienterad).

Comsos DB är ett bra val för datalagring om:

• Din applikation behöver utföra komplexa frågor och analyser på stora dataset.
• Din applikation behöver flexibel och schemalös datahantering.
• Din applikation kräver hög tillgänglighet och pålitlig prestanda (Cosmos DB's SLA är 99.999 vid mer än en region).
• Din applikation har varierande belastning och kräver elastisk skalning.
• Din applikation behöver snabb åtkomst och korta svarstider.

Denna guide förutsätter att man har en Azure subscription och viss vana inom Azure. Om man inte har en subscription kan man skaffa en här.

1. Välj API

Det först man möts av när man skapar upp en ny Cosmos DB är att välja vilket API man ska använda.

I detta exemplet kommer vi använda "Azure Cosmos DB for NoSQL" då jag är gammal SQL-räv och gillar möjligheten att kunna använda SQL för att ställa frågor mot databasen.

2. Skapa upp en Cosmos DB-resurs.

Här anger man som vanligt när man skapar upp resurser i Azure, Subscription, Resource Group och Location.

Nedan förklaras andra valen man behöver göra för att skapa upp resursen.

• Account Name: Detta är namnet på resursen.
• Availability Zones: Genom att aktivera Availability Zones för Cosmos får man replikering i tre fysiskt separerade instanser inom sin valda region. Mer om detta här.
• Capacity mode: Provisioned Throughput innebär att du på förhand allokerar en specifik mängd Request Units (RUs) per sekund för din databas eller container. Du betalar för kapaciteten oavsett om den används fullt ut eller inte. Provisioned Throughput passar bäst för applikationer med jämn belastning. Serverless innebär att du inte behöver förhandsallokera någon genomströmning. Istället betalar du bara för de RUs som faktiskt förbrukas av dina databasoperationer. Serverless passar bäst för applikationer med varierande belastning.

Mer om Capacity mode och RUs finner du här men kort kan man säga att varje operation, inklusive läsningar, skrivningar, SQL-frågor, och indexeringsoperationer, förbrukar ett visst antal RUs.

En läsning av ett dokument på 1kb med en känd nyckel kan kosta runt 1 RU.

Att skriva ett dokument beror på dokumentets storlek och kan kosta runt 5 RUs.

I detta exemplet kommer vi använda Provisioned Throughput då vi kan dra nytta av de 1000 gratis RUs Azure bjuder på.

När din resurs är skapad så navigera till "Data Explorer" i menyn till vänster.

3. Skapa upp en Container

En container i Azure Cosmos DB är en logisk enhet som används för att organisera och lagra data. Den kan liknas vid en databas-tabell i SQL-server.

Här väljer vi New Container.

Database id: När man skapar en container får man valet om man vill lägga till den i en befintlig databas eller skapa en ny. Eftersom vi inte har skapat upp någon databas ännu så väljer vi create new.

• Share throughput across containers: Kryssar man i boxen så kommer databasens allokerade RU's delas mellan alla containers i databasen.
• Database throughput (autoscale): Här väljer man om Azure ska sköta skalningen åt en eller om man vill hantera det själv.
• Database Max RU/s: Här anges max antal RU/s som man vill att Azure ska kunna skala upp till. Tänk på att ju fler RU/s ju dyrare kostnad.
• Container id: Namnet på din container.
• Indexing: Väljer man Automatic så indexeras alla properties i ens dokument automatiskt, vilket är ett måste om man tänker göra sökningar på olika properties i dokumenten. Om man endast tänker hämta dokument baserat på ett dokument-id så kan man stänga av indexering.
• Partition key: Primary key används för att skala databasen horisontellt genom att distribuera data över flera partitioner. En väl vald partition key förbättrar prestanda och effektivitet i datahantering och frågor. För t.ex en e-handelsplattform kan "customerId" vara en partition key för en "orders container", vilket gör att alla beställningar från en viss kund lagras tillsammans.
• Unique keys: används för att säkerställa dataintegritet i containern. En unique key kan liknas vid en primärnyckel eller ett unique-index i SQL-server och förhindrar duplicerade värden.

När containern skapats är den redo att fyllas med data.

4. Injicera data

Här är ett enkelt program i .Net som skapar upp fem "Items" och injicerar datan till Cosmos.

För att det ska fungera behöver man installera följande nuget-paket.

Install-Package Microsoft.Azure.Cosmos

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Microsoft.Azure.Cosmos;

namespace CosmosDBTestData
{
    class Program
    {
        private static readonly string EndpointUri = "https://<your-cosmosdb-account>.documents.azure.com:443/";
        private static readonly string PrimaryKey = "<your-primary-key>";
        private static CosmosClient cosmosClient;
        private static Database database;
        private static Container container;
        private static readonly string databaseId = "MyCosmosDB";
        private static readonly string containerId = "Items";
        static async Task Main(string[] args)
        {
            cosmosClient = new CosmosClient(EndpointUri, PrimaryKey);
            database = await cosmosClient.CreateDatabaseIfNotExistsAsync(databaseId);
            container = await database.CreateContainerIfNotExistsAsync(containerId, "/itemId");
            await AddTestData();
            Console.WriteLine("Test data added successfully.");
        }

        private static async Task AddTestData()
        {
            var items = new List<dynamic>
            {
                new { id = "1", itemId = "1", name = "Item1", description = "This is item 1", price = 10.0 },
                new { id = "2", itemId = "2", name = "Item2", description = "This is item 2", price = 20.0 },
                new { id = "3", itemId = "3", name = "Item3", description = "This is item 3", price = 30.0 },
                new { id = "4", itemId = "4", name = "Item4", description = "This is item 4", price = 40.0 },
                new { id = "5", itemId = "5", name = "Item5", description = "This is item 5", price = 50.0 }
            };

            foreach (var item in items)
           {
                try
                {
                    await container.CreateItemAsync(item, new PartitionKey(item.itemId));
                    Console.WriteLine($"Item with id {item.id} added.");
                }
                catch (CosmosException ex)
                {
                    Console.WriteLine($"Error occurred: {ex.StatusCode}");
                }
            }
        }
    }
}

Värdena för "EndpointUri" och "PrimaryKey" hittar man under Connect på startsidan för DataExplorer.

När programmet har körts så ska det nu finnas data i Cosmos.

Navigera till Data Explorer och klicka på New SQL Query.

Klicka på Execute Query för att köra SQL-frågan.