Changes to the findOneAnd* APIs in Node.js Driver 6.0.0

Alex Bevilacqua
August 8, 2023

Do you use the MongoDB Node.js driver? If so, there’s a good chance you use various find() operations regularly.

MongoDB plans to release version 6.0.0 of the Node.js driver in August 2023, and we’ve made some exciting improvements to the findOneAnd* operation. With the new driver release, the modified (or original) document targeted by a findOneAnd* operation will now be returned by default.

Current state

Up until now, as opposed to returning the requested document, this family of API methods would return a ModifyResult, which would contain the requested document in a value field. This design was due to these APIs leveraging the MongoDB Server’s findOneAndModify command and wrapping the command’s output directly.

To demonstrate, let’s adapt the code from the Driver’s documented usage examples to update one document in our movies collection using the findOneAndUpdate API.

const database = client.db("sample_mflix");
const movies = database.collection("movies");
// Query for a movie that has the title 'The Room'
const query = { title: "The Room" };
const updatedMovie = await movies.findOneAndUpdate(query,
  { $set: { "imdb.rating": 3.4, "imdb.votes": 25750 } },
  { projection: { _id: 0, title: 1, imdb: 1 }, returnDocument: "after" });
console.log(updatedMovie);

{
  lastErrorObject: { n: 1, updatedExisting: true },
  value: {
    title: 'The Room',
    imdb: { rating: 3.4, votes: 25750, id: 368226 }
  },
  ok: 1,
  '$clusterTime': {
    clusterTime: new Timestamp({ t: 1689343889, i: 2 }),
    signature: {
      hash: Binary.createFromBase64("3twlRKhDSGIW25WVHZl17EV2ulM=", 0),
      keyId: new Long("7192273593030410245")
    }
  },
  operationTime: new Timestamp({ t: 1689343889, i: 2 })
}

One of the options we set was a returnDocument of after, which should return the updated document. Though the expectation may be that the function call would return the document directly, as we can see this isn’t the case.

While the document you’re looking for can be accessed using updatedMovie.value, that isn’t the most intuitive experience. But changes are on the way!

What can we do right now?

Starting with the Node.js Driver 5.7.0 release a new FindOneAnd*Options property called includeResultMetadata has been introduced. When this property is set to false (default is true) the findOneAnd* APIs will return the requested document as expected.

const updatedMovie = await movies.findOneAndUpdate(query,
  { $set: { "imdb.rating": 3.3, "imdb.votes": 25999 } },
  { projection: { _id: 0, title: 1, imdb: 1 }, includeResultMetadata: false });
console.dir(updatedMovie);

{ title: 'The Room', imdb: { rating: 3.3, votes: 25999, id: 368226 } }

What about TypeScript?

If your application uses TypeScript and the MongoDB Node.js Driver, anywhere a findOneAnd* call is made, if the requested document is required it will be accessed via the value property of the ModifyResult. This occurs when includeResultMetadata is not set or when it is set to true (the current default value).

Type hinting will indicate the Schema associated with the collection the operation was executed against. As we would expect, when the includeResultMetadata is changed to false inline validation will indicate there’s an issue as the value property no longer exists on the type associated with the result.

Attempting to compile our TypeScript project will also fail.

TSError: ⨯ Unable to compile TypeScript:
index.ts:31:17 - error TS18047: 'updatedMovie' is possibly 'null'.

31     console.dir(updatedMovie.value);
                   ~~~~~~~~~~~~
index.ts:31:30 - error TS2339: Property 'value' does not exist on type 'WithId<Movie>'.

31     console.dir(updatedMovie.value);

Next Steps

If you’re using the findOneAnd* family of APIs in your JavaScript or TypeScript project, upgrading the MongoDB Node.js Driver to 5.7.0+ and adding the includeResultMetadata: false option to those API calls will allow you to adapt your application to the new behavior prior to the 6.0.0 release.

Once 6.0.0 is released, includeResultMetadata: false will become the default behavior. If your application relies on the previous behavior of these APIs, setting includeResultMetadata: true will allow you to continue to access the ModifyResult directly.

← Previous

The MongoDB for VS Code Extension Is Now Generally Available

