Merge pull request #98655 from linda33wj/cosmos-db-tips

Update Cosmos DB connector content

Author: PRMerger6

articles/data-factory/connector-azure-cosmos-db-mongodb-api.md

@@ -169,6 +169,9 @@ The following properties are supported in the Copy Activity **sink** section:
 | writeBatchSize | The **writeBatchSize** property controls the size of documents to write in each batch. You can try increasing the value for **writeBatchSize** to improve performance and decreasing the value if your document size being large. |No<br />(the default is **10,000**) |
 | writeBatchTimeout | The wait time for the batch insert operation to finish before it times out. The allowed value is timespan. | No<br/>(the default is **00:30:00** - 30 minutes) |
 
+>[!TIP]
+>To import JSON documents as-is, refer to [Import or export JSON documents](#import-and-export-json-documents) section; to copy from tabular-shaped data, refer to [Schema mapping](#schema-mapping).
+
 **Example**
 
 ```json
@@ -201,18 +204,18 @@ The following properties are supported in the Copy Activity **sink** section:
 ]
 ```
 
->[!TIP]
->To import JSON documents as-is, refer to [Import or export JSON documents](#import-or-export-json-documents) section; to copy from tabular-shaped data, refer to [Schema mapping](#schema-mapping).
-
-## Import or export JSON documents
+## Import and export JSON documents
 
 You can use this Azure Cosmos DB connector to easily:
 
-* Import JSON documents from various sources to Azure Cosmos DB, including from Azure Blob storage, Azure Data Lake Store, and other file-based stores that Azure Data Factory supports.
-* Export JSON documents from an Azure Cosmos DB collection to various file-based stores.
 * Copy documents between two Azure Cosmos DB collections as-is.
+* Import JSON documents from various sources to Azure Cosmos DB, including from MongoDB, Azure Blob storage, Azure Data Lake Store, and other file-based stores that Azure Data Factory supports.
+* Export JSON documents from an Azure Cosmos DB collection to various file-based stores.
+
+To achieve schema-agnostic copy:
 
-To achieve such schema-agnostic copy, skip the "structure" (also called *schema*) section in dataset and schema mapping in copy activity.
+* When you use the Copy Data tool, select the **Export as-is to JSON files or Cosmos DB collection** option.
+* When you use activity authoring, choose JSON format with the corresponding file store for source or sink.
 
 ## Schema mapping
 

articles/data-factory/connector-azure-cosmos-db.md

@@ -10,7 +10,7 @@ ms.service: multiple
 ms.workload: data-services
 ms.topic: conceptual
 ms.custom: seo-lt-2019
-ms.date: 11/13/2019
+ms.date: 12/11/2019
 ---
 
 # Copy and transform data in Azure Cosmos DB (SQL API) by using Azure Data Factory
@@ -36,7 +36,7 @@ For Copy activity, this Azure Cosmos DB (SQL API) connector supports:
 
 - Copy data from and to the Azure Cosmos DB [SQL API](https://docs.microsoft.com/azure/cosmos-db/documentdb-introduction).
 - Write to Azure Cosmos DB as **insert** or **upsert**.
-- Import and export JSON documents as-is, or copy data from or to a tabular dataset. Examples include a SQL database and a CSV file. To copy documents as-is to or from JSON files or to or from another Azure Cosmos DB collection, see Import or export JSON documents.
+- Import and export JSON documents as-is, or copy data from or to a tabular dataset. Examples include a SQL database and a CSV file. To copy documents as-is to or from JSON files or to or from another Azure Cosmos DB collection, see [Import and export JSON documents](#import-and-export-json-documents).
 
 Data Factory integrates with the [Azure Cosmos DB bulk executor library](https://github.com/Azure/azure-cosmosdb-bulkexecutor-dotnet-getting-started) to provide the best performance when you write to Azure Cosmos DB.
 
@@ -141,19 +141,9 @@ If you use "DocumentDbCollection" type dataset, it is still supported as-is for
 }
 ```
 
-### Schema by Data Factory
-
-For schema-free data stores like Azure Cosmos DB, Copy Activity infers the schema in one of the ways described in the following list. Unless you want to [import or export JSON documents as-is](#import-or-export-json-documents), the best practice is to specify the structure of data in the **structure** section.
-
-Data Factory honors the mapping you specified on the activity. If a row doesn't contain a value for a column, a null value is provided for the column value.
-
-If you don't specify a mapping, the Data Factory service infers the schema by using the first row in the data. If the first row doesn't contain the full schema, some columns will be missing in the result of the activity operation.
-
 ## Copy Activity properties
 
-This section provides a list of properties that the Azure Cosmos DB (SQL API) source and sink support.
-
-For a full list of sections and properties that are available for defining activities, see [Pipelines](concepts-pipelines-activities.md).
+This section provides a list of properties that the Azure Cosmos DB (SQL API) source and sink support. For a full list of sections and properties that are available for defining activities, see [Pipelines](concepts-pipelines-activities.md).
 
 ### Azure Cosmos DB (SQL API) as source
 
@@ -205,6 +195,8 @@ If you use "DocumentDbCollectionSource" type source, it is still supported as-is
 ]
 ```
 
+When copy data from Cosmos DB, unless you want to [export JSON documents as-is](#import-and-export-json-documents), the best practice is to specify the mapping in copy activity. Data Factory honors the mapping you specified on the activity - if a row doesn't contain a value for a column, a null value is provided for the column value. If you don't specify a mapping, Data Factory infers the schema by using the first row in the data. If the first row doesn't contain the full schema, some columns will be missing in the result of the activity operation.
+
 ### Azure Cosmos DB (SQL API) as sink
 
 To copy data to Azure Cosmos DB (SQL API), set the **sink** type in Copy Activity to **DocumentDbCollectionSink**. 
@@ -218,6 +210,9 @@ The following properties are supported in the Copy Activity **source** section:
 | writeBatchSize | Data Factory uses the [Azure Cosmos DB bulk executor library](https://github.com/Azure/azure-cosmosdb-bulkexecutor-dotnet-getting-started) to write data to Azure Cosmos DB. The **writeBatchSize** property controls the size of documents that ADF provide to the library. You can try increasing the value for **writeBatchSize** to improve performance and decreasing the value if your document size being large - see below tips. |No<br />(the default is **10,000**) |
 | disableMetricsCollection | Data Factory collects metrics such as Cosmos DB RUs for copy performance optimization and recommendations. If you are concerned with this behavior, specify `true` to turn it off. | No (default is `false`) |
 
+>[!TIP]
+>To import JSON documents as-is, refer to [Import or export JSON documents](#import-and-export-json-documents) section; to copy from tabular-shaped data, refer to [Migrate from relational database to Cosmos DB](#migrate-from-relational-database-to-cosmos-db).
+
 >[!TIP]
 >Cosmos DB limits single request's size to 2MB. The formula is Request Size = Single Document Size * Write Batch Size. If you hit error saying **"Request size is too large."**, **reduce the `writeBatchSize` value** in copy sink configuration.
 
@@ -255,6 +250,10 @@ If you use "DocumentDbCollectionSink" type source, it is still supported as-is f
 ]
 ```
 
+### Schema mapping
+
+To copy data from Azure Cosmos DB to tabular sink or reversed, refer to [schema mapping](copy-activity-schema-and-type-mapping.md#schema-mapping).
+
 ## Mapping data flow properties
 
 Learn details from [source transformation](data-flow-source.md) and [sink transformation](data-flow-sink.md) in mapping data flow.
@@ -263,19 +262,23 @@ Learn details from [source transformation](data-flow-source.md) and [sink transf
 
 To learn details about the properties, check [Lookup activity](control-flow-lookup-activity.md).
 
-## Import or export JSON documents
+## Import and export JSON documents
 
 You can use this Azure Cosmos DB (SQL API) connector to easily:
 
+* Copy documents between two Azure Cosmos DB collections as-is.
 * Import JSON documents from various sources to Azure Cosmos DB, including from Azure Blob storage, Azure Data Lake Store, and other file-based stores that Azure Data Factory supports.
 * Export JSON documents from an Azure Cosmos DB collection to various file-based stores.
-* Copy documents between two Azure Cosmos DB collections as-is.
 
 To achieve schema-agnostic copy:
 
 * When you use the Copy Data tool, select the **Export as-is to JSON files or Cosmos DB collection** option.
 * When you use activity authoring, choose JSON format with the corresponding file store for source or sink.
 
+## Migrate from relational database to Cosmos DB
+
+When migrating from a relational database e.g. SQL Server to Azure Cosmos DB, copy activity can easily map tabular data from source to flatten JSON documents in Cosmos DB. In some cases, you may want to redesign the data model to optimize it for the NoSQL use-cases according to [Data modelling in Azure Cosmos DB](../cosmos-db/modeling-data.md), for example, to denormalize the data by embedding all of the related sub-items within one JSON document. For such case, refer to [this blog post](https://medium.com/@ArsenVlad/denormalizing-via-embedding-when-copying-data-from-sql-to-cosmos-db-649a649ae0fb) with a walkthrough on how to achieve it using Azure Data Factory copy activity.
+
 ## Next steps
 
 For a list of data stores that Copy Activity supports as sources and sinks in Azure Data Factory, see [supported data stores](copy-activity-overview.md##supported-data-stores-and-formats).