Repository: googleapis/python-bigquery

Issue:
Document how to construct external tables
 **Is your feature request related to a problem? Please describe.**

Currently, the document on creating a table is clear on how to initialize a Table object with a specific fields schema. For example, here is a code snippet from the docs:

![image](https://user-images.githubusercontent.com/2574498/125806269-c756b636-22de-4353-b0f4-ebdfe9b7214a.png)

However, a challenge I faced with these docs is knowing how to create a Table with, e.g., an ExternalConfig set.

Based on the source for Table / unit tests, is the correct approach using a property setter?:

```python
from google.cloud import bigquery
client bigquery.Client()

table = bigquery.Table(...)

# use property setter
table.external_data_configuration = bigquery.ExternalConfig(...)

# edit: it looks like ExternalConfig also needs to use setters, so might include, e.g..
external_config = bigquery.ExternalConfig("NEWLINE_DELIMITED_JSON")
external_config.source_uris = [...]
```


 **Describe the solution you'd like**

Can we add an example to the docs so that readers learn these two pieces?:

* Table attributes like schema can be set on `__init__` (or via setters)
* Other Table attributes must be set using setters

It seems like two places users may look for this info is in the Table API doc, and in the [usage/tables - creating a table](https://googleapis.dev/python/bigquery/latest/usage/tables.html#creating-a-table) doc. Also, apologies if it's already somewhere in the docs and I missed it 😅.

 **Describe alternatives you've considered**

Since Table can be constructed using `.from_api_repr()`, I wondered if this is a more common approach for construction? In that case it seems like having a nudge in the docs on using this path for e.g. constructing an external table would be super helpful!


Discussion:
It could also be good to include such a sample here as well: https://cloud.google.com/bigquery/external-table-definition
There is a Python sample here: https://cloud.google.com/bigquery/external-data-cloud-storage#python
Looks like we already had such a code sample here: https://github.com/googleapis/python-bigquery/blob/35627d145a41d57768f19d4392ef235928e00f72/docs/snippets.py#L935

It appears on cloud.google.com here: https://cloud.google.com/bigquery/docs/external-data-cloud-storage#create_an_external_table

Admittedly, that was a bit difficult for me to find, but it's there. It does need an update, though.

The Python code sample on https://cloud.google.com/bigquery/docs/external-table-definition is a bit misleading, so I propose we remove that one.
1. Move https://github.com/googleapis/python-bigquery/blob/main/samples/create_table_external_data_configuration.py to samples/snippets (and its corresponding test)

2. Update the region tag. It should be bigquery_query_external_gcs_perm

3. Update the docs here: https://cloud.google.com/bigquery/docs/external-data-cloud-storage
4. Delete the old sample from snippets.py https://github.com/googleapis/python-bigquery/blob/35627d145a41d57768f19d4392ef235928e00f72/docs/snippets.py#L935
PR above addresses (1) and (2) steps in Tim's comment. *Edit* will reopen PR, there's a few more changes I want to make. 
There are no Python samples in https://cloud.google.com/bigquery/docs/external-table-definition anymore (removed in internal change 506395040). Submitted a new PR to tackle (1) and (2) above. 
Sent cl/565816568 to update the sample location as per (3) above. Pending. 

Resolving patch:
diff --git a/docs/snippets.py b/docs/snippets.py
--- a/docs/snippets.py
+++ b/docs/snippets.py
@@ -617,48 +617,6 @@ def test_client_query_total_rows(client, capsys):
     assert "Got 100 rows." in out
 
 
-def test_query_external_gcs_permanent_table(client, to_delete):
-    dataset_id = "query_external_gcs_{}".format(_millis())
-    project = client.project
-    dataset_ref = bigquery.DatasetReference(project, dataset_id)
-    dataset = bigquery.Dataset(dataset_ref)
-    client.create_dataset(dataset)
-    to_delete.append(dataset)
-
-    # [START bigquery_query_external_gcs_perm]
-    # from google.cloud import bigquery
-    # client = bigquery.Client()
-    # dataset_id = 'my_dataset'
-
-    # Configure the external data source
-    dataset_ref = bigquery.DatasetReference(project, dataset_id)
-    table_id = "us_states"
-    schema = [
-        bigquery.SchemaField("name", "STRING"),
-        bigquery.SchemaField("post_abbr", "STRING"),
-    ]
-    table = bigquery.Table(dataset_ref.table(table_id), schema=schema)
-    external_config = bigquery.ExternalConfig("CSV")
-    external_config.source_uris = [
-        "gs://cloud-samples-data/bigquery/us-states/us-states.csv"
-    ]
-    external_config.options.skip_leading_rows = 1  # optionally skip header row
-    table.external_data_configuration = external_config
-
-    # Create a permanent table linked to the GCS file
-    table = client.create_table(table)  # API request
-
-    # Example query to find states starting with 'W'
-    sql = 'SELECT * FROM `{}.{}` WHERE name LIKE "W%"'.format(dataset_id, table_id)
-
-    query_job = client.query(sql)  # API request
-
-    w_states = list(query_job)  # Waits for query to finish
-    print("There are {} states with names starting with W.".format(len(w_states)))
-    # [END bigquery_query_external_gcs_perm]
-    assert len(w_states) == 4
-
-
 def test_ddl_create_view(client, to_delete, capsys):
     """Create a view via a DDL query."""
     project = client.project


Test patch: