IRPCObjectOperations.DestroyObjectVersionsByConditions
Vault API / core write session or assertion returns metadata structure version
Destroys the old versions of an object that match search conditions, and returns how many were destroyed.
| Service | Objects, versions, properties and files MFiles.IRPCObjectOperations |
|---|---|
| gRPC method | /MFiles.IRPCObjectOperations/DestroyObjectVersionsByConditions |
| HTTP (mf-http-grpc) | POST /grpc/v1/destroy-object-versions-by-conditions |
| Request | DestroyObjectVersionsByConditionsRequest |
| Response | DestroyObjectVersionsByConditionsResponse |
| Book and level | Vault API, core |
| Kind | write |
| Session | Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata). |
| Idempotent | no |
| Returns metadata structure version | yes (in the mfiles-metadata-version-bin trailer) |
| Streaming | none (unary) |
Remarks
The newest version is never destroyed, and when the object is checked out both the checked-out
version and the latest checked-in version are kept, whoever has the object checked out; conditions
cannot override this. conditions must not be empty. Check a condition set first with
CountObjectVersionsMatchingConditions:
destruction cannot be undone. If more_versions_remain is true, call again. Requires the
vault-level right to destroy objects. Not available on servers where the feature is not enabled
(the call fails with not implemented).
Request: DestroyObjectVersionsByConditionsRequest
The request of DestroyObjectVersionsByConditions: the object and the conditions a version must match to be destroyed. The conditions only select candidates: the newest version, and for a checked-out object the checked-out version and the latest checked-in version, are always kept.
Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
obj_id | ObjID | The object whose versions are destroyed. |
obj_id.type | int32 | The object type ID, for example 0 for documents. In a lookup value, the value list ID (for a lookup to objects, the object type ID). |
obj_id.item_id | ItemID | The ID of the object within its type, in item_id.internal_id. |
obj_id.item_id.internal_id | int32 | The ID of the object or value list item. |
obj_id.item_id.external_repository_id | ExternalRepositoryID | Used only for objects in external repositories (external connectors). Leave it unset for objects stored in the vault. |
conditions[] | repeated SearchCondition | The conditions a version must match to be destroyed. Must not be empty. |
conditions[].expression | Expression | The left side of the condition: what is evaluated for each object, such as a property value, a status value or any field (full-text search). |
conditions[].expression.type | ExpressionType | The kind of expression. Must match the member set in data.Values: EXPRESSION_TYPE_UNINITIALIZED (0), EXPRESSION_TYPE_PROPERTY_VALUE (1), EXPRESSION_TYPE_ID_SEGMENT (2), EXPRESSION_TYPE_STATUS_VALUE (3), EXPRESSION_TYPE_FILE_VALUE (4), EXPRESSION_TYPE_TYPED_VALUE (5), EXPRESSION_TYPE_ANY_FIELD (6), EXPRESSION_TYPE_PERMISSIONS (7). |
conditions[].expression.data | ExpressionUnion | The expression data. Set the member that matches type. |
conditions[].expression.indirection_levels[] | repeated IndirectionLevel | The lookups to follow before evaluating the expression, from the searched object outwards. Empty evaluates the expression on the object itself. |
conditions[].type | ConditionType | The comparison operator. |
conditions[].value | TypedValue | The right side of the condition: the value to compare with. Its data type must suit the expression, for example a lookup for a lookup property, Boolean for STATUS_TYPE_IS_DELETED. |
conditions[].value.is_null_value | bool | True if the value is empty. data is then unset. |
conditions[].value.type | Datatype | The data type of the value. |
conditions[].value.data | TypedValueUnion | The value, in the member that matches type. Unset for an empty value. |
max_versions_to_destroy | int32 | The most versions this call destroys. Zero or less means no limit, so set a limit deliberately. |
Response: DestroyObjectVersionsByConditionsResponse
The response of DestroyObjectVersionsByConditions: the number of versions destroyed, and whether more matching versions remain.
Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
destroyed_version_count | int32 | The number of versions destroyed by this call. |
more_versions_remain | bool | True if more matching versions remained; call again to continue. |
Related methods
- CountObjectVersionsMatchingConditions -- Counts the versions of an object that DestroyObjectVersionsByConditions would destroy with the same inputs, without destroying anything.
- DestroyObject -- Permanently destroys an object, or one version of it.
- DestroyObjectVersions -- Permanently destroys specific object versions.