DO NOT MERGE: Add dataset builder docs by Jack-Keene · Pull Request #1857 · snowplow/documentation

Jack Keene (Jack-Keene) · 2026-07-16T13:38:43Z

What changed?

Docs for as yet unreleased dataset builder AISP 1401 & 1402

AI reviews

Claude will automatically review this PR against the docs style guide.

If you have questions or want it to look again at something specific, tag @claude in a comment.

cloudflare-workers-and-pages · 2026-07-16T13:38:48Z

Deploying with Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	documentation	`e504aec`	Commit Preview URL Branch Preview URL	Jul 27 2026, 04:58 PM

claude · 2026-07-16T13:39:58Z

Documentation style review

Overall this is a well-structured, cleanly written page — good frontmatter, sentence-case headings, 4 H2 sections (within the 3–5 limit), correct terminology, and all internal links (attribute-groups, connection) end in /index.md and resolve. No external URLs were touched. A few style items to address:

1. Bold used for non-UI text (CLAUDE.md)

CLAUDE.md: "Use bold only for UI elements (buttons, page titles)." The stage names in the "How it works" list are bolded but aren't UI elements:

1. **Anchors** - identify moments in historical sessions...
2. **Attributes** - compute attribute values...
3. **Assembly** - join anchors...

Suggest removing the bold (the names are already emphasized by their list position), e.g. 1. Anchors: identify moments in historical sessions.... Note CLAUDE.md overrides the style guide's more permissive "bold or italic to highlight key phrases" here.

2. Underscore name not in backticks (style guide)

Style guide: "If the name has underscores, use code formatting."

| ... | Default: page_ping events excluded |

Should be `page_ping`.

3. Spaced hyphens used as dashes (minor)

Several sentences use a spaced hyphen - as a dash, e.g.:

"You specify a goal - the criteria that define a positive outcome - and a time window to scan."

Prefer an em dash or restructure with a colon/commas, e.g. "You specify a goal (the criteria that define a positive outcome) and a time window to scan." This applies in a few other places (the "How it works" list items, "Session anchors" intro).

Minor note

The ### Snowflake heading is followed immediately by a code block with no prose of its own (the style guide asks that every heading be preceded/backed by a paragraph). The parent H2 has a lead-in sentence, so this is borderline — optional to add a short introductory line.

jborlase-snowplow

Added some comments.

I think we need a tutorial to alongside the release of this to make it clear on how we expect this to be used.

jborlase-snowplow · 2026-07-17T15:02:59Z

+
+The dataset builder produces a training dataset in three stages:
+
+1. **Anchors** - identify moments in historical sessions where a user either achieved a goal (positive label) or did not (negative label)


I think this section could use a diagram to make it clear how anchors and attributes work

jborlase-snowplow · 2026-07-17T15:04:51Z

+
+Use the Signals Python SDK to build labeled training datasets from your [attribute groups](/docs/signals/attributes/attribute-groups/index.md). The dataset builder generates SQL that computes attribute values over historical data and joins them with labeled anchor events, producing a dataset ready for model training.
+
+Start by [connecting to Signals](/docs/signals/connection/index.md) to create a `Signals` client object.


We should have a more high-level why / how it works section showing how this is meant to be used to enable you to train ML models using same definitions as your attribute groups that you can use to serve the attributes to your ML models

and there we can highlight why PIT correctness is important

We should also highlight the overall process we expect users to take - not just the flow on how the dataset builder works.

jborlase-snowplow · 2026-07-17T15:07:56Z

+        schema="ml",
+        table="my_anchor_events",
+    ),
+    has_label=True,


What does label need to look like?

jborlase-snowplow · 2026-07-17T15:08:40Z

+from snowplow_signals import UserSuppliedAnchors, WarehouseTable
+
+anchors = UserSuppliedAnchors(
+    source=WarehouseTable(


Can we show an example input table and requirements?

jborlase-snowplow · 2026-07-17T15:08:58Z

+        start_time=datetime(2024, 1, 1, tzinfo=timezone.utc),
+        end_time=datetime(2024, 4, 1, tzinfo=timezone.utc),
+    ),
+)


Can we show example output of what this creates?

