Update by Query (PATCH) v2
Perform asynchronous bulk updates on objects that match a specific set of criteria using the v2 Update by Query API endpoint.
This endpoint requires HMAC authentication. Refer to the Authentication documentation for details.
Overview
This is the v2 version of the Update by Query API endpoint. This endpoint allows you to perform bulk updates on objects that match a specific set of criteria. It is an asynchronous operation: the API call initiates a background job, and you must poll a status URL to check its progress. This is ideal for large-scale changes, such as applying a sale to an entire brand, without requiring a list of individual identities.
v2 Enhancements:
- Improved query performance: Faster execution of complex search criteria
- Enhanced error reporting: More detailed failure information and recovery suggestions
- Better job tracking: Enhanced status monitoring with progress indicators
- Advanced matching: Extended search capabilities with more flexible criteria
https://live.luigisbox.com/v2/update_by_query
Request Structure (v2)
The request body consists of two main parts: a search object to define the update criteria and an update object to specify the changes.
Request Body Structure
| Parameter | Type | Required | Description |
|---|---|---|---|
search |
Object | ✓ | An object containing rules to select which items will be updated. |
update |
Object | ✓ | An object specifying the field changes to apply to all matching items. |
search Object Parameters (v2)
| Parameter | Type | Required | Description |
|---|---|---|---|
types |
Array | ✓ | An array of strings specifying the object types to include in the search (e.g., ["item"]). |
partial |
Object | ✓ | An object containing the fields to match. Enhanced matching capabilities in v2. |
update Object Parameters (v2)
| Parameter | Type | Required | Description |
|---|---|---|---|
fields |
Object | ✓ | An object specifying the fields to update and their new values. Enhanced field validation in v2. |
Example: request body (JSON) v2
{
"search": {
"types": [
"product"
],
"partial": {
"fields": {
"color": "olive",
"v2_metadata": {
"enhanced": true
}
}
}
},
"update": {
"fields": {
"color": "green",
"updated_at": "2024-10-20T15:30:00Z",
"v2_processing": {
"batch_id": "update-20241020-001",
"confidence_score": 0.95
}
}
}
}
Check Job Status (v2)
After a successful PATCH request, the API will respond with a status_url. You must then make a GET request to this URL to check the status of the background job. v2 provides enhanced progress tracking.
Status Check Request:
GET https://live.luigisbox.com/v2/update_by_query?job_id=12345
The response will show the current status of your bulk update operation with additional v2 progress information.
Initial PATCH Response v2
{
"status_url": "/v2/update_by_query?job_id=12345",
"v2_features": {
"progress_tracking": true,
"estimated_duration": "5-10 minutes"
}
}
Job Completion Response (v2)
Once the job is finished, the GET request to the status URL will return a summary of the results, including enhanced reporting in v2.
Response Fields (v2)
| Field | Type | Description |
|---|---|---|
tracker_id |
String | Your tracker identifier |
status |
String | Job status: "in_progress", "complete", or "failed" |
updates_count |
Integer | Number of objects successfully updated |
failures_count |
Integer | Number of objects that failed to update |
failures |
Object | Details about any failures (empty if none) |
v2_metrics |
Object | Enhanced metrics and performance data (v2 only) |
Complete Job Response v2
{
"tracker_id": "YOUR-TRACKER-ID",
"status": "complete",
"updates_count": 5,
"failures_count": 0,
"failures": {},
"v2_metrics": {
"processing_time_ms": 2450,
"objects_processed_per_second": 2.04,
"peak_memory_usage_mb": 128,
"query_complexity_score": 3.2
}
}
Error Handling (v2)
| HTTP Status | Description |
|---|---|
| 400 Bad Request | The request structure is invalid, JSON is malformed, or some objects failed validation. Enhanced error details in v2. |
| 403 Forbidden | The request is not allowed for your site in Luigi's Box. |
| 405 Method Not Allowed | The request method is not supported for the specified resource. |
| 413 Payload Too Large | The request exceeds 5 MB (10 MB if compressed). Reduce batch size or enable compression. |
Example: Job Failure Response v2
{
"tracker_id": "YOUR-TRACKER-ID",
"status": "complete",
"updates_count": 4,
"failures_count": 1,
"failures": {
"/products/1": {
"type": "data_schema_mismatch",
"reason": "failed to parse [attributes.price]",
"caused_by": {
"type": "number_format_exception",
"reason": "For input string: \"wrong sale price\""
},
"v2_recovery": {
"suggested_action": "Ensure price field contains numeric values only",
"retry_recommended": true
}
}
},
"v2_error_summary": {
"total_categories": 1,
"most_common_error": "data_schema_mismatch",
"recovery_suggestions": [
"Validate data types before update",
"Use smaller batch sizes for complex updates"
]
}
}
v2 Improvements
- Enhanced query performance: Up to 3x faster execution for complex search criteria
- Better progress tracking: Real-time progress indicators and estimated completion times
- Improved error reporting: Detailed failure analysis with specific recovery suggestions
- Advanced matching capabilities: Support for more complex field matching patterns
- Performance metrics: Detailed execution statistics for optimization insights
Performance Guidelines (v2)
For optimal bulk update performance in v2:
- Query complexity: Enhanced support for complex search criteria
- Batch efficiency: Optimized processing for large-scale updates
- Memory usage: Better memory management for large datasets
- Error recovery: Improved retry mechanisms for failed operations
Related Endpoints
- Content Update v2 - Create or replace objects
- Partial Content Update v2 - Update specific fields only
- Content Removal v2 - Delete objects from index