Update Tables README

sdk/tables/azure-data-tables/README.md

@@ -4,14 +4,15 @@ key/attribute store with a schemaless design. Tables storage gives developers fl
 best parts of Azure cloud.
 
 [Source code][source_code] | [Package (Maven)][package] | [API reference documentation][api_documentation]
-| [Product documentation][azconfig_docs] | [Samples][samples]
+| [REST API documentation][rest_api] | [Product documentation][product_documentation] | [Samples][samples]
 
 ## Getting started
 
 ### Prerequisites
 
-- Java Development Kit (JDK) with version 8 or above
+- [Java Development Kit (JDK)][jdk] with version 8 or above
 - [Azure Subscription][azure_subscription]
+- An existing Azure storage account or Azure Cosmos DB Table API account
 
 ### Include the Package
 
@@ -25,17 +26,159 @@ best parts of Azure cloud.
 ```
 [//]: # ({x-version-update-end})
 
+### Create a Storage Account
+To create a Storage Account you can use the [Azure Portal][storage_account_create_portal] or [Azure CLI][storage_account_create_cli].
+
+```bash
+az storage account create \
+    --resource-group <resource-group-name> \
+    --name <storage-account-name> \
+    --location <location>
+```
+
+Your storage account URL, subsequently identified as `<your-table-account-url>`, would be formatted as follows
+`http(s)://<storage-account-name>.table.core.windows.net`.
+
+### Create a Cosmos DB Table API account
+To create a Cosmos DB Table API account you can use the [Azure Portal][cosmosdb_create_portal] or [Azure CLI][cosmosdb_create_cli].
+
+```bash
+az cosmosdb create \
+    --resource-group <resource-group-name> \
+    --name <cosmosdb-account-name>
+    --capabilities EnableTable
+```
+
+Your Table API account URL, subsequently identified as `<your-table-account-url>`, would be formatted as follows
+`http(s)://<cosmosdb-account-name>.table.cosmosdb.azure.com`.
+
 ## Key concepts
 
+Common uses of the Table service include:
+
+- Storing TBs of structured data capable of serving web scale applications
+- Storing datasets that don't require complex joins, foreign keys, or stored procedures and can be de-normalized for fast access
+- Quickly querying data using a clustered index
+- Accessing data using the OData protocol
+
+Learn more about options for authentication _(including Connection Strings, Shared Key Authentication, and Shared Access Signatures)_ [in our samples][samples].
+
 ## Examples
-Use the client library for Tables to:
-- manages tables
-- edit and access table contents
+
+### Create, List, and Delete Azure tables
+
+First, we need to construct a `TableServiceClient`.
+
+```java
+TableServiceClient tableServiceClient = new TableServiceClientBuilder()
+    .endpoint("<your-table-account-url>")
+    .sasToken("<your-sasToken>")
+    .buildClient();
+```
+
+Next, we can create a new table.
+
+```java
+tableServiceClient.createTable(tableName);
+```
+
+The set of existing Azure tables can be queries using an OData filter.
+
+```java
+ListTablesOptions options = new ListTablesOptions()
+    .setFilter(String.format("TableName eq '%s'", tableName));
+
+for (TableItem tableItem : tableServiceClient.listTables(options)) {
+    System.out.println(tableItem.getName());
+}
+```
+
+Individual tables can be deleted from the service.
+
+```java
+tableServiceClient.deleteTable(tableName);
+```
+
+### Add, Query, and Delete table entities
+
+To interact with table entities, we must first construct a `TableClient`.
+
+```java
+TableClient tableClient = new TableClientBuilder()
+    .endpoint("<your-table-account-url>")
+    .sasToken("<your-sasToken>")
+    .tableName(tableName)
+    .buildClient();
+```
+
+Alternatively, a `TableClient` can be retrieved from an existing `TableServiceClient`.
+
+```java
+TableClient tableClient = tableServiceClient.getTableClient(tableName);
+```
+
+Define a new `TableEntity` with some properties so that we can add it to the table.
+
+```java
+TableEntity entity = new TableEntity(partitionKey, rowKey)
+    .addProperty("Product", "Marker Set")
+    .addProperty("Price", 5.00)
+    .addProperty("Quantity", 21);
+```
+
+Using the `TableClient` we can now add our new entity to the table.
+
+```java
+tableClient.createEntity(entity);
+```
+
+To inspect the set of existing table entities, we can query the table using an OData filter.
+
+```java
+ListEntitiesOptions options = new ListEntitiesOptions()
+    .setFilter(String.format("PartitionKey eq '%s'", partitionKey));
+
+for (TableEntity entity : tableClient.listEntities(options)) {
+    System.out.println(String.format("%s: %.2f", entity.getProperty("Product"), entity.getProperty("Price")));
+}
+```
+
+If we no longer need our new table entity, it can be deleted.
+
+```java
+tableClient.deleteEntity(partitionKey, rowKey);
+```
 
 ## Troubleshooting
 
+When you interact with the Azure table library, errors returned by the service correspond to the same HTTP 
+status codes returned for [REST API][rest_api] requests.
+
+For example, if you try to create a table that already exists, a `409` error is returned, indicating "Conflict".
+
+```java
+TableServiceClient tableServiceClient = new TableServiceClientBuilder()
+    .endpoint("<your-table-account-url>")
+    .sasToken("<your-sasToken>")
+    .buildClient();
+
+// Create the table if it doesn't already exist.
+
+tableServiceClient.createTableIfNotExists(tableName);
+
+// Now attempt to create the same table unconditionally.
+
+try {
+    tableServiceClient.createTable(tableName);
+} catch (TableServiceErrorException e) {
+    System.out.println(e.getResponse().getStatusCode()); // 409
+}
+```
+
 ## Next steps
 
+Get started with our [Table samples][samples].
+
 ## Contributing
 
 This project welcomes contributions and suggestions. Most contributions require you to agree to a [Contributor License Agreement (CLA)][cla] declaring that you have the right to, and actually do, grant us the rights to use your contribution.
@@ -51,9 +194,15 @@ This project has adopted the [Microsoft Open Source Code of Conduct][coc]. For m
 [coc_contact]: mailto:opencode@microsoft.com
 [coc_faq]: https://opensource.microsoft.com/codeofconduct/faq/
 [coc]: https://opensource.microsoft.com/codeofconduct/
+[cosmosdb_create_cli]: https://docs.microsoft.com/en-us/azure/cosmos-db/scripts/cli/table/create
+[cosmosdb_create_portal]: https://docs.microsoft.com/en-us/azure/cosmos-db/create-table-java#create-a-database-account
+[jdk]: https://docs.microsoft.com/java/azure/jdk/
 [package]: https://search.maven.org/artifact/com.azure/azure-data-tables
-[samples_readme]: src/samples/README.md
+[product_documentation]: https://docs.microsoft.com/en-us/azure/cosmos-db/table-storage-overview
+[rest_api]: https://docs.microsoft.com/en-us/rest/api/storageservices/table-service-rest-api
 [samples]: src/samples/java/
 [source_code]: src
+[storage_account_create_cli]: https://docs.microsoft.com/en-us/azure/storage/common/storage-account-create?tabs=azure-cli
+[storage_account_create_portal]: https://docs.microsoft.com/en-us/azure/storage/common/storage-account-create?tabs=azure-portal
 
-![Impressions](https://azure-sdk-impressions.azurewebsites.net/api/impressions/azure-sdk-for-java%2Fsdk%2Ftables%2Fazure-data-tables%2FREADME.png)
+![Impressions](https://azure-sdk-impressions.azurewebsites.net/api/impressions/azure-sdk-for-java%2Fsdk%2Ftables%2Fazure-data-tables%2FREADME.png)