Updated metadata and schema templates

Author: wwyc

CODEOWNERS

@@ -26,6 +26,4 @@ dags.yaml
 /sql/moz-fx-data-shared-prod/contextual_services_derived/request_payload_tiles_v2 @mozilla/request_payload_reviewers
 /sql/moz-fx-data-shared-prod/contextual_services_derived/suggest_revenue_levers_daily_v1 @mozilla/revenue_forecasting_data_reviewers
 /sql/moz-fx-data-shared-prod/monitoring_derived/jobs_by_organization_v1 @mozilla/dataops
-# City Seen
-/sql_generators/clients_city_seen/templates/ @wichan @soGaussian
-/sql/**/clients_city_seen_v1 @wichan @soGaussian
+

dags.yaml

@@ -2456,7 +2456,7 @@ bqetl_bigeye_derived:
     - impact/tier_3
 
 bqetl_clients_city_seen:
-  schedule_interval: 0 2 * * *
+  schedule_interval: 0 4 * * *
   default_args:
     owner: [email protected]
     start_date: "2025-08-25"

sql/moz-fx-data-shared-prod/fenix_derived/clients_city_seen_v1/metadata.yaml

@@ -1,19 +1,24 @@
 friendly_name: Fenix Clients City Seen
 description: |-
-  This table captures the first and last seen geo attributes for each client_id and normalized channel.
+  This table stores the first-seen and last-seen geo attributes for each (client_id, normalized_channel).
+  The table was initialized from stable tables (with ~2 years of retention), so the initial dates reflect the earliest/latest
+  observations within that window.  It then updates daily using live tables, replacing last-seen fields for existing
+  clients and adding new clients with first-seen geo attributes that do not yet exist in the table.
+  Implementation Plan: https://docs.google.com/document/d/1S8yVEwJjtJy3Pd8cn_BHRhgxllVnoxKylGCpuMyqWNQ/edit?usp=sharing
 owners:
   - [email protected]
 labels:
-  change_controlled: true
   incremental: true
   schedule: daily
   table_type: client_level
   dag: bqetl_clients_city_seen
 scheduling:
   dag_name: bqetl_clients_city_seen
-  task_group: fenix_clients_city_seen
+  task_name: fenix_clients_city_seen_v1
   depends_on_past: true
   date_partition_parameter: null
+  parameters:
+    - submission_date:DATE:
   depends_on:
     - task_id: copy_deduplicate_all
       dag_name: copy_deduplicate
@@ -24,7 +29,6 @@ bigquery:
     field: last_seen_geo_date
     require_partition_filter: false
     expiration_days: null
-  range_partitioning: null
   clustering:
     fields:
       - sample_id

sql/moz-fx-data-shared-prod/fenix_derived/clients_city_seen_v1/schema.yaml

@@ -10,40 +10,40 @@ fields:
 - name: sample_id
   type: INTEGER
   mode: NULLABLE
-  description: sample_id derived from client_id
+  description: A number, 0-99, that samples by client_id and allows filtering data for analysis.
 - name: normalized_channel
   type: STRING
   mode: NULLABLE
   description: The normalized channel the application is being distributed on.
 - name: first_seen_geo_date
   type: DATE
   mode: NULLABLE
-  description: Date when the first seen geo data were captured.
+  description: Date when the first seen geo fields were captured.
 - name: first_seen_geo_city
   type: STRING
   mode: NULLABLE
-  description: First city captured from a client captured on first_seen_geo_date.
+  description: City captured on first_seen_geo_date.
 - name: first_seen_geo_subdivision1
   type: STRING
   mode: NULLABLE
-  description: First major country subdivision, typically a state, province, or county captured on first_seen_geo_date.
+  description: Major country subdivision, typically a state, province, or county captured on first_seen_geo_date.
 - name: first_seen_geo_subdivision2
   type: STRING
   mode: NULLABLE
   description: Second major country subdivision; not applicable for most countries captured on first_seen_geo_date.
 - name: last_seen_geo_date
   type: DATE
   mode: NULLABLE
-  description: Date when the last seen geo data were captured.
+  description: Date when the last seen geo fields were captured.
 - name: last_seen_geo_city
   type: STRING
   mode: NULLABLE
