Initial Signals Docs #1197

Jack-Keene · 2025-04-07T16:34:03Z

No description provided.

netlify · 2025-04-07T16:34:21Z

✅ Deploy Preview for snowplow-docs ready!

Name	Link
🔨 Latest commit	`6149798`
🔍 Latest deploy log	https://app.netlify.com/projects/snowplow-docs/deploys/68370c645ad6290008100840
😎 Deploy Preview	https://deploy-preview-1197--snowplow-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

docs/signals/attributes/index.md

docs/signals/index.md

docs/signals/quickstart/index.md

docs/signals/attributes/index.md

matus-tomlein · 2025-04-14T09:08:07Z

docs/signals/attributes/index.md

+| `events` | List of Snowplow Events that the Attribute is calculated on | List of `Event` type |
+| `aggregation` | The aggregation type of the Attribute  | One of:  `counter`, `sum`, `min`, `max`, `mean`, `first`, `last`, `unique_list` |
+| `property_syntax` | The syntax used to reference the property. | One of: `snowflake`, `blobl` |
+| `property` | The property of the event or entity you wish to use in the aggregation | `string` |


I think we'll need a bit more documentation on this as there are complexities about the syntax and naming that should be used here.

We decided that we'll use Snowflake syntax for accessing nested properties within events and entities. Also the columns names are the same as in the atomic events table. There was a bit more detail in this doc.

One can also access other properties in the atomic events table like app_id and more. It'd be great to provide some examples.

I think it deserves a separate paragraph/section as users will definitely need to figure out how to do that.

docs/signals/attributes/index.md

johnmicahreid

@ilias1111 left some comments re the batch tutorial

johnmicahreid · 2025-04-15T15:25:50Z

tutorials/snowplow-signals-cli/meta.json

