UpdateClip

Updates existing Clip objects that satisfy the specified constraints.

Parameters

ref and constraints are optional and are intersected when both are present. Scope warning: omitting all selectors targets every Clip object. Always supply selectors for a scoped mutation.

Parameter	JSON type	Behavior
constraints	array expression	Optional. No property filter; the command-specific selector requirement still applies. Filters existing objects using the constraints expression language. When ref is supplied it filters that referenced set.
frame_number_range	object with nonnegative integer start/stop, at most 9007199254740992	Optional. No change to this range unless a different range type is supplied. At least one endpoint is required when this field is present; omitted endpoints retain their stored value. When both endpoints are supplied, start must not exceed stop; equal endpoints are accepted. Supplied endpoints are checked against the linked video bounds. Supply one range type per update. If multiple range fields are supplied, parsing uses frame_number_range first, then time_offset_range, then time_fraction_range; lower-priority values are ignored.
label	string	Optional. When omitted, the existing label is unchanged. Sets the object’s label independently of user properties.
properties	object mapping property names to values	Optional. When omitted, existing user properties are unchanged except for keys listed in remove_props. Stores booleans, numbers, strings, supported arrays, or single-key _date, _blob, and _json wrappers. Bare null is rejected; property names and wrapped values are validated. See the properties reference for nested value rules. Replaces supplied property values without replacing the whole property map.
ref	integer, 1 through 100000	Optional. Select using the other supplied selectors; see the selection rule above. Uses an earlier compatible Clip reference in this transaction; forward references, wrong types, and undeclared references are rejected.
remove_props	array of strings	Optional. When omitted, no properties are removed. Removes named properties from selected objects; missing keys have no effect. A value also supplied in properties is stored after removal. Unlike the other typed update handlers, this handler does not validate each removal name; use user property names only.
time_fraction_range	object with numeric start/stop in [0, 1]	Optional. No change to this range unless a different range type is supplied. At least one endpoint is required when this field is present; omitted endpoints retain their stored value. When both endpoints are supplied, start must not exceed stop; equal endpoints are accepted. Supply one range type per update. If multiple range fields are supplied, parsing uses frame_number_range first, then time_offset_range, then time_fraction_range; lower-priority values are ignored.
time_offset_range	object with time-string start/stop	Optional. No change to this range unless a different range type is supplied. At least one endpoint is required when this field is present; omitted endpoints retain their stored value. When both endpoints are supplied, start must not exceed stop; equal endpoints are accepted. Time strings accept seconds, minutes:seconds, or hours:minutes:seconds with optional fractional seconds and unrestricted digit counts. Supplied endpoints are checked against the linked video bounds. Supply one range type per update. If multiple range fields are supplied, parsing uses frame_number_range first, then time_offset_range, then time_fraction_range; lower-priority values are ignored.

Details

If the ref parameter is used, constraints will act as additional filters on the referenced result set.

If the ref parameter is specified, it must refer to the results of an earlier AddClip or FindClip.

For more complex searches for objects to update, a Find command must be used first within the transaction.

Response and errors

An authenticated session is required. This command currently has no objects.update permission requirement. This is a known permission-mapping limitation; do not use that permission as an access boundary for this command.

The response is an object under UpdateClip with integer status and, on success, integer count. Status 0 means the mutation completed; count is the number of selected objects affected, including zero when none match. No output blobs are returned.

Invalid field types, missing required fields, malformed expressions, and invalid references fail validation. Execution failures include a nonzero status and an info message; inspect the transaction response before assuming a mutation succeeded. Use one range type and both endpoints when changing representation; partial updates do not compare new endpoints to retained endpoints.

Examples

Find the clips with the “name” property equal to “The Lodge”, and update the label and the time fraction range:

[{
    "UpdateClip": {
        "constraints": ["$name", "==", "The Lodge"],
        "label": "Building",
        "time_fraction_range": {
            "start": 0.5,
            "stop": 0.6
        }
    }
}]

Successful response:

[{
    "UpdateClip": {
        "count": 1,
        "status": 0
    }
}]

Find the clips connected to the video with “name” = “The Shining”, and update “year” property to 1980

[{
    "FindVideo": {
        "_ref": 1,
        "constraints": ["$name", "==", "The Shining"]
    }
}, {
    "FindClip": {
        "video_ref": 1,
        "_ref": 2
    }
}, {
    "UpdateClip": {
        "ref": 2,
        "properties": {
            "year": 1980
        }
    }
}]

Successful response:

[{
    "FindVideo": {
        "returned": 0,
        "status": 0
    }
}, {
    "FindClip": {
        "returned": 0,
        "status": 0
    }
}, {
    "UpdateClip": {
        "count": 4,
        "status": 0
    }
}]