feat(nimbus): Add targetingSql field to v8 API (#16354)

Because

- `bigquery-etl` needs the translated SQL to run sizing queries against
`nimbus_targeting_context` for the draft experiment to estimate the
population

This commit

- Adds `targetingSql` field to `/api/v8/experiments/` API response
- For Draft experiments: returns the translated BigQuery SQL WHERE
clause and any warnings for untranslatable attributes
- For Live/Complete experiments: returns null — they don't need sizing
- bigquery-etl reads this field directly, no JEXL parser needed on its
side

Fixes #16352

---------

Co-authored-by: Yashika Khurana <yashikakhurana@Yashikas-MBP.home.local>
Co-authored-by: Yashika Khurana <yashikakhurana@Yashikas-MacBook-Pro.local>

Author: 3 people

docs/experimenter/openapi-schema.json

@@ -1660,6 +1660,10 @@
           "requiresRestart": {
             "type": "string",
             "readOnly": true
+          },
+          "targetingSql": {
+            "type": "string",
+            "readOnly": true
           }
         },
         "required": [

docs/experimenter/swagger-ui.html

@@ -1672,6 +1672,10 @@
           "requiresRestart": {
             "type": "string",
             "readOnly": true
+          },
+          "targetingSql": {
+            "type": "string",
+            "readOnly": true
           }
         },
         "required": [

experimenter/experimenter/experiments/api/v8/serializers.py

@@ -5,6 +5,7 @@
 from django.conf import settings
 from rest_framework import serializers
 
+from experimenter.experiments.jexl_to_sql import jexl_to_sql
 from experimenter.experiments.models import (
     NimbusBranch,
     NimbusBucketRange,
@@ -120,6 +121,7 @@ class NimbusExperimentSerializer(serializers.ModelSerializer):
     firefoxLabsDescriptionLinks = serializers.SerializerMethodField()
     firefoxLabsGroup = serializers.ReadOnlyField(source="firefox_labs_group")
     requiresRestart = serializers.ReadOnlyField(source="requires_restart")
+    targetingSql = serializers.SerializerMethodField()
 
     class Meta:
         model = NimbusExperiment
@@ -160,8 +162,20 @@ class Meta:
             "firefoxLabsDescriptionLinks",
             "firefoxLabsGroup",
             "requiresRestart",
+            "targetingSql",
         )
 
+    def get_targetingSql(self, obj):
+        if obj.status != NimbusExperiment.Status.DRAFT:
+            return None
+        result = jexl_to_sql(obj.targeting)
+        if result.sql is None and not result.warnings:
+            return None
+        return {
+            "sql": result.sql,
+            "warnings": result.warnings,
+        }
+
     def _holdback_enrollment_end(self, obj):
         if obj.is_holdback and not obj.end_date and not obj.actual_enrollment_end_date:
             return datetime.date.today() - datetime.timedelta(

experimenter/experimenter/experiments/jexl_to_sql.py

@@ -293,6 +293,11 @@ def _array_to_sql(node: ArrayLiteral, warnings: list[str]) -> Optional[str]:
 def _transform_to_sql(node: Transform, warnings: list[str]) -> Optional[str]:
     subject_path = _identifier_path(node.subject)
 
+    # If the subject itself is untranslatable, warn about it rather than the transform
+    if subject_path and _is_untranslatable(subject_path):
+        _add_warning(warnings, subject_path)
+        return None
+
     if node.name == "date":
         # profileAgeCreated is stored as epoch ms — return column directly for arithmetic
         if subject_path == "profileAgeCreated":

experimenter/experimenter/experiments/tests/api/v8/test_serializers.py

@@ -8,13 +8,15 @@
 
 from experimenter.base.tests.factories import LocaleFactory
 from experimenter.experiments.api.v8.serializers import NimbusExperimentSerializer
+from experimenter.experiments.jexl_to_sql import jexl_to_sql
 from experimenter.experiments.models import NimbusBranchFeatureValue, NimbusExperiment
 from experimenter.experiments.tests.factories import (
     TEST_LOCALIZATIONS,
     NimbusBranchFactory,
     NimbusExperimentFactory,
     NimbusFeatureConfigFactory,
 )
+from experimenter.targeting.constants import WINDOWS_ONLY
 
 
 class TestNimbusExperimentSerializer(TestCase):
@@ -496,4 +498,67 @@ def _experiment_data_without_branches_and_featureIds(
             "firefoxLabsDescriptionLinks": None,
             "firefoxLabsGroup": None,
             "requiresRestart": False,
+            "targetingSql": None,  # None for non-Draft experiments
         }
+
+    def test_targeting_sql_populated_for_draft(self):
+        _os = "metrics.object.nimbus_targeting_context_os"
+        experiment = NimbusExperimentFactory.create_with_lifecycle(
+            NimbusExperimentFactory.Lifecycles.CREATED,
+            targeting_config_slug=WINDOWS_ONLY.slug,
+            channels=[],
+            firefox_min_version=NimbusExperiment.Version.NO_VERSION,
+            firefox_max_version=NimbusExperiment.Version.NO_VERSION,
+        )
+        experiment.locales.clear()
+        experiment.countries.clear()
+        experiment.languages.clear()
+
+        expected_sql = (
+            f"(NOT CAST(JSON_VALUE({_os}, '$.isMac') AS BOOL)"
+            f" AND NOT CAST(JSON_VALUE({_os}, '$.isLinux') AS BOOL))"
+        )
+
+        jexl_result = jexl_to_sql(experiment.targeting)
+        self.assertEqual(jexl_result.sql, expected_sql)
+        self.assertEqual(jexl_result.warnings, [])
+
+        # Validate the serializer returns the same SQL in the correct shape
+        serializer = NimbusExperimentSerializer(experiment)
+        self.assertEqual(
+            serializer.data["targetingSql"],
+            {"sql": expected_sql, "warnings": []},
+        )
+
+    def test_targeting_sql_with_warnings_for_draft(self):
+        # relay_user uses attachedFxAOAuthClients which is KNOWN_UNTRANSLATABLE
+        # → sql is None, warning is attachedFxAOAuthClients
+        experiment = NimbusExperimentFactory.create_with_lifecycle(
+            NimbusExperimentFactory.Lifecycles.CREATED,
+            targeting_config_slug="relay_user",
+            channels=[],
+            firefox_min_version=NimbusExperiment.Version.NO_VERSION,
+            firefox_max_version=NimbusExperiment.Version.NO_VERSION,
+        )
+        experiment.locales.clear()
+        experiment.countries.clear()
+        experiment.languages.clear()
+
+        # relay_user uses attachedFxAOAuthClients (KNOWN_UNTRANSLATABLE) → sql=None
+        jexl_result = jexl_to_sql(experiment.targeting)
+        self.assertIsNone(jexl_result.sql)
+        self.assertEqual(jexl_result.warnings, ["attachedFxAOAuthClients"])
+
+        # Serializer should produce the same result as jexl_to_sql
+        serializer = NimbusExperimentSerializer(experiment)
+        self.assertEqual(
+            serializer.data["targetingSql"],
+            {"sql": jexl_result.sql, "warnings": jexl_result.warnings},
+        )
+
+    def test_targeting_sql_none_for_live_experiment(self):
+        experiment = NimbusExperimentFactory.create_with_lifecycle(
+            NimbusExperimentFactory.Lifecycles.LIVE_ENROLLING,
+        )
+        serializer = NimbusExperimentSerializer(experiment)
+        self.assertIsNone(serializer.data["targetingSql"])

experimenter/experimenter/experiments/tests/test_jexl_to_sql.py

@@ -181,7 +181,7 @@ def test_untranslatable_returns_none_and_warning(self, _name, jexl, expected_war
             (
                 "length_untranslatable_subject",
                 "attachedFxAOAuthClients|length >= 1",
-                "|length",
+                "attachedFxAOAuthClients",
             ),
             ("preference_value_variable", "someVar|preferenceValue", "|preferenceValue"),
             (