Coverage for /var/srv/projects/api.amasfac.comuna18.com/tmp/venv/lib/python3.9/site-packages/pandas/io/gbq.py: 30%
21 statements
« prev ^ index » next coverage.py v6.4.4, created at 2023-07-17 14:22 -0600
1""" Google BigQuery support """
2from __future__ import annotations
4from typing import (
5 TYPE_CHECKING,
6 Any,
7)
9from pandas.compat._optional import import_optional_dependency
11if TYPE_CHECKING: 11 ↛ 12line 11 didn't jump to line 12, because the condition on line 11 was never true
12 from pandas import DataFrame
15def _try_import():
16 # since pandas is a dependency of pandas-gbq
17 # we need to import on first use
18 msg = (
19 "pandas-gbq is required to load data from Google BigQuery. "
20 "See the docs: https://pandas-gbq.readthedocs.io."
21 )
22 pandas_gbq = import_optional_dependency("pandas_gbq", extra=msg)
23 return pandas_gbq
26def read_gbq(
27 query: str,
28 project_id: str | None = None,
29 index_col: str | None = None,
30 col_order: list[str] | None = None,
31 reauth: bool = False,
32 auth_local_webserver: bool = True,
33 dialect: str | None = None,
34 location: str | None = None,
35 configuration: dict[str, Any] | None = None,
36 credentials=None,
37 use_bqstorage_api: bool | None = None,
38 max_results: int | None = None,
39 progress_bar_type: str | None = None,
40) -> DataFrame:
41 """
42 Load data from Google BigQuery.
44 This function requires the `pandas-gbq package
45 <https://pandas-gbq.readthedocs.io>`__.
47 See the `How to authenticate with Google BigQuery
48 <https://pandas-gbq.readthedocs.io/en/latest/howto/authentication.html>`__
49 guide for authentication instructions.
51 Parameters
52 ----------
53 query : str
54 SQL-Like Query to return data values.
55 project_id : str, optional
56 Google BigQuery Account project ID. Optional when available from
57 the environment.
58 index_col : str, optional
59 Name of result column to use for index in results DataFrame.
60 col_order : list(str), optional
61 List of BigQuery column names in the desired order for results
62 DataFrame.
63 reauth : bool, default False
64 Force Google BigQuery to re-authenticate the user. This is useful
65 if multiple accounts are used.
66 auth_local_webserver : bool, default True
67 Use the `local webserver flow`_ instead of the `console flow`_
68 when getting user credentials.
70 .. _local webserver flow:
71 https://google-auth-oauthlib.readthedocs.io/en/latest/reference/google_auth_oauthlib.flow.html#google_auth_oauthlib.flow.InstalledAppFlow.run_local_server
72 .. _console flow:
73 https://google-auth-oauthlib.readthedocs.io/en/latest/reference/google_auth_oauthlib.flow.html#google_auth_oauthlib.flow.InstalledAppFlow.run_console
75 *New in version 0.2.0 of pandas-gbq*.
77 .. versionchanged:: 1.5.0
78 Default value is changed to ``True``. Google has deprecated the
79 ``auth_local_webserver = False`` `"out of band" (copy-paste)
80 flow
81 <https://developers.googleblog.com/2022/02/making-oauth-flows-safer.html?m=1#disallowed-oob>`_.
82 dialect : str, default 'legacy'
83 Note: The default value is changing to 'standard' in a future version.
85 SQL syntax dialect to use. Value can be one of:
87 ``'legacy'``
88 Use BigQuery's legacy SQL dialect. For more information see
89 `BigQuery Legacy SQL Reference
90 <https://cloud.google.com/bigquery/docs/reference/legacy-sql>`__.
91 ``'standard'``
92 Use BigQuery's standard SQL, which is
93 compliant with the SQL 2011 standard. For more information
94 see `BigQuery Standard SQL Reference
95 <https://cloud.google.com/bigquery/docs/reference/standard-sql/>`__.
96 location : str, optional
97 Location where the query job should run. See the `BigQuery locations
98 documentation
99 <https://cloud.google.com/bigquery/docs/dataset-locations>`__ for a
100 list of available locations. The location must match that of any
101 datasets used in the query.
103 *New in version 0.5.0 of pandas-gbq*.
104 configuration : dict, optional
105 Query config parameters for job processing.
106 For example:
108 configuration = {'query': {'useQueryCache': False}}
110 For more information see `BigQuery REST API Reference
111 <https://cloud.google.com/bigquery/docs/reference/rest/v2/jobs#configuration.query>`__.
112 credentials : google.auth.credentials.Credentials, optional
113 Credentials for accessing Google APIs. Use this parameter to override
114 default credentials, such as to use Compute Engine
115 :class:`google.auth.compute_engine.Credentials` or Service Account
116 :class:`google.oauth2.service_account.Credentials` directly.
118 *New in version 0.8.0 of pandas-gbq*.
119 use_bqstorage_api : bool, default False
120 Use the `BigQuery Storage API
121 <https://cloud.google.com/bigquery/docs/reference/storage/>`__ to
122 download query results quickly, but at an increased cost. To use this
123 API, first `enable it in the Cloud Console
124 <https://console.cloud.google.com/apis/library/bigquerystorage.googleapis.com>`__.
125 You must also have the `bigquery.readsessions.create
126 <https://cloud.google.com/bigquery/docs/access-control#roles>`__
127 permission on the project you are billing queries to.
129 This feature requires version 0.10.0 or later of the ``pandas-gbq``
130 package. It also requires the ``google-cloud-bigquery-storage`` and
131 ``fastavro`` packages.
133 .. versionadded:: 0.25.0
134 max_results : int, optional
135 If set, limit the maximum number of rows to fetch from the query
136 results.
138 *New in version 0.12.0 of pandas-gbq*.
140 .. versionadded:: 1.1.0
141 progress_bar_type : Optional, str
142 If set, use the `tqdm <https://tqdm.github.io/>`__ library to
143 display a progress bar while the data downloads. Install the
144 ``tqdm`` package to use this feature.
146 Possible values of ``progress_bar_type`` include:
148 ``None``
149 No progress bar.
150 ``'tqdm'``
151 Use the :func:`tqdm.tqdm` function to print a progress bar
152 to :data:`sys.stderr`.
153 ``'tqdm_notebook'``
154 Use the :func:`tqdm.tqdm_notebook` function to display a
155 progress bar as a Jupyter notebook widget.
156 ``'tqdm_gui'``
157 Use the :func:`tqdm.tqdm_gui` function to display a
158 progress bar as a graphical dialog box.
160 Note that this feature requires version 0.12.0 or later of the
161 ``pandas-gbq`` package. And it requires the ``tqdm`` package. Slightly
162 different than ``pandas-gbq``, here the default is ``None``.
164 .. versionadded:: 1.0.0
166 Returns
167 -------
168 df: DataFrame
169 DataFrame representing results of query.
171 See Also
172 --------
173 pandas_gbq.read_gbq : This function in the pandas-gbq library.
174 DataFrame.to_gbq : Write a DataFrame to Google BigQuery.
175 """
176 pandas_gbq = _try_import()
178 kwargs: dict[str, str | bool | int | None] = {}
180 # START: new kwargs. Don't populate unless explicitly set.
181 if use_bqstorage_api is not None:
182 kwargs["use_bqstorage_api"] = use_bqstorage_api
183 if max_results is not None:
184 kwargs["max_results"] = max_results
186 kwargs["progress_bar_type"] = progress_bar_type
187 # END: new kwargs
189 return pandas_gbq.read_gbq(
190 query,
191 project_id=project_id,
192 index_col=index_col,
193 col_order=col_order,
194 reauth=reauth,
195 auth_local_webserver=auth_local_webserver,
196 dialect=dialect,
197 location=location,
198 configuration=configuration,
199 credentials=credentials,
200 **kwargs,
201 )
204def to_gbq(
205 dataframe: DataFrame,
206 destination_table: str,
207 project_id: str | None = None,
208 chunksize: int | None = None,
209 reauth: bool = False,
210 if_exists: str = "fail",
211 auth_local_webserver: bool = True,
212 table_schema: list[dict[str, str]] | None = None,
213 location: str | None = None,
214 progress_bar: bool = True,
215 credentials=None,
216) -> None:
217 pandas_gbq = _try_import()
218 pandas_gbq.to_gbq(
219 dataframe,
220 destination_table,
221 project_id=project_id,
222 chunksize=chunksize,
223 reauth=reauth,
224 if_exists=if_exists,
225 auth_local_webserver=auth_local_webserver,
226 table_schema=table_schema,
227 location=location,
228 progress_bar=progress_bar,
229 credentials=credentials,
230 )