-  description: Last city captured from a client on last_seen_geo_city.
+  description: City captured on last_seen_geo_city.
 - name: last_seen_geo_subdivision1
   type: STRING
   mode: NULLABLE
-  description: First major country subdivision, typically a state, province, or county captured on last_seen_geo_city.
+  description: Major country subdivision, typically a state, province, or county captured on last_seen_geo_date.
 - name: last_seen_geo_subdivision2
   type: STRING
   mode: NULLABLE
-  description: Second major country subdivision; not applicable for most countries captured on last_seen_geo_city.
+  description: Second major country subdivision; not applicable for most countries captured on last_seen_geo_date.

sql/moz-fx-data-shared-prod/firefox_desktop_derived/clients_city_seen_v1/metadata.yaml

@@ -1,19 +1,24 @@
 friendly_name: Firefox Desktop Clients City Seen
 description: |-
-  This table captures the first and last seen geo attributes for each client_id and normalized channel.
+  This table stores the first-seen and last-seen geo attributes for each (client_id, normalized_channel).
+  The table was initialized from stable tables (with ~2 years of retention), so the initial dates reflect the earliest/latest
+  observations within that window.  It then updates daily using live tables, replacing last-seen fields for existing
+  clients and adding new clients with first-seen geo attributes that do not yet exist in the table.
+  Implementation Plan: https://docs.google.com/document/d/1S8yVEwJjtJy3Pd8cn_BHRhgxllVnoxKylGCpuMyqWNQ/edit?usp=sharing
 owners:
   - [email protected]
 labels:
-  change_controlled: true
   incremental: true
   schedule: daily
   table_type: client_level
   dag: bqetl_clients_city_seen
 scheduling:
   dag_name: bqetl_clients_city_seen
-  task_group: firefox_desktop_clients_city_seen
+  task_name: firefox_desktop_clients_city_seen_v1
   depends_on_past: true
   date_partition_parameter: null
+  parameters:
+    - submission_date:DATE:
   depends_on:
     - task_id: copy_deduplicate_all
       dag_name: copy_deduplicate
@@ -24,7 +29,6 @@ bigquery:
     field: last_seen_geo_date
     require_partition_filter: false
     expiration_days: null
-  range_partitioning: null
   clustering:
     fields:
       - sample_id

sql/moz-fx-data-shared-prod/firefox_desktop_derived/clients_city_seen_v1/schema.yaml

@@ -10,40 +10,40 @@ fields:
 - name: sample_id
   type: INTEGER
   mode: NULLABLE
-  description: sample_id derived from client_id
+  description: A number, 0-99, that samples by client_id and allows filtering data for analysis.
 - name: normalized_channel
   type: STRING
   mode: NULLABLE
   description: The normalized channel the application is being distributed on.
 - name: first_seen_geo_date
   type: DATE
   mode: NULLABLE
-  description: Date when the first seen geo data were captured.
+  description: Date when the first seen geo fields were captured.
 - name: first_seen_geo_city
   type: STRING
   mode: NULLABLE
-  description: First city captured from a client captured on first_seen_geo_date.
+  description: City captured on first_seen_geo_date.
 - name: first_seen_geo_subdivision1
   type: STRING
   mode: NULLABLE
-  description: First major country subdivision, typically a state, province, or county captured on first_seen_geo_date.
+  description: Major country subdivision, typically a state, province, or county captured on first_seen_geo_date.
 - name: first_seen_geo_subdivision2
   type: STRING
   mode: NULLABLE
   description: Second major country subdivision; not applicable for most countries captured on first_seen_geo_date.
 - name: last_seen_geo_date
   type: DATE
   mode: NULLABLE
-  description: Date when the last seen geo data were captured.
+  description: Date when the last seen geo fields were captured.
 - name: last_seen_geo_city
   type: STRING
   mode: NULLABLE
-  description: Last city captured from a client on last_seen_geo_city.
+  description: City captured on last_seen_geo_city.
 - name: last_seen_geo_subdivision1
   type: STRING
   mode: NULLABLE
