find

Retrieve documents in MongoDB collection

The find function will be removed in a future release. Use the find function of the MongoDB^® C++ interface instead.

Syntax

documents = find(conn,collection)

documents = find(conn,collection,Name,Value)

Description

documents = find(conn,collection) returns all documents in a collection by using the MongoDB connection.

documents = find(conn,collection,Name,Value) specifies additional options using one or more name-value pair arguments. For example, 'Limit',10 limits the number of documents returned to 10.

Examples

Retrieve All Documents in Collection

Connect to MongoDB, retrieve all documents in a collection, and import them into MATLAB^®. Here, each document in the collection represents an employee.

Create a MongoDB connection to the database mongotest. Here, the database server dbtb01 hosts this database using port number 27017.

server = "dbtb01";
port = 27017;
dbname = "mongotest";
conn = mongo(server,port,dbname)

conn = 

  mongo with properties:

               Database: 'mongotest'
               UserName: ''
                 Server: {'dbtb01'}
                   Port: 27017
        CollectionNames: {'airlinesmall', 'employee', 'largedata' ... and 3 more}
         TotalDocuments: 23485919

conn is the mongo object that contains the MongoDB connection. The object properties contain information about the connection and the database.

• The database name is mongotest.

• The user name is blank.

• The database server is dbtb01.

• The port number is 27017.

• This database contains six document collections. The first three collection names are airlinesmall, employee, and largedata.

• This database contains 23,485,919 documents.

Verify the MongoDB connection.

isopen(conn)

ans =

  logical

   1

The database connection is successful because the isopen function returns 1. Otherwise, the database connection is closed.

Specify the employee collection for document retrieval. Retrieve all documents in the collection by using the MongoDB connection. documents is a structure array.

collection = "employee";
documents = find(conn,collection);

Display the first document in the collection. Each document is a structure with these fields.

Field	Description	Data Type
x_id	Unique identifier	Structure
department	Department name	Character vector
employee	Employee identifier	Double
salary	Employee salary	Double

documents(1)

ans = 

  struct with fields:

          x_id: [1×1 struct]
    department: 'Sales'
      employee: 1
        salary: 60000

Close the MongoDB connection.

close(conn)

Retrieve All Documents in MongoDB Query

Connect to MongoDB, retrieve all documents in a MongoDB query on a collection in the database, and import them into MATLAB. Here, each document in the collection represents an employee.

Create a MongoDB connection to the database mongotest. Here, the database server dbtb01 hosts this database using port number 27017.

server = "dbtb01";
port = 27017;
dbname = "mongotest";
conn = mongo(server,port,dbname)

conn = 

  mongo with properties:

               Database: 'mongotest'
               UserName: ''
                 Server: {'dbtb01'}
                   Port: 27017
        CollectionNames: {'airlinesmall', 'employee', 'largedata' ... and 3 more}
         TotalDocuments: 23485919

conn is the mongo object that contains the MongoDB connection. The object properties contain information about the connection and the database.

• The database name is mongotest.

• The user name is blank.

• The database server is dbtb01.

• The port number is 27017.

• This database contains six document collections. The first three collection names are airlinesmall, employee, and largedata.

• This database contains 23,485,919 documents.

Verify the MongoDB connection.

isopen(conn)

ans =

  logical

   1

The database connection is successful because the isopen function returns 1. Otherwise, the database connection is closed.

Specify the employee collection for document retrieval. Create the MongoDB query as a character vector that contains a JSON-style string. This query retrieves all employees in the Sales department.

collection = "employee";
mongoquery = '{"department":"Sales"}';

Retrieve all documents in the MongoDB query on the employee collection by using the MongoDB connection. documents is a structure array that contains a structure for each document returned by the query.

documents = find(conn,collection,'Query',mongoquery);

Close the MongoDB connection.

close(conn)

Sort Retrieved Documents in Collection

Connect to MongoDB and retrieve documents in a MongoDB query on a collection in the database. Then, sort the results by a field in the documents. Here, each document in the collection represents an employee.

Create a MongoDB connection to the database mongotest. Here, the database server dbtb01 hosts this database using port number 27017.

server = "dbtb01";
port = 27017;
dbname = "mongotest";
conn = mongo(server,port,dbname)

conn = 

  mongo with properties:

               Database: 'mongotest'
               UserName: ''
                 Server: {'dbtb01'}
                   Port: 27017
        CollectionNames: {'airlinesmall', 'employee', 'largedata' ... and 3 more}
         TotalDocuments: 23485919

conn is the mongo object that contains the MongoDB connection. The object properties contain information about the connection and the database.

• The database name is mongotest.

• The user name is blank.

• The database server is dbtb01.

• The port number is 27017.

• This database contains six document collections. The first three collection names are airlinesmall, employee, and largedata.

• This database contains 23,485,919 documents.

Verify the MongoDB connection.

isopen(conn)

ans =

  logical

   1

The database connection is successful because the isopen function returns 1. Otherwise, the database connection is closed.

Specify the employee collection for document retrieval. Create the MongoDB query as a character vector that contains a JSON-style string. This query retrieves all employees in the Sales department.

collection = "employee";
mongoquery = '{"department":"Sales"}';

Create the sort query as a character vector that contains a JSON-style string. Sort the documents by the salary field.

sortquery = '{"salary":1.0}';

Retrieve all documents in the MongoDB query on the employee collection by using the MongoDB connection, and sort the documents. documents is a structure array that contains a structure for each document returned by the query. The documents are sorted by salary in increasing order.

documents = find(conn,collection,'Query',mongoquery,'Sort',sortquery);

Display the sorted salaries for the first two employees.

documents(1:2).salary

ans =

       60000


ans =

       64440

Close the MongoDB connection.

close(conn)

Retrieve Specific Fields in Collection

Connect to MongoDB and retrieve all documents in a collection. Specify the fields to retrieve for each document. Import the documents into MATLAB. Here, each document in the collection represents an employee.

Create a MongoDB connection to the database mongotest. Here, the database server dbtb01 hosts this database using port number 27017.

server = "dbtb01";
port = 27017;
dbname = "mongotest";
conn = mongo(server,port,dbname)

conn = 

  mongo with properties:

               Database: 'mongotest'
               UserName: ''
                 Server: {'dbtb01'}
                   Port: 27017
        CollectionNames: {'airlinesmall', 'employee', 'largedata' ... and 3 more}
         TotalDocuments: 23485919

conn is the mongo object that contains the MongoDB connection. The object properties contain information about the connection and the database.

• The database name is mongotest.

• The user name is blank.

• The database server is dbtb01.

• The port number is 27017.

• This database contains six document collections. The first three collection names are airlinesmall, employee, and largedata.

• This database contains 23,485,919 documents.

Verify the MongoDB connection.

isopen(conn)

ans =

  logical

   1

The database connection is successful because the isopen function returns 1. Otherwise, the database connection is closed.

Specify the employee collection for document retrieval. Specify the fields to retrieve for each document by using a character vector that contains a JSON-style string. Here, return the department and salary fields.

collection = "employee";
fields = '{"department":1.0,"salary":1.0}';

Retrieve all documents in the collection. Use the name-value pair argument 'Projection' to retrieve the specified fields for each document. documents is a structure array.

documents = find(conn,collection,'Projection',fields);

Display the first document in the results. In addition to the unique identifier for the document, the document contains only the specified fields, department and salary.

documents(1)

ans = 

  struct with fields:

          x_id: [1×1 struct]
    department: 'Sales'
        salary: 60000

Close the MongoDB connection.

close(conn)

Retrieve Specific Number of Documents Using Offset

Connect to MongoDB and retrieve a specific number of documents in a collection in the database. Return documents from a specific position in the results using an offset value. Import the documents into MATLAB. Here, each document in the collection represents an employee.

Create a MongoDB connection to the database mongotest. Here, the database server dbtb01 hosts this database using port number 27017.

