determine_grid_layout_v1 (UDF)
Determine the grid layout type for the Newtab Context: this layout type can help in identifying the number of tiles that are displayed per row on the newtab homepage
UDF: Grid Type Determination for Firefox New Tab Layout
This User-Defined Function (UDF) determines the appropriate grid layout type for Firefox new tab pages based on various input parameters including whether the new tab is section-based, the browser version, and experiment enrollment metadata.
📥 Input Parameters
| Name | Type | Description |
|---|---|---|
is_section |
BOOLEAN | Indicates whether the new tab impressions are based on section layout. |
app_version |
INTEGER | Represents the Firefox major version number. |
experiment |
ARRAY |
An array of experimental configurations assigned to the client. Each entry is a STRUCT<key STRING, value STRUCT<branch STRING, extra STRUCT<type STRING, enrollment_id STRING>>>. |
📌 Evaluation Criteria
The UDF returns one of six possible values based on the following conditions:
POSTNOVA_SECTION
The post-Nova layout can have both sections and grid variants. Both have the same breakpoints, but the possible tiles differ
Returned when:
- app_version >= 155 AND is_section=TRUE
POSTNOVA_GRID
Returned when:
- app_version >= 155 AND is_section=FALSE
NOVA_SECTION
Nova can have both sections and grid variants. Both have the same breakpoints, but the possible tiles differ
Returned when:
- 155 > app_version >= 151 AND is_section=TRUE
NOVA_GRID
Returned when:
- 155 > app_version >= 151 AND is_section=FALSE
SECTION_GRID
Returned when:
- app_version < 151 AND is_section = TRUE
NEW_GRID
Returned when:
- is_section = FALSE AND
- One of the following holds:
- 151 > app_version >= 136
- app_version < 136 AND experiment.key matches one of the following:
- default-ui-experiment
- new-tab-layout-variant-b-and-content-card-ui-rollout-global
- new-tab-layout-variant-b-and-content-card-ui-release-rollout-global-v2
- default-ui-experiment-logo-in-corner-rollout
OLD_GRID
Returned when:
- is_section = FALSE AND
- app_version < 136 AND
- No matching experiment from the above list is found
🏁 Return Values
POSTNOVA_SECTIONPOSTNOVA_GRIDNOVA_SECTIONNOVA_GRIDSECTION_GRIDNEW_GRIDOLD_GRID
🛠 Example Usage
SELECT determine_grid_layout(
TRUE,
135,
ARRAY[
STRUCT('default-ui-experiment', STRUCT('branch1', STRUCT('type1', 'enroll123')))
]
) AS grid_type;
-- Returns: SECTION_GRID
### Parameters
**INPUTS**
**OUTPUTS**
[Source](https://github.com/mozilla/bigquery-etl/blob/generated-sql/sql/mozfun/newtab/determine_grid_layout_v1) | [Edit](https://github.com/mozilla/bigquery-etl/edit/generated-sql/sql/mozfun/newtab/determine_grid_layout_v1/metadata.yaml)
## determine_tiles_per_row_v1 (UDF)
Determine the tiles per row for Firefox Newtab based on layout type and window width
# UDF: Tiles per row on Firefox Newtab
This UDF (`determine_tiles_per_row_v1`) determines the number of tiles displayed per row on the Firefox Newtab page,
based on the layout type and window width.
## 📥 Input Parameters
| Parameter Name | Type | Description |
|---------------------------|---------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `layout_type` | STRING | The layout style of the Newtab page. Can be one of `NOVA`, `SECTION_GRID`, `NEW_GRID`, or `OLD_GRID` and is computed using the UDF `determine_grid_layout`.<br/> [README](https://github.com/mozilla/bigquery-etl/blob/main/sql/mozfun/newtab/determine_grid_layout_v1/README.md) for more information about the `determine_grid_layout` UDF |
| `newtab_window_inner_width` | INTEGER | The width (in pixels) of the Firefox browser window. An attribute of the newtab `opened` event. |
## 📤 Output
- Returns an `INTEGER` indicating the number of tiles per row based on the logic described below.
- If an unrecognized layout type is passed, the function returns `NULL`.
## 📐 Logic
### For layout type: `SECTION_GRID`
| `newtab_window_inner_width` | Tiles per row |
|-----------------------------------|----------------|
| `< 724` | 1 |
| `724 ≤ width < 1122` | 2 |
| `1122 ≤ width < 1390` | 3 |
| `≥ 1390` | 4 |
### For layout type: `NEW_GRID` or `OLD_GRID`
| `newtab_window_inner_width` | Tiles per row |
|-----------------------------------|----------------|
| `< 724` | 1 |
| `724 ≤ width < 1122` | 2 |
| `1122 ≤ width < 1698` or layout is `OLD_GRID` | 3 |
| `≥ 1698` and layout is `NEW_GRID` | 4 |
### For layout type: `Nova`
| `newtab_window_inner_width` | Tiles per row |
|-----------------------------------|----------------|
| `< 1024` | 1 |
| `1024≤ width < 1366` | 2 |
| `1366 ≤ width < 1920` | 3 |
| `1920 ≤ width < 2650` | 4 |
| `≥ 2650` | 6 |
> Note: The largest bin does have room for 6 tiles, skipping width 5
## ✅ Example Usage
```sql
SELECT `determine_tiles_per_row_v1`('SECTION_GRID', 1200); -- Returns 3
SELECT `determine_tiles_per_row_v1`('NEW_GRID', 1700); -- Returns 4
SELECT `determine_tiles_per_row_v1`('OLD_GRID', 1800); -- Returns 3
### Parameters
**INPUTS**
**OUTPUTS**
[Source](https://github.com/mozilla/bigquery-etl/blob/generated-sql/sql/mozfun/newtab/determine_tiles_per_row_v1) | [Edit](https://github.com/mozilla/bigquery-etl/edit/generated-sql/sql/mozfun/newtab/determine_tiles_per_row_v1/metadata.yaml)
## determine_tiles_per_row_v2 (UDF)
Determine the tiles per row for Firefox Newtab based on layout type and window width
# UDF: Tiles per row on Firefox Newtab
This UDF (`determine_tiles_per_row_v2`) determines the number of tiles displayed per row on the Firefox Newtab page,
based on the layout type and window width. It is an update of `determine_tiles_per_row_v1` based on corrected Nova breakpoints and a new case for the post-Nova layout.
## 📥 Input Parameters
| Parameter Name | Type | Description |
|---------------------------|---------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `layout_type` | STRING | The layout style of the Newtab page. Can be one of `POSTNOVA_GRID`, `POSTNOVA_SECTION`, `NOVA_GRID`, `NOVA_SECTION`, `SECTION_GRID`, `NEW_GRID`, or `OLD_GRID`, and is computed using the UDF `determine_grid_layout`.<br/> [README](https://github.com/mozilla/bigquery-etl/blob/main/sql/mozfun/newtab/determine_grid_layout_v1/README.md) for more information about the `determine_grid_layout` UDF |
| `newtab_window_inner_width` | INTEGER | The width (in pixels) of the Firefox browser window. An attribute of the newtab `opened` event. |
## 📤 Output
- Returns an `INTEGER` indicating the number of tiles per row based on the logic described below.
- If `newtab_window_inner_width` is `NULL`, or an unrecognized layout type is passed, the function returns `NULL`.
## 📐 Logic
### For layout type: `POSTNOVA_GRID` or `POSTNOVA_SECTION`
| `newtab_window_inner_width` | Tiles per row |
|-----------------------------------|----------------|
| `< 724` | 1 |
| `724 ≤ width < 1069` | 2 |
| `1069 ≤ width < 1414` | 3 |
| `≥ 1414` | 4 |
### For layout type: `NOVA_GRID` or `NOVA_SECTION`
| `newtab_window_inner_width` | Tiles per row |
|-----------------------------------|----------------|
| `< 1047` | 1 |
| `1047 ≤ width < 1392` | 2 |
| `1392 ≤ width < 1737` | 3 |
| `≥ 1737` | 4 |
### For layout type: `SECTION_GRID`
| `newtab_window_inner_width` | Tiles per row |
|-----------------------------------|----------------|
| `< 724` | 1 |
| `724 ≤ width < 1122` | 2 |
| `1122 ≤ width < 1390` | 3 |
| `≥ 1390` | 4 |
### For layout type: `NEW_GRID` or `OLD_GRID`
| `newtab_window_inner_width` | Tiles per row |
|-----------------------------------|----------------|
| `< 724` | 1 |
| `724 ≤ width < 1122` | 2 |
| `1122 ≤ width < 1698` or layout is `OLD_GRID` | 3 |
| `≥ 1698` and layout is `NEW_GRID` | 4 |
## ✅ Example Usage
```sql
SELECT `determine_tiles_per_row_v2`('POSTNOVA_SECTION', 1200); -- Returns 3
SELECT `determine_tiles_per_row_v2`('NOVA_SECTION', 1500); -- Returns 3
SELECT `determine_tiles_per_row_v2`('SECTION_GRID', 1200); -- Returns 3
SELECT `determine_tiles_per_row_v2`('NEW_GRID', 1700); -- Returns 4
SELECT `determine_tiles_per_row_v2`('OLD_GRID', 1800); -- Returns 3
Parameters
INPUTS
layout_type STRING, newtab_window_inner_width INTEGER
OUTPUTS
INTEGER
is_default_ui_v1 (UDF)
Determine if the newtab open is attributed to default UI
Is Default UI UDF
This function computes if the newtab opened by the client is attributed to the Default UI.
Input parameters from the newtab ping:
event_category as STRING (category)
event_name as STRING (name)
event_details as ARRAY<STRUCT<key STRING, value STRING>> (extra)
newtab_homepage_category as STRING (metrics.string.newtab_homepage_category)
newtab_newtab_category as STRING (metrics.string.newtab_newtab_category)
Parameters
INPUTS
event_category STRING, event_name STRING, event_details ARRAY<STRUCT<key STRING, value STRING>>, newtab_homepage_category STRING, newtab_newtab_category STRING
OUTPUTS
BOOLEAN
scheduled_surface_id_v1 (UDF)
Content teams reference for the surface where an article is published on Newtab
Scheduled Surface Id UDF
This function takes a country and locale to compute the Content teams identifier for the surface the article is published.
Note: The UDF tries to mimic the backend merino implementation (https://github.com/mozilla-services/merino-py/blob/main/merino/curated_recommendations/provider.py#L66-L103) for the Scheduled_Surface_Id. The UDF is meant to be used temporarily until the backend computed value gets added to the newtab ping
Parameters
INPUTS
country STRING, locale STRING
OUTPUTS
STRING
surface_id_country (UDF)
Parse country from surface_id for use in Newtab entities
Surface ID Country UDF
This function derives country from surface_id string, particularly when country is null.
In general, it should be used for content recommendations in the newtab_content ping, which is based on country rather than surface.
For tables:
moz-fx-data-shared-prod.firefox_desktop_*.newtab_v1moz-fx-data-shared-prod.firefox_desktop_*.newtab_content_v1
Parameters
INPUTS
surface_id STRING, locale STRING, country STRING
OUTPUTS
STRING