experiment_definitions

Creates, updates, deletes, gets or lists an experiment_definitions resource.

Overview

Name	experiment_definitions
Type	Resource
Id	aws.appconfig.experiment_definitions

Fields

The following fields are returned by SELECT queries:

get_experiment_definition

Name	Datatype	Description
application_id	string	The application ID. (pattern: <code>[a-z0-9]{4,7}</code>)
audience_description	string	A description of the intended audience for the experiment.
audience_rule	string	The rule that defines which users are eligible to be assigned to treatments.
configuration_profile_id	string	The configuration profile ID associated with the experiment. (pattern: <code>[a-z0-9]{4,7}</code>)
control	object	Describes a treatment in an experiment, including its traffic allocation weight and feature flag value.
created_at	string (date-time)	The date and time the experiment definition was created, in ISO 8601 format.
environment_id	string	The environment ID where the experiment runs. (pattern: <code>[a-z0-9]{4,7}</code>)
flag_key	string	The key of the feature flag used by the experiment. (pattern: <code>^[a-z][a-zA-Z0-9_-]{1,64}</code>)
hypothesis	string	The hypothesis that the experiment is designed to validate.
id	string	The experiment definition ID. (pattern: <code>[a-z0-9]{4,7}</code>)
kms_key_identifier	string	The Amazon Resource Name (ARN) of the KMS key used to encrypt experiment data.
launch_criteria	string	The conditions under which the winning treatment should be launched.
name	string	The name of the experiment definition.
status	string	The current status of the experiment definition. Valid values: ACTIVE, IDLE, ARCHIVED. (ACTIVE, IDLE, ARCHIVED)
treatments	array	The list of treatments defined for the experiment.
updated_at	string (date-time)	The date and time the experiment definition was last updated, in ISO 8601 format.

list_experiment_definitions

Name	Datatype	Description
application_id	string	The application ID. (pattern: <code>[a-z0-9]{4,7}</code>)
configuration_profile_id	string	The configuration profile ID associated with the experiment. (pattern: <code>[a-z0-9]{4,7}</code>)
created_at	string (date-time)	The date and time the experiment definition was created, in ISO 8601 format.
environment_id	string	The environment ID where the experiment runs. (pattern: <code>[a-z0-9]{4,7}</code>)
flag_key	string	The key of the feature flag used by the experiment. (pattern: <code>^[a-z][a-zA-Z0-9_-]{1,64}</code>)
hypothesis	string	The hypothesis that the experiment is designed to validate.
id	string	The experiment definition ID. (pattern: <code>[a-z0-9]{4,7}</code>)
name	string	The name of the experiment definition.
status	string	The current status of the experiment definition. (ACTIVE, IDLE, ARCHIVED)
updated_at	string (date-time)	The date and time the experiment definition was last updated, in ISO 8601 format.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get_experiment_definition	select	application_identifier, experiment_definition_identifier, region		Retrieves information about an experiment definition.
list_experiment_definitions	select	region	application_identifier, configuration_profile_identifier, environment_identifier, status, max_results, next_token	Lists the experiment definitions for an account. You can filter results by application, configuration profile, environment, or status.
create_experiment_definition	insert	application_identifier, region, ConfigurationProfileIdentifier, EnvironmentIdentifier, FlagKey, AudienceRule		Creates an experiment definition in AppConfig. An experiment definition describes the purpose, scope, and operational configuration of an experiment, including the target audience, feature flag, and treatment configurations.
update_experiment_definition	update	application_identifier, experiment_definition_identifier, region		Updates an experiment definition. You can update treatments, the control, audience rules, and other properties. You cannot update an experiment definition while an experiment run is active.
delete_experiment_definition	delete	application_identifier, experiment_definition_identifier, region	delete_type	Deletes an experiment definition. You can archive the definition to hide it from the active list while preserving it for future reference, or permanently delete it along with all associated run history.
start_experiment_run	exec	application_identifier, experiment_definition_identifier, region		Starts an experiment run for the specified experiment definition. An experiment run delivers treatments to the target audience and collects metrics. You can start multiple experiment runs from the same experiment definition. Billing for this experiment begins when you call this operation and continues until the experiment is stopped. For pricing details, see AppConfig pricing.
stop_experiment_run	exec	application_identifier, experiment_definition_identifier, run, region		Stops a running experiment. Stopping an experiment run ends audience exposure and returns users to the currently deployed feature flag configuration.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
application_identifier	string	The application ID or name.
experiment_definition_identifier	string	The experiment definition ID or name.
region	string	AWS region (default: us-east-1)
run	integer	The run number to stop.
application_identifier	string	The application ID or name to filter results.
configuration_profile_identifier	string	The configuration profile ID or name to filter results.
delete_type	string	The type of deletion to perform. Valid values include archive (hide but preserve) and permanent (delete permanently).
environment_identifier	string	The environment ID or name to filter results.
max_results	integer	The maximum number of items to return for this call.
next_token	string	A token to start the list from a previously truncated response.
status	string	A filter for the experiment definition status.

