From e3c9ab351a24cd47e0873e6b55ac81c7fa4c4bc2 Mon Sep 17 00:00:00 2001 From: jamescott Date: Thu, 4 Dec 2025 00:10:28 -0800 Subject: [PATCH 1/5] add best practice for very small test audiences --- amperity_reference/source/sandboxes.rst | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/amperity_reference/source/sandboxes.rst b/amperity_reference/source/sandboxes.rst index eb371662c..508000df5 100644 --- a/amperity_reference/source/sandboxes.rst +++ b/amperity_reference/source/sandboxes.rst @@ -217,6 +217,7 @@ Amperity recommends the following patterns when working with sandboxes: * :ref:`Delete sandbox on promote ` * :ref:`Run partial workflows ` * :ref:`Short-lived sandboxes ` +* :ref:`Very small test audiences ` .. sandboxes-best-practice-end @@ -337,7 +338,7 @@ Run partial workflows Each workflow should be validated before promoting changes to production using a partial workflow. -* A partial workflow pulls data from upstream sources to the sandbox, run Stitch, and then refresh databases. +* A partial workflow pulls data from upstream sources to the sandbox, runs Stitch, and then refreshes databases. * A partial workflow *does not* run orchestrations *or* campaigns. This ensures that data in your sandbox is not inadvertently sent to any downstream workflows. .. sandboxes-best-practice-partial-workflows-end @@ -366,6 +367,18 @@ A sandbox should be short-lived and should be used to make small, iterative chan .. sandboxes-best-practice-short-lived-end +.. _sandboxes-best-practice-small-test-audiences: + +Very small test audiences +-------------------------------------------------- + +.. sandboxes-best-practice-small-test-audiences-start + +To validate configuration updates for destinations use a manual workflow and a query to send a very small test audience from Amperity to the configured destination. Use the **LIMIT** clause at the end of the query to enforce the size of the very small audience. For example: ``LIMIT 10`` or ``LIMIT 100``. + +.. sandboxes-best-practice-small-test-audiences-end + + .. _sandboxes-howtos: How-tos From b909bb75ff29ca589a01b704a1111445740f7618 Mon Sep 17 00:00:00 2001 From: jamescott Date: Thu, 4 Dec 2025 00:10:37 -0800 Subject: [PATCH 2/5] links to sandbox topic and sections --- shared/destination_settings.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/shared/destination_settings.rst b/shared/destination_settings.rst index 01ce10374..5aac493b3 100755 --- a/shared/destination_settings.rst +++ b/shared/destination_settings.rst @@ -486,10 +486,11 @@ Use the **Column name** setting to specify the name of the row number column in .. setting-common-sandbox-recommendation-start -Use a sandbox to configure a destination for |destination-name|. Before promoting your changes, send a test audience, and then verify the results in |destination-name|. After verifying the end-to-end workflow, push the destination from the sandbox to production. +Amperity recommends using a sandbox to configure a destination for |destination-name|. Before promoting your changes to production from the sandbox, consider sending a very small test audience using a query and an orchestration to verify the results in |destination-name|. After verifying the end-to-end workflow, push the configuration changes from the sandbox to production. -.. setting-common-sandbox-recommendation-end +.. tip:: Learn more about `how sandboxes work <../reference/sandboxes.html>`__ and sandbox best practices such as `deleting sandboxes after configuration changes are promoted to production <..../reference/sandboxes.html#sandboxes-best-practice-delete-on-promote>`__, `using short-lived sandboxes <../reference/sandboxes.html#short-lived-sandboxes>`__, and `sending very small test audiences <../reference/sandboxes.html#short-lived-small-test-audiences>`__. +.. setting-common-sandbox-recommendation-end **Split outputs** From 7c36eb9d6cee6cd33c9b6941aaa9ecb8905e5e50 Mon Sep 17 00:00:00 2001 From: jamescott Date: Thu, 4 Dec 2025 00:15:10 -0800 Subject: [PATCH 3/5] fix path --- shared/destination_settings.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/shared/destination_settings.rst b/shared/destination_settings.rst index 5aac493b3..72b7159a5 100755 --- a/shared/destination_settings.rst +++ b/shared/destination_settings.rst @@ -488,7 +488,7 @@ Use the **Column name** setting to specify the name of the row number column in Amperity recommends using a sandbox to configure a destination for |destination-name|. Before promoting your changes to production from the sandbox, consider sending a very small test audience using a query and an orchestration to verify the results in |destination-name|. After verifying the end-to-end workflow, push the configuration changes from the sandbox to production. -.. tip:: Learn more about `how sandboxes work <../reference/sandboxes.html>`__ and sandbox best practices such as `deleting sandboxes after configuration changes are promoted to production <..../reference/sandboxes.html#sandboxes-best-practice-delete-on-promote>`__, `using short-lived sandboxes <../reference/sandboxes.html#short-lived-sandboxes>`__, and `sending very small test audiences <../reference/sandboxes.html#short-lived-small-test-audiences>`__. +.. tip:: Learn more about `how sandboxes work <../reference/sandboxes.html>`__ and sandbox best practices such as `deleting sandboxes after configuration changes are promoted to production <../reference/sandboxes.html#sandboxes-best-practice-delete-on-promote>`__, `using short-lived sandboxes <../reference/sandboxes.html#short-lived-sandboxes>`__, and `sending very small test audiences <../reference/sandboxes.html#short-lived-small-test-audiences>`__. .. setting-common-sandbox-recommendation-end From d5e9cf46fa5235932ae36286a0e13106d734d677 Mon Sep 17 00:00:00 2001 From: jamescott Date: Thu, 4 Dec 2025 08:25:53 -0800 Subject: [PATCH 4/5] add included section to operators guide --- amperity_operator/source/sandboxes.rst | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/amperity_operator/source/sandboxes.rst b/amperity_operator/source/sandboxes.rst index c5358735f..1ba000713 100755 --- a/amperity_operator/source/sandboxes.rst +++ b/amperity_operator/source/sandboxes.rst @@ -147,6 +147,16 @@ Short-lived sandboxes :end-before: .. sandboxes-best-practice-short-lived-end +.. _sandboxes-best-practice-small-test-audiences: + +Very small test audiences +-------------------------------------------------- + +.. include:: ../../amperity_reference/source/sandboxes.rst + :start-after: .. sandboxes-best-practice-small-test-audiences-start + :end-before: .. sandboxes-best-practice-small-test-audiences-end + + .. _sandboxes-howtos: Common activities From 062c0e4dea082c6bfab52130087a9d06f93d9e33 Mon Sep 17 00:00:00 2001 From: jamescott Date: Thu, 4 Dec 2025 14:28:49 -0800 Subject: [PATCH 5/5] edit --- amperity_reference/source/sandboxes.rst | 43 +++++++++++++++++++++++-- 1 file changed, 41 insertions(+), 2 deletions(-) diff --git a/amperity_reference/source/sandboxes.rst b/amperity_reference/source/sandboxes.rst index 508000df5..d70d0b42b 100644 --- a/amperity_reference/source/sandboxes.rst +++ b/amperity_reference/source/sandboxes.rst @@ -218,7 +218,6 @@ Amperity recommends the following patterns when working with sandboxes: * :ref:`Run partial workflows ` * :ref:`Short-lived sandboxes ` * :ref:`Very small test audiences ` - .. sandboxes-best-practice-end @@ -367,6 +366,46 @@ A sandbox should be short-lived and should be used to make small, iterative chan .. sandboxes-best-practice-short-lived-end +.. sandboxes-best-practice-small-test-audiences-start + +Use very small audiences to test and validate configuration updates for destinations. In a sandbox you can build a query that returns an audience that matches the requirements for the downstream use case. Use the **LIMIT** clause at the end of the query to limit the size of the audience to the specified integer. For example: ``LIMIT 10`` returns an audience with ten members and ``LIMIT 100`` returns an audience with one hundred members. Use a manual orchestration to send the test audience to the destination. Log into the destination and verify the audience was received and is correctly formatted for your use case. + +.. tip:: Campaigns do not run in sandboxes. If you must use a segment and campaign to test an audience you must do this in production. Promote the sandbox with the configuration updates, and then build a query that is unique by Amperity ID with the same size limits. Make this query available to the **Segments** page, and then build a segment using that query. Add the query to the campaign, and then run the test with the limited audience size. + +.. sandboxes-best-practice-small-test-audiences-end + + +.. _sandboxes-howtos: + +How-tos +================================================== + +.. sandboxes-howtos-start + +Tasks related to working with sandboxes in Amperity: + +* :ref:`Access a sandbox ` +* :ref:`Add a sandbox ` +* :ref:`Delete a sandbox ` +* :ref:`Edit sandbox details ` +* :ref:`Open a sandbox ` +* :ref:`Pull updates from production ` +* :ref:`Promote changes ` +* :ref:`Resolve validation issues ` +* :ref:`Review changes ` +* :ref:`View sandbox details ` +* :ref:`View validation details ` + +.. sandboxes-howtos-end + + +.. _sandboxes-howto-access-sandbox: + +Access a sandbox +-------------------------------------------------- + +.. sandboxes-howto-access-sandbox-start +======= .. _sandboxes-best-practice-small-test-audiences: Very small test audiences @@ -379,7 +418,7 @@ To validate configuration updates for destinations use a manual workflow and a q .. sandboxes-best-practice-small-test-audiences-end -.. _sandboxes-howtos: +>>>>>>> External Changes How-tos ==================================================