jborlase-snowplow · 2026-07-17T15:17:31Z

+
+## Execute against your warehouse
+
+Execute the generated SQL directly against your warehouse to produce the training dataset.


We should explain a bit about how - for example - using your existing Signals warehouse connection...

jborlase-snowplow · 2026-07-17T15:18:02Z

+        account=os.environ["SNOWFLAKE_ACCOUNT"],
+        user=os.environ["SNOWFLAKE_USER"],
+        warehouse=os.environ["SNOWFLAKE_WAREHOUSE"],
+        private_key=private_key_der,


What is the private key? Do we just auth via this? Is that the Snowflake term?

jborlase-snowplow · 2026-07-17T15:18:56Z

+| `source` | Table containing your pre-built anchor events | `WarehouseTable` | ✅ |
+| `has_label` | Whether the source table contains a label column | `bool` | Default: `True` |
+
+## Build the dataset


This header shouldn't be build the dataset - its more related to building the SQL rather than the actual dataset

jborlase-snowplow · 2026-07-17T15:19:41Z

+print(df.head())
+```
+
+You can also inspect the execution stages:


What are the execution stages?

If it is for monitoring execution - this doesn't feel like it should be in this section

jborlase-snowplow · 2026-07-17T15:20:54Z

+After execution, convert the result to a pandas DataFrame for analysis or model training.
+
+```python
+df = result.to_pandas()


We should show example of what is the output

Matus Tomlein (matus-tomlein) · 2026-07-21T07:56:02Z

+After execution, access the `dataframe` attribute to get the training dataset as a pandas DataFrame, ready for model training.
+
+```python
+df = result.dataframe


Just a note to update this to reflect the changes in the SDK.

add dataset builder docs

283acf1

Snowplow CLA bot (snowplowcla) added the cla:yes label Jul 16, 2026

Matus Tomlein (matus-tomlein) reviewed Jul 16, 2026

View reviewed changes

Comment thread docs/signals/applications/create-training-datasets/index.md Outdated

Matus Tomlein (matus-tomlein) reviewed Jul 16, 2026

View reviewed changes

jborlase-snowplow requested changes Jul 17, 2026

View reviewed changes

pr comments

787b1f8

Jack Keene (Jack-Keene) force-pushed the signals-dataset-builder branch from 4e22634 to 787b1f8 Compare July 17, 2026 15:38

Jack Keene (Jack-Keene) added 2 commits July 17, 2026 16:38

Merge branch 'main' into signals-dataset-builder

c9ee3f3

reflect latest sdk changes

8861fb2

Matus Tomlein (matus-tomlein) reviewed Jul 21, 2026

View reviewed changes

Jack Keene (Jack-Keene) added 6 commits July 24, 2026 10:01

update to final sdk

8a3524b

pr comments

2bb46cb

add example notebook

40e9b47

use google colab

1df6b11

pr comments

5b99ac9

add more complete criterion example

e504aec


		The dataset builder produces a training dataset in three stages:

		1. Anchors - identify moments in historical sessions where a user either achieved a goal (positive label) or did not (negative label)


		Use the Signals Python SDK to build labeled training datasets from your [attribute groups](/docs/signals/attributes/attribute-groups/index.md). The dataset builder generates SQL that computes attribute values over historical data and joins them with labeled anchor events, producing a dataset ready for model training.

		Start by [connecting to Signals](/docs/signals/connection/index.md) to create a `Signals` client object.


		## Execute against your warehouse

		Execute the generated SQL directly against your warehouse to produce the training dataset.

Uh oh!

Conversation

Jack Keene (Jack-Keene) commented Jul 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What changed?

AI reviews

Uh oh!

cloudflare-workers-and-pages Bot commented Jul 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Deploying with Cloudflare Workers

Uh oh!

claude Bot commented Jul 16, 2026

Documentation style review

1. Bold used for non-UI text (CLAUDE.md)

2. Underscore name not in backticks (style guide)

3. Spaced hyphens used as dashes (minor)

Minor note

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jborlase-snowplow left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Jack Keene (Jack-Keene) commented Jul 16, 2026 •

edited

Loading

cloudflare-workers-and-pages Bot commented Jul 16, 2026 •

edited

Loading