Field

Add Field

The Add Field tab on the document view page is used to add fields to the document:

_images/ViewDocument-af.png

Before you start adding fields to the User document, you should get familiar with MongoDB data types supported by M2.


Type Description
Array An array of basic types or embedded documents
Binary This type is used to save images, binaries, and other non-UTF8 data.
Boolean Boolean object type
boolean Boolean primitive type (false and true values)
DBRef

DBRef is a reference from one document to another using the value of the referenced (parent) document’s _id field, its collection name, and database name.

While the MongoDB allows DBRefs without database name provided, M2 models require database name to be provided.

To resolve DBRefs, your application must perform additional queries to return the referenced documents. Many language drivers supporting MondoDB have helper methods that form the query for the DBRef automatically. Some drivers do not automatically resolve DBRefs into documents. Please refer to MongoDB language drivers documentation for more details.

The DBRef format provides common semantics for representing links between documents if your database must interact with multiple frameworks and tools.

You should use Manual References unless you have a firm reason reason for using DBRefs.

Date BSON Date is a 64-bit integer that represents the number of milliseconds since the Unix epoch (Jan 1, 1970). The official BSON specification refers to the BSON Date type as the UTC datetime. BSON Date type is signed. Negative values represent dates before 1970.
Double Floating point object for the double-precision 64-bit floating point type
double Primitive double-precision 64-bit floating point type
Embedded document Embedded document
Integer Integer object for the 32-bit integer type.
int Primitive 32-bit signed integer type
JavaScript code Represents JavaScript code
Long Integer object for the 64-bit integer type.
long Primitive 64-bit integer
Manual Reference

The Manual Reference indicates that associated field references another document’s _id. The _id is a unique ID field that acts as a primary key. The referenced (parent) document can be in the same or separate collection.

Manual references are simple to create and they should be used for nearly every case where you want to store a relationship between two documents.

Object Object type
ObjectId

A 12-byte BSON type that guarantees uniqueness within the collection.

ObjectIds consist of 12-bytes:
  • a 4-byte value representing the seconds since the Unix epoch,
  • a 3-byte machine identifier,
  • a 2-byte process id, and
  • a 3-byte counter, starting with a random value.

MongoDB uses ObjectId as a default value for the _id field if the _id field is not specified. MongoDB clients should add an _id field with a unique ObjectId. However, if a client does not add an _id field, MongoDB will add an _id field that holds an ObjectId.

Regular expression Regular expression
String

Strings are UTF-8. MongoDB drivers for most programming languages do conversions from the language’s string format to UTF-8 when serializing and deserializing BSON.