SELECT examples

get_experiment_definition

Retrieves information about an experiment definition.

SELECT
application_id,
audience_description,
audience_rule,
configuration_profile_id,
control,
created_at,
environment_id,
flag_key,
hypothesis,
id,
kms_key_identifier,
launch_criteria,
name,
status,
treatments,
updated_at
FROM aws.appconfig.experiment_definitions
WHERE application_identifier = '{{ application_identifier }}' -- required
AND experiment_definition_identifier = '{{ experiment_definition_identifier }}' -- required
AND region = '{{ region }}' -- required
;

list_experiment_definitions

Lists the experiment definitions for an account. You can filter results by application, configuration profile, environment, or status.

SELECT
application_id,
configuration_profile_id,
created_at,
environment_id,
flag_key,
hypothesis,
id,
name,
status,
updated_at
FROM aws.appconfig.experiment_definitions
WHERE region = '{{ region }}' -- required
AND application_identifier = '{{ application_identifier }}'
AND configuration_profile_identifier = '{{ configuration_profile_identifier }}'
AND environment_identifier = '{{ environment_identifier }}'
AND status = '{{ status }}'
AND max_results = '{{ max_results }}'
AND next_token = '{{ next_token }}'
;

INSERT examples

create_experiment_definition

Creates an experiment definition in AppConfig. An experiment definition describes the purpose, scope, and operational configuration of an experiment, including the target audience, feature flag, and treatment configurations.

INSERT INTO aws.appconfig.experiment_definitions (
Name,
ConfigurationProfileIdentifier,
EnvironmentIdentifier,
FlagKey,
Treatments,
Control,
AudienceRule,
Hypothesis,
AudienceDescription,
LaunchCriteria,
Tags,
application_identifier,
region
)
SELECT 
'{{ Name }}',
'{{ ConfigurationProfileIdentifier }}' /* required */,
'{{ EnvironmentIdentifier }}' /* required */,
'{{ FlagKey }}' /* required */,
'{{ Treatments }}',
'{{ Control }}',
'{{ AudienceRule }}' /* required */,
'{{ Hypothesis }}',
'{{ AudienceDescription }}',
'{{ LaunchCriteria }}',
'{{ Tags }}',
'{{ application_identifier }}',
'{{ region }}'
RETURNING
application_id,
audience_description,
audience_rule,
configuration_profile_id,
control,
created_at,
environment_id,
flag_key,
hypothesis,
id,
kms_key_identifier,
launch_criteria,
name,
status,
treatments,
updated_at
;

Manifest