-  description: First major country subdivision, typically a state, province, or county captured on last_seen_geo_city.
+  description: Major country subdivision, typically a state, province, or county captured on last_seen_geo_date.
 - name: last_seen_geo_subdivision2
   type: STRING
   mode: NULLABLE
-  description: Second major country subdivision; not applicable for most countries captured on last_seen_geo_city.
+  description: Second major country subdivision; not applicable for most countries captured on last_seen_geo_date.

sql_generators/clients_city_seen_v1/templates/metadata.yaml

@@ -1,19 +1,24 @@
 friendly_name: {{ app_value }} Clients City Seen
 description: |-
-  This table captures the first and last seen geo attributes for each client_id and normalized channel.
+  This table stores the first-seen and last-seen geo attributes for each (client_id, normalized_channel).
+  The table was initialized from stable tables (with ~2 years of retention), so the initial dates reflect the earliest/latest
+  observations within that window.  It then updates daily using live tables, replacing last-seen fields for existing
+  clients and adding new clients with first-seen geo attributes that do not yet exist in the table.
+  Implementation Plan: https://docs.google.com/document/d/1S8yVEwJjtJy3Pd8cn_BHRhgxllVnoxKylGCpuMyqWNQ/edit?usp=sharing
 owners:
   - [email protected]
 labels:
-  change_controlled: true
   incremental: true
   schedule: daily
   table_type: client_level
   dag: bqetl_clients_city_seen
 scheduling:
   dag_name: bqetl_clients_city_seen
-  task_group: {{ app_name }}_clients_city_seen
+  task_name: {{ app_name }}_{{ table_name }}
   depends_on_past: true
   date_partition_parameter: null
+  parameters:
+    - submission_date:DATE:{{ds}}
   depends_on:
     - task_id: copy_deduplicate_all
       dag_name: copy_deduplicate
@@ -24,7 +29,6 @@ bigquery:
     field: last_seen_geo_date
     require_partition_filter: false
     expiration_days: null
-  range_partitioning: null
   clustering:
     fields:
       - sample_id

sql_generators/clients_city_seen_v1/templates/schema.yaml

@@ -10,40 +10,40 @@ fields:
 - name: sample_id
   type: INTEGER
   mode: NULLABLE
-  description: sample_id derived from client_id
+  description: A number, 0-99, that samples by client_id and allows filtering data for analysis.
 - name: normalized_channel
   type: STRING
   mode: NULLABLE
   description: The normalized channel the application is being distributed on.
 - name: first_seen_geo_date
   type: DATE
   mode: NULLABLE
-  description: Date when the first seen geo data were captured.
+  description: Date when the first seen geo fields were captured.
 - name: first_seen_geo_city
   type: STRING
   mode: NULLABLE
-  description: First city captured from a client captured on first_seen_geo_date.
+  description: City captured on first_seen_geo_date.
 - name: first_seen_geo_subdivision1
   type: STRING
   mode: NULLABLE
-  description: First major country subdivision, typically a state, province, or county captured on first_seen_geo_date.
+  description: Major country subdivision, typically a state, province, or county captured on first_seen_geo_date.
 - name: first_seen_geo_subdivision2
   type: STRING
   mode: NULLABLE
   description: Second major country subdivision; not applicable for most countries captured on first_seen_geo_date.
 - name: last_seen_geo_date
   type: DATE
   mode: NULLABLE
-  description: Date when the last seen geo data were captured.
+  description: Date when the last seen geo fields were captured.
 - name: last_seen_geo_city
   type: STRING
   mode: NULLABLE
-  description: Last city captured from a client on last_seen_geo_city.
+  description: City captured on last_seen_geo_city.
 - name: last_seen_geo_subdivision1
   type: STRING
   mode: NULLABLE
-  description: First major country subdivision, typically a state, province, or county captured on last_seen_geo_city.
+  description: Major country subdivision, typically a state, province, or county captured on last_seen_geo_date.
 - name: last_seen_geo_subdivision2
   type: STRING
   mode: NULLABLE
-  description: Second major country subdivision; not applicable for most countries captured on last_seen_geo_city.
+  description: Second major country subdivision; not applicable for most countries captured on last_seen_geo_date.