If you need to save a non-UTF-8 string, you can save it as a binary data (see the Binary data type.

Timestamp BSON has a special timestamp type for internal MongoDB use and is not associated with the regular Date type. Timestamp values are 64-bit values where: - the first 32 bits are a time_t value (seconds since the Unix epoch)</li> - the second 32 bits are an incrementing ordinal for operations within a given second.</li>

MongoDB stores documents in BSON format.

BSON is a binary representation of JSON documents. BSON data types include JSON data types plus BSON specific data types.

Field names cannot contain null characters, dots (.) or start with the dollar ($) character. BSON may have more than one field with the same name, but most MongoDB language drivers represent MongoDB documents with data structures (e.g., a hash table, etc.) that do not allow duplicate field names. M2 does not support duplicate field names.

Let us have a quick look at the structure of the User collection first modeled by the User document:

User {
    _id : ObjectId,
    comp : String,
    email : String,
    fName : String,
    fUse : String,
    perms : Array:Document
        Permission {
            _id : ObjectId
            name : String
        },
    pwd : String,
    roles : Array:Document
        Role {
            _id : Manual Reference:ObjectId
            name : String
        },
    srvs : Array:Document
        Service {
            _id : ObjectId
            name : String
        },
    token : String,
    uName : String,
    vrfd : String
}

The User document has the following fields:

  • _id ObjectId field (a.k.a. primary key of the document)
  • comp Company user works for
  • email Email address
  • fName User’s full name
  • fUse Free user account flag
  • perms An array of embedded permission documents
  • password Password
  • perms An array of embedded role documents
  • srvs An array of embedded service documents
  • token User’s identity token
  • username Username used by the user to login into the system
  • vrfd “Has user been verified” flag

This is the Role collection which documents are referenced by the _id field in the embedded documents of the User document’s roles field (see above):

Role {
    _id : ObjectId,
    descr : String,
    name : String,
    perms : Array:Document
        Perms {
            _id : ObjectId
            name : String
            oIds : Array:ObjectId
            oType : String
        }
}

We do not have to get into the details of the Role’s fields at this point, but make sure that both User and Role collections are created first.

The _id field acts as a primary key. The _id field is always included in documents of regular collections. It can reference a value of any BSON type other than an array. In the case of MongoDB replication use, the regular expression type is not used either.

We will start with the User document by adding the _id field to it. Click the Add Field tab on the User document page and enter the name, description and type of the field:

_images/AddField-id.png

and click the Add Field to add the field. The document page will be loaded with the _id field listed on it. The Required checkbox should be checked if the field’s value is mandatory. _id is by default a field with mandatory value and M2 will manage it as the field with mandatory value regardless if you checked the Required checkbox or not. For all other fields you have to check the Required checkbox if their value is mandatory.

_images/AddField-id-2.png

Since adding the fields of basic data types (e.g., ObjectId, Integer, Date, Double, etc.) is straight forward, now we will show how to add the roles field which is an array of embedded documents. This field’s embedded documents use Manual References to reference documents in the Role collection.

Click the Add Field tab to add the roles field and enter the name, description and the type of the roles field. For the field type we will select Array first:

_images/ViewDocument-AddField.png

and then we will select Document as an additional type that together with Array type models array of embedded documents:

_images/ViewDocument-AddField-2.png

Click the Add Field button to add the field. When the roles field is added, click on its link to load the field’s page:

_images/ViewDocument-AddField-3.png

When the field’s page is loaded you will see the Documents section that belongs to the embedded documents for this field. Click the Roles document link to load its page:

_images/ViewDocument-AddField-4.png

Now add embedded document’s fields:

  • _id - Role’s ObjectId
  • name - Role’s name

The _id field is of the Manual Reference type since it references Role collection document’s _id:

_images/ViewDocument-AddField-5.png

After selecting the Manual Reference as its type, we will also select ObjectId as a part of its composite type that belongs to its ObjectId value:

_images/ViewDocument-AddField-6.png

Click the Add Field to add the field.

_images/ViewDocument-AddField-7.png

As you can see, the field’s type is Manual Reference:ObjectId. Now, we have to specify which collection’s document this field will be referencing. In this example, it will be referencing the Role collection’s document. We assume here that the Role collection has been already created.

Now click the _id field’s link to load its page:

_images/ViewDocument-AddField-8.png

Click the Manual Reference tab to specify which collection the reference belongs to:

Select the Role collection’s document and click the Reference Collection button to complete the setup for the field.

_images/ViewDocument-AddField-9.png

View Field

When you click a field’s link on the document page,

_images/ViewDocument-ViewField.png

the field view page will be loaded:

_images/ViewField.png

This page has few buttons you can use:

  • Models (go back to M2 home page that lists all models you have access to)
  • Full Model View (the full model view page that shows all elements of the model)
  • Update (update field)
  • Delete (delete field)

The Options tab means that the field has Options defined. You can use this tab to check out options, add options or update/remove options.

Update Field

Click the Update button on the field page to update the field

_images/ViewField-Update.png

and the update field page will be loaded:

_images/UpdateField.png

You can update the name, description and the type of the field and click the Update button to submit the updates. Otherwise, click the Cancel button if you do not want to update the field.

Delete Field

Click the Delete button on the field page to remove the field:

_images/ViewField-Delete.png

A small confirmation window will pop up. You can either confirm field removal or cancel it.

Manual Reference

MongoDB does not support joins. For some data models, it is fine to model data with embedded documents (denormalized model), but in some cases referencing documents (normalized model) is a better choice. A referenced document can be in the same collection or in the separate collection in the same database or in another database.

Manual References are used to reference documents either in the same collection or in the separate collection in the same database.

The Manual Reference MongoDB type indicates that the associated field references another document’s _id. The _id is a unique ID field that acts as a primary key. Manual references are simple to create and they should be used for nearly every case where you want to store a relationship between two documents.

We will use MongoDB’s Publisher-Book example of the Referenced One-to-Many model. This model comes as a pre-created public model in M2:

_images/Ref-One-To-Many.png

Publisher‘s id is of type String and it is referenced in the Book document by the publisher_id field of the type Manual reference:String. This means that the values of the publisher_id field will be referencing the values of the Publisher document _id field.

Now, we will demonstrate how we created this model in M2. We will concentrate only on the Publisher and Book collections creation and the creation of their relevant fields (_id and publisher_id) for this example.

First we will create the Referenced One-to-Many model in M2. Enter the name and description of the model and click the Create Model button to create the model as shown below:

_images/AddModel-RefOneToMany.png

When the model is created, the M2 models page will be loaded and we will click the Referenced One-to-Many model link to load the model’s page:

_images/AddModel-RefOneToMany-2.png

When the model page is loaded, click the Add Collection tab in order to add the Publisher collection to the model:

_images/AddModel-RefOneToMany-2_2.png

Enter the Publisher name and description and click the Add Collection button to create it:

_images/AddModel-RefOneToMany-3.png

Also create the Book collection.

When both collections are created

_images/AddModel-RefOneToMany-5.png

we will continue with the Publisher document’s _id field creation. Click the Publisher collection link to load the Publisher collection page and then click the Publisher document link to load the Publisher document page. When the Publisher document page is loaded click the Add Field tab to add the _id field first:

_images/AddModel-RefOneToMany-6.png

Click the Add Field button to add the field. When the field is added, the Publisher document page will be reloaded:

_images/AddModel-RefOneToMany-8.png

Click the Full Model View to load the full model view page and then click the Book document link, as depicted below, to load the Book document page:

_images/AddModel-RefOneToMany-9.png

When the Book document page is loaded, click the Add Field tab to add the publisher_id field. First we will select the Manual Reference as its type:

_images/AddModel-RefOneToMany-10.png

and then we will add the String as the second part of its composite type which belongs to its values:

_images/AddModel-RefOneToMany-11.png

Click the Add Field button to add the field. The document page will be reloaded when the field is added:

_images/AddModel-RefOneToMany-12.png

Click the publisher_id link to load the field page and then click the Manual Reference tab to specify reference details:

_images/AddModel-RefOneToMany-13.png

When the Manual Reference section is loaded, select the Publisher collection’s document and click the Reference Collection button to complete the Manual reference setup for the publisher_id field:

_images/AddModel-RefOneToMany-14.png

M2 will create the manual reference and reload the Manual Reference section:

_images/AddModel-RefOneToMany-15.png

Click the Referenced One-to-Many model link above to load the Referenced One-to-Many model page and then click the Full Model View button to load the full model view page:

_images/AddModel-RefOneToMany-16.png

The References section of the page (please see above) lists the reference that was just created. Both the Source (Parent) and Target (Child) column has the format: Collection –> Document –> Field. For example, the Target (Child) column contains the Book –> Book –> publisher_id value which means that Book is the target (child) collection and publisher_id is the field in the Book document of the Book collection whose value will reference the _id field value of the parent Collection (Publisher) document. The Database column is reserved for DBRef only.

It is also possible that the target (child) document, in the Collection –> Document –> Field value, is not the target collection document but an embedded document (on any level) in the target collection. For example, the UserRole document in the User –> UserRole –> _id target reference value in the RBAC model below:

_images/AddModel-RefOneToMany-17.png

DBRef

MongoDB does not support joins. For some data models, it is fine to model data with embedded documents (denormalized model), but in some cases referencing documents (normalized model) is a better choice. A referenced document can be in the same collection or in a separate collection in the same database or in another database.

Database references (DBRef) are references from one document to another using the value of the referenced (parent) document’s _id field, its collection name, and the database name. While the MongoDB allows DBRefs without the database name provided, M2 models require the database name to be provided. The reason for this is because a Manual Reference in an M2 model must specify the collection name for the model to be complete in which case the DBRef without the database name from the M2 model point of view is the same as the Manual Reference. The database name in DBRef is more of an implementation aspect of the model and it is needed in order to make the DBRef definition complete. Otherwise, without the database name, the DBRef is the same as the Manual Reference to M2.

To resolve DBRefs, your application must perform additional queries to return the referenced documents. Many language drivers supporting MondoDB have helper methods that form the query for the DBRef automatically. Some drivers do not automatically resolve DBRefs into documents. Please refer to MongoDB language drivers documentation for more details.

The DBRef format provides common semantics for representing links between documents if your database must interact with multiple frameworks and tools.

Unless you have a firm reason for using a DBRef, use Manual References.

The example below is taken from MongoDB’s DBRef documentation page:

{
    "_id" : ObjectId("5126bbf64aed4daf9e2ab771"),
    // .. application fields
    "creator" : {
        "$ref" : "creators",
        "$id" : ObjectId("5126bc054aed4daf9e2ab772"),
        "$db" : "users"
    }
}

The DBRef in this example references the creators collection’s document that has ObjectId(“5126bc054aed4daf9e2ab772”) value for its _id field. The creators collection is stored in the users database.

Let us create a sample collection Object and model it in M2.

First we will create a model with the name DBRef Sample Model:

_images/CreateModel-DBRef.png

Click the Create Model button to create the model. When the model is created, the M2 home page will be reloaded:

_images/DBRef-ListModels.png

Click the DBRef Sample Model link to load the model page and then click the Add Collection tab to load the section for the collection creation. Enter the name and description of the Object collection:

_images/DBRef-ObjectCollection.png

Click the Add Collection button to create the collection. M2 will automatically create the collection’s document:

_images/DBRef-ListCollection.png

Click the Object collection link to load the collection page and then click the Object document link in the Documents section to load the document page:

_images/DBRef-Document.png

Click the Add Field tab to load the section for the field creation. Enter the name and description of the creator field and select DBRef for the field’s type. When the DBRef is selected as the field’s type, M2 will also require selection of the field’s value type which belongs to the value type of the referenced document’s _id field. It will be ObjectId in this example:

_images/DBRef-AddField.png

Click the Add Field button to create the field. When the field is created it will be listed on the document page:

_images/DBRef-DocWithField.png

Click the creator field link to load the field page:

_images/DBRef-DBRef.png

Click the DBRef tab to load the DBRef section and specify the referenced collection name (Creators) and its database (users) to complete the creator field creation:

_images/DBRef-Spec.png

As you can see, you can either specify a collection name if it is not included in the model (as in this case) or select a collection’s document from the Collection –> Document list if it is included in the model. Click the Add DBRef button to update the creator field definition:

_images/DBRef-Final2.png

Click the model link above to load the DBRef Sample Model page and then click the Full Model View button:

_images/DBRef-Final3.png

The References section of the page, as represented above, lists the reference that was just created. The Target (Child) column has the format: Collection –> Document –> Field. It contains the Object –> Object –> creator value which means that the Object is the target (child) collection and the creator is the field in the Object document of the Object collection whose value will reference the _id field value of the parent Collection (Creators) document. The Database column specifies the database of the source (parent) collection.

It is also possible that the target (child) document, in the Collection –> Document –> Field value, is not the target collection document but an embedded document (on any level) in the target collection.

Options

Fields may have optional values. For example, yes/no, male/female, list of states/provinces, list of countries, etc.

We created the Referenced One-to-Many model to demonstrate the Manual Reference modeling in M2. Let us update this model by adding the language field to the Book document:

_images/Option-1.png

When you click the Add Field tab, the page to add a field will be loaded. We will add the language field:

_images/Option-2.png

When the field is added, the document page will be reloaded.

_images/Option-3.png

Click the language field link to load the field page:

_images/Option-4.png

Now click the Options tab to show the options section for the field. Enter the English value first:

_images/Option-5.png

and click the Add Option button to add it. Options section will be reloaded when the value is added:

_images/Option-6.png

You can continue adding other values. You will use the Update Option button if you want to update and/or remove some of the values.