As of today, the MongoDB for VS Code Extension has been downloaded one million times! A huge thank you to all the developers who build with MongoDB and VS Code. We look forward to working with you to continue to improve the extension. Two million downloads, here we come! Three years ago, we introduced the MongoDB for VS Code Extension to the world in Public Preview. VS Code is the most popular Integrated Development Environment (IDE) for developers, and we were excited to bring the power of MongoDB, one of the world’s most-loved databases, to developers right in their favorite IDE. Since that time, we’ve seen skyrocketing growth in adoption of the extension, which now has over 800k installs and an average rating of 4.5 stars in the VS Code Extension store. The verdict is in: people love not only VS Code and MongoDB, but love a unified experience in the form of the MongoDB for VS Code Extension. Given the popularity of the tool and innovations we’ve continued to make in the experience, we are delighted to announce that the MongoDB for VS Code Extension is now generally available. Why use the extension? This free, downloadable extension makes it easy for developers to build applications and work application data in MongoDB directly from VS Code. Not only do you get the benefit of interacting with MongoDB data in a familiar IDE experience you’ve likely already customized to your preferences—you also can work with your application data and your application code all in one place. And with the extension now generally available (GA), you can have increased confidence in the extension and MongoDB’s long-term commitment to ongoing improvements to the experience. What the extension can do With the MongoDB for VS Code Extension, you get a single unified interface (VS Code) that you already know and love. Within the extension, you can work with your application data from MongoDB side-by-side with your application code for a more streamlined software development experience. Let’s take a look at what you can do with the extension. Connect to MongoDB After you’ve installed the extension , the first thing you’ll want to do is connect to MongoDB using a connection string. If you’re using MongoDB Atlas, you can find your connection string in the Atlas Web UI under the “Database” view by clicking the “Connect” button and then choosing VS Code as your connection option. Data exploration Within the extension, it’s easy to look at your data on MongoDB while working on your code. In the left-hand sidebar, you can easily click through databases, collections, and documents, as well as see relevant schema and indexes. Referencing both schema and indexes here during development can be helpful because: 1. By looking at the schema, you can see what fields you can query on and what their types are, and 2. You can confirm if your query is covered by an index for faster reads against the database. Playgrounds The MongoDB for VS Code Extension gives you a fully-featured JavaScript Playgrounds experience for rapid scripting and prototyping. In Playgrounds you can prototype queries, aggregations, and MongoDB commands with syntax highlighting and intelligent autocomplete. After you write your code, just hit the “play” button or use your favorite keyboard shortcut to instantly see the results of code execution. Within Playgrounds you can: Create new databases and collections Execute Create-Read-Update-Delete (CRUD) operations against your MongoDB database Prototype queries and aggregations using MongoDB’s powerful and expressive Query API Export the syntax for a given query or aggregation to your chosen programming language (including language driver syntax) You can also save Playground files together with your application code and version them in git. This is a great option for documenting all the queries and aggregations your application runs, for scripts that generate or import sample datasets to seed your development clusters, or for scripts that create indexes or define schema migrations. And because Playgrounds use the shell syntax, you can then run them programmatically with the MongoDB Shell. Access the MongoDB Shell Sometimes you just want to run a quick query or command in your terminal rather than using a fully-featured UI. The MongoDB Shell is the perfect tool for these kinds of quick data interactions, and you can access the Shell without ever leaving VS Code. Just right-click on your cluster and select “Launch MongoDB Shell” to get started with the Shell. Terraform If your team uses Terraform, you’ll probably be interested in the MongoDB Atlas Terraform Provider for building with MongoDB. The MongoDB for VS Code Extension gives you access to snippets of code for common tasks you might want to accomplish—including managing your Terraform configuration for Atlas. To use this feature, just open a Terraform file, type atlas , go through the predefined placeholders, and configure your credentials. The MongoDB for VS Code Extension lets you do all of the above - and more. To learn about all the different capabilities of the extension, check out the documentation here . New features Here’s what’s new in the extension now that it’s generally available: Autocomplete support with IntelliSense for using the MongoDB Query API, making it more intuitive to type queries and aggregations for your data on MongoDB Improvements to the Playgrounds experience to make them more reflective of a traditional JavaScript environment, including the ability to integrate them with common tools for the JavaScript ecosystem such as ESLint and Prettier Time series collections can now be created right from Playgrounds You can create column store indexes to support your analytics queries Get started today If you haven’t tried it yet, now is the time to start using the MongoDB for VS Code Extension! To install it, simply search for it in the Extensions list inside VS Code or download it from the VS Code Marketplace . Or if you’re a current user, be sure to check for updates so you get the latest version of the extension and access to the new features that come with it. As you build with the MongoDB for VS Code Extension, feel free to give us feedback on your product experience in the MongoDB Feedback Engine , so we can continue to take the pulse of the community and further optimize the extension for users.