server = "dbtb01";
port = 27017;
dbname = "mongotest";
conn = mongo(server,port,dbname)

conn = 

  mongo with properties:

               Database: 'mongotest'
               UserName: ''
                 Server: {'dbtb01'}
                   Port: 27017
        CollectionNames: {'airlinesmall', 'employee', 'largedata' ... and 3 more}
         TotalDocuments: 23485919

conn is the mongo object that contains the MongoDB connection. The object properties contain information about the connection and the database.

• The database name is mongotest.

• The user name is blank.

• The database server is dbtb01.

• The port number is 27017.

• This database contains six document collections. The first three collection names are airlinesmall, employee, and largedata.

• This database contains 23,485,919 documents.

Verify the MongoDB connection.

isopen(conn)

ans =

  logical

   1

The database connection is successful because the isopen function returns 1. Otherwise, the database connection is closed.

Specify the employee collection for document retrieval.

collection = "employee";

Use the name-value pair argument 'Skip' to skip the first five documents in the collection. Then, use the name-value pair argument 'Limit' to return the next 10 documents in the collection. documents is structure array that contains 10 documents.

documents = find(conn,collection,'Skip',5,'Limit',10);

Close the MongoDB connection.

close(conn)

Input Arguments

conn — MongoDB connection

mongo object

MongoDB connection, specified as a mongo object.

collection — Collection name

string scalar

Collection name, specified as a string scalar.

Example: "taxidata"

Data Types: string

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: 'Skip',5,'Limit',10 skips the first five documents in a collection and returns the next 10 documents.

Query — MongoDB query

string scalar | character vector

MongoDB query, specified as the comma-separated pair consisting of 'Query' and a string scalar or character vector. Specify a JSON-style string to query the database.

Example: 'Query','{"department":"Sales"}' queries the database for documents where the department field is equal to Sales.

Example: 'Query','{"salary": {$gt: 90000}}' queries the database for documents where the value of the salary field is greater than 90000.

Example: 'Query','{"_id":{$oid:"593fec95b78dc311e01e9204"}}' queries the database for the document that has the identifier 593fec95b78dc311e01e9204.

Data Types: char | string

Projection — Fields

string scalar | character vector

Fields to retrieve in each document, specified as the comma-separated pair consisting of 'Projection' and a string scalar or character vector. Specify a JSON-style string to describe the fields.

Example: 'Projection','{"department":1.0,"salary":1.0}' returns the department and salary fields.

Data Types: char | string

Sort — Sort field

string scalar | character vector

Sort field for documents, specified as the comma-separated pair consisting of 'Sort' and a string scalar or character vector. Specify a JSON-style string to describe the sort field.

Example: 'Sort','{"department":1.0}' sorts the returned documents by the department field.

Data Types: char | string

Skip — Offset

numeric scalar

Offset from the beginning of the returned documents, specified as the comma-separated pair consisting of 'Skip' and a numeric scalar.

Example: 'Skip',5 skips the first five returned documents.

Data Types: double

Limit — Number of documents to return

numeric scalar

Number of documents to return, specified as the comma-separated pair consisting of 'Limit' and a numeric scalar.

Example: 'Limit',10 returns 10 documents.

Data Types: double

Output Arguments

documents — Documents

structure | structure array | cell array of structures

Documents in a MongoDB collection or query on a collection, returned as a structure, structure array, or cell array of structures.

Each JSON-style document is represented as a structure. The find function returns a:

• Structure for one document

• Structure array for multiple documents containing the same fields

• Cell array of structures for multiple documents containing different fields

Tips

• The find function estimates memory requirements when retrieving many documents using the Java^® heap. To avoid out-of-memory issues, the function automatically limits the number of returned documents in a single execution.

  When an issue occurs, the function throws a warning message, for example, Warning: Available memory is less than Total memory required. Limiting the RESULTSET from 15837001 to 59248. Use Skip and Limit to retrieve resultset in batches.

  To retrieve many documents, retrieve them in batches. For an example, see Import Large Data from MongoDB.

Version History

Introduced in R2017b