Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings
This repository was archived by the owner on May 7, 2026. It is now read-only.

Commit 3c21993

Browse filesBrowse files
google-labs-jules[bot]tswast
google-labs-jules[bot]
and
tswast
authored
docs: Add code examples to configuration docstrings (#2352)
Added code examples to the docstrings of global configuration properties to demonstrate how to set them using `bigframes.pandas.options`. This covers BigQuery options, compute options, sampling options, experiment options, and display options. --- *PR created automatically by Jules for task [15986639753712030034](https://jules.google.com/task/15986639753712030034) started by @tswast* --------- Co-authored-by: google-labs-jules[bot] <161369871+google-labs-jules[bot]@users.noreply.github.com> Co-authored-by: Tim Sweña (Swast) <swast@google.com> Co-authored-by: tswast <247555+tswast@users.noreply.github.com>
1 parent 5c91fb6 commit 3c21993
Copy full SHA for 3c21993

5 files changed

+193-16Lines changed: 193 additions & 16 deletions

File tree

Expand file treeCollapse file tree
Open diff view settings
Filter options
Expand file treeCollapse file tree
Open diff view settings
Collapse file

‎bigframes/_config/bigquery_options.py‎

Copy file name to clipboardExpand all lines: bigframes/_config/bigquery_options.py
+56-1Lines changed: 56 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -127,6 +127,11 @@ def application_name(self) -> Optional[str]:
127127
The recommended format is ``"application-name/major.minor.patch_version"``
128128
or ``"(gpn:PartnerName;)"`` for official Google partners.
129129
130+
**Examples:**
131+
132+
>>> import bigframes.pandas as bpd
133+
>>> bpd.options.bigquery.application_name = "my-app/1.0.0" # doctest: +SKIP
134+
130135
Returns:
131136
None or str:
132137
Application name as a string if exists; otherwise None.
@@ -145,6 +150,13 @@ def application_name(self, value: Optional[str]):
145150
def credentials(self) -> Optional[google.auth.credentials.Credentials]:
146151
"""The OAuth2 credentials to use for this client.
147152
153+
**Examples:**
154+
155+
>>> import bigframes.pandas as bpd
156+
>>> import google.auth
157+
>>> credentials, project = google.auth.default() # doctest: +SKIP
158+
>>> bpd.options.bigquery.credentials = credentials # doctest: +SKIP
159+
148160
Returns:
149161
None or google.auth.credentials.Credentials:
150162
google.auth.credentials.Credentials if exists; otherwise None.
@@ -163,6 +175,11 @@ def location(self) -> Optional[str]:
163175
164176
For more information, see https://cloud.google.com/bigquery/docs/locations BigQuery locations.
165177
178+
**Examples:**
179+
180+
>>> import bigframes.pandas as bpd
181+
>>> bpd.options.bigquery.location = "US" # doctest: +SKIP
182+
166183
Returns:
167184
None or str:
168185
Default location as a string; otherwise None.
@@ -179,6 +196,11 @@ def location(self, value: Optional[str]):
179196
def project(self) -> Optional[str]:
180197
"""Google Cloud project ID to use for billing and as the default project.
181198
199+
**Examples:**
200+
201+
>>> import bigframes.pandas as bpd
202+
>>> bpd.options.bigquery.project = "my-project" # doctest: +SKIP
203+
182204
Returns:
183205
None or str:
184206
Google Cloud project ID as a string; otherwise None.
@@ -206,6 +228,11 @@ def bq_connection(self) -> Optional[str]:
206228
If this option isn't provided, or project or location aren't provided,
207229
session will use its default project/location/connection_id as default connection.
208230
231+
**Examples:**
232+
233+
>>> import bigframes.pandas as bpd
234+
>>> bpd.options.bigquery.bq_connection = "my-project.us.my-connection" # doctest: +SKIP
235+
209236
Returns:
210237
None or str:
211238
Name of the BigQuery connection as a string; otherwise None.
@@ -228,6 +255,11 @@ def skip_bq_connection_check(self) -> bool:
228255
necessary permissions set up to support BigQuery DataFrames operations,
229256
then a runtime error will be reported.
230257
258+
**Examples:**
259+
260+
>>> import bigframes.pandas as bpd
261+
>>> bpd.options.bigquery.skip_bq_connection_check = True # doctest: +SKIP
262+
231263
Returns:
232264
bool:
233265
A boolean value, where True indicates a BigQuery connection is
@@ -300,6 +332,12 @@ def use_regional_endpoints(self) -> bool:
300332
does not promise any guarantee on the request remaining within the
301333
location during transit.
302334
335+
**Examples:**
336+
337+
>>> import bigframes.pandas as bpd
338+
>>> bpd.options.bigquery.location = "europe-west3" # doctest: +SKIP
339+
>>> bpd.options.bigquery.use_regional_endpoints = True # doctest: +SKIP
340+
303341
Returns:
304342
bool:
305343
A boolean value, where True indicates that regional endpoints
@@ -339,6 +377,11 @@ def kms_key_name(self) -> Optional[str]:
339377
For more information, see https://cloud.google.com/bigquery/docs/customer-managed-encryption#assign_role
340378
Assign the Encrypter/Decrypter.
341379
380+
**Examples:**
381+
382+
>>> import bigframes.pandas as bpd
383+
>>> bpd.options.bigquery.kms_key_name = "projects/my-project/locations/us/keyRings/my-ring/cryptoKeys/my-key" # doctest: +SKIP
384+
342385
Returns:
343386
None or str:
344387
Name of the customer managed encryption key as a string; otherwise None.
@@ -356,6 +399,11 @@ def kms_key_name(self, value: str):
356399
def ordering_mode(self) -> Literal["strict", "partial"]:
357400
"""Controls whether total row order is always maintained for DataFrame/Series.
358401
402+
**Examples:**
403+
404+
>>> import bigframes.pandas as bpd
405+
>>> bpd.options.bigquery.ordering_mode = "partial" # doctest: +SKIP
406+
359407
Returns:
360408
Literal:
361409
A literal string value of either strict or partial ordering mode.
@@ -432,7 +480,14 @@ def requests_transport_adapters(
432480

433481
@property
434482
def enable_polars_execution(self) -> bool:
435-
"""If True, will use polars to execute some simple query plans locally."""
483+
"""If True, will use polars to execute some simple query plans locally.
484+
485+
**Examples:**
486+
487+
>>> import bigframes.pandas as bpd
488+
>>> bpd.options.bigquery.enable_polars_execution = True # doctest: +SKIP
489+
490+
"""
436491
return self._enable_polars_execution
437492

438493
@enable_polars_execution.setter
Collapse file

‎bigframes/_config/compute_options.py‎

Copy file name to clipboardExpand all lines: bigframes/_config/compute_options.py
+36-8Lines changed: 36 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -28,30 +28,30 @@ class ComputeOptions:
2828
>>> import bigframes.pandas as bpd
2929
>>> df = bpd.read_gbq("bigquery-public-data.ml_datasets.penguins")
3030
31-
>>> bpd.options.compute.maximum_bytes_billed = 500
31+
>>> bpd.options.compute.maximum_bytes_billed = 500 # doctest: +SKIP
3232
>>> df.to_pandas() # this should fail # doctest: +SKIP
3333
google.api_core.exceptions.InternalServerError: 500 Query exceeded limit for bytes billed: 500. 10485760 or higher required.
3434
35-
>>> bpd.options.compute.maximum_bytes_billed = None # reset option
35+
>>> bpd.options.compute.maximum_bytes_billed = None # reset option # doctest: +SKIP
3636
3737
To add multiple extra labels to a query configuration, use the `assign_extra_query_labels`
3838
method with keyword arguments:
3939
40-
>>> bpd.options.compute.assign_extra_query_labels(test1=1, test2="abc")
41-
>>> bpd.options.compute.extra_query_labels
40+
>>> bpd.options.compute.assign_extra_query_labels(test1=1, test2="abc") # doctest: +SKIP
41+
>>> bpd.options.compute.extra_query_labels # doctest: +SKIP
4242
{'test1': 1, 'test2': 'abc'}
4343
4444
Alternatively, you can add labels individually by directly accessing the `extra_query_labels`
4545
dictionary:
4646
47-
>>> bpd.options.compute.extra_query_labels["test3"] = False
48-
>>> bpd.options.compute.extra_query_labels
47+
>>> bpd.options.compute.extra_query_labels["test3"] = False # doctest: +SKIP
48+
>>> bpd.options.compute.extra_query_labels # doctest: +SKIP
4949
{'test1': 1, 'test2': 'abc', 'test3': False}
5050
5151
To remove a label from the configuration, use the `del` keyword on the desired label key:
5252
53-
>>> del bpd.options.compute.extra_query_labels["test1"]
54-
>>> bpd.options.compute.extra_query_labels
53+
>>> del bpd.options.compute.extra_query_labels["test1"] # doctest: +SKIP
54+
>>> bpd.options.compute.extra_query_labels # doctest: +SKIP
5555
{'test2': 'abc', 'test3': False}
5656
"""
5757

@@ -63,6 +63,11 @@ class ComputeOptions:
6363
their operations to resume. The default value is 0. Set the value to None
6464
to turn off the guard.
6565
66+
**Examples:**
67+
68+
>>> import bigframes.pandas as bpd
69+
>>> bpd.options.compute.ai_ops_confirmation_threshold = 100 # doctest: +SKIP
70+
6671
Returns:
6772
Optional[int]: Number of rows.
6873
"""
@@ -73,6 +78,11 @@ class ComputeOptions:
7378
7479
When set to True, the operation automatically fails without asking for user inputs.
7580
81+
**Examples:**
82+
83+
>>> import bigframes.pandas as bpd
84+
>>> bpd.options.compute.ai_ops_threshold_autofail = True # doctest: +SKIP
85+
7686
Returns:
7787
bool: True if the guard is enabled.
7888
"""
@@ -85,6 +95,10 @@ class ComputeOptions:
8595
10 GB for potentially faster execution; BigQuery will raise an error if this
8696
limit is exceeded. Setting to True removes this result size limit.
8797
98+
**Examples:**
99+
100+
>>> import bigframes.pandas as bpd
101+
>>> bpd.options.compute.allow_large_results = True # doctest: +SKIP
88102
89103
Returns:
90104
bool | None: True if results > 10 GB are enabled.
@@ -97,6 +111,10 @@ class ComputeOptions:
97111
query engine to handle. However this comes at the cost of increase cost and
98112
latency.
99113
114+
**Examples:**
115+
116+
>>> import bigframes.pandas as bpd
117+
>>> bpd.options.compute.enable_multi_query_execution = True # doctest: +SKIP
100118
101119
Returns:
102120
bool | None: True if enabled.
@@ -121,6 +139,11 @@ class ComputeOptions:
121139
default. See `maximum_bytes_billed`:
122140
https://cloud.google.com/python/docs/reference/bigquery/latest/google.cloud.bigquery.job.QueryJobConfig#google_cloud_bigquery_job_QueryJobConfig_maximum_bytes_billed.
123141
142+
**Examples:**
143+
144+
>>> import bigframes.pandas as bpd
145+
>>> bpd.options.compute.maximum_bytes_billed = 1000 # doctest: +SKIP
146+
124147
Returns:
125148
int | None: Number of bytes, if set.
126149
"""
@@ -136,6 +159,11 @@ class ComputeOptions:
136159
of rows to be downloaded exceeds this limit, a
137160
``bigframes.exceptions.MaximumResultRowsExceeded`` exception is raised.
138161
162+
**Examples:**
163+
164+
>>> import bigframes.pandas as bpd
165+
>>> bpd.options.compute.maximum_result_rows = 1000 # doctest: +SKIP
166+
139167
Returns:
140168
int | None: Number of rows, if set.
141169
"""
Collapse file

‎bigframes/_config/experiment_options.py‎

Copy file name to clipboardExpand all lines: bigframes/_config/experiment_options.py
+14Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,13 @@ def __init__(self):
3131

3232
@property
3333
def semantic_operators(self) -> bool:
34+
"""Deprecated.
35+
36+
**Examples:**
37+
38+
>>> import bigframes.pandas as bpd
39+
>>> bpd.options.experiments.semantic_operators = True # doctest: +SKIP
40+
"""
3441
return self._semantic_operators
3542

3643
@semantic_operators.setter
@@ -44,6 +51,13 @@ def semantic_operators(self, value: bool):
4451

4552
@property
4653
def ai_operators(self) -> bool:
54+
"""If True, allow using the AI operators.
55+
56+
**Examples:**
57+
58+
>>> import bigframes.pandas as bpd
59+
>>> bpd.options.experiments.ai_operators = True # doctest: +SKIP
60+
"""
4761
return self._ai_operators
4862

4963
@ai_operators.setter
Collapse file

‎bigframes/_config/sampling_options.py‎

Copy file name to clipboardExpand all lines: bigframes/_config/sampling_options.py
+20Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,11 @@ class SamplingOptions:
3131
Download size threshold in MB. Default 500.
3232
3333
If value set to None, the download size won't be checked.
34+
35+
**Examples:**
36+
37+
>>> import bigframes.pandas as bpd
38+
>>> bpd.options.sampling.max_download_size = 1000 # doctest: +SKIP
3439
"""
3540

3641
enable_downsampling: bool = False
@@ -40,6 +45,11 @@ class SamplingOptions:
4045
If max_download_size is exceeded when downloading data (e.g., to_pandas()),
4146
the data will be downsampled if enable_downsampling is True, otherwise, an
4247
error will be raised.
48+
49+
**Examples:**
50+
51+
>>> import bigframes.pandas as bpd
52+
>>> bpd.options.sampling.enable_downsampling = True # doctest: +SKIP
4353
"""
4454

4555
sampling_method: Literal["head", "uniform"] = "uniform"
@@ -50,6 +60,11 @@ class SamplingOptions:
5060
the beginning. It is fast and requires minimal computations to perform the
5161
downsampling.; "uniform": This algorithm returns uniform random samples of
5262
the data.
63+
64+
**Examples:**
65+
66+
>>> import bigframes.pandas as bpd
67+
>>> bpd.options.sampling.sampling_method = "head" # doctest: +SKIP
5368
"""
5469

5570
random_state: Optional[int] = None
@@ -58,6 +73,11 @@ class SamplingOptions:
5873
5974
If provided, the uniform method may take longer to execute and require more
6075
computation.
76+
77+
**Examples:**
78+
79+
>>> import bigframes.pandas as bpd
80+
>>> bpd.options.sampling.random_state = 42 # doctest: +SKIP
6181
"""
6282

6383
def with_max_download_size(self, max_rows: Optional[int]) -> SamplingOptions:

0 commit comments

Comments
0 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.