diff --git a/bigquery/docs/usage/queries.rst b/bigquery/docs/usage/queries.rst index 1f0720e47f1a..5c9dbe18fa63 100644 --- a/bigquery/docs/usage/queries.rst +++ b/bigquery/docs/usage/queries.rst @@ -48,3 +48,16 @@ See BigQuery documentation for more information on :dedent: 4 :start-after: [START bigquery_query_params_named] :end-before: [END bigquery_query_params_named] + +Run a script +^^^^^^^^^^^^ + +See BigQuery documentation for more information on `scripting in BigQuery +standard SQL +`_. + +.. literalinclude:: ../samples/query_script.py + :language: python + :dedent: 4 + :start-after: [START bigquery_query_script] + :end-before: [END bigquery_query_script] diff --git a/bigquery/samples/query_script.py b/bigquery/samples/query_script.py new file mode 100644 index 000000000000..453b7c6f9435 --- /dev/null +++ b/bigquery/samples/query_script.py @@ -0,0 +1,69 @@ +# Copyright 2019 Google LLC +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# https://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + + +def query_script(client): + # [START bigquery_query_script] + # TODO(developer): Import the client library. + # from google.cloud import bigquery + + # TODO(developer): Construct a BigQuery client object. + # client = bigquery.Client() + + # Run a SQL script. + sql_script = """ + -- Declare a variable to hold names as an array. + DECLARE top_names ARRAY; + + -- Build an array of the top 100 names from the year 2017. + SET top_names = ( + SELECT ARRAY_AGG(name ORDER BY number DESC LIMIT 100) + FROM `bigquery-public-data.usa_names.usa_1910_2013` + WHERE year = 2000 + ); + + -- Which names appear as words in Shakespeare's plays? + SELECT + name AS shakespeare_name + FROM UNNEST(top_names) AS name + WHERE name IN ( + SELECT word + FROM `bigquery-public-data.samples.shakespeare` + ); + """ + parent_job = client.query(sql_script) + + # Wait for the whole script to finish. + rows_iterable = parent_job.result() + print("Script created {} child jobs.".format(parent_job.num_child_jobs)) + + # Fetch result rows for the final sub-job in the script. + rows = list(rows_iterable) + print( + "{} of the top 100 names from year 2000 also appear in Shakespeare's works.".format( + len(rows) + ) + ) + + # Fetch jobs created by the SQL script. + child_jobs_iterable = client.list_jobs(parent_job=parent_job) + for child_job in child_jobs_iterable: + child_rows = list(child_job.result()) + print( + "Child job with ID {} produced {} row(s).".format( + child_job.job_id, len(child_rows) + ) + ) + + # [END bigquery_query_script] diff --git a/bigquery/samples/tests/test_query_script.py b/bigquery/samples/tests/test_query_script.py new file mode 100644 index 000000000000..70bb9df76fd4 --- /dev/null +++ b/bigquery/samples/tests/test_query_script.py @@ -0,0 +1,28 @@ +# Copyright 2019 Google LLC +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# https://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +from .. import query_script + + +def test_query_script(capsys, client): + + query_script.query_script(client) + out, _ = capsys.readouterr() + assert "Script created 2 child jobs." in out + assert ( + "53 of the top 100 names from year 2000 also appear in Shakespeare's works." + in out + ) + assert "produced 53 row(s)" in out + assert "produced 1 row(s)" in out diff --git a/bigquery/tests/system.py b/bigquery/tests/system.py index 09fa7f456214..4816962a70d6 100644 --- a/bigquery/tests/system.py +++ b/bigquery/tests/system.py @@ -431,37 +431,6 @@ def test_list_tables(self): ) self.assertGreater(len(list(iterator)), 0) - def test_listing_scripting_jobs(self): - # Run a SQL script. - sql_script = """ - -- Declare a variable to hold names as an array. - DECLARE top_names ARRAY; - - -- Build an array of the top 100 names from the year 2017. - SET top_names = ( - SELECT ARRAY_AGG(name ORDER BY number DESC LIMIT 100) - FROM `bigquery-public-data.usa_names.usa_1910_current` - WHERE year = 2017 - ); - - -- Which names appear as words in Shakespeare's plays? - SELECT - name AS shakespeare_name - FROM UNNEST(top_names) AS name - WHERE name IN ( - SELECT word - FROM `bigquery-public-data.samples.shakespeare` - ); - """ - parent_job = Config.CLIENT.query(sql_script, project=Config.CLIENT.project) - parent_job.result() - - # Fetch jobs created by the SQL script. - child_jobs = list(Config.CLIENT.list_jobs(parent_job=parent_job)) - - assert parent_job.num_child_jobs > 0 - assert len(child_jobs) == parent_job.num_child_jobs - def test_update_table(self): dataset = self.temp_dataset(_make_dataset_id("update_table"))