docs: recommend insert_rows_json to avoid call to tables.get (#258)

* docs: recommend insert_rows_json to avoid call to tables.get

Since tables.get has a much lower QPS than tabledata.insertAll, we want
to avoid recommending a pattern that requires fetching a table schema.
If developers convert to a dictionary of the correct JSON format, no
table schema is required.

* update comments

Author: tswast

samples/table_insert_rows.py

@@ -16,19 +16,22 @@
 def table_insert_rows(table_id):
 
     # [START bigquery_table_insert_rows]
-
     from google.cloud import bigquery
 
     # Construct a BigQuery client object.
     client = bigquery.Client()
 
-    # TODO(developer): Set table_id to the ID of the model to fetch.
+    # TODO(developer): Set table_id to the ID of table to append to.
     # table_id = "your-project.your_dataset.your_table"
 
-    table = client.get_table(table_id)  # Make an API request.
-    rows_to_insert = [(u"Phred Phlyntstone", 32), (u"Wylma Phlyntstone", 29)]
+    rows_to_insert = [
+        {u"full_name": u"Phred Phlyntstone", u"age": 32},
+        {u"full_name": u"Wylma Phlyntstone", u"age": 29},
+    ]
 
-    errors = client.insert_rows(table, rows_to_insert)  # Make an API request.
+    errors = client.insert_rows_json(table_id, rows_to_insert)  # Make an API request.
     if errors == []:
         print("New rows have been added.")
+    else:
+        print("Encountered errors while inserting rows: {}".format(errors))
     # [END bigquery_table_insert_rows]

samples/table_insert_rows_explicit_none_insert_ids.py

@@ -16,21 +16,24 @@
 def table_insert_rows_explicit_none_insert_ids(table_id):
 
     # [START bigquery_table_insert_rows_explicit_none_insert_ids]
-
     from google.cloud import bigquery
 
     # Construct a BigQuery client object.
     client = bigquery.Client()
 
-    # TODO(developer): Set table_id to the ID of the model to fetch.
+    # TODO(developer): Set table_id to the ID of table to append to.
     # table_id = "your-project.your_dataset.your_table"
 
-    table = client.get_table(table_id)  # Make an API request.
-    rows_to_insert = [(u"Phred Phlyntstone", 32), (u"Wylma Phlyntstone", 29)]
+    rows_to_insert = [
+        {u"full_name": u"Phred Phlyntstone", u"age": 32},
+        {u"full_name": u"Wylma Phlyntstone", u"age": 29},
+    ]
 
-    errors = client.insert_rows(
-        table, rows_to_insert, row_ids=[None] * len(rows_to_insert)
+    errors = client.insert_rows_json(
+        table_id, rows_to_insert, row_ids=[None] * len(rows_to_insert)
     )  # Make an API request.
     if errors == []:
         print("New rows have been added.")
+    else:
+        print("Encountered errors while inserting rows: {}".format(errors))
     # [END bigquery_table_insert_rows_explicit_none_insert_ids]