From f6291c68660dabbce70c03a94f16e08688742ffb Mon Sep 17 00:00:00 2001 From: Qinyi Ding Date: Tue, 29 Sep 2026 23:22:07 -0700 Subject: [PATCH] [DOC-12200] Add table sampling examples and clarify fractions Clarify existing API behavior without changing executable code. Generated with [Snowflake CoCo](https://docs.snowflake.com/en/user-guide/cortex-code/cortex-code) Co-authored-by: Snowflake CoCo --- src/snowflake/snowpark/table.py | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/src/snowflake/snowpark/table.py b/src/snowflake/snowpark/table.py index 0dbe7199cf..d12d797be2 100644 --- a/src/snowflake/snowpark/table.py +++ b/src/snowflake/snowpark/table.py @@ -446,7 +446,9 @@ def sample( This is the main difference between :meth:`DataFrame.sample` and this method. Args: - frac: The percentage of rows to be sampled. + frac: The fraction of rows to sample, from 0.0 to 1.0 inclusive. + For example, ``0.25`` requests approximately 25 percent of rows, + not exactly one quarter of the table. Specify either ``frac`` or ``n``. n: The fixed number of rows to sample in the range of 0 to 1,000,000 (inclusive). Either ``frac`` or ``n`` should be provided. seed: Specifies a seed value to make the sampling deterministic. Can be any integer between 0 and 2147483647 inclusive. Default value is ``None``. @@ -461,6 +463,18 @@ def sample( - Fixed-size sampling can be slower than equivalent fraction-based sampling because fixed-size sampling prevents some query optimization. - Fixed-size sampling doesn't work with SYSTEM | BLOCK sampling. + These examples require an existing table named ``sample_source``. + Sampling doesn't guarantee row order, and fraction-based sampling + doesn't guarantee a particular row count. + + Examples:: + + >>> table = session.table("sample_source") # doctest: +SKIP + >>> fraction_sample = table.sample(frac=0.25, seed=7) # doctest: +SKIP + >>> fixed_sample = table.sample(n=5) # doctest: +SKIP + >>> len(fixed_sample.collect()) <= 5 # doctest: +SKIP + True + """ DataFrame._validate_sample_input(frac, n) if sampling_method and sampling_method.upper() not in (