# Description fields are for documentation purposes
- name: experiment_definitions
props:
  - name: application_identifier
    value: "{{ application_identifier }}"
    description: Required parameter for the experiment_definitions resource.
  - name: region
    value: "{{ region }}"
    description: Required parameter for the experiment_definitions resource.
  - name: Name
    value: "{{ Name }}"
  - name: ConfigurationProfileIdentifier
    value: "{{ ConfigurationProfileIdentifier }}"
  - name: EnvironmentIdentifier
    value: "{{ EnvironmentIdentifier }}"
  - name: FlagKey
    value: "{{ FlagKey }}"
  - name: Treatments
    value:
      - Weight: {{ Weight }}
        Description: "{{ Description }}"
        FlagValue:
          Enabled: {{ Enabled }}
          AttributeValues: "{{ AttributeValues }}"
  - name: Control
    description: |
      Input structure for defining a treatment when creating or updating an experiment definition.
    value:
      Weight: {{ Weight }}
      Description: "{{ Description }}"
      FlagValue:
        Enabled: {{ Enabled }}
        AttributeValues: "{{ AttributeValues }}"
  - name: AudienceRule
    value: "{{ AudienceRule }}"
  - name: Hypothesis
    value: "{{ Hypothesis }}"
  - name: AudienceDescription
    value: "{{ AudienceDescription }}"
  - name: LaunchCriteria
    value: "{{ LaunchCriteria }}"
  - name: Tags
    value: "{{ Tags }}"

UPDATE examples

update_experiment_definition

Updates an experiment definition. You can update treatments, the control, audience rules, and other properties. You cannot update an experiment definition while an experiment run is active.

UPDATE aws.appconfig.experiment_definitions
SET 
Treatments = '{{ Treatments }}',
Control = '{{ Control }}',
Hypothesis = '{{ Hypothesis }}',
AudienceRule = '{{ AudienceRule }}',
AudienceDescription = '{{ AudienceDescription }}',
LaunchCriteria = '{{ LaunchCriteria }}'
WHERE 
application_identifier = '{{ application_identifier }}' --required
AND experiment_definition_identifier = '{{ experiment_definition_identifier }}' --required
AND region = '{{ region }}' --required
RETURNING
application_id,
audience_description,
audience_rule,
configuration_profile_id,
control,
created_at,
environment_id,
flag_key,
hypothesis,
id,
kms_key_identifier,
launch_criteria,
name,
status,
treatments,
updated_at;

DELETE examples

delete_experiment_definition

Deletes an experiment definition. You can archive the definition to hide it from the active list while preserving it for future reference, or permanently delete it along with all associated run history.

DELETE FROM aws.appconfig.experiment_definitions
WHERE application_identifier = '{{ application_identifier }}' --required
AND experiment_definition_identifier = '{{ experiment_definition_identifier }}' --required
AND region = '{{ region }}' --required
AND delete_type = '{{ delete_type }}'
;

Lifecycle Methods

start_experiment_run

Starts an experiment run for the specified experiment definition. An experiment run delivers treatments to the target audience and collects metrics. You can start multiple experiment runs from the same experiment definition. Billing for this experiment begins when you call this operation and continues until the experiment is stopped. For pricing details, see AppConfig pricing.

EXEC aws.appconfig.experiment_definitions.start_experiment_run 
@application_identifier='{{ application_identifier }}' --required, 
@experiment_definition_identifier='{{ experiment_definition_identifier }}' --required, 
@region='{{ region }}' --required 
@@json=
'{
"Description": "{{ Description }}", 
"ExposurePercentage": {{ ExposurePercentage }}, 
"TreatmentOverrides": "{{ TreatmentOverrides }}", 
"Tags": "{{ Tags }}", 
"DeploymentParameters": "{{ DeploymentParameters }}"
}'
;

stop_experiment_run

Stops a running experiment. Stopping an experiment run ends audience exposure and returns users to the currently deployed feature flag configuration.

EXEC aws.appconfig.experiment_definitions.stop_experiment_run 
@application_identifier='{{ application_identifier }}' --required, 
@experiment_definition_identifier='{{ experiment_definition_identifier }}' --required, 
@run='{{ run }}' --required, 
@region='{{ region }}' --required 
@@json=
'{
"Result": "{{ Result }}", 
"DeploymentParameters": "{{ DeploymentParameters }}"
}'
;