insert(): Insert a document

Creates a document in a collection by using z/TPF support for MongoDB.

Last updated

Changed in 2020.
Changed in 2019 (information only; no code change).
Changed for PUT14.
Added for PUT13.

Format

db.collection.insert(insertedDocument)

collection

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

insertedDocument

Specify insertedDocument in the following format:

{
  specialFields,

  indexNames, 

  documentContents

}

specialFields

The specialFields section defines extra criteria when the document is created. These fields are virtual fields and will not be in the inserted document. You can specify 0 or more of the following fields:

_interleave: interleaveNum,           /*Optional*/
_partition: partitionNum,             /*Optional*/
_tenant: "tenantName",                /*Optional*/
_location: "locationName",            /*Optional*/

_interleave: interleaveNum

Use this field to create the document in 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 create the document in 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 create the document in 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.

_location: locationName

Specifies the location to store the document after the document is successfully inserted, where locationName is the location name. You can specify one of the following values:

The name of the target remote data store that is defined by a deployed remote data store descriptor. The document is stored in the specified remote data store by using z/TPFDF remote subfile support.
A NULL value. The document is stored on the local z/TPF system.

This field is optional. If you do not specify this field, the document is stored on the local z/TPF system.

indexNames

The indexNames section defines the indexes that must be created for the document to be inserted. The indexNames section is required unless the indexes have automatic indexing rules defined in the z/TPFDF collection descriptor. You must create at least one index for an inserted document by specifying the indexNames section or by defining an automatic indexing rule for this collection. The indexNames are virtual fields and will not be in the inserted document. Specify the indexNames in the following format:

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

IndexName: The name of an index element that is defined in the z/TPFDF collection descriptor.
IndexSpecification: 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. Non-key values that are defined in the DFDL schema file for a multi-level database are ignored for paths that exist before a new index is created.

documentContents

The documentContents section includes the LRECs and fields that make up the document in the z/TPF database. Each lrecName is represented as an array of that type of record. Specify 0 or more lrecName fields in the following format:

lrecName: [{lrecSpecification}, 
            ⋮
           {lrecSpecification}],
⋮
lrecName: [{lrecSpecification}, 
            ⋮
           {lrecSpecification}]

lrecName

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

lrecSpecification

The fields of the record that is defined in the DFDL schema file and the value of each field. You must specify the fields of the record in the order that these fields are defined in the DFDL schema file. Specify the fields of the LREC and their value in the following format:

"Field1" : value,
"Field2" : value,
⋮
"Fieldn" : value

n: The number of fields that you specify.

If you do not specify the value for a field in an LREC, the default value that is defined in the DFDL schema file for the z/TPFDF file is used.

Return conditions

The document is inserted into 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 inserted.

Programming considerations

The z/TPF system assigns the _id value for the document as the z/TPF file address. If you specify the _id field in the document contents, it is ignored.
The z/TPF system manages the _seq value for the document. If you specify the _seq field in the document that is specified for the insertedDocument parameter, the value of the _seq field is ignored.
Specifying the _interleave, _partition, or _tenant field applies the value to all index names that are specified on the insert() request. To insert indexes in multiple partitions, interleaves, or tenants, you must insert 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 inserts a document into the PNR collection by using the MongoDB shell and indexes the document by using the PnrByName and PnrByNumber index names.

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

"PassengerNumberRecord" : [
{
"PassengerNumber" : 21
}
],

"PassengerNameRecord" : [
{
"PassengerName" : "ABEDFORD "
}
],

"FlightHistoryRecord" : [
{
"FlightInfo": {
    "Flight": {
        "FlightDate" : 22,
        "FlightNumber" : "002"
    },
    "Origin" : "ZRH",
    "Destination" : "POK"
 }
},
{
"FlightInfo": {
    "Flight": {
        "FlightDate" : 53,
        "FlightNumber" : "005"
    },
    "Origin" : "POK",
    "Destination" : "ZRH"
 }


},
{
"FlightInfo": {
    "Flight": {
        "FlightDate" : 113,
        "FlightNumber" : "009"
    },
    "Origin" : "POK",
    "Destination" : "ZRH"
 }

}]
})

The following example inserts a document into the PNR collection by using the MongoDB Java™ client driver and indexes the document by using the PnrByName and PnrByNumber index names.