@@ -0,0 +1,5 @@
+{
+  "title": "Snowplow Signals CLI Tutorial",


@ilias1111 can we rename this to Create Batch Attributes using Snowplow Signals?

Create Batch Attributes using Snowplow Signals But isnt what we are doin, we are creating dbt projects ( batch engine projects ) based on already generated attributes :/ What should we say?

tutorials/snowplow-signals-cli/meta.json

johnmicahreid · 2025-04-15T15:27:01Z

tutorials/snowplow-signals-cli/start.md

+Before starting, ensure you have:
+
+- Python 3.11+ installed
+- Snowplow Signals SDK installed


Show them how to install this - have a pip install command or something.

Also it's not totally obvious to me that installing a Python package means it can be used as a CLI tool, maybe just clarify that piece.

This is skipped for now, in the sense that the cli is not live in pypi thus i cannot test the command and there is no point to saying it. Will add it when we are live with the sdk

johnmicahreid · 2025-04-15T15:27:23Z

tutorials/snowplow-signals-cli/start.md

+  - API URL
+  - API Key
+  - API Key ID
+  - Organization ID


Tell them how to find all these bits of information - you can copy from the Quickstart guide.

johnmicahreid · 2025-04-15T15:28:09Z

tutorials/snowplow-signals-cli/initialize-project.md

+  --api-key "YOUR_API_KEY" \
+  --api-key-id "YOUR_API_KEY_ID" \
+  --org-id "YOUR_ORG_ID" \
+  --repo-path "./my_snowplow_repo" \


You should show a step to create the repo earlier on (mkdir...)

johnmicahreid · 2025-04-15T15:29:01Z

tutorials/snowplow-signals-cli/initialize-project.md

+
+## Choosing Between Options
+
+- Use **Option 1** when you want to set up projects for all your batch views at once


I had already forgotten what Option 1 and 2 were here, could you just use their descriptive names?

tutorials/snowplow-signals-cli/start.md

* Add missing batch content * Updates * Updates on the installation * John changes --------- Co-authored-by: Ilias Xenogiannis <ilias1111@users.noreply.github.com>

* Rename signals to sp_signals * Rename cli tutorial * Remove cli details from batch engine * Add view prerequisite to cli tutorial * Add online offline to view def * Clarify onlne offline matrix * Update docs/signals/views_services/index.md

mscwilson · 2025-05-21T14:52:42Z

Can someone check this PR against Vale please, haven't finished reviewing yet but seen a few formatting problems

mscwilson

Add the new Signals terms to the Glossary please

I haven't reviewed the Tutorial part since the main docs are more urgent

docs/signals/index.md

mscwilson · 2025-05-21T14:55:12Z

docs/signals/quickstart/index.md

+
+page_view_count = Attribute(
+    name="page_view_count",
+    type="int32",


why does type come up a different colour in the codeblock?

type gets special treatment in the highlighting because it's a language "builtin".

mscwilson · 2025-05-21T14:56:47Z

docs/signals/quickstart/index.md

+$ pip install snowplow-signals
+```
+
+To connect to your Signals deployment, you will need 4 values.


isn't this 3 things

mscwilson · 2025-05-21T14:57:48Z

docs/signals/quickstart/index.md

+## Step 1: Installation and Setup
+The Snowplow Signals SDK allows you to define attributes, create views, and retrieve user features. It requires Python 3.12 or above.
+
+Install the SDK using pip:


docs/signals/batch_engine/index.md

mscwilson · 2025-05-21T16:08:02Z

docs/signals/batch_engine/index.md

+There is a second layer of incremental processing logic dictated by the `daily_aggregation_manifest` table. After the `filtered_events` table is created or updated, the `daily_aggregates` table gets updated with the help of this manifest. It is needed due to late arriving data, which may mean that some days will need to be reprocessed as a whole. For optimization purposes there are variables to fine-tune how this works such as the `snowplow__reprocess_days` and the `snowplow__min_rows_to_process`.
+
+Finally, the `Attributes` table is generated which is a drop and recompute table, fully updated each time an incremental update runs. This is made possible without much effort as the data is already pre-aggregated on a daily level.
+![](../images/batch_engine_data_models.png)


this diagram would work better vertically, then the text wouldn't be tiny

mscwilson · 2025-05-21T16:10:47Z

docs/signals/batch_engine/index.md

+Finally, the `Attributes` table is generated which is a drop and recompute table, fully updated each time an incremental update runs. This is made possible without much effort as the data is already pre-aggregated on a daily level.
+![](../images/batch_engine_data_models.png)
+
+## Variables


what are the defaults?

mscwilson · 2025-05-21T16:40:39Z

docs/signals/index.md

+sidebar_label: "Signals"
+---
+
+Snowplow Signals is a personalization engine built on Snowplow’s behavioral data pipeline. The Profile API, hosted in your BDP cloud allows you to create, manage and access user attributes by using the Signals SDKs.


what SDKs? how many are there? link to github repos

mscwilson · 2025-05-21T16:41:53Z

docs/signals/index.md

+![](./images/signals.png)
+
+Signals allows users to enhance their applications by aggregating user attributes and providing near real-time visibility into customer behavior. With seamless access to user history, it simplifies creating personalized, intelligent experiences.
+


add a short paragraph or section here about how to use Signals

mscwilson · 2025-05-21T18:42:28Z

docs/signals/index.md

+sidebar_label: "Signals"
+---
+
+Snowplow Signals is a personalization engine built on Snowplow’s behavioral data pipeline. The Profile API, hosted in your BDP cloud allows you to create, manage and access user attributes by using the Signals SDKs.


should be named Profiles Store to match the official announcement

Suggested change

Snowplow Signals is a personalization engine built on Snowplow’s behavioral data pipeline. The Profile API, hosted in your BDP cloud allows you to create, manage and access user attributes by using the Signals SDKs.

Snowplow Signals is a personalization engine built on Snowplow’s behavioral data pipeline. The Profiles Store API, hosted in your BDP cloud allows you to create, manage and access user attributes by using the Signals SDKs.

mscwilson · 2025-05-21T18:54:57Z

docs/signals/index.md

+
+Signals allows users to enhance their applications by aggregating user attributes and providing near real-time visibility into customer behavior. With seamless access to user history, it simplifies creating personalized, intelligent experiences.
+
+### Sources


this section refers to views, should go below View section

mscwilson · 2025-05-21T19:37:01Z

docs/signals/index.md

+
+### Services
+
+A `Service` is a collection of `Views` that are grouped to make the retrieval of attributes simpler. 


expand on this - there's more info to copy in the other page. why would they want multiple views?

docs/signals/quickstart/index.md

docs/signals/sources/index.md

mscwilson · 2025-05-21T19:43:54Z

docs/signals/sources/index.md

@@ -0,0 +1,16 @@
+---
+title: "Sources"
+sidebar_position: 10


this section should be below Attributes

mscwilson · 2025-05-21T19:48:06Z

docs/signals/views_services/index.md

+A `View` is a versioned collection of attributes grouped by a common `Entity` (e.g., `session_id` or `user_id`). Once defined, a `View` allows you to retrieve the calculated values of the attributes it contains.
+
+### What is a Service?
+A `Service` is a collection of views that streamlines the retrieval of multiple views. By grouping related views into a `Service`, you can efficiently manage and access user insights, making it easier to personalize applications and analyze behavior.


can one service have views with different sources?

mscwilson · 2025-05-21T19:54:16Z

docs/signals/batch_engine/index.md

+The entity here is typically the user, which may be the `domain_userid` or other Snowplow identifier fields, such as the logged in `user_id`. 
+
+:::info
+For now, only the `domain_userid` can be used, but shortly we will extend support for all Snowplow identifiers


does this also apply to the stream source?

mscwilson · 2025-05-21T19:58:58Z

docs/signals/batch_engine/index.md

+Finally, the `Attributes` table is generated which is a drop and recompute table, fully updated each time an incremental update runs. This is made possible without much effort as the data is already pre-aggregated on a daily level.
+![](../images/batch_engine_data_models.png)
+
+## Variables


this section should go higher on the page, under Generating the dbt project

mscwilson · 2025-05-21T20:06:16Z

docs/signals/index.md

+
+Signals allows users to enhance their applications by aggregating user attributes and providing near real-time visibility into customer behavior. With seamless access to user history, it simplifies creating personalized, intelligent experiences.
+
+### Sources


actually put these bits under a subheading

Signals components

The core components are Attributes, Sources, Views, and Services.

You will need to create a new Python project that imports the Signals SDK. Configure Signals by defining these components, and deploying them to the Profiles Store. You can then pull aggregrated attributes, using the Signals SDK, to use in your applications.

[diagram like this - is this right?]

mscwilson · 2025-05-21T20:13:12Z

docs/signals/index.md

+
+Snowplow Signals is a personalization engine built on Snowplow’s behavioral data pipeline. The Profile API, hosted in your BDP cloud allows you to create, manage and access user attributes by using the Signals SDKs.
+
+![](./images/signals.png)


move this diagram into the new "Signals components" subheading below, replace it with the fancy official one that matches the docs homepage architecture diagram

Co-authored-by: Miranda Wilson <miranda@snowplow.io>

Jack-Keene marked this pull request as ready for review April 7, 2025 16:34

mscwilson added the do not merge Flag to denote a Issue or PR which should not yet be merged (usually pending a release) label Apr 7, 2025

jpiekos requested changes Apr 8, 2025

View reviewed changes

docs/signals/attributes/index.md Show resolved Hide resolved

docs/signals/index.md Outdated Show resolved Hide resolved

docs/signals/index.md Outdated Show resolved Hide resolved

docs/signals/index.md Outdated Show resolved Hide resolved

mscwilson requested changes Apr 9, 2025

View reviewed changes

Jack-Keene force-pushed the add-signals-docs branch from f40a7bc to db48419 Compare April 11, 2025 10:08

Jack-Keene added 2 commits April 11, 2025 11:13

Initial Signals Docs

0664c70

de-marketingify intro

321d5d5

Jack-Keene force-pushed the add-signals-docs branch from db48419 to 321d5d5 Compare April 11, 2025 10:13

Jack-Keene and others added 5 commits April 11, 2025 11:28

add missing image

29af49e

add note for google colab

9effec5

update spelling/grammar/us terms

889087a

separate sources into batch and stream

a035621

Add signals docs cli tutorial (#1212)

4ea4e8a

matus-tomlein reviewed Apr 14, 2025

View reviewed changes

docs/signals/attributes/index.md Outdated Show resolved Hide resolved

Jack-Keene added 2 commits April 14, 2025 20:06

rename filter to criteria

3ed1987

remove unused API syntax

5810bce

johnmicahreid reviewed Apr 15, 2025

View reviewed changes

agnessnowplow and others added 2 commits April 25, 2025 16:37

Add missing batch content (#1218)

9931fba

* Add missing batch content * Updates * Updates on the installation * John changes --------- Co-authored-by: Ilias Xenogiannis <ilias1111@users.noreply.github.com>

Fix/signals feedback (#1229)

eb235c5

* Rename signals to sp_signals * Rename cli tutorial * Remove cli details from batch engine * Add view prerequisite to cli tutorial * Add online offline to view def * Clarify onlne offline matrix * Update docs/signals/views_services/index.md

johnmicahreid requested a review from mscwilson May 21, 2025 10:45

mscwilson reviewed May 21, 2025

View reviewed changes

docs/signals/quickstart/index.md Outdated Show resolved Hide resolved

mscwilson reviewed May 21, 2025

View reviewed changes

docs/signals/sources/index.md Outdated Show resolved Hide resolved

mscwilson reviewed May 21, 2025

View reviewed changes

johnmicahreid requested review from miike and jethron May 22, 2025 09:10

matus-tomlein and others added 6 commits May 23, 2025 14:29

Apply suggestions from code review

535cb5c

Co-authored-by: Miranda Wilson <miranda@snowplow.io>

Apply suggestions from code review

7fcc79e

Co-authored-by: Miranda Wilson <miranda@snowplow.io>

Apply suggestions from code review

edd31a3

Co-authored-by: Miranda Wilson <miranda@snowplow.io>

Suggestion from review

0505299

Update with changes in the latest API and SDK version

c88ca78

AISP 446 448 (#1262)

6149798


		## Choosing Between Options

		- Use Option 1 when you want to set up projects for all your batch views at once

		![](./images/signals.png)

		Signals allows users to enhance their applications by aggregating user attributes and providing near real-time visibility into customer behavior. With seamless access to user history, it simplifies creating personalized, intelligent experiences.

	Snowplow Signals is a personalization engine built on Snowplow’s behavioral data pipeline. The Profile API, hosted in your BDP cloud allows you to create, manage and access user attributes by using the Signals SDKs.
	Snowplow Signals is a personalization engine built on Snowplow’s behavioral data pipeline. The Profiles Store API, hosted in your BDP cloud allows you to create, manage and access user attributes by using the Signals SDKs.


		Signals allows users to enhance their applications by aggregating user attributes and providing near real-time visibility into customer behavior. With seamless access to user history, it simplifies creating personalized, intelligent experiences.

		### Sources


		### Services

		A `Service` is a collection of `Views` that are grouped to make the retrieval of attributes simpler.

Initial Signals Docs #1197

Are you sure you want to change the base?

Initial Signals Docs #1197

Uh oh!

Conversation

Jack-Keene commented Apr 7, 2025

Uh oh!

netlify bot commented Apr 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for snowplow-docs ready!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

johnmicahreid 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!

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!

Uh oh!

mscwilson commented May 21, 2025

Uh oh!

mscwilson left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

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!

Uh oh!

Uh oh!

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!

Uh oh!

Uh oh!

netlify bot commented Apr 7, 2025 •

edited

Loading

mscwilson May 21, 2025 •

edited

Loading

mscwilson May 21, 2025 •

edited

Loading