Skip to content

Commit 18780b4

Browse files
Genesis929tswast
andauthored
docs: deprecate bpd.options.bigquery.allow_large_results in favor of bpd.options.compute.allow_large_results (#1597)
* update allow_large_result warning * Update bigframes/_config/bigquery_options.py Co-authored-by: Tim Sweña (Swast) <[email protected]> * Update bigframes/_config/bigquery_options.py Co-authored-by: Tim Sweña (Swast) <[email protected]> * Update bigframes/_config/bigquery_options.py Co-authored-by: Tim Sweña (Swast) <[email protected]> * update setting * Update bigframes/_config/bigquery_options.py Co-authored-by: Tim Sweña (Swast) <[email protected]> * update docs * Update bigframes/_config/bigquery_options.py * fix execute --------- Co-authored-by: Tim Sweña (Swast) <[email protected]>
1 parent ab24b6a commit 18780b4

13 files changed

+91
-31
lines changed

bigframes/_config/__init__.py

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -150,6 +150,24 @@ def is_bigquery_thread_local(self) -> bool:
150150
"""
151151
return self._local.bigquery_options is not None
152152

153+
@property
154+
def _allow_large_results(self) -> bool:
155+
"""The effective 'allow_large_results' setting.
156+
157+
This value is `self.compute.allow_large_results` if set (not `None`),
158+
otherwise it defaults to `self.bigquery.allow_large_results`.
159+
160+
Returns:
161+
bool:
162+
Whether large query results are permitted.
163+
- `True`: The BigQuery result size limit (e.g., 10 GB) is removed.
164+
- `False`: Results are restricted to this limit (potentially faster).
165+
BigQuery will raise an error if this limit is exceeded.
166+
"""
167+
if self.compute.allow_large_results is None:
168+
return self.bigquery.allow_large_results
169+
return self.compute.allow_large_results
170+
153171

154172
options = Options()
155173
"""Global options for default session."""

bigframes/_config/bigquery_options.py

Lines changed: 20 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -19,10 +19,8 @@
1919
from typing import Literal, Optional
2020
import warnings
2121

22-
import google.api_core.exceptions
2322
import google.auth.credentials
2423

25-
import bigframes.constants
2624
import bigframes.enums
2725
import bigframes.exceptions as bfe
2826

@@ -239,21 +237,34 @@ def skip_bq_connection_check(self, value: bool):
239237
@property
240238
def allow_large_results(self) -> bool:
241239
"""
242-
Sets the flag to allow or disallow query results larger than 10 GB.
240+
DEPRECATED: Checks the legacy global setting for allowing large results.
241+
Use ``bpd.options.compute.allow_large_results`` instead.
243242
244-
The default setting for this flag is True, which allows queries to return results
245-
exceeding 10 GB by creating an explicit destination table. If set to False, it
246-
restricts the result size to 10 GB, and BigQuery will raise an error if this limit
247-
is exceeded.
243+
Warning: Accessing ``bpd.options.bigquery.allow_large_results`` is deprecated
244+
and this property will be removed in a future version. The configuration for
245+
handling large results has moved.
248246
249247
Returns:
250-
bool: True if large results are allowed with an explicit destination table,
251-
False if results are limited to 10 GB and errors are raised when exceeded.
248+
bool: The value of the deprecated setting.
252249
"""
253250
return self._allow_large_results
254251

255252
@allow_large_results.setter
256253
def allow_large_results(self, value: bool):
254+
warnings.warn(
255+
"Setting `bpd.options.bigquery.allow_large_results` is deprecated, "
256+
"and will be removed in the future. "
257+
"Please use `bpd.options.compute.allow_large_results = <value>` instead. "
258+
"The `bpd.options.bigquery.allow_large_results` option is ignored if "
259+
"`bpd.options.compute.allow_large_results` is set.",
260+
FutureWarning,
261+
stacklevel=2,
262+
)
263+
if self._session_started and self._allow_large_results != value:
264+
raise ValueError(
265+
SESSION_STARTED_MESSAGE.format(attribute="allow_large_results")
266+
)
267+
257268
self._allow_large_results = value
258269

259270
@property

bigframes/_config/compute_options.py

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -86,6 +86,12 @@ class ComputeOptions:
8686
ai_ops_threshold_autofail (bool):
8787
Guards against unexpected processing of large amount of rows by semantic operators.
8888
When set to True, the operation automatically fails without asking for user inputs.
89+
90+
allow_large_results (bool):
91+
Specifies whether query results can exceed 10 GB. Defaults to False. Setting this
92+
to False (the default) restricts results to 10 GB for potentially faster execution;
93+
BigQuery will raise an error if this limit is exceeded. Setting to True removes
94+
this result size limit.
8995
"""
9096

9197
maximum_bytes_billed: Optional[int] = None
@@ -97,7 +103,9 @@ class ComputeOptions:
97103
semantic_ops_threshold_autofail = False
98104

99105
ai_ops_confirmation_threshold: Optional[int] = 0
100-
ai_ops_threshold_autofail = False
106+
ai_ops_threshold_autofail: bool = False
107+
108+
allow_large_results: Optional[bool] = None
101109

102110
def assign_extra_query_labels(self, **kwargs: Any) -> None:
103111
"""

bigframes/session/bq_caching_executor.py

Lines changed: 9 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -61,7 +61,7 @@ def with_require_table(self, value: bool) -> OutputSpec:
6161

6262
def _get_default_output_spec() -> OutputSpec:
6363
return OutputSpec(
64-
require_bq_table=bigframes.options.bigquery.allow_large_results, cluster_cols=()
64+
require_bq_table=bigframes.options._allow_large_results, cluster_cols=()
6565
)
6666

6767

@@ -157,9 +157,6 @@ def execute(
157157
ordered: bool = True,
158158
use_explicit_destination: Optional[bool] = None,
159159
) -> executor.ExecuteResult:
160-
if use_explicit_destination is None:
161-
use_explicit_destination = bigframes.options.bigquery.allow_large_results
162-
163160
if bigframes.options.compute.enable_multi_query_execution:
164161
self._simplify_with_caching(array_value)
165162

@@ -553,6 +550,14 @@ def _execute_plan(
553550
else:
554551
size_bytes = None
555552

553+
if size_bytes is not None and size_bytes >= MAX_SMALL_RESULT_BYTES:
554+
msg = bfe.format_message(
555+
"The query result size has exceeded 10 GB. In BigFrames 2.0 and "
556+
"later, you might need to manually set `allow_large_results=True` in "
557+
"the IO method or adjust the BigFrames option: "
558+
"`bigframes.options.compute.allow_large_results=True`."
559+
)
560+
warnings.warn(msg, FutureWarning)
556561
# Runs strict validations to ensure internal type predictions and ibis are completely in sync
557562
# Do not execute these validations outside of testing suite.
558563
if "PYTEST_CURRENT_TEST" in os.environ:

tests/system/conftest.py

Lines changed: 4 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -142,7 +142,7 @@ def resourcemanager_client(
142142

143143
@pytest.fixture(scope="session")
144144
def session() -> Generator[bigframes.Session, None, None]:
145-
context = bigframes.BigQueryOptions(location="US", allow_large_results=False)
145+
context = bigframes.BigQueryOptions(location="US")
146146
session = bigframes.Session(context=context)
147147
yield session
148148
session.close() # close generated session at cleanup time
@@ -158,19 +158,15 @@ def session_load() -> Generator[bigframes.Session, None, None]:
158158

159159
@pytest.fixture(scope="session", params=["strict", "partial"])
160160
def maybe_ordered_session(request) -> Generator[bigframes.Session, None, None]:
161-
context = bigframes.BigQueryOptions(
162-
location="US", ordering_mode=request.param, allow_large_results=False
163-
)
161+
context = bigframes.BigQueryOptions(location="US", ordering_mode=request.param)
164162
session = bigframes.Session(context=context)
165163
yield session
166164
session.close() # close generated session at cleanup type
167165

168166

169167
@pytest.fixture(scope="session")
170168
def unordered_session() -> Generator[bigframes.Session, None, None]:
171-
context = bigframes.BigQueryOptions(
172-
location="US", ordering_mode="partial", allow_large_results=False
173-
)
169+
context = bigframes.BigQueryOptions(location="US", ordering_mode="partial")
174170
session = bigframes.Session(context=context)
175171
yield session
176172
session.close() # close generated session at cleanup type
@@ -1419,7 +1415,7 @@ def floats_product_bf(session, floats_product_pd):
14191415

14201416
@pytest.fixture(scope="session", autouse=True)
14211417
def use_fast_query_path():
1422-
with bpd.option_context("bigquery.allow_large_results", False):
1418+
with bpd.option_context("compute.allow_large_results", False):
14231419
yield
14241420

14251421

tests/system/large/test_dataframe_io.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@
1818
import bigframes
1919

2020
WIKIPEDIA_TABLE = "bigquery-public-data.samples.wikipedia"
21-
LARGE_TABLE_OPTION = "bigquery.allow_large_results"
21+
LARGE_TABLE_OPTION = "compute.allow_large_results"
2222

2323

2424
def test_to_pandas_batches_raise_when_large_result_not_allowed(session):

tests/system/small/test_dataframe.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5081,7 +5081,7 @@ def test_df_bool_interpretation_error(scalars_df_index):
50815081

50825082
def test_query_job_setters(scalars_df_default_index: dataframe.DataFrame):
50835083
# if allow_large_results=False, might not create query job
5084-
with bigframes.option_context("bigquery.allow_large_results", True):
5084+
with bigframes.option_context("compute.allow_large_results", True):
50855085
job_ids = set()
50865086
repr(scalars_df_default_index)
50875087
assert scalars_df_default_index.query_job is not None

tests/system/small/test_dataframe_io.py

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -254,7 +254,7 @@ def test_to_pandas_array_struct_correct_result(session):
254254
def test_to_pandas_override_global_option(scalars_df_index):
255255
# Direct call to_pandas uses global default setting (allow_large_results=True),
256256
# table has 'bqdf' prefix.
257-
with bigframes.option_context("bigquery.allow_large_results", True):
257+
with bigframes.option_context("compute.allow_large_results", True):
258258

259259
scalars_df_index.to_pandas()
260260
table_id = scalars_df_index._query_job.destination.table_id
@@ -324,7 +324,7 @@ def test_to_pandas_dry_run(session, scalars_pandas_df_multi_index):
324324

325325
def test_to_arrow_override_global_option(scalars_df_index):
326326
# Direct call to_arrow uses global default setting (allow_large_results=True),
327-
with bigframes.option_context("bigquery.allow_large_results", True):
327+
with bigframes.option_context("compute.allow_large_results", True):
328328

329329
scalars_df_index.to_arrow()
330330
table_id = scalars_df_index._query_job.destination.table_id

tests/system/small/test_index_io.py

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@
1515

1616

1717
def test_to_pandas_override_global_option(scalars_df_index):
18-
with bigframes.option_context("bigquery.allow_large_results", True):
18+
with bigframes.option_context("compute.allow_large_results", True):
1919

2020
bf_index = scalars_df_index.index
2121

@@ -39,7 +39,7 @@ def test_to_pandas_dry_run(scalars_df_index):
3939

4040

4141
def test_to_numpy_override_global_option(scalars_df_index):
42-
with bigframes.option_context("bigquery.allow_large_results", True):
42+
with bigframes.option_context("compute.allow_large_results", True):
4343

4444
bf_index = scalars_df_index.index
4545

tests/system/small/test_progress_bar.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -64,7 +64,7 @@ def test_progress_bar_scalar_allow_large_results(
6464
capsys.readouterr() # clear output
6565

6666
with bf.option_context(
67-
"display.progress_bar", "terminal", "bigquery.allow_large_results", "True"
67+
"display.progress_bar", "terminal", "compute.allow_large_results", "True"
6868
):
6969
penguins_df_default_index["body_mass_g"].head(10).mean()
7070

tests/system/small/test_series.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3960,7 +3960,7 @@ def test_series_bool_interpretation_error(scalars_df_index):
39603960

39613961
def test_query_job_setters(scalars_dfs):
39623962
# if allow_large_results=False, might not create query job
3963-
with bigframes.option_context("bigquery.allow_large_results", True):
3963+
with bigframes.option_context("compute.allow_large_results", True):
39643964
job_ids = set()
39653965
df, _ = scalars_dfs
39663966
series = df["int64_col"]

tests/system/small/test_series_io.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@
1919

2020

2121
def test_to_pandas_override_global_option(scalars_df_index):
22-
with bigframes.option_context("bigquery.allow_large_results", True):
22+
with bigframes.option_context("compute.allow_large_results", True):
2323

2424
bf_series = scalars_df_index["int64_col"]
2525

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# Copyright 2025 Google LLC
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License");
4+
# you may not use this file except in compliance with the License.
5+
# You may obtain a copy of the License at
6+
#
7+
# http://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS,
11+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
# See the License for the specific language governing permissions and
13+
# limitations under the License.
14+
15+
import bigframes._config as config
16+
17+
18+
def test_default_options():
19+
options = config.compute_options.ComputeOptions()
20+
21+
assert options.allow_large_results is None
22+
assert config.options._allow_large_results is False

0 commit comments

Comments
 (0)