FireDAC.Phys.MongoDBWrapper.TMongoCollection

• Up to Parent: FireDAC.Phys.MongoDBWrapper
• Methods
• Properties
• Types

Delphi

TMongoCollection = class(TMongoObject)

C++

class PASCALIMPLEMENTATION TMongoCollection : public TMongoObject

Properties

Type	Visibility	Source	Unit	Parent
class	public	FireDAC.Phys.MongoDBWrapper.pas FireDAC.Phys.MongoDBWrapper.hpp	FireDAC.Phys.MongoDBWrapper	FireDAC.Phys.MongoDBWrapper

Description

Represents a MongoDB collection.

TMongoCollection encapsulates the mongoc_collection_t structure of MongoDB.

You cannot create an instance of TMongoCollection directly. Instead, you must use one of the following members of TMongoConnection and TMongoDatabase:

• TMongoConnection.GetCollection to get a new instance of TMongoCollection.
• TMongoConnection.Collections to get a shared instance of TMongoCollection.
• TMongoDatabase.GetCollection to get a new instance of TMongoCollection.
• TMongoDatabase.Collections to get a shared instance of TMongoCollection.

TMongoCollection provides read-only properties to access basic data about the collection:

• DB is the name of the database that contains the collection.
• Name is the name of the collection.
• NS is the namespace of the collection.

Use the following members to query data from the collection:

• Find, to find documents in the collection that match a given query.
• Count, to obtain the number of documents in the collection that match a given query.
• Dereference, to obtain a document from the collection given its object ID.
• ListIndexes, to obtain a list of the indexes in the collection.
• Aggregate, to aggregate documents using an aggregation pipeline.
• Statistics, to obtain statistics about the collection.

To edit the data of the collection, you can use the following members:

• Insert to insert a new document. After a call to Insert, you can read the object ID of the inserted document from the LastID property of the collection.
• Remove to delete an existing document. You can also use RemoveAll to remove all the documents from the collection, or Drop to remove the collection itself from the database.
• Update to modify existing documents.
• CreateIndex to create an index in the collection, or DropIndex to remove one.
• Rename to change the name of the collection and its database.

Each call to Insert, Remove, or Update, TMongoCollection submits the changes to the database. To perform several changes and submit them to the database all at once:

1. Call BeginBulk to start a bulk operation.
2. Call Insert, Remove, or Update as many times as you need to perform your changes locally.
3. Call EndBulk to submit your bulk operation.

You can call CancelBulk if you want to abort a bulk operation that you started with BeginBulk. You can read the value of IsBulk to determine whether you are in the middle of a bulk operation (True) or not (False).

TMongoCollection provides properties that indicate the number of documents inserted (DocsInserted), matched (DocsMatched), modified (DocsModified), removed (DocsRemoved), or inserted as part of an update operation (DocsUpserted). TMongoCollection updates the values of these properties after each submission of data to the database.

To run database commands on the collection, use any of the following methods:

• Command runs the specified command and returns a cursor to access all result documents.
• CommandSimple runs the specified command and returns a document that contains the response from the server.
• LastError provides the result of the getLastError command.
• Validate runs the validate command.

To configure the replica set read and write semantics use the following properties:

• ReadPreference is the read preference of the collection.
• WriteConcern is the write concern of the collection.

Some Methods Support Two Different Coding Styles

Some methods of TMongoCollection support two different coding styles: a regular coding style and a fluent coding style. Those methods are: Aggregate, Count, Find, Insert, Remove, Update.

Using a Regular Coding Style

If you use a regular coding style you can reuse builder objects, such as instances of TMongoPipeline or TMongoQuery.

You must pass the the target method a builder object that you have previously created and configured. The method submits a request to the MongoDB server based on the specified builder object.

The following example shows how to submit a query using a regular coding style:

Delphi:

MyQuery := TMongoQuery.Create(MyConnection.Env);
try
  MyQuery.Match
    .Add('cuisine', 'Italian')
    .Add('address.zipcode', '10075');
  MyQuery.Sort
    .Ascending(['name']);
  MyQuery.Limit(3);
  MyCursor := MyCollection.Find(MyQuery);
  // …
finally
  MyQuery.Free;

C++:

TMongoQuery* MyQuery = new TMongoQuery(MyConnection->Env);
try {
  MyQuery->Match()
    ->Add("cuisine", String("Italian"))
    ->Add("address.zipcode", String("10075"));
  MyQuery->Sort()
    ->Ascending(OPENARRAY((String("name"))));
  MyQuery->Limit(3);
  _di_IMongoCursor MyCursor = MyCollection->Find(MyQuery);
  // …
} __finally {
  delete MyQuery;
}

Using a Fluent Coding Style

If you use a fluent coding style you can make your code more readable.

The target method returns a builder object. You can fill the returned builder object with data and submit your request to the MongoDB server using method chaining.

The method that you use to submit your request depends on the method that you use to obtain a builder object:

TMongoCollection Method	Builder Object Method
Aggregate	TMongoPipeline.Open
Count	TMongoQuery.Value
Find	TMongoQuery.Open
Insert	TMongoInsert.Exec
Remove	TMongoSelector.Exec
Update	TMongoUpdate.Exec

Note: In Delphi you can omit the call to TMongoPipeline.Open orTMongoQuery.Open, you can cast your builder object to IMongoCursor instead. See the example below.

The following example shows how to submit a query using a fluent coding style:

Delphi:

MyCursor := MyCollection.Find
  .Match
    .Add('cuisine', 'Italian')
    .Add('address.zipcode', '10075')
  .&End
  .Sort
    .Ascending(['name'])
  .&End
  .Limit(3);

C++:

_di_IMongoCursor MyCursor = MyCollection->Find()
  ->Match()
    ->Add("cuisine", String("Italian"))
    ->Add("address.zipcode", String("10075"))
  ->End()
  ->Sort()
    ->Ascending(OPENARRAY((String("name"))))
  ->End()
  ->Limit(3)
  ->Open();