> Portal Navigation: > > - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version. > - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages). > - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`). > - Top-level index of all portals: https://dev.wix.com/docs/llms.txt > - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt # AsyncPatchDataItemsByFilter # Package: cms # Namespace: DataItemService # Method link: https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/async-patch-data-items-by-filter.md ## Permission Scopes: Write Data Items: SCOPE.DC-DATA.WRITE ## Introduction Patches all data items matching a filter. Runs asynchronously. This method selects all items that match the specified filter and applies the given field modifications to each one. Unlike [Bulk Patch Data Items](https://dev.wix.com/docs/rest/business-solutions/cms/data-items/bulk-patch-data-items.md), you don't need to specify individual item IDs. Instead, items are selected by filter. The operation runs asynchronously and returns a job ID for tracking status. Call [Get Async Job Status](https://dev.wix.com/docs/rest/business-solutions/cms/data-items/get-async-job-status.md) with the returned job ID to poll for status. An empty `filter` patches all items in the collection. > **Notes:** > - The number of affected items is not bounded. > - If any item fails to be patched, the async job stops and its status becomes `FAILED`. Some items may already have been patched before the failure. > - Each patched item's `data._updatedDate` property is updated to the current date and time. > - Calling this method triggers the [Data Item Updated](https://dev.wix.com/docs/rest/business-solutions/cms/data-items/data-item-updated.md) event for each patched item. > - Job records are retained for 30 days. After that, querying the job ID returns `NOT_FOUND`. --- ## REST API ### Schema ``` Method: asyncPatchDataItemsByFilter Description: Patches all data items matching a filter. Runs asynchronously. This method selects all items that match the specified filter and applies the given field modifications to each one. Unlike [Bulk Patch Data Items](https://dev.wix.com/docs/rest/business-solutions/cms/data-items/bulk-patch-data-items.md), you don't need to specify individual item GUIDs. Instead, items are selected by filter. The operation runs asynchronously and returns a job GUID for tracking status. Call [Get Async Job Status](https://dev.wix.com/docs/rest/business-solutions/cms/data-items/get-async-job-status.md) with the returned job GUID to poll for status. An empty `filter` patches all items in the collection. > **Notes:** > - The number of affected items is not bounded. > - If any item fails to be patched, the async job stops and its status becomes `FAILED`. Some items may already have been patched before the failure. > - Each patched item's `data._updatedDate` property is updated to the current date and time. > - Calling this method triggers the [Data Item Updated](https://dev.wix.com/docs/rest/business-solutions/cms/data-items/data-item-updated.md) event for each patched item. > - Job records are retained for 30 days. After that, querying the job GUID returns `NOT_FOUND`. URL: https://www.wixapis.com/wix-data/v2/bulk/items/async-patch-by-filter Method: POST # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present. Required parameters: dataCollectionId, fieldModifications, fieldModifications.fieldPath, fieldModifications.action Method parameters: param name: dataCollectionId | type: dataCollectionId | description: GUID of the collection containing items to patch. | required: true | validation: maxLength 256 param name: fieldModifications | type: array | description: Field modifications to apply to each matching item. Supports the same modification model as [Patch Data Item](https://dev.wix.com/docs/rest/business-solutions/cms/data-items/patch-data-item.md), including setting, removing, and incrementing fields. Maximum 100 modifications per request. | required: true | validation: minItems 1, maxItems 100 - ONE-OF: - name: setFieldOptions | type: SetFieldOptions | description: Options for setting the value of the specified field. Required when `action` is `SET_FIELD`. - name: value | type: Value | description: Value to set for the specified field. This replaces the existing value. - ONE-OF: - name: nullValue | type: | description: - name: numberValue | type: number | description: - name: stringValue | type: string | description: - name: boolValue | type: boolean | description: - name: structValue | type: object | description: - name: listValue | type: ListValue | description: - name: values | type: array | description: - name: incrementFieldOptions | type: IncrementFieldOptions | description: Options for incrementing the value of the specified field. Required when `action` is `INCREMENT_FIELD`. - name: value | type: number | description: Numerical value by which to increment the field value. To decrement, specify a negative value. - name: appendToArrayOptions | type: AppendToArrayOptions | description: Options for appending a value to the specified array or a multi-reference field. Required when `action` is `APPEND_TO_ARRAY`. - name: value | type: Value | description: Value to append to the specified array. - name: removeFromArrayOptions | type: RemoveFromArrayOptions | description: Options for removing a value from the specified array or a multi-reference field. Required when `action` is `REMOVE_FROM_ARRAY`. - name: value | type: Value | description: Value whose first instance is removed from the specified array. - name: fieldPath | type: string | description: Path of the field to be modified. For example: `title`. Nested fields can be specified using dot notation. For example: `address.street`. | required: true | validation: maxLength 1000 - name: action | type: ACTION | description: Patch action to apply to the specified field. | required: true - enum: - SET_FIELD: Sets the specified field to the specified value. - REMOVE_FIELD: Clears the specified field. - INCREMENT_FIELD: Increments the specified field by the specified value. To decrement, specify a negative value. - APPEND_TO_ARRAY: Appends the specified value to the array. Learn more about [data types in Wix Data](https://dev.wix.com/docs/rest/business-solutions/cms/data-types-in-wix-data.md). - REMOVE_FROM_ARRAY: Removes the first instance of the specified value from the array. Learn more about [data types in Wix Data](https://dev.wix.com/docs/rest/business-solutions/cms/data-types-in-wix-data.md). param name: filter | type: filter | description: Filter to select items to patch, using [WQL filter syntax](https://dev.wix.com/docs/rest/api-reference/api-query-language/filtering.md). Filtering is supported for fields explicitly defined in the [data collection structure](https://dev.wix.com/docs/rest/business-solutions/cms/data-collections/introduction.md#data-collections-and-their-structure). Fields not defined in the collection structure can't be used for filtering. Using an undefined field in the filter causes the async job to fail after the method returns a job GUID. Each [field type](https://support.wix.com/en/article/cms-formerly-content-manager-about-your-collection-fields#field-type) supports specific [filter operators](https://dev.wix.com/docs/rest/articles/get-started/api-query-language.md#operators). Using an unsupported operator causes the async job to fail after the method returns a job GUID. Poll [Get Async Job Status](https://dev.wix.com/docs/rest/business-solutions/cms/data-items/get-async-job-status.md) for the final status. An empty filter patches all items in the collection. param name: publishPluginOptions | type: PublishPluginOptions - name: includeDraftItems | type: boolean | description: Whether to include draft items. When `true`, both published and draft items are affected. Default: `false`. Return type: AsyncPatchDataItemsByFilterResponse - name: jobId | type: string | description: Job GUID for tracking the async operation. Call [Get Async Job Status](https://dev.wix.com/docs/rest/business-solutions/cms/data-items/get-async-job-status.md) with this GUID to poll for status. | validation: maxLength 256 ``` ### Examples ### Patch items asynchronously by filter ```curl curl -X POST \ 'https://www.wixapis.com/wix-data/v2/bulk/items/async-patch-by-filter' \ -H 'Content-Type: application/json' \ -H 'Authorization: ' \ -d '{ "dataCollectionId": "cities", "filter": { "$and": [ { "state": { "$eq": "California" } }, { "population": { "$lt": 500000 } } ] }, "fieldModifications": [ { "fieldPath": "region", "action": "SET_FIELD", "setFieldOptions": { "value": "West Coast" } } ] }' ``` ---