August 8, 2023

Next →

Staff Engineering at MongoDB: Your Path to Making Broad Impact

Andrew Whitaker is a Senior Staff Engineer at MongoDB. His previous experience spans tiny startups to enormous organizations like AWS, where he held several different roles focusing on databases. Before joining MongoDB, he worked at a startup building optimized machine learning models in the cloud. Read on to learn more about why Andrew decided to join MongoDB in a senior-level engineering role and how his work is driving improvement within our engineering organization. Why MongoDB I have long been a fan of MongoDB’s products and services. MongoDB the database has always been a pleasure to work with – the system “brings joy” to quote a phrase. As a Python developer, I appreciate how the Python driver feels “Pythonic” in a completely natural way. The programmer interacts with the database using Python constructs: dictionaries, lists, and primitive types. By contrast, SQL databases force me to change my mental model, and the query language feels like an add-on that does not blend with the core language. As an engineer, I am always looking to expand my knowledge and grow my skills. The scope of challenges engineers face at MongoDB is what triggered my interest in the company. We obviously have people working on core databases and distributed systems. But, we also have teams dedicated to machine learning, streaming data, analytics, networking, developer tooling, drivers, and many more areas. It is very hard to get bored working at MongoDB. Finally, I would be remiss if I did not mention the people. Overall, MongoDB’s engineering culture prioritizes intelligence, low ego, and an ability to get stuff done. CL/CI (Continuous Learning, Continuous Improvement) Working at MongoDB has provided me with opportunities for continued learning and growth. Though I do not program as much as I did earlier in my career, I have recently been exploring the Rust language. I’m excited by Rust because it avoids the tradeoffs between predictable performance and safety. My work in the search space has given me exposure to the fast moving world of AI: vector embeddings, RAG, etc. For various reasons, I think MongoDB is uniquely positioned to do well in this area. On top of this, I’m working on some initiatives that are not fully public. I can say that one focus area is improving the sharding experience for our customers. We believe MongoDB sharding is best-in-breed. Still, the process requires more manual configuration than we think is ideal: customers select the shard key, cluster type, shard count, etc. We give guidance here, but I think we can raise the bar in terms of offering a seamless experience with less “futz”. I’m also working with the search team. We believe there is a natural affinity between MongoDB’s document model and AI/ML workloads. We have some features in the works that extend this integration in new and interesting ways. I also spend a fair bit of time driving quality improvements across our suite of products. Our CTO Jim Scharf frequently refers to our “ big 4 ” goals: security, durability, availability, and performance. These goals are more important than any feature we build. I’ve been working across the company to help teams define their availability SLO/SLAs. It turns out that measuring availability is a subtle topic. For example, a naive approach of counting the percentage of failed requests can underestimate downtime because customers make fewer requests when a service is unavailable. So, the first step is to clarify the definition of availability. Finally, as a lapsed academic (in a distant life, I was a graduate student at the University of Washington Department of Computer Science and Engineering), I’m always interested in finding ways to bridge theory and practice. I’ve been collaborating with some folks in our research team to drive improvements to our replication protocols. There are theoretical results that suggest it is impossible to simultaneously achieve low latency and strong consistency (“linearizability” in the technical jargon). However, we believe there are intermediate points in the consistency/latency spectrum that have not been fully explored. This work hasn't been made into a product yet, but stay tuned. Flexible working MongoDB is a hybrid company. Like many of our engineers, I work outside the company headquarters in New York City (I live in Seattle). I appreciate MongoDB’s approach to hybrid working and that company leadership, starting with Dev , cares about the well-being of their employees. It seems there are companies that don’t seem to trust their employees to make decisions, such as which days to come into the office, so I’m thankful for the autonomy I receive at MongoDB to work in a way that’s best for me. Remote work has its challenges, but I would say that the benefit for my work/life balance has been transformative. Final thoughts I have found MongoDB engineers demonstrate a strong mix of technical depth, pragmatism, and empathy. I have yet to find the “smart jerk” prototype that seems to exist throughout the tech industry. Overall, I have found MongoDB is open to change and growth at both the team level and the individual level. There is a willingness to evolve and improve that aligns with the company’s values and leadership principles and enables the success of our technology and people. Find out more about MongoDB culture and career opportunities by joining our talent community .

November 20, 2024