import com.mongodb.*;

//Connect to z/TPF and obtain the PNR collection
MongoClient mongoClient = new MongoClient( "ztpf.mydomain.com");
DB db = mongoClient.getDB( "tpfdf" );
DBCollection coll = db.getCollection("PNR"); 

//Create a string containing the PNR JSON document to insert

String pnrString = "{
_index: {
PnrByName: {name: ‘ABEDFORD’},
PnrByNumber: {number: 21},
},

‘PassengerNumberRecord’ : [
{
‘PassengerNumber’ : 21
}
],

‘PassengerNameRecord’ : [
{
‘PassengerName’ : ‘ABEDFORD’
}
],

‘FlightHistoryRecord’ : [
{
‘FlightInfo’: {
    ‘Flight’: {
        ‘FlightDate’ : 22,
        ‘FlightNumber’ : ‘002’
    },
    ‘Origin’ : ‘ZRH’,
    ‘Destination’ : ‘POK’
 }
},
{
‘FlightInfo’: {
    ‘Flight’: {
        ‘FlightDate’ : 53,
        ‘FlightNumber’ : ‘005’
    },
    ‘Origin’ : ‘POK’,
    ‘Destination’ : ‘ZRH’
 }


},
{
‘FlightInfo’: {
    ‘Flight’: {
        ‘FlightDate’ : 113,
        ‘FlightNumber’ : ‘009’
    },
    ‘Origin’ : ‘POK’,
    ‘Destination’ : ‘ZRH’
 }

}]
}”;

//Parse the string into a DBObject

DBObject pnrDoc = (DBObject) JSON.parse(pnrString);

//Insert the DBObject into the PNR collection

coll.insert(pnrDoc);

The following example inserts a document into the PNR collection by using the MongoDB shell and indexes the document by using the PnrByName and PnrByNumber index names in the SSU1 subsystem user or tenant.

db.PNR.insert({
_tenant: “SSU1”,
_index: {
PnrByName: {name: "ABEDFORD"},
PnrByNumber: {number: 21},
},
"PassengerNumberRecord" : [
{
"PassengerNumber" : 21
}
],
"PassengerNameRecord" : [
{
"PassengerName" : "ABEDFORD "
}
],
"FlightHistoryRecord" : [
{
"FlightInfo": {
    "Flight": {
        "FlightDate" : 22,
        "FlightNumber" : "002"
    },
    "Origin" : "ZRH",
    "Destination" : "POK"
 }
},
{
"FlightInfo": {
    "Flight": {
        "FlightDate" : 53,
        "FlightNumber" : "005"
    },
    "Origin" : "POK",
    "Destination" : "ZRH"
 }


},
{
"FlightInfo": {
    "Flight": {
        "FlightDate" : 113,
        "FlightNumber" : "009"
    },
    "Origin" : "POK",
    "Destination" : "ZRH"
 }

}]
})

The following example inserts a document into the PNR collection by using the MongoDB shell. The PnrByName and PnrByNumber index names are defined in the z/TPFDF collection descriptor with the automatic indexing rules defined. For more information about defining the automatic indexing rules, see step 4 in Verifying and customizing the z/TPFDF collection descriptor.

db.PNR.insert({

"PassengerNumberRecord" : [
{
"PassengerNumber" : 21
}
],

"PassengerNameRecord" : [
{
"PassengerName" : "ABEDFORD "
}
]
})

The following example inserts a document in the PNR collection by using the MongoDB shell, sets the location to a remote data store with name FAR_AWAY, and indexes the document by using the PnrByName and PnrByNumber index names.

db.PNR.insert({
  _location: "FAR_AWAY",
  _index: {
    PnrByName: {name: "ABEDFORD"},
    PnrByNumber: {number: 21},
  },
  "PassengerNumberRecord" : [ 
    { "PassengerNumber" : 21 }
  ],  
  "PassengerNameRecord" : [
    { "PassengerName" : "ABEDFORD " }
  ],  "FlightHistoryRecord" : [
    {
      "FlightInfo": {
        "Flight": {
          "FlightDate" : 22,
          "FlightNumber" : "002"
        },
        "Origin": "ZRH",
        "Destination": "POK"
      }
    }
 ]});