Skip to content

Commit

Permalink
Cosmos DB : Docs update (Getting started) (Azure#1280)
Browse files Browse the repository at this point in the history 
## Why make this change?

- Reference associated issue using `#` syntax. e.g. Closes #XX
  - closes Azure#1131
  - closes  Azure#1123 
  - closes Azure#876 

## What is this change?

-  Updated getting started doc for cosmos db with the embeded data model type that aligns with Common scenarios of Cosmos DB
  - Updated SQL to NOSQL API as there was a rebranding
  - Removed data migration tool link as the tool have been deprecated

## How was this tested?

- [ ] Integration Tests
- [ ] Unit Tests

## Sample Request(s)

- Example REST and/or GraphQL request to demonstrate modifications
```
   query{
  books {
    items{
     id,
      title
      Authors {
        id,
        first_name,
         last_name
      }
    }
  }
}
```
- Example of CLI usage to demonstrate modifications
whole sample of Getting started with Cosmos DB

Note : I am also updating the same document with the public preview docs repository https://github.com/MicrosoftDocs/data-api-builder-docs-pr
  • Loading branch information
@sajeetharan
sajeetharan authored Mar 6, 2023
1 parent f7986f7 commit 80c2bc6
Show file tree
Hide file tree
Showing 4 changed files with 47 additions and 192 deletions.
101 changes: 37 additions & 64 deletions docs/getting-started/getting-started-azure-cosmos-db.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,38 +2,38 @@

Make sure you have read the [Getting Started](getting-started.md) document.

This tutorial assumes that you have already a [Cosmos DB SQL API database account](https://learn.microsoft.com/azure/cosmos-db/sql/create-cosmosdb-resources-portal#create-an-azure-cosmos-db-account) that can be used as a playground.
This tutorial assumes that you have already a [Cosmos DB NoSQL API database account](https://learn.microsoft.com/azure/cosmos-db/sql/create-cosmosdb-resources-portal#create-an-azure-cosmos-db-account) that can be used as a playground.

## Create the database containers
## Create the database container

Create the necessary database containers needed to represent Authors and Books.
Create the database container needed to represent Books. There are different ways to model this sample and you can learn more about data modeling from [here](https://learn.microsoft.com/azure/cosmos-db/nosql/modeling-data). We will use the [embedded data model](https://learn.microsoft.com/en-us/azure/cosmos-db/nosql/modeling-data#embedding-data) in this sample.

- `authors`: Collection containing authors with 'id' as the partition key
- `books`: Collection containing books with 'id' as the partition key
- `books`: Collection containing books and its authors with 'id' as the partition key

Read more about [choosing partition key](https://docs.microsoft.com/en-us/azure/cosmos-db/partitioning-overview#choose-partitionkey) and [data modelling](https://docs.microsoft.com/en-us/azure/cosmos-db/sql/modeling-data)
Read more about [choosing partition key](https://docs.microsoft.com/en-us/azure/cosmos-db/partitioning-overview#choose-partitionkey) and [data modeling](https://docs.microsoft.com/en-us/azure/cosmos-db/sql/modeling-data)

Once the containers are created, you can import the sample data which are placed in the 'azure-cosmos-db' folder to the respective collections by using the [Data Import Tool](https://docs.microsoft.com/en-us/azure/cosmos-db/import-data#JSON).
Once the container is created, we can import the sample data from `books.json` which is placed in the ['azure-cosmos-db'](../samples/getting-started/azure-cosmos-db) folder to the book collection by using the add new item option (Make sure you add one by one item) in the Azure Data Explorer.

## Add Book and Author schema files
![Cosmos DB Add New Document](../media/cosmos-insert-new.png)

We need to expose the books and the authors collections so that they can be used via GraphQL. Cosmos DB, being schema agnostic, requires us to provide the schema definition for the collections. These schema definitions need to be added in the `schema.gql` file.
## Add Book schema file

Start by adding the `Author` and `Book` schema:
We need to expose the books collection so that it can be used via GraphQL. Cosmos DB, being schema agnostic, requires us to provide the schema definition for the collection. The schema definition needs to be added in the `schema.gql` file.

Start by adding the `Book` schema:

```graphql
type Author @model {
type Book @model {
id: ID
first_name: String
middle_name: String
last_name: String
Books: [Book]
title: String
Authors: [Author]
}

type Book @model {
type Author {
id: ID
title: String
Authors: [String]
first_name: String
middle_name: String
last_name: String
}
```

Expand Down Expand Up @@ -107,24 +107,24 @@ As you can see there the `data-source` property specifies that our chosen `datab
With the configuration file in place, then it's time to start defining which entities you want to expose via the API.

## Add Book and Author entities
## Add Book entity

We want to expose the books and the authors collections so that they can be used via GraphQL. For doing that, all we need is to add the related information to the entities section of the configuration file.
We want to expose the books collection so that it can be accessed via GraphQL. For doing that, all we need is to add the related information to the entities section of the configuration file.

> **NOTE**: REST operations are not supported for Cosmos DB via the
> Data API Builder, You can use the existing [REST API](https://learn.microsoft.com/rest/api/cosmos-db/)
You can do this either by using the CLI with the add command :

```bash
dab add Author --source authors --permissions "anonymous:*"
dab add Book --source books --permissions "anonymous:*"
```

or by adding the `Author` entity manually to the configuration file under entities section:
or by adding the `Book` entity manually to the configuration file under entities section:

```json
"Author": {
"source": "authors",
"Book": {
"source": "books",
"rest": false,
"graphql": true,
"permissions": [
Expand All @@ -136,51 +136,16 @@ or by adding the `Author` entity manually to the configuration file under entiti
}
```

within the `entities` object you can create any entity with any name (as long as it is valid for GraphQL). The name `Author`, in this case, will be used to build the GraphQL type. Within the entity you have the `source` element that specifies which container contains the entity data. In our case it is `authors`.

> **NOTE**: Entities names are case sensitive and they will be exposed via GraphQL as you have typed them.
After that, you need to specify the permission for the exposed entity, so that you can be sure only those users making a request with the right claims will be able to access the entity and its data. In this getting started tutorial we're just allowing anyone, without the need to be authenticated, to perform all the CRUD operations to the `Author` entity.
Within the `entities` object you can create any entity with any name (as long as it is valid for GraphQL). The name `Book`, in this case, will be used to build the GraphQL type. Within the entity you have the `source` element that specifies which container contains the entity data. In our case it is `books`.

You can also add the `Book` entity now, applying the same concepts you just learnt for the `Author` entity.
> **NOTE**: Entity names are case sensitive and they will be exposed via GraphQL as you have typed them.
CLI add command :

```bash
dab add Book --source books --permissions "anonymous:*"
```
After that, you need to specify the permissions for the exposed entity, so that you can be sure only those users making a request with the right claims will be able to access the entity and its data. In this getting started tutorial we're just allowing anyone, without the need to be authenticated, to perform all the CRUD operations to the `Book` entity.

or by adding the `Book` entity manually to the configuration file:

```json
"Book": {
"source": "books",
"rest": false,
"graphql": true,
"permissions": [
{
"role": "anonymous",
"actions": [ "*" ]
}
]
}
```

Once you have added the `Author` entity, the `entities` object of configuration file will look like the following:
Once you have added the `Book` entity, the `entities` object of the configuration file will look like the following:

```json
"entities": {
"Author": {
"source": "authors",
"rest": false,
"graphql": true,
"permissions": [
{
"role": "anonymous",
"actions": [ "*" ]
}
]
},
"Book": {
"source": "books",
"rest": false,
Expand Down Expand Up @@ -266,7 +231,7 @@ Using GraphQL you can now execute queries like:
items {
id
title
authors {
Authors {
first_name
last_name
}
Expand All @@ -278,3 +243,11 @@ Using GraphQL you can now execute queries like:
This query will return list of Books and its Authors.

Congratulations, you have just created a fully working backend to support your modern applications!

## Exercise

If you want to practice what you have learned, here's a little exercise you can do on your own

- Add the collection `series` which will store series names (for example: [Foundation Series](https://en.wikipedia.org/wiki/Foundation_series)) and respective ids.
- Update the `books` collection by adding a field named `series_id` and update with matching series_id.
- Update the configuration file with a new entity named `Series`, supported by the `series` source collection you just created.
Binary file added docs/media/cosmos-insert-new.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
39 changes: 0 additions & 39 deletions samples/getting-started/azure-cosmos-db/authors.json
View file

This file was deleted.

99 changes: 10 additions & 89 deletions samples/getting-started/azure-cosmos-db/books.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,19 +2,25 @@
{
"id": "1000",
"title": "Foundation",
"authors": [
"Authors": [
{
"id": "1",
"first_name": "Isaac",
"middle_name": "",
"last_name": "Asimov"
},
{
"id": "2",
"first_name": "Lewis",
"middle_name": "",
"last_name": "Carroll"
}
]
},
{
"id": "1001",
"title": "Foundation and Empire",
"authors": [
"Authors": [
{
"id": "1",
"first_name": "Isaac",
Expand All @@ -26,7 +32,7 @@
{
"id": "1002",
"title": "Second Foundation",
"authors": [
"Authors": [
{
"id": "1",
"first_name": "Isaac",
Expand All @@ -35,70 +41,10 @@
}
]
},
{
"id": "1003",
"title": "Foundation's Edge",
"authors": [
{
"id": "1",
"first_name": "Isaac",
"middle_name": "",
"last_name": "Asimov"
}
]
},
{
"id": "1004",
"title": "Foundation and Earth",
"authors": [
{
"id": "1",
"first_name": "Isaac",
"middle_name": "",
"last_name": "Asimov"
}
]
},
{
"id": "1005",
"title": "Starship Troopers",
"authors": [
{
"id": "1",
"first_name": "Isaac",
"middle_name": "",
"last_name": "Asimov"
}
]
},
{
"id": "1006",
"title": "Stranger in a Strange Land",
"authors": [
{
"id": "2",
"first_name": "Isaac",
"middle_name": "",
"last_name": "Asimov"
}
]
},
{
"id": "1007",
"title": "Nightfall",
"authors": [
{
"id": "2",
"first_name": "Robert",
"middle_name": "A",
"last_name": "Heinlein"
}
]
},
{
"id": "1008",
"title": "Nightwings",
"authors": [
"Authors": [
{
"id": "1",
"first_name": "Isaac",
Expand All @@ -112,30 +58,5 @@
"last_name": "Silvenberg"
}
]
},
{
"id": "1009",
"title": "Across a Billion Years",
"authors": [
{
"id": "3",
"first_name": "Robert",
"middle_name": "",
"last_name": "Silvenberg"
}
]
},
{
"id": "1010",
"title": "Across a Billion Years",
"authors": [
{
"id": "3",
"first_name": "Robert",
"middle_name": "",
"last_name": "Silvenberg"
}
]
}
]

0 comments on commit 80c2bc6

Please sign in to comment.