UpdateFrame

Updates existing Frame objects that satisfy the specified constraints.

Parameters

Exactly one of ref or constraints is required. Supplying both is rejected. Use a preceding FindFrame to combine property and relationship filters, then pass its reference.

Parameter	JSON type	Behavior
constraints	array expression	Optional. No property filter; the command-specific selector requirement still applies. Selects existing frames by expression. Cannot be combined with ref.
frame_number	integer, 0 through 9007199254740992	Optional. Existing position is retained unless another position field replaces it. Zero-based frame position. At most one position field may be supplied; it removes the previous position representation. Storage does not check video boundaries; retrieving an out-of-range frame can fail.
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 Frame 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.
time_fraction	number, 0 through 1 inclusive	Optional. Existing position is retained unless another position field replaces it. Fraction of the video duration; 0 is the start and 1 the end. At most one position field may be supplied; it removes the previous position representation. Storage does not check video boundaries; retrieving an out-of-range frame can fail.
time_offset	time string: SS[.ffffff], MM:SS[.ffffff], or HH:MM:SS[.ffffff]	Optional. Existing position is retained unless another position field replaces it. Offset from the video start. At most one position field may be supplied; it removes the previous position representation. Each colon-delimited component has one or two digits and the optional fractional part has one through six digits. Storage does not check video boundaries; retrieving an out-of-range frame can fail.

Details

The ref and constraints parameters are mutually exclusive. To combine filters, use FindFrame first and update or delete through its reference.

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

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

Response and errors

An authenticated session with the objects update permission is required.

The response is an object under UpdateFrame 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.

Examples

Find the frames with the “year_captured” property equal to 2007, remove the “focal_length” property:

[{
    "UpdateFrame": {
        "constraints": ["$year_captured", "==", 2007],
        "remove_props": ["focal_length"]
    }
}]

Successful response:

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

Find a video with the “year_captured” property equal to 2007, verify that only one video satisfy the constraint, and add a “source” property to all its associated frames with the value “my_new_model”:

[{
    "FindVideo": {
        "_ref": 1,
        "unique": true,
        "constraints": ["$year_captured", "==", 2007]
    }
}, {
    "FindFrame": {
        "video_ref": 1,
        "_ref": 2
    }
}, {
    "UpdateFrame": {
        "ref": 2,
        "properties": {
            "source": "my_new_model"
        }
    }
}]

Successful response:

[{
    "FindVideo": {
        "returned": 0,
        "status": 0
    }
}, {
    "FindFrame": {
        "returned": 0,
        "status": 0
    }
}, {
    "UpdateFrame": {
        "count": 1,
        "status": 0
    }
}]

Find the frame with frame_number equals to 32 for the video with the “year_captured” property equal to 2007, and remove the “source” property.

[{
    "FindVideo": {
        "_ref": 1,
        "unique": true,
        "constraints": ["$year_captured", "==", 1995]
    }
}, {
    "FindFrame": {
        "video_ref": 1,
        "_ref": 2,
        "in_frame_number_range": {
            "start": 31,
            "stop": 33
        }
    }
}, {
    "UpdateFrame": {
        "ref": 2,
        "remove_props": ["source"]
    }
}]

Successful response:

[{
    "FindVideo": {
        "returned": 0,
        "status": 0
    }
}, {
    "FindFrame": {
        "returned": 0,
        "status": 0
    }
}, {
    "UpdateFrame": {
        "count": 1,
        "status": 0
    }
}]