BigQuery: Adds samples for to_dataframe() (googleapis#5051)

alixhami · web-flow · commit 38ba166864c7 · 2018-03-16T14:56:48.000-07:00
diff --git a/docs/bigquery/snippets.py b/docs/bigquery/snippets.py
@@ -27,6 +27,10 @@
 
 import pytest
 import six
+try:
+    import pandas
+except ImportError:
+    pandas = None
 
 from google.cloud import bigquery
 
@@ -1545,5 +1549,39 @@ def do_something_with(_):
     # [END client_list_jobs]
 
 
+@pytest.mark.skipif(pandas is None, reason='Requires `pandas`')
+def test_query_results_as_dataframe(client):
+    # [START bigquery_query_results_dataframe]
+    # client = bigquery.Client()
+    sql = """
+        SELECT name, SUM(number) as count
+        FROM `bigquery-public-data.usa_names.usa_1910_current`
+        GROUP BY name
+        ORDER BY count DESC
+        LIMIT 10
+    """
+
+    df = client.query(sql).to_dataframe()
+    # [END bigquery_query_results_dataframe]
+    assert isinstance(df, pandas.DataFrame)
+    assert len(list(df)) == 2  # verify the number of columns
+    assert len(df) == 10       # verify the number of rows
+
+
+@pytest.mark.skipif(pandas is None, reason='Requires `pandas`')
+def test_list_rows_as_dataframe(client):
+    # [START bigquery_list_rows_dataframe]
+    # client = bigquery.Client()
+    dataset_ref = client.dataset('samples', project='bigquery-public-data')
+    table_ref = dataset_ref.table('shakespeare')
+    table = client.get_table(table_ref)
+
+    df = client.list_rows(table).to_dataframe()
+    # [END bigquery_list_rows_dataframe]
+    assert isinstance(df, pandas.DataFrame)
+    assert len(list(df)) == 2  # verify the number of columns
+    assert len(df) == 10       # verify the number of rows
+
+
 if __name__ == '__main__':
     pytest.main()
diff --git a/docs/bigquery/usage.rst b/docs/bigquery/usage.rst
@@ -364,3 +364,36 @@ Jobs describe actions performed on data in BigQuery tables:
 .. literalinclude:: snippets.py
    :start-after: [START client_list_jobs]
    :end-before: [END client_list_jobs]
+
+
+Using BigQuery with Pandas
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+As of version 0.29.0, you can use the
+:func:`~google.cloud.bigquery.table.RowIterator.to_dataframe` function to
+retrieve query results or table rows as a :class:`pandas.DataFrame`.
+
+First, ensure that the :mod:`pandas` library is installed by running:
+
+.. code-block:: bash
+
+   pip install --upgrade pandas
+
+Alternatively, you can install the BigQuery python client library with
+:mod:`pandas` by running:
+
+.. code-block:: bash
+
+   pip install --upgrade google-cloud-bigquery[pandas]
+
+To retrieve query results as a :class:`pandas.DataFrame`:
+
+.. literalinclude:: snippets.py
+   :start-after: [START bigquery_query_results_dataframe]
+   :end-before: [END bigquery_query_results_dataframe]
+
+To retrieve table rows as a :class:`pandas.DataFrame`:
+
+.. literalinclude:: snippets.py
+   :start-after: [START bigquery_list_rows_dataframe]
+   :end-before: [END bigquery_list_rows_dataframe]
