Repository: googleapis/python-bigquery

Issue:
Python `bigquery_create_job` sample is inconsistent with other code samples
The https://github.com/googleapis/python-bigquery/blob/main/samples/create_job.py code sample appears here: https://cloud.google.com/bigquery/docs/running-jobs#running_jobs_using_client_libraries

This sample requires two improvements:

* [ ] That section is about any kind of job, not just queries. As such, it should use the [create_job](https://googleapis.dev/python/bigquery/latest/generated/google.cloud.bigquery.client.Client.html#google.cloud.bigquery.client.Client.create_job) method instead of the more specific `query` method. There should be comments that it is recommended to use the corresponding method for query/copy/load/extract.
* [ ] Remove `job_id_prefix` logic, as labels cover similar functionality and are recommended over custom job IDs.
* [ ] Move the sample to the `samples/snippets` directory. Needs to be done in 2 separate PRs so that the existing samples in the docs don't 404.


Discussion:
Candidate issue for @loferris to take in Q1? 

Resolving patch:
diff --git a/samples/create_job.py b/samples/create_job.py
--- a/samples/create_job.py
+++ b/samples/create_job.py
@@ -13,12 +13,13 @@
 # limitations under the License.
 
 import typing
+from typing import Union
 
 if typing.TYPE_CHECKING:
-    from google.cloud import bigquery
+    from google.cloud.bigquery import LoadJob, CopyJob, ExtractJob, QueryJob
 
 
-def create_job() -> "bigquery.QueryJob":
+def create_job() -> "Union[LoadJob, CopyJob, ExtractJob, QueryJob]":
 
     # [START bigquery_create_job]
     from google.cloud import bigquery
@@ -26,20 +27,41 @@ def create_job() -> "bigquery.QueryJob":
     # Construct a BigQuery client object.
     client = bigquery.Client()
 
-    query_job = client.query(
-        "SELECT country_name from `bigquery-public-data.utility_us.country_code_iso`",
-        # Explicitly force job execution to be routed to a specific processing
-        # location.
-        location="US",
-        # Specify a job configuration to set optional job resource properties.
-        job_config=bigquery.QueryJobConfig(
-            labels={"example-label": "example-value"}, maximum_bytes_billed=1000000
-        ),
-        # The client libraries automatically generate a job ID. Override the
-        # generated ID with either the job_id_prefix or job_id parameters.
-        job_id_prefix="code_sample_",
+    query_job = client.create_job(
+        # Specify a job configuration, providing a query
+        # and/or optional job resource properties, as needed.
+        # The job instance can be a LoadJob, CopyJob, ExtractJob, QueryJob
+        # Here, we demonstrate a "query" job.
+        # References:
+        #     https://googleapis.dev/python/bigquery/latest/generated/google.cloud.bigquery.client.Client.html#google.cloud.bigquery.client.Client.create_job
+        #     https://cloud.google.com/bigquery/docs/reference/rest/v2/Job
+        #
+        # Example use cases for .create_job() include:
+        #    * to retry failed jobs
+        #    * to generate jobs with an experimental API property that hasn't
+        #      been added to one of the manually written job configuration
+        #      classes yet
+        #
+        # NOTE: unless it is necessary to create a job in this way, the
+        # preferred approach is to use one of the dedicated API calls:
+        #   client.query()
+        #   client.extract_table()
+        #   client.copy_table()
+        #   client.load_table_file(), client.load_table_from_dataframe(), etc
+        job_config={
+            "query": {
+                "query": """
+                         SELECT country_name
+                         FROM `bigquery-public-data.utility_us.country_code_iso`
+                         LIMIT 5
+                         """,
+            },
+            "labels": {"example-label": "example-value"},
+            "maximum_bytes_billed": 10000000,
+        }
     )  # Make an API request.
 
-    print("Started job: {}".format(query_job.job_id))
+    print(f"Started job: {query_job.job_id}")
     # [END bigquery_create_job]
+
     return query_job


Test patch: