Data / Find items

Task in alpha phase

This Data Factory task is in phase. You can contact the Product-Live team at contact@product-live.com if you want more details and get an early access.

This task allows to find items. Items are the individual records/rows in a table, representing products or other entities.

Task name:

Examples

JSON input - Find items by ID

{
    "name": "data-item-find",
    "taskReferenceName": "find_items",
    "description": "Find items by their IDs",
    "type": "SUB_WORKFLOW",
    "optional": false,
    "inputParameters": {
        "findMode": "REQUEST",
        "request": {
            "method": "INLINE",
            "contentType": "application/json",
            "model": "default",
            "json": {
                "context": {
                    "partitionId": "2342"
                },
                "criteria": {
                    "type": "in",
                    "field": "id",
                    "value": ["123456", "789012"]
                }
            }
        }
    }
}

JSON input - Find items by partition key (no id needed)

{
    "name": "data-item-find",
    "taskReferenceName": "find_items",
    "description": "Find items in a partition referenced by its business keys",
    "type": "SUB_WORKFLOW",
    "optional": false,
    "inputParameters": {
        "findMode": "REQUEST",
        "request": {
            "method": "INLINE",
            "contentType": "application/json",
            "model": "default",
            "json": {
                "context": {
                    "tableKey": "PRODUCTS",
                    "partitionKey": "ACTIVES"
                },
                "criteria": {
                    "type": "in",
                    "field": "id",
                    "value": ["123456", "789012"]
                }
            }
        }
    }
}

JSON input - Find items by field value (e.g. EAN)

{
    "name": "data-item-find",
    "taskReferenceName": "find_items",
    "description": "Find items by EAN code",
    "type": "SUB_WORKFLOW",
    "optional": false,
    "inputParameters": {
        "findMode": "REQUEST",
        "request": {
            "method": "INLINE",
            "contentType": "application/json",
            "model": "default",
            "json": {
                "context": {
                    "partitionId": "2342"
                },
                "criteria": {
                    "type": "eq",
                    "caseSensitive": true,
                    "field": {
                        "target": "item.fields",
                        "key": "EAN_13"
                    },
                    "value": "3838782464300"
                }
            }
        }
    }
}

JSON input - Find every item in a single partition (findMode=ALL)

{
    "name": "data-item-find",
    "taskReferenceName": "find_all_items_in_partition",
    "description": "Find every item in a single partition",
    "type": "SUB_WORKFLOW",
    "optional": false,
    "inputParameters": {
        "findMode": "ALL",
        "request": {
            "method": "INLINE",
            "contentType": "application/json",
            "model": "default",
            "json": {
                "context": {
                    "partitionId": "2342"
                },
                "options": {
                    "limit": 500
                }
            }
        }
    }
}

JSON input - Find items across every partition of ONE table (findOptions.partitionSelection=TABLE)

{
    "name": "data-item-find",
    "taskReferenceName": "find_items_in_table",
    "description": "Find items matching a list of EANs across every partition of the PRODUCTS table",
    "type": "SUB_WORKFLOW",
    "optional": false,
    "inputParameters": {
        "findMode": "REQUEST",
        "findOptions": {
            "partitionSelection": "TABLE",
            "tableKey": "PRODUCTS"
        },
        "request": {
            "method": "INLINE",
            "contentType": "application/json",
            "model": "default",
            "json": {
                "criteria": {
                    "type": "in",
                    "field": {
                        "target": "item.fields",
                        "key": "EAN_13"
                    },
                    "value": ["8003437047848", "5011546052536"]
                }
            }
        }
    }
}

JSON input - Find items across every partition (findOptions.partitionSelection=ALL)

{
    "name": "data-item-find",
    "taskReferenceName": "find_items_all_partitions",
    "description": "Find items by EAN across every partition of the account",
    "type": "SUB_WORKFLOW",
    "optional": false,
    "inputParameters": {
        "findMode": "REQUEST",
        "findOptions": {
            "partitionSelection": "ALL"
        },
        "request": {
            "method": "INLINE",
            "contentType": "application/json",
            "model": "default",
            "json": {
                "criteria": {
                    "type": "eq",
                    "caseSensitive": true,
                    "field": {
                        "target": "item.fields",
                        "key": "EAN_13"
                    },
                    "value": "3838782464300"
                }
            }
        }
    }
}

Definition

Property	Type	Required	Description
			The name (or type) of the task
			The unique name of the task in your job. It is used to reference this task in the workflow.
			The functional description of this task in your job.
			The type of the task. It must be SUB_WORKFLOW.
	:		true: the job continues if there is an error on this task. false: the job fails.
			Input parameters of the task. See below

Inputs Parameters

Property	Type	Required	Description
			The Product-Live API key If not provided, an automatically generated API key will be used to perform the request on behalf of the current user. If provided, the given API key will be used to perform the request.
			ALL: Fetch all elements. REQUEST: Fetch all elements matching certain criteria.
			See below
			Today, application/json and application/xml are supported.
			INLINE: The request body is provided inline in the request object. ATTACHMENT: The request body is provided as an attachment in the request object.
			The request body as a JSON object.
			The options of the request. Available options are: limit, sort, sortOrder.
			The maximum number of elements to be returned by the task. If not set, the task returns the maximum number of elements available. If the limit property is less than the maximum number of elements that can be returned, the task returns the number of elements specified by the limit property.
			The field to sort the elements by.
			The order to sort the elements by. Available orders are: ASC, DESC.
			The criteria of the request. See examples below
			Resolves business keys into ids before the request is sent, so the request can be written without hardcoding ids. See the Lookups reference.
		If request.method == ATTACHMENT	The request body as a file.
			The model/format used in the request. Today, only default is supported.
			Default: [{"mediaType": "application/json", "outputMode": "INLINE", "outputKey": "json"}].
			The media type of the output. Today, application/json and application/xml are supported.
			INLINE: The output is provided inline in the output object. ATTACHMENT: The output is provided as an attachment in the output object. INLINE is only supported for mediaType=application/json
			The key of the output. Either json or xml
			Default: default. The model/format used in the output. Today, only default is supported.
			Number of elements fetched per page when results are retrieved in a paginated way. Default: 200. Maximum: 1000 (values above are clamped).

Specific input parameters

Property	Type	Required	Description
			The context of the request. Must use either form A (partitionId) or form B (tableKey + partitionKey); the two forms are mutually exclusive and mixing technical ids with business keys is rejected.
			Form A - by id. The id of the partition to find items in. Mutually exclusive with tableKey and partitionKey.
			Form B - by business keys. The business key of the table that owns the target partition. Must be paired with partitionKey. The task resolves the table key and the partition key into the corresponding ids before running the find. Mutually exclusive with partitionId.
			Form B - by business keys. The business key of the partition to find items in. Must be paired with tableKey. Mutually exclusive with partitionId.
			Optional request-level options forwarded to the underlying items API (sort, sortOrder, limit, includedFieldKeys, ...).
			A whitelist of root field keys to include in each returned item's fields[]. When omitted, all fields are returned (legacy behaviour). When set to an empty array, items are returned with fields: []. Unknown keys are silently ignored. Root metadata (id, itemMetadata, createdAt, updatedAt, parent, children) is always preserved. Forwarded as repeated query parameters to the items API. The same option can be supplied via an XML request body (see XML example below).
			A list of options for the find operation.
			Controls the partition scope of the search. DEFAULT: search the single partition identified by request.json.context.partitionId (or by tableKey + partitionKey). TABLE: search every partition of the single table designated by findOptions.tableKey. LIST: search an explicit set of partitions, designated by findOptions.partitionIds or by findOptions.tableKey + findOptions.partitionKeys. ALL: search every partition of the account, across all its tables. With TABLE, LIST and ALL, the partition scope lives entirely in findOptions: request.json.context must not designate a partition (see the mutual-exclusivity note below).
			The business key of the table to search. Required by partitionSelection: "TABLE", where it is the only input needed. Also required by partitionSelection: "LIST" when the partitions are designated by partitionKeys (it scopes the key resolution to one table). Forbidden with partitionIds.
			LIST only. The business keys of the partitions to search, within findOptions.tableKey. Non-empty, at most 1000 entries, duplicates removed. Every key must exist, otherwise the task fails and names the missing ones. Mutually exclusive with partitionIds, and forbidden with partitionSelection: "TABLE".
			LIST only. The ids of the partitions to search. Non-empty, at most 1000 entries, duplicates removed. Mutually exclusive with partitionKeys and with tableKey, and forbidden with partitionSelection: "TABLE".

Find mode and partition selection

Items are scoped to a partition, so two parameters together define what is fetched and where the task looks for it:

• findMode controls the matching strategy:
  • REQUEST - only items matching request.json.criteria are returned.
  • ALL - every item is returned, subject to request.json.options.limit. No criteria is needed.
• findOptions.partitionSelection controls the partition scope:
  • DEFAULT (or unset) - search a single partition. It is designated either by its id, in request.json.context.partitionId, or by its business keys, with request.json.context.tableKey + request.json.context.partitionKey.
  • TABLE - search every partition of one table, designated by findOptions.tableKey alone. The task resolves the table key into its id, lists that table's partitions, runs the find for each one and merges the results.
  • LIST - search an explicit set of partitions, designated by findOptions.partitionIds (ids) or by findOptions.tableKey + findOptions.partitionKeys (business keys).
  • ALL - search every partition of the account, across all of its tables.

In the three multi-partition modes the request context no longer designates a partition: the scope lives entirely in findOptions. The two parameters can then be combined freely:

findMode	findOptions.partitionSelection	Items returned
REQUEST	DEFAULT	Items matching criteria in the partition partitionId.
ALL	DEFAULT	Every item in the partition partitionId.
REQUEST	TABLE	Items matching criteria across every partition of the table tableKey.
ALL	TABLE	Every item of the table tableKey.
REQUEST	LIST	Items matching criteria across the listed partitions.
ALL	LIST	Every item of the listed partitions.
REQUEST	ALL	Items matching criteria across every partition of the account.
ALL	ALL	Every item across every partition of the account.

Choosing a partition scope

The three multi-partition modes work the same way and differ only in which partitions end up in the set. Each one first resolves a set of partitions, then runs your request unchanged once per partition, then merges everything into a single result: totalElements is the sum over the partitions, and result.json holds the matching items from all of them, with nothing indicating which partition each item came from. The find is not a single query over several partitions - it is one query per partition - so the cost of the task grows with the size of the set, and a partition that fails to answer fails the whole task.

What separates the modes is therefore how the set is built, which decides both how much gets scanned and how much the caller has to know before calling:

Your situation	Use	Why not the others
You know the table and want all of it, without caring how many partitions it has	TABLE with tableKey	LIST would force you to enumerate the partitions yourself, and to keep that list up to date as partitions are added or renamed. ALL would additionally scan every other table of the account for nothing.
You want a specific subset - one partition, or a few named ones	LIST with partitionKeys or partitionIds	TABLE always takes the whole table. It cannot be narrowed: adding partitionKeys or partitionIds to a TABLE call is rejected rather than applied, precisely so that a request meant for one partition never turns into a silent full-table scan. Switch the mode, don't add a filter.
You don't know which table the items live in	ALL	Broadest and slowest: it lists every table of the account, then every partition of each. Prefer TABLE as soon as you can name the table.

Example - the same list of EANs, across the whole PRODUCTS table:

{
    "findMode": "REQUEST",
    "findOptions": {
        "partitionSelection": "TABLE",
        "tableKey": "PRODUCTS"
    },
    "request": {
        "method": "INLINE",
        "contentType": "application/json",
        "model": "default",
        "json": {
            "criteria": {
                "type": "in",
                "field": {
                    "target": "item.fields",
                    "key": "EAN_13"
                },
                "value": ["8003437047848", "5011546052536"]
            }
        }
    }
}

Each partition of PRODUCTS is searched with that same criteria, and the matches are merged: totalElements is the sum over the partitions, and result.json contains the matching items regardless of which partition each one lives in.

WARNING

request.json.context must not designate a partition in TABLE, LIST or ALL mode. Supplying partitionId, partitionKey, tableKey or tableId there fails the task with findOptions.partitionSelection: "..." is mutually exclusive with request.json.context.{...}, rather than silently picking one of the two scopes. In TABLE mode the table key goes in findOptions.tableKey, never in the request context.

WARNING

TABLE and LIST iterate over at most 1000 partitions per execution. ALL is capped lower: at most 100 tables, and at most 100 partitions per table.

TABLE refuses rather than guesses at both ends of that range: a table with no partition at all fails instead of returning an empty result, and a table that reaches the 1000-partition ceiling fails instead of scanning a silently truncated subset. Use LIST with explicit partitionKeys to work through such a table in bounded batches.

Field targeting

When searching for items, you can target item field values using a special field object syntax instead of a simple string:

Property	Type	Required	Description
			Must be item.fields to target item field values
			The key of the field to search (e.g. EAN_13, TITLE, BRAND)

Example - Search by EAN code:

{
    "criteria": {
        "type": "eq",
        "caseSensitive": true,
        "field": {
            "target": "item.fields",
            "key": "EAN_13"
        },
        "value": "3838782464300"
    }
}

Example - Search items containing text in title:

{
    "criteria": {
        "type": "search",
        "caseSensitive": false,
        "field": {
            "target": "item.fields",
            "key": "TITLE"
        },
        "value": "organic"
    }
}

JSON criteria examples

TIP

The full list of searchable fields and supported operators is documented in the Find request body - Items reference.

Find by ID

{
    "context": {
        "partitionId": "2342"
    },
    "criteria": {
        "type": "eq",
        "field": "id",
        "value": "80303"
    }
}

Find by multiple IDs

{
    "context": {
        "partitionId": "2342"
    },
    "criteria": {
        "type": "in",
        "field": "id",
        "value": ["80303", "80304", "80305"]
    }
}

Find by field value (EAN)

{
    "context": {
        "partitionId": "2342"
    },
    "criteria": {
        "type": "eq",
        "caseSensitive": true,
        "field": {
            "target": "item.fields",
            "key": "EAN_13"
        },
        "value": "3838782464300"
    }
}

XML criteria examples

Find by ID

<?xml version="1.0" encoding="UTF-8"?>
<map xmlns="http://www.w3.org/2005/xpath-functions">
    <map key="context">
        <string key="partitionId">2342</string>
    </map>
    <map key="criteria">
        <string key="field">id</string>
        <string key="type">eq</string>
        <string key="value">80303</string>
    </map>
</map>

Find by partition key

<?xml version="1.0" encoding="UTF-8"?>
<map xmlns="http://www.w3.org/2005/xpath-functions">
    <map key="context">
        <string key="tableKey">PRODUCTS</string>
        <string key="partitionKey">ACTIVES</string>
    </map>
    <map key="criteria">
        <string key="field">id</string>
        <string key="type">eq</string>
        <string key="value">80303</string>
    </map>
</map>

Outputs

Property	Type	Description
		The total number of elements exported by the task
		An object containing the result of the task. Each output key is the key of the output defined in the outputs[].outputKey input parameter.

Json output - outputs[].outputMode=application/json

• result.json is an array of objects as defined in the items API.
• json is the default output key but may be changed by setting the outputKey property.

JSON output

{
    "totalElements": 1,
    "result": {
        "json": [
            {
                "object": "item",
                "id": "1",
                "updatedAt": "2022-05-13T07:54:59.000Z",
                "createdAt": "2022-05-13T07:54:55.000Z",
                "fields": [
                    {
                        "value": {
                            "data": "1234567890123"
                        },
                        "type": "IDENTIFIER",
                        "key": "EAN_13"
                    },
                    {
                        "key": "TITLE_EN",
                        "type": "SINGLE-LINE-TEXT",
                        "value": {
                            "data": "My title"
                        }
                    }
                ],
                "itemMetadata": {
                    "createdAt": "2025-11-18T10:00:00.000Z",
                    "updatedAt": "2025-11-18T10:00:00.000Z",
                    "tableId": "1",
                    "tableKey": "1",
                    "tableOwnerAccountId": "1",
                    "levelId": "1",
                    "levelKey": "1",
                    "partitionId": "1"
                }
            }
        ]
    }
}

XML output - outputs[].outputMode=application/xml

• result.xml is an array of objects as defined in the items API.
• xml is the default output key but may be changed by setting the outputKey property.

XML output

<?xml version="1.1" encoding="UTF-8"?>
   <map xmlns="http://www.w3.org/2005/xpath-functions">
      <array key="operations">
         <map>
            <string key="key">item-0</string>
            <map key="response">
               <string key="object">item</string>
               <string key="id">1</string>
               <string key="updatedAt">2025-11-04T15:26:00.000Z</string>
               <string key="createdAt">2025-11-04T15:26:00.000Z</string>
               <array key="fields">
                  <map>
                     <map key="value">
                        <string key="data">1234567890123</string>
                     </map>
                     <string key="type">IDENTIFIER</string>
                     <string key="key">EAN_13</string>
                  </map>
                  <map>
                     <string key="key">TITLE_EN</string>
                     <string key="type">SINGLE-LINE-TEXT</string>
                     <map key="value">
                        <string key="data">My title</string>
                     </map>
                  </map>
               </array>
               <map key="itemMetadata">
                  <string key="createdAt">2025-11-18T10:00:00.000Z</string>
                  <string key="updatedAt">2025-11-18T10:00:00.000Z</string>
                  <string key="tableId">1</string>
                  <string key="tableKey">1</string>
                  <string key="tableOwnerAccountId">1</string>
                  <string key="levelId">1</string>
                  <string key="levelKey">1</string>
                  <string key="partitionId">1</string>
               </map>
            </map>
         </map>
      </array>
   </map>
</map>

• The default format follow the W3C JSON-to-XML function.
• To be noted:
  • Illegal characters are escaped (replaced with numeric character references).
  • When a json object presents a duplicate key, the first value is kept.

Limits and additional notes

• When the outputMode=INLINE is selected, the maximum number of elements returned by this task is limited to 1000. If more elements are to be returned, the task ends with an error. To export up to the maximum of elements, use the limit input parameter to limit the number of elements return.

Additional examples

Find items by multiple field values

job.json

{
    "name": "data-item-find",
    "taskReferenceName": "find_items",
    "description": "Find items matching multiple criteria",
    "type": "SUB_WORKFLOW",
    "optional": false,
    "inputParameters": {
        "findMode": "REQUEST",
        "request": {
            "method": "INLINE",
            "contentType": "application/json",
            "model": "default",
            "json": {
                "context": {
                    "partitionId": "2342"
                },
                "criteria": {
                    "type": "and",
                    "queries": [
                        {
                            "type": "eq",
                            "field": {
                                "target": "item.fields",
                                "key": "BRAND"
                            },
                            "value": "Acme"
                        },
                        {
                            "type": "search",
                            "caseSensitive": false,
                            "field": {
                                "target": "item.fields",
                                "key": "TITLE"
                            },
                            "value": "organic"
                        }
                    ]
                },
                "options": {
                    "sort": "createdAt",
                    "sortOrder": "DESC",
                    "limit": 50
                }
            }
        }
    }
}

Find items returning only a whitelist of field keys

When a job only needs a few fields per item (e.g. EAN_13 and TITLE), set request.json.options.includedFieldKeys to drastically reduce the response payload and speed up downstream transforms. All other fields are stripped from each item's fields[] array; root metadata is preserved.

job.json (INLINE JSON request)

{
    "name": "data-item-find",
    "taskReferenceName": "find_items",
    "description": "Find items, returning only EAN_13 and TITLE in each item's fields",
    "type": "SUB_WORKFLOW",
    "optional": false,
    "inputParameters": {
        "findMode": "ALL",
        "request": {
            "method": "INLINE",
            "contentType": "application/json",
            "model": "default",
            "json": {
                "context": {
                    "partitionId": "2342"
                },
                "options": {
                    "includedFieldKeys": ["EAN_13", "TITLE"]
                }
            }
        }
    }
}

request.xml (FILE XML request)

The same option can be supplied through an XML request body. The XML is parsed into the equivalent JSON structure before being processed.

<?xml version="1.0" encoding="UTF-8"?>
<map xmlns="http://www.w3.org/2005/xpath-functions">
    <map key="context">
        <string key="partitionId">2342</string>
    </map>
    <map key="options">
        <array key="includedFieldKeys">
            <string>EAN_13</string>
            <string>TITLE</string>
        </array>
    </map>
</map>

TIP

• includedFieldKeys is forwarded to the underlying items API as repeated query parameters (?includedFieldKeys=EAN_13&includedFieldKeys=TITLE).
• Unknown keys are silently ignored - they do not raise an error, they just don't appear in the response.
• An empty array ("includedFieldKeys": []) returns items with fields: [] (still with their metadata).
• Composite fields are returned as a whole when their root key is listed. Inner field keys (dot-notation) are not supported.
• This parameter is not a security mechanism. It only shapes the response; access control is unchanged.