remove(): Remove a document

Deletes a document from a collection by using z/TPF support for MongoDB.

Last updated

Changed for PUT14.
Added for PUT13.

Format

db.collection.remove(query)

collection

The name of the collection that the document is in. The name of the collection is the name that is defined in the z/TPFDF collection descriptor.

query

A JSON document that defines which document to remove. The JSON document must be in the following format:

_interleave: interleaveNum,                  /*Optional*/
_partition: partitionNum,                    /*Optional*/
_tenant: "tenantName",                       /*Optional*/
_index.IndexName: IndexNameSpecification,      
_id: ObjectId (objectIdValue),
conditionalField: conditionalValue           /*Optional*/

Specify one or more of the following fields:

_interleave: interleaveNum

Use this field to remove the document from a z/TPFDF interleave, where interleaveNum is an integer number that represents the target interleave.

If this field is not specified for a collection or z/TPFDF file that is defined as interleaved, an interleave number of 0 is assumed. If the z/TPFDF file is not defined as interleaved, specifying this field has no effect.

This field is optional.

_partition: partitionNum

Use this field to remove the document from a z/TPFDF partition, where partitionNum is an integer number that represents the target partition.

If this field is not specified for a collection or z/TPFDF file that is defined as partitioned, a partition number of 0 is assumed. If the z/TPFDF file is not defined as partitioned, specifying this field has no effect.

This field is optional.

_tenant: tenantName

Use this field to remove the document from a subsystem user, where tenantName is the name that represents the target subsystem user.

If this field is not specified for a collection or z/TPFDF file that is subsystem unique, the default subsystem user for the subsystem is assumed. If the z/TPFDF file is defined as subsystem user shared, specifying this field has no effect.

This field is optional.

_index.IndexName: IndexNameSpecification

Use this field to locate a document and then deindex the document from this path. IndexName is the name of an index element that is defined in the z/TPFDF collection descriptor, and IndexNameSpecification is the document that specifies the fields that are defined for the index element in the z/TPFDF collection descriptor and the value of the fields.

You must specify the fields of the index name in the order that these fields are defined in the DFDL schema file. If you do not specify the value for a field of an index name, the default value that is defined in the DFDL schema file for the z/TPFDF file is used.

The _index.IndexName field uses dot notation because IndexName is an embedded document of the _index field. When you specify fields with dot notation in the MongoDB shell, you must enclose the field name in single or double quotation marks.

You can specify more than one index name as part of a remove() operation to deindex the document from multiple paths when the document is removed. It is not necessary to deindex a document when any of the following conditions is met:

If the z/TPFDF database definition (DBDEF) that represents this collection has AUTODEINDEX=YES specified and the indexes for this collection are not defined as custom indexes.
If all of the index names for this collection have automatic index rules defined in the z/TPFDF collection descriptor.

To specify more than one index name, use the following format:

_index.IndexName: {IndexSpecification},
⋮
_index.IndexName: {IndexSpecification}

When you specify more than one index name without the _id field specified, z/TPF support for MongoDB searches for the document by using the list of index names. The search process starts from the first index name that was specified and goes through the list sequentially until a document is found. When a document is found, the document is removed and then deindexed by using all of the specified index names.

This field is required unless the _id field is specified. If you specify both fields, only the _id field is used to locate the document. If the document is located by using the _id field, the document is removed and then deindexed by using the specified index names. Otherwise, the remove process does not occur.

_id: ObjectId(objectIdValue)

Use this field to locate and remove the document directly by using an ObjectId value, where objectIdValue is the ObjectId value or z/TPF file address that is used to access the document.

If you specify the _id field and _index fields, the document is located by using the _id field. The _index fields are not used for locating the document even if the document is not located by using the _id field, and the document or the indexes are not removed.

This field is required unless the _index field is specified. If you specify both fields, only the _id field is used to locate the document. If the document is located by using the _id field, the document is removed and then deindexed by using the specified index names. Otherwise, the remove process does not occur.

conditionalField: conditionalValue

Use this field with the _index or _id field to conditionally return the document based on the contents of the document, where conditionalField is a field in the document that is defined in the DFDL schema file that describes this document, and conditionalValue is the value of the field. Specify this field in one of the following formats:

LRECs in a document are represented as an array, so you must use the $elemMatch operator to conditionally find documents based on fields in an LREC.
```
lrecName: { $elemMatch: {conditionalField: conditionalValue, 
                          ⋮
	                 conditionalField: conditionalValue				  
                         }
           }
```
lrecName

