Batch segmentation guide
- Topics:
- Segments
CREATED FOR:
- User
Batch segmentation is a segmentation evaluation method that lets you move profile data all at once to create corresponding audiences.
With batch segmentation, you can create detailed and rich audiences, and run segmentation jobs to determine when you want this data propagated to downstream services.
Eligible query types
All queries are eligible for batch segmentation.
Create audience
You can create an audience that is evaluated using batch segmentation using either the Segmentation Service API or through Audience Portal in the UI.
API format
POST /segment/definitions
Request
curl -X POST https://platform.adobe.io/data/core/ups/segment/definitions
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
-d '{
"name": "People in the USA",
"description: "An audience that looks for people who live in the USA",
"expression": {
"type": "PQL",
"format": "pql/text",
"value": "homeAddress.country = \"US\""
},
"evaluationInfo": {
"batch": {
"enabled": true
},
"continuous": {
"enabled": false
},
"synchronous": {
"enabled": false
}
},
"schema": {
"name": "_xdm.context.profile"
}
}'
Response
A successful response returns HTTP status 200 with details of your newly created segment definition.
{
"id": "4afe34ae-8c98-4513-8a1d-67ccaa54bc05",
"schema": {
"name": "_xdm.context.profile"
},
"profileInstanceId": "ups",
"imsOrgId": "{ORG_ID}",
"sandbox": {
"sandboxId": "28e74200-e3de-11e9-8f5d-7f27416c5f0d",
"sandboxName": "prod",
"type": "production",
"default": true
},
"name": "People in the USA",
"description": "An audience that looks for people who live in the USA",
"expression": {
"type": "PQL",
"format": "pql/text",
"value": "homeAddress.country = \"US\""
},
"evaluationInfo": {
"batch": {
"enabled": true
},
"continuous": {
"enabled": false
},
"synchronous": {
"enabled": false
}
},
"dataGovernancePolicy": {
"excludeOptOut": true
},
"creationTime": 0,
"updateEpoch": 1579292094,
"updateTime": 1579292094000
}
More information about using this endpoint can be found in the segment definition endpoint guide.
In Audience Portal, select Create audience.
A popover appears. Select Build rules to enter Segment Builder.
After creating your segment definition, select Batch as the Evaluation method.
To learn more about creating segment definitions, please read the Segment Builder guide
Retrieve audiences
You can retrieve all audiences that are evaluated using batch segmentation using either the Segmentation Service API or through Audience Portal in the UI.
Retrieve a list of all segment definitions that are evaluated using batch segmentation within your organization by making a GET request to the /segment/definitions endpoint.
API format
You must include the query parameter evaluationInfo.batch.enabled=true in the request path to retrieve segment definitions evaluated using batch segmentation.
GET /segment/definitions?evaluationInfo.batch.enabled=true
Request
curl -X GET \
'https://platform.adobe.io/data/core/ups/segment/definitions?evaluationInfo.batch.enabled=true' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
Response
A successful response returns HTTP status 200 with an array of segment definitions in your organization that are evaluated using batch segmentation.
{
"segments": [
{
"id": "15063cb-2da8-4851-a2e2-bf59ddd2f004",
"schema": {
"name": "_xdm.context.profile"
},
"ttlInDays": 30,
"imsOrgId": "{ORG_ID}",
"sandbox": {
"sandboxId": "",
"sandboxName": "",
"type": "production",
"default": true
},
"name": " People who are NOT on their homepage ",
"expression": {
"type": "PQL",
"format": "pql/text",
"value": "select var1 from xEvent where var1._experience.analytics.endUser.firstWeb.webPageDetails.isHomePage = false"
},
"evaluationInfo": {
"batch": {
"enabled": true
},
"continuous": {
"enabled": false
},
"synchronous": {
"enabled": false
}
},
"creationTime": 1572029711000,
"updateEpoch": 1572029712000,
"updateTime": 1572029712000
},
{
"id": "f15063cb-2da8-4851-a2e2-bf59ddd2f004",
"schema": {
"name": "_xdm.context.profile"
},
"ttlInDays": 30,
"imsOrgId": "{ORG_ID}",
"sandbox": {
"sandboxId": "",
"sandboxName": "",
"type": "production",
"default": true
},
"name": "Homepage_continuous",
"description": "People who are on their homepage - continuous",
"expression": {
"type": "PQL",
"format": "pql/text",
"value": "select var1 from xEvent where var1._experience.analytics.endUser.firstWeb.webPageDetails.isHomePage = true"
},
"evaluationInfo": {
"batch": {
"enabled": true
},
"continuous": {
"enabled": true
},
"synchronous": {
"enabled": false
}
},
"creationTime": 1572021085000,
"updateEpoch": 1572021086000,
"updateTime": 1572021086000
}
],
"page": {
"totalCount": 2,
"totalPages": 1,
"sortField": "creationTime",
"sort": "desc",
"pageSize": 2,
"limit": 100
},
"link": {}
}
More detailed information about the segment definition returned can be found in the segment definitions endpoint guide.
You can retrieve all the audiences that are enabled for batch segmentation within your organization by using filters in Audience Portal. Select the
Within the available filters, go to Update frequency and select “Batch”. Using this filter displays all audiences in your organization that are evaluated using batch segmentation.
To learn more about viewing audiences in Experience Platform, please read the Audience Portal guide.
Next steps
This guide explains how to create a segment definition that can be evaluated using batch segmentation on Adobe Experience Platform.
To learn more about using the Experience Platform user interface, please read the Segmentation user guide.
For frequently asked questions about batch segmentation, please read the batch segmentation section of the FAQ.