Collections

Trigger Collection Processing

Changed on

Process data through a collection - works for both bucket-sourced and collection-sourced collections.

**For bucket-sourced collections:**
Creates a batch and answers with its id and a task id, then reads the source
bucket(s), splits a load over 1,000 objects into several batches, and submits
them. Use `include_buckets` to limit which source buckets to process from.
If the buckets hold no matching objects, or a submission is refused, the
batch and the task read FAILED with the reason. The task lists every batch
as `additional_data.trigger.batch_ids` once they are submitted.

**For collection-sourced collections:**
Processes existing documents from upstream collection(s).
Use `include_collections` to limit which source collections to process from.

**Filtering:**
- `source_filters`: Field-level filters using LogicalOperator format
- Example: `{"AND": [{"field": "status", "operator": "eq", "value": "pending"}]}`
- For specific objects: `{"AND": [{"field": "object_id", "operator": "in", "value": ["obj_1", "obj_2"]}]}`

**Returns:**
- batch_id: Track progress via GET /batches/{batch_id}
- task_id: Monitor via GET /tasks/{task_id}
post/v1/collections/{collection_identifier}/trigger

Request

  • Base URL: https://api.mixpeek.com
  • URL: https://api.mixpeek.com/v1/collections/{collection_identifier}/trigger
  • Auth: HTTP bearer and API key in header X-Namespace

Path parameters

collection_identifierstring required

The ID or name of the collection to trigger

Request body

include_bucketsstring[] nullable

Limit processing to objects from these specific buckets (IDs or names). Only applies to bucket-sourced collections. If not provided, all configured source buckets are used.

include_collectionsstring[] nullable

Limit processing to documents from these specific collections (IDs or names). Only applies to collection-sourced collections. If not provided, all configured source collections are used.

object_idsstring[] nullable

Limit processing to these specific object IDs. Only applies to bucket-sourced collections. This is a convenience shorthand — equivalent to using source_filters with {"AND": [{"field": "object_id", "operator": "in", "value": [...]}]}.

dedup_strategy'skip' | 'replace' | 'force'

Controls how duplicate objects are handled during batch processing.

Dedup is scoped to (bucket_id, collection_id): an object is considered a duplicate if the target collection already has documents produced from the same source object in any prior batch.

Example request

{
  "source_filters": {
    "AND": [
      {
        "field": "name",
        "operator": "eq",
        "value": "John"
      },
      {
        "field": "age",
        "operator": "gte",
        "value": 30
      }
    ],
    "OR": [
      {
        "field": "status",
        "operator": "eq",
        "value": "active"
      },
      {
        "field": "role",
        "operator": "eq",
        "value": "admin"
      }
    ],
    "NOT": [
      {
        "field": "department",
        "operator": "eq",
        "value": "HR"
      },
      {
        "field": "location",
        "operator": "eq",
        "value": "remote"
      }
    ],
    "case_sensitive": true
  },
  "reembed": {
    "target_feature_uri": "mixpeek://text_extractor@v1/all_minilm_l6_v2_v1"
  }
}

Response

Successful Response

batch_idstring nullable

ID of the created batch for tracking progress. Null for a stored-text re-embed (reembed), which runs as a task, not a batch.

task_idstring required

Task ID for monitoring via GET /v1/tasks/{task_id}.

collection_idstring required

ID of the collection being processed.

source_bucket_idsstring[] nullable

Bucket IDs that objects were discovered from (bucket-sourced collections).

source_collection_idsstring[] nullable

Collection IDs that documents were read from (collection-sourced collections).

object_countinteger nullable

Number of objects in the trigger (bucket-sourced collections). Null when the trigger answered before reading the bucket; the count is then on the task, as additional_data.trigger.object_count.

batch_idsstring[] nullable

All batch IDs created for this trigger. Present when a large load was auto-chunked into multiple right-sized batches; batch_id is the first of these. Null (absent) for a single-batch trigger, and when the trigger answered before reading the bucket: the task then lists them as additional_data.trigger.batch_ids.

task_idsstring[] nullable

Task IDs for each created batch, aligned with batch_ids.

batch_countinteger nullable

Number of batches created. Null for a single-batch trigger; set when the load was auto-chunked into multiple batches.

document_countinteger nullable

Total number of documents to process (collection-sourced collections).

total_tiersinteger required

Number of processing tiers in the DAG.

messagestring required

Human-readable status message.

Changes

  • 61a175e8eb9aRevision changes
    • warning

      removed the optional property from the response with the status

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      added the optional property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

  • b75474e978ffRevision changes
    • info

      added the optional property to the response with the status