The name of the record that is defined in the z/TPFDF collection descriptor and DFDL schema file.

$elemMatch

Use this operator to conditionally find documents based on fields in an LREC.

You can specify multiple lrecName conditions, and for each lrecName, you can specify multiple fields in the LREC.
For z/TPFDF files with SEQUPDT=YES specified in the z/TPFDF database definition, you can use the _seq field as a conditional field with the value of the current file sequence update counter of the document:
```
		_seq: sequenceValue
```
_seq

The file sequence update counter that z/TPFDF maintains.
When the z/TPFDF database definition for the z/TPFDF files have SEQUPDT=YES specified, all documents that are returned by using z/TPF support for MongoDB for the collection that represents the z/TPFDF file contain an _seq field with the current file sequence update counter of the document as the value.

When you update the document, use the _seq field as a conditional field to ensure that the document is not changed in between the time the document is queried and updated.

sequenceValue

The current file sequence update counter of the document that is obtained from a previous query.

The document is removed if all of the conditional field specifications match. Otherwise, a not found condition occurs. To determine whether the document does not exist or the document exists but the conditional fields do not match, issue a subsequent MongoDB findOne() operation without the conditional fields specified.

This field is optional.

Return conditions

The document is removed from the collection, and a document that contains the status of the operation is returned. If an error occurs, the errmsg field of the document that is returned contains the information about why the document could not be removed.

Programming considerations

If the document was not removed from an index, subsequent recoup processing might identify the index reference as a broken chain when both of the following conditions occur:
- The z/TPFDF database definition (DBDEF) that represents this collection does not have AUTODEINDEX=YES specified.
- The index name for this collection does not have automatic indexing rules defined for the index in the z/TPFDF collection descriptor.
Only one document can be removed on a remove() request by using z/TPF support for MongoDB. If the document that is specified for the query field on the remove() request returns multiple documents, an error is returned.
Specifying the _interleave, _partition, or _tenant field applies the value to all index paths that are specified on the remove() request. To remove indexes in multiple partitions, interleaves, or tenants, you must remove indexes individually by using the update() method through z/TPF support for MongoDB.
This method is not supported for filtered collections.

Examples

The following example removes a document from the PNR collection by using the MongoDB shell. z/TPF support for MongoDB locates the document by using one of the supplied index names. If the document is found, the document is removed and deindexed from all specified index names.

db.PNR.remove({
       '_index.PnrByName': {name: "ABEDFORD"},
       '_index.PnrByNumber': {number: 21}
})

The following example removes a document from the PNR collection by using the MongoDB shell. z/TPF support for MongoDB locates the document to remove by using the _id parameter. If the document is found, the document is removed and deindexed from all specified index names.

db.PNR.remove({
      	_id:ObjectId("00000000000000001802110c"),
       PnrByName: {name: "ABEDFORD"},
       PnrByNumber: {number: 21}
})

The following example removes a document from the PNR collection by using the MongoDB shell. z/TPF support for MongoDB locates the document in the SSU1 subsystem user or tenant by using one of the supplied index names. If the document is found, the document is removed and deindexed from all specified index names.

db.PNR.remove({
	     _tenant: "SSU1",
      '_index.PnrByName': {name: "ABEDFORD"},
      '_index.PnrByNumber': {number: 21}
})

The following example removes a document from the PNR collection by using the MongoDB Java™ client driver. z/TPF support for MongoDB locates the document in the SSU1 subsystem or tenant by using one of the supplied index names. If the document is found, the document is removed and deindexed from all specified index names.

import com.mongodb.*;

MongoClient mongoClient = new MongoClient( "ztpf.mydomain.com");
DB db = mongoClient.getDB( "tpfdf" );
DBCollection coll = db.getCollection("PNR");
BasicDBObject doc = new BasicDBObject("_tenant", "SSU1").append
                   ("_index.PnrByName",new BasicDBObject("name"," ABEDFORD")).append
                   ("_index.PnrByNumber",new BasicDBObject("number", 21));
coll.remove(doc);

The following example uses a MongoDB shell to remove a PNR document from the MongoDB PNR collection with the _id field by using the ObjectId BSON type and specifying the z/TPFDF file sequence update counter in the request. The _seq field and value were returned on a previous find() or findOne() operation. The document is removed only if the current z/TPFDF file sequence update counter matches the request. Otherwise a not found condition occurs.

db.PNR.remove({
	_id: ObjectId("0000000000000000088755fe"),
	_